pg_idkit - a tool kit for generating IDs in postgres

pg_idkit is a Postgres extension for generating IDs. It aims to be have just about every ID you'd normally think of using:

Methodology	function	Crate	Description
UUID v6	idkit_uuidv6_generate	uuidv6	UUID v6 (RFC 4122)
UUID v7	idkit_uuidv7_generate	uuid7	UUID v7 (RFC 4122)
nanoid	idkit_nanoid_generate	nanoid	NanoID, develepod by Andrey Sitnik
ksuid	idkit_ksuid_generate	ksuid	developed by Segment
ulid	idkit_ulid_generate	ulid	unique, lexicographically sortable identifiers
Timeflake	idkit_timeflake_generate	timeflake-rs	Twitter's Snowflake + Instagram's ID + Firebase's PushID
PushID	idkit_pushid_generate	pushid	Google Firebase's PushID
xid	idkit_xid_generate	xid	XID
cuid	idkit_cuid_generate	cuid	CUID

This Postgres extension is made possible thanks to pgx.

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

Installing pg_idkit

Binary install

If running a custom version of locally/globally manually installed Postgres, you may download (and verify the checksum of) a shared library versionfrom 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'

Dockerfile

To build pg_idkit into a Postgres instance you can use a Dockerfile like the following:

TODO

Local Development

Here's how to get started working on pg_idkit locally.

Prerequisites

To work on pg_idkit, you'll need the following:

• Rust toolchain (rustup)
• pgx and it's toolchain (the rust subcommand)
• (optional) Docker
• (optional) cargo-watch

Setting up local environment

Assuming you are using something like direnv, use the following .envrc file:

# Use local docker auth file
export DOCKER_CONFIG=$(realpath infra/docker)

NOTE, that is not a .env file, it is a .envrc file, with separate semantics

Building the project

To build the project:

make build

To run the build continuously for quicker local development (assuming you have cargo-watch installed):

make build-watch

pgx workflow

Note that you can use the pgx-documented development flow as well (using cargo pgx) as well, for example:

cargo pgx run pg14

Run tests

To run the tests:

make test

To run tests continuously for quicker local development (requires cargo-watch):

make build-test-watch

Starting a local Postgres instance with pg_idkit installed

Assuming you have Docker installed, to start a local Postgres instance first you must build a postgres docker image with pg_idkit:

make image

Then start the container:

make db-local

You may attach to the local DB with psql and execute commands:

make db-local-psql

Continuous Integration

To push up images that are used from continuous integration:

1. Get a personal access token from Github
2. Ensuring DOCKER_LOGIN is set (see instructions above), perform a login (echo $GH_PAT | docker login ghcr.io -u <username> --password-stdin)
3. Observe the docker login credentials generated in this local repo directory (infra/docker/config.json)
4. Run make build-ci-image push-ci-image