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-pg18:

target/release/pg_idkit-pg18
├── home
│   └── <user>
│       └── .pgrx
│           └── 18.0
│               └── pgrx-install
│                   ├── lib
│                   │   └── postgresql
│                   │       └── pg_idkit.so
│                   └── share
│                       └── postgresql
│                           └── extension
│                               ├── pg_idkit--0.4.0.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/18.0/pgrx-install/lib/postgresql/pg_idkit.so
• target/release/home/<user>/.pgrx/18.0/pgrx-install/share/postgresql/extension/pg_idkit--0.4.0.sql
• target/release/home/<user>/.pgrx/18.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.

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

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.4.0-pg18.0-alpine3.22.2-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 (18.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

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.4.0-pg18.x86_64.rpm, you should be able to run:

dnf install pg_idkit-0.4.0-pg18.x86_64.rpm