Skip to content

Global sequences

New feature

This feature is new and experimental. Make sure to test it before deploying to production.

The open source edition of PgDog can generate unique, BIGINT primary keys in two ways:

  1. Timestamp-based unique ID
  2. Sharded sequences

However, both methods produce gaps in the numbers, while the unique ID generates very large 64-bit numbers, which may not work with all applications, e.g., JavaScript apps that pass identifiers directly.

Global sequences are powered by Raft and are guaranteed to produce sequential integers, starting at 1, just like regular PostgreSQL sequences.

How it works

This feature requires PgDog to be connected to the control plane. Once configured, the following functions will begin to work automatically:

Function Description
pgdog.nextval(name) Return a monotonically increasing integer for the given sequence name. 
SELECT pgdog.nextval('public_users_id_seq') AS id;

 id
----
  1
(1 row)

Usage

The sequence functions can be called in any query, including INSERT, UPDATE, and DELETE statements. The sequence values can also be automatically injected into INSERT queries targeting omnisharded tables:

[rewrite]
primary_key = "rewrite_omni_global"

rewrite:
  primaryKey: rewrite_omni_global

The name of the sequence is automatically derived from the table and column names of the table targeted by the INSERT statement. For example, enabling this feature will produce the following rewrite:

INSERT INTO tenants (tenant_name) VALUES ($1)

INSERT INTO tenants (id, tenant_name) VALUES (pgdog.nextval('tenants_id_seq'), $1)

Under the hood

All sequence values are stored in the Raft log, which makes them durable, just like PostgreSQL sequences. For this reason, enabling Raft in the control plane is required for this feature to work.

Performance

Due to their distributed and durable nature, global sequences are slower to generate numbers than Unique ID and sharded sequences, and should be used for infrequent writes into tables that otherwise would not be able to support BIGINT numbers.