Glossary

Stable

A glossary of SPG99 terms: tenant, timeline, compute, soft basebackup, candidate writer, freeze, drain, and other key concepts.

Updated: March 21, 2026

Tenant — a logical container in the SPG99 catalog. It owns a set of databases and tenant credentials pg_user / pg_password.
Database — a specific PostgreSQL database inside a tenant with a lifecycle (creating, booting, ready, stopped, and so on).
Timeline — the durable history of the database state on the platform storage side.
Compute — the working PostgreSQL executor. It runs SQL and uses the local disk as a write-back cache.
Gateway — the single external PostgreSQL entry point over TLS. Applications connect here.
Control Plane — the platform management layer. It stores the catalog, starts and stops databases, manages leases, and tracks autoscaler state.
Provisioner — the component that creates and deletes compute workers in the infrastructure.
Pageserver — the bootstrap and data-history service. It serves soft basebackup and handles remote read-through.
Safekeeper — the WAL reliability service. A quorum of three nodes is typically used.
Cold start — the first Compute startup after stopped, when the database must be brought back to ready.
Soft basebackup — a thin startup image from Pageserver. Only the startup minimum stays local, while user relation pages are fetched on demand.
Thin startup image — the minimal set of files and metadata sufficient to start PostgreSQL without a full local PGDATA.
Write-back cache — the local working layer of Compute. It accelerates reads and writes, but it is not the only durable source of truth.
Writer term — the generation of the active writer. It is used for split-brain protection.
Current profile / target profile — the current and target writer profile in the autoscaler contract.
Candidate writer — a pre-prepared new writer generation for a safe handoff between profiles.
Freeze new checkouts — the mode in which Gateway stops issuing new checkouts to the old writer before cutover.
Drain — the phase where the platform waits for active load to finish before switching writers.
Pinned session — a connection that cannot be moved seamlessly by a transaction-pooling cutover because of session state.
Scale state — the autoscaler handoff stage: STEADY, PREPARING, FREEZING, DRAINING, STOPPING_OLD, STARTING_NEW, SWITCHING, COOLDOWN, FAILED.
Ready / Readiness — the state in which the database is truly ready to accept real traffic.
DSN — the PostgreSQL connection string to Gateway.
API key — the key for the Control Plane API, Console, and CLI. It is not used inside the PostgreSQL DSN.