postgres-ulid

lcdss/postgres-ulid is the official PostgreSQL Docker image with the pgx_ulid extension already built in, so you get a native ulid column type and gen_ulid() without compiling anything.

If you already use the official Postgres image, this one behaves the same way. The only difference is that pgx_ulid is available inside the database.

• Docker Hub: https://hub.docker.com/r/lcdss/postgres-ulid
• Tag list: https://hub.docker.com/r/lcdss/postgres-ulid/tags
• Source: https://github.com/lcdss/postgres-ulid

Supported Platforms

linux/amd64 only. Upstream postgres publishes more architectures, but these images do not, so on Apple Silicon and other arm64 hosts Docker falls back to emulation.

Quick Start

docker run -d \
  --name postgres-ulid \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  lcdss/postgres-ulid:18-alpine

docker exec -it postgres-ulid psql -U postgres

CREATE TABLE users (
  id ulid PRIMARY KEY DEFAULT gen_ulid(),
  email text NOT NULL UNIQUE,
  created_at timestamptz NOT NULL DEFAULT now()
);

INSERT INTO users (email) VALUES ('someone@example.com') RETURNING id;

docker compose

services:
  postgres:
    image: lcdss/postgres-ulid:18-alpine
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_USER: postgres
      POSTGRES_DB: app
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Enabling The Extension

On a fresh data directory the entrypoint enables pgx_ulid in postgres, template1, and POSTGRES_DB, so those databases and any database created later inherit it.

An existing data directory is never touched, so when you switch a running volume from the official image to this one, enable the extension yourself in each database that needs it:

CREATE EXTENSION IF NOT EXISTS pgx_ulid;

To check what is installed:

SELECT extversion FROM pg_extension WHERE extname = 'pgx_ulid';

Monotonic ULIDs

gen_monotonic_ulid() needs the library preloaded, which the image does not do by default:

docker run -d \
  --name postgres-ulid-monotonic \
  -e POSTGRES_PASSWORD=postgres \
  lcdss/postgres-ulid:18-alpine \
  postgres -c shared_preload_libraries=pgx_ulid

SELECT gen_monotonic_ulid();

In compose, pass the same override as command:.

Configuration

Everything the official image supports applies here unchanged: the POSTGRES_* variables, PGDATA, POSTGRES_INITDB_ARGS, scripts dropped into /docker-entrypoint-initdb.d, the data volume layout, and the entrypoint behavior. See https://hub.docker.com/_/postgres for that reference.

Tags

Tags mirror the official postgres image:

• Exact major tags from 14 and newer
• The alpine and trixie image families
• The floating alpine and trixie tags, which move with the newest major

Examples: 18-alpine, 18-trixie, 16-alpine, alpine, trixie. The live list is at https://hub.docker.com/r/lcdss/postgres-ulid/tags.

A scheduled job checks upstream daily and rebuilds a tag when the upstream digest or the build inputs change, so pinning a floating tag means the underlying major can change under you. Pin an exact major, or a digest, when that matters.

Each image records where it came from, which you can inspect before trusting a mirror:

docker image inspect lcdss/postgres-ulid:18-alpine \
  --format '{{ json .Config.Labels }}'

• org.opencontainers.image.base.name — the upstream tag it was built from
• io.github.lcdss.postgres-ulid.source-digest — the upstream manifest digest
• io.github.lcdss.postgres-ulid.build-signature — the build inputs used

What This Image Changes

pgx_ulid is compiled once per Postgres major and image family, published as a standalone artifact, and copied into the mirrored image along with one initialization script that enables the extension on first startup. Nothing else about the official image is modified: same entrypoint, same defaults, no preloaded libraries.

pgx_ulid is pinned to v0.2.3, so a given image tag always carries a known extension revision. Use the extversion query above to confirm what an image has.

Contributing

Build, test, and automation details live in CONTRIBUTING.md.

License

This repository's own files are MIT licensed, see LICENSE. The images also carry everything upstream ships: PostgreSQL under the PostgreSQL License, the base image contents under their respective licenses, and pgx_ulid under its own terms.

Disclaimer

Unofficial image, not affiliated with Docker, Inc., the PostgreSQL Global Development Group, or the pgx_ulid maintainers.