Sequence · XB Field Notes

Postgres sequences hand out numbers with a cache

Mon, 02 Aug 2027 00:00:00 +0000

A PostgreSQL sequence cache reserves values for a database backend, not for an application object or one transaction. The distinction explains why the sequence’s stored state can run ahead of values actually returned, why reconnecting can create holes, and why making CACHE smaller cannot make identifiers gapless. Start by separating allocation state from the rows the application successfully committed.

Three different numbers

For a new ascending sequence with CACHE 5, its first nextval can return one while last_value already records five. The latter is the reservation boundary, not a count of inserted rows. Currval reports the value most recently established for that sequence in this session; another connection’s allocations do not replace it. Comparing these fields without naming their scope produces misleading monitoring.

The following calls in that backend can use its reserved values. PostgreSQL’s implementation has a backend-local fast path and separate buffer locking when refilling; it is inaccurate to describe every nextval as taking an ordinary table row lock. Caching reduces repeated sequence-state access, but that is not evidence that sequence contention dominates a particular application’s insert latency. Measure before changing the cache.

Session lifetime matters

Unused reservations are abandoned when the session ends, even after a clean exit. A service that frequently opens new database sessions can therefore waste more reservations than a long-lived pool using the same allocation rate. The cache belongs to the server session, so an application-level connection abstraction does not tell you how long that cache survives.

Different sessions can hold different ranges. One can return one, another six, and the first then two. This is allocation interleaving, not a promise about commit order or evidence that those values were lost. Even CACHE 1 cannot impose commit order: transactions can obtain numbers and finish in the opposite order. A timestamp recorded before commit does not repair that ordering guarantee either.

When it breaks

Do not use CACHE as a maximum crash-gap formula. Multiple sessions can hold reservations, and the implementation also logs sequence progress ahead of individual returned values. Rollbacks, conflict-handled inserts, and unused allocations produce additional holes. A gap alone proves neither data loss nor the absence of data loss; reconcile committed business records and recovery evidence before dismissing an incident.

During normal operation, noncycling allocation provides distinct values when administrators do not reset the allocator into an already used range. CYCLE, manual resets, and explicit imported identifiers change that premise. A table still needs its primary key or uniqueness constraint. Reducing the cache cannot replace that integrity rule, recover deleted rows, or make a business numbering process auditable. Before exposing an allocation durably outside the database, commit its transaction; a crash can leave uncommitted sequence changes uncertain.

Changing sequence settings also requires attention to live sessions that already hold values. Do not reset an active sequence to a table maximum in an attempt to close holes. If a business requires contiguous issued numbers, define issuance, rollback, cancellation, and external publication separately, then evaluate a transactional counter. There is no universal cache size or performance gain to prescribe without a measured workload.

Returned two and never-returned four/five are distinct gap sources. Exact historical shell evidence covers sequential standalone backends only, not crash gaps or concurrency.

Check it quickly

This socket-free exercise uses two successive single-user backends against one newly initialized, disposable cluster. Run the shell script as a non-root account with PostgreSQL 18 initdb and postgres in PATH. Never point single-user mode at a live cluster. It grants implicit superuser powers and cannot test concurrent clients, realistic interprocess locking, or failover.

#!/bin/sh
set -eu
umask 077
export LC_ALL=C
lab=$(mktemp -d "${TMPDIR:-/tmp}/xbcatm-sequence-cache.XXXXXX")
initdb -D "$lab/data" --no-locale --encoding=UTF8 \
 --auth-local=trust --auth-host=reject >"$lab/init.log" 2>&1
postgres --single -j -D "$lab/data" -c io_method=sync -c log_min_messages=notice postgres \
 >"$lab/session-a.log" 2>&1 <<'SQL'
CREATE SEQUENCE cache_probe CACHE 5;

SELECT nextval('cache_probe') AS first_value;

SELECT last_value AS reserved_through FROM cache_probe;

BEGIN;

SELECT nextval('cache_probe') AS rolled_back_value;

ROLLBACK;

SELECT nextval('cache_probe') AS after_rollback;

DO $$ BEGIN
 IF currval('cache_probe') <> 3 OR
 (SELECT last_value FROM cache_probe) <> 5 THEN
 RAISE EXCEPTION 'cache reservation or rollback result wrong';
 END IF;
 RAISE NOTICE 'cache_probe_a_ok';
END $$;

