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:

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) git-crypt (for working with secrets)
• (optional) direnv
• (optional) Docker
• (optional) cargo-watch

Setting up the local environment

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

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

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

Install cargo-pgx

cargo install [email protected]
cargo pgx init --pg14 download

Building 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)
3. Perform a login
   1. Manually via echo $GH_PAT | docker login ghcr.io -u <username> --password-stdin
   2. Automatically, via make docker-login which will use the git-crypt protected credentials (you must have run git-crypt unlock first)
4. Observe the docker login credentials generated in this local repo directory (secrets/docker/config.json)
5. Run make build-ci-image push-ci-image