Skip to content

Latest commit

 

History

History
311 lines (246 loc) · 14.3 KB

README.md

File metadata and controls

311 lines (246 loc) · 14.3 KB
Raw

🐘 🪪 `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.20.3-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:

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