SQL
if grep -E '(ERROR|FATAL|PANIC):' "$lab/session-a.log"; then exit 1; fi
grep -q 'cache_probe_a_ok' "$lab/session-a.log"
postgres --single -j -D "$lab/data" -c io_method=sync -c log_min_messages=notice postgres \
 >"$lab/session-b.log" 2>&1 <<'SQL'
SELECT nextval('cache_probe') AS after_clean_session_end;

DO $$ BEGIN
 IF currval('cache_probe') <> 6 OR
 (SELECT last_value FROM cache_probe) <> 10 THEN
 RAISE EXCEPTION 'unused cache values were unexpectedly reused';
 END IF;
 RAISE NOTICE 'cache_probe_b_ok';
END $$;

DROP SEQUENCE cache_probe;

SQL
if grep -E '(ERROR|FATAL|PANIC):' "$lab/session-b.log"; then exit 1; fi
grep -q 'cache_probe_b_ok' "$lab/session-b.log"
cat "$lab/session-a.log" "$lab/session-b.log"
printf 'retained_lab %s\n' "$lab"

Retained exact-script records and raw logs report a PostgreSQL 18.6 pass; this source review did not rerun the script. The first backend returned one, recorded reservation five, allocated two inside a transaction that rolled back, and then returned three. Its assertion checks that the cache boundary remains five. Blank lines delimit commands in single-user -j mode, preserving the intended transaction boundaries rather than sending the entire example as one command.

After that backend exited cleanly, the second returned six and recorded reservation ten. Four and five were never returned; two was returned but belonged to a rolled-back transaction. These are distinct gap sources demonstrated without a crash. Both success notices appeared, and the sequence was dropped. The printed directory retains the disposable cluster and logs for inspection; it is not automatic filesystem cleanup. Failures can leave the same artifacts.

The script checks error text as well as process status because a standalone backend can report SQL errors without a failing exit code. This is a reservation-lifecycle test, not a throughput benchmark or durability drill. It supplies no evidence for a fixed crash-gap bound or a recommended production cache size.

Sources

PostgreSQL CREATE SEQUENCE, per-session reservations, ordering, and unused values, checked 2026-10-15.
PostgreSQL sequence functions, rollback, session values, and integrity boundaries, checked 2026-10-15.
PostgreSQL 18 sequence implementation, backend-local allocation and advance WAL logging, checked 2026-10-15.
PostgreSQL standalone server, single-user command boundaries and limitations, checked 2026-10-15.

A sequence allocates numbers independently of rollback

Mon, 12 Apr 2027 00:00:00 +0000

A PostgreSQL sequence allocates numbers independently of whether the caller’s transaction eventually commits. That makes ordinary identifier generation practical under concurrency, but it also makes gaps normal. A sequence number describes an allocation; it does not prove that a row exists, that a transaction committed, or that every smaller number has been used.

Atomic allocation, with conditions

Nextval advances a sequence atomically. Concurrent callers using an ordinary noncycling sequence receive distinct allocations as long as nobody resets it into an already used range. This is not a promise of lock-free implementation or immunity from every administrative operation. CYCLE and explicit resets can reuse values, so the table’s PRIMARY KEY or UNIQUE constraint remains responsible for stored-row uniqueness.

A sequence also has finite bounds. A noncycling sequence raises an error when it cannot allocate another value within those bounds; it does not silently grow into an unlimited integer. Choose the underlying type and increment deliberately, and monitor remaining capacity when a heavily used identifier approaches its configured limit. A wider sequence does not widen a narrower destination column automatically.

Identity and serial columns use sequences to provide default values. The sequence is an allocator, while the column’s constraints define which rows are allowed. Explicitly imported identifiers can leave the allocator behind the table’s data. Repairing that mismatch requires accounting for active writers and reserved values, not merely issuing a live setval based on an uncoordinated maximum.

Gaps and order are different properties

Nextval allocations are not reclaimed on transaction rollback. An unused allocation, an aborted insert, or an INSERT that takes an ON CONFLICT branch can therefore leave a gap. Deleting a row also does not wind its sequence backward. Missing numbers alone are not evidence of lost records or a damaged sequence.

CACHE reserves batches for individual sessions. If one session reserves 1 through 10 and another reserves 11 through 20, observed calls can return 1, then 11, then 2. Ending a session can abandon its unused reservations. Caching improves allocation efficiency, but increasing it trades against continuity and globally ordered observation; even without caching, allocation order is not transaction commit order.

Setval changes sequence state without being undone by a caller’s rollback. Do not generalize that rule to every sequence command: ALTER SEQUENCE RESTART is transactional and blocks concurrent allocation until its transaction ends. Other sessions may also still hold previously cached values, so resetting an active allocator is not a safe gap-removal operation. If uninterrupted business numbering is required, design transactional allocation and cancellation semantics explicitly. That may serialize access to a dedicated counter; it does not inherently require locking every row in the business table.

When it breaks

Currval holds a named sequence’s session-local value, normally established by nextval. Calling it before the session has established a value raises an error; setval with is_called true also changes this session value. Another connection’s activity does not initialize it for you. A connection pool can therefore make a nextval-then-currval workflow fail if the calls run on different database sessions.

INSERT RETURNING is usually clearer when the application needs the identifier attached to the row it just inserted. Lastval is broader than currval because it refers to whichever sequence was used most recently in the session, which can be surprising around triggers. Neither function is a general query for the table’s newest committed row.

Publishing an allocated number outside the database before its transaction commits is another boundary to consider. A crash can leave an uncommitted sequence change uncertain after recovery. The sequence documentation therefore requires committing the allocation before relying on it for persistent external purposes; an allocation alone is not a durable business event.

Rollback does not reclaim a nextval allocation. A reset can reissue a value; the table constraint still protects stored-row uniqueness. Historical SQL adaptation does not validate the full client invocation.

Check it quickly

Save this as sequence.sql and run psql -X -v ON_ERROR_STOP=1 -f sequence.sql in a disposable PostgreSQL 18 database. Keep normal autocommit outside the explicit transaction. Use a fresh session with temporary-object privileges. All objects are temporary; the deliberate reset is confined to this session’s test sequence.

\set ON_ERROR_STOP on
CREATE TEMP SEQUENCE ids;
CREATE TEMP TABLE allocated (stage text,id bigint);
DO $$ BEGIN
 PERFORM currval('ids');
 RAISE EXCEPTION 'currval was defined before nextval';
EXCEPTION WHEN object_not_in_prerequisite_state THEN
 RAISE NOTICE 'currval is undefined in this session before nextval';
END $$;
INSERT INTO allocated VALUES ('first',nextval('ids')) RETURNING *;
BEGIN;
SELECT nextval('ids') AS allocation_in_aborted_transaction;
ROLLBACK;
INSERT INTO allocated VALUES ('after rollback',nextval('ids')) RETURNING *;
SELECT currval('ids') AS session_value;
DO $$ BEGIN
 IF (SELECT array_agg(id ORDER BY id) FROM allocated) IS DISTINCT FROM ARRAY[1,3]::bigint[] THEN
 RAISE EXCEPTION 'rollback unexpectedly reclaimed a value';
 END IF;
END $$;
CREATE TEMP TABLE unique_rows (id bigint PRIMARY KEY);
INSERT INTO unique_rows SELECT id FROM allocated;
SELECT setval('ids',1,false);
DO $$ BEGIN
 INSERT INTO unique_rows VALUES (nextval('ids'));
 RAISE EXCEPTION 'duplicate identifier accepted';
EXCEPTION WHEN unique_violation THEN
 RAISE NOTICE 'the primary key rejected the reset sequence value';
END $$;
SELECT currval('ids') AS reissued_value;
DROP TABLE unique_rows,allocated;
DROP SEQUENCE ids;

Retained PostgreSQL 18.6 standalone SQL logs show initial currval rejected, then allocations one, two inside the aborted transaction, and three. This review did not rerun it. The adaptation omitted the psql directive and added command-delimiting blank lines; the full client invocation was not tested. The stored allocation list was therefore one and three, proving that rollback did not reclaim two. Currval reported three for this session.

The final reset requested that the next call return one again. The sequence did so, and the primary key rejected that duplicate while currval recorded the reissued value. This distinguishes safe ordinary allocation from table integrity under resets. The script removes its temporary objects; it neither renumbers existing application rows nor proposes repairing production gaps.

Sources

PostgreSQL sequence functions, atomic allocation, session values, rollback, and external durability, checked 2026-10-15.
PostgreSQL CREATE SEQUENCE, bounds, cycling, caching, and allocation order, checked 2026-10-15.
PostgreSQL ALTER SEQUENCE, transactional RESTART behavior, checked 2026-10-15.