🐘 🪪 `pg_idkit`

postgres=# CREATE EXTENSION pg_idkit;
CREATE EXTENSION

postgres=# SELECT idkit_uuidv7_generate();
        idkit_uuidv7_generate
--------------------------------------
 018c106f-9304-79bb-b5be-4483b92b036c

Description

pg_idkit is a Postgres extension for generating many popular types of identifiers:

Methodology	Function	Crate	Description
UUID v6	idkit_uuidv6_generate()	uuidv6	UUID v6 (RFC 4122)
	idkit_uuidv6_generate_uuid()
	idkit_uuidv6_extract_timestamptz(TEXT)
UUID v7	idkit_uuidv7_generate()	uuid7	UUID v7 (RFC 4122)
	idkit_uuidv7_generate_uuid()
	idkit_uuidv7_extract_timestamptz(TEXT)
nanoid	idkit_nanoid_generate()	nanoid	NanoID, developed by Andrey Sitnik
	idkit_nanoid_custom_generate_text()	nanoid	NanoID with a custom length and alphabet
ksuid	idkit_ksuid_generate()	svix-ksuid	Created by Segment
	idkit_ksuid_extract_timestamptz(TEXT)
	idkit_ksuidms_generate()	svix-ksuid	Same as ksuid but with millisecond precision
	idkit_ksuidms_extract_timestamptz(TEXT)
ulid	idkit_ulid_generate()	ulid	Unique, lexicographically sortable identifiers
	idkit_ulid_extract_timestamptz(TEXT)
Timeflake	idkit_timeflake_generate()	timeflake-rs	Twitter's Snowflake + Instagram's ID + Firebase's PushID
	idkit_timeflake_extract_timestamptz(TEXT)
PushID	idkit_pushid_generate()	pushid	Google Firebase's PushID
xid	idkit_xid_generate()	xid	XID
	idkit_xid_extract_timestamptz(TEXT)
cuid (deprecated)	idkit_cuid_generate()	cuid	CUID
	idkit_cuid_extract_timestamptz(TEXT)
cuid2	idkit_cuid2_generate()	cuid2	CUID2

This Postgres extension is made possible thanks to [pgrx][pgrx].

Quickstart

You can try out pg_idkit incredibly quickly by using docker, and a previously released package of pg_idkit:

docker run \
    --rm \
    -e POSTGRES_PASSWORD=replace_this \
    -p 5432 \
    --name pg_idkit \
    ghcr.io/vadosware/pg_idkit:0.2.4-pg17.0-alpine3.18-amd64

Warning

Currently only amd64 (x86_64) images are present/supported (See pg_idkit packages).

Work to support more platforms is described in issue #30

Once the postgres server is running, open another shell and connect to the dockerized Postgres instance running on port 5432:

➜ docker exec -it pg_idkit psql -U postgres
psql (17.0)
Type "help" for help.

postgres=# CREATE EXTENSION pg_idkit;
CREATE EXTENSION

postgres=# SELECT idkit_uuidv7_generate();
        idkit_uuidv7_generate
--------------------------------------
 018c106f-9304-79bb-b5be-4483b92b036c
(1 row)

Installing pg_idkit

📃 From Source

Source install

To build pg_idkit from source, clone this repository and run the following:

cargo install cargo-get cargo-pgrx just
just package

After running these commands you should see the following directory structure in target/release/pg_idkit-pg16:

target/release/pg_idkit-pg16
├── home
│   └── <user>
│       └── .pgrx
│           └── 17.0
│               └── pgrx-install
│                   ├── lib
│                   │   └── postgresql
│                   │       └── pg_idkit.so
│                   └── share
│                       └── postgresql
│                           └── extension
│                               ├── pg_idkit--0.2.4.sql
│                               └── pg_idkit.control
└── usr
    ├── lib
    │   └── postgresql
    │       └── pg_idkit.so
    └── share
        └── postgresql
            └── extension
                └── pg_idkit.control

24 directories, 8 files

As the installation of the extension into a specific version of postgres uses your local installation of pgrx-managed Postgres by default (normally at $HOME/.pgrx), cargo pgrx package reproduces the directory structure in target/release. You can safely ignore the shorter usr/lib/user/share tree.

In the example above, the files you need for a Postgres extension are:

• target/release/home/<user>/.pgrx/17.0/pgrx-install/lib/postgresql/pg_idkit.so
• target/release/home/<user>/.pgrx/17.0/pgrx-install/share/postgresql/extension/pg_idkit--0.2.4.sql
• target/release/home/<user>/.pgrx/17.0/pgrx-install/share/postgresql/extension/pg_idkit.control

Install these files in the relevant folders for your Postgres installation -- note that exactly where these files should go can can differ across linux distributions and containerized environments.

💽 From Binary

Binary install

If running a custom version of locally/globally manually installed Postgres, you may download (and verify the checksum of) a shared library version from the releases, and add it as one of your shared_preload_libraries in postgresql.conf.

Assuming you have downloaded the pg_idkit-vX.X.X.so file to /etc/postgresql/extensions, you might change the file like this:

postgresql.conf

shared_preload_libraries = '/etc/postgresql/extensions/pg_idkit-vX.X.X.so'

Once your postgres instance is started up, you should be able to CREATE EXTENSION:

postgres=# CREATE EXTENSION pg_idkit;
CREATE EXTENSION
postgres=# SELECT idkit_uuidv7_generate();
        idkit_uuidv7_generate
--------------------------------------
 018c106f-9304-79bb-b5be-4483b92b036c

🐳 Dockerfile

Dockerfile

To use pg_idkit easily from a containerized environment, you can use the pg_idkit image, built from postgres:

docker run \
    --rm \
    -e POSTGRES_PASSWORD=replace_this \
    -p 5432 \
    --name pg_idkit \
    ghcr.io/vadosware/pg_idkit:0.2.4-pg17.0-alpine3.18-amd64

From another terminal, you can exec into the pg_idkit container and enable pg_idkit:

➜ docker exec -it pg_idkit psql -U postgres
psql (17.0)
Type "help" for help.

postgres=# CREATE EXTENSION pg_idkit;
CREATE EXTENSION
postgres=# SELECT idkit_uuidv7_generate();
        idkit_uuidv7_generate
--------------------------------------
 018c106f-9304-79bb-b5be-4483b92b036c
(1 row)

[!WARNING] Currently only amd64 (x86_64) images are present/supported (See pg_idkit packages).

Work to support more platforms is described in issue #30

📦 Debian (RPM)

RPM install

RPMs are produced upon every official release of pg_idkit.

Grab a released version of the RPM (or build one yourself by running just build-rpm after setting up local development).

For example, with an RPM named pg_idkit-0.2.4-pg17.x86_64.rpm, you should be able to run:

dnf install pg_idkit-0.2.4-pg17.x86_64.rpm

Prior Art

There are some other projects in the Postgres ecosystem that implement alternative UUID generation mechanisms.

Here are some you may or may not have heard of:

• spa5k/uids-postgres
• scoville/pgsql-ulid
• pg-xid
• geckoboard/pgulid
• this gist by fabiolimace for generating UUIDv6

Setting up for local development

Interested in contributing on the project? Set up your local development environment w/ docs/local-development.md.

Contributing

Contributions are welcome!

If you find a bug or an impovement that should be included in pg_idkit, create an issue.

If you'd like to contribute code, get started by:

1. Reading the local development guide
2. Creating an issue (if necessary) to explain the new feature/bugfix/etc
3. Forking this repository
4. Creating a feature/bugfix/etc branch (we expect [conventional commits][conventional-commits], i.e. feat: new awesome feature)
5. Opening a Pull Request to this repository