Database¶
With FASTMOCK_STORAGE=postgres (the default) FastMock keeps its durable data in PostgreSQL and short-lived shared
state in Valkey. This page covers how the schema is migrated, which server versions are supported and how to
upgrade PostgreSQL to a new major version. Connection settings and TLS are in
Configuration and Security.
- What is stored where
- How migrations run
- Running migrations separately
- Writing migrations
- Supported versions
- PostgreSQL major upgrades
What is stored where¶
| Store | Table or keys | Content |
|---|---|---|
| PostgreSQL | fm_stubs, fm_revision |
Stubs and the revision counter that tells replicas to reload them. |
| PostgreSQL | fm_data |
Body files, settings, gRPC descriptors, async mocks, the service catalog, specifications and contract-test runs. |
| PostgreSQL | fm_journal |
Request journal (kept for FASTMOCK_JOURNAL_RETENTION). |
| PostgreSQL | fm_outbox |
Callbacks waiting for delivery and their results. |
| PostgreSQL | fm_audit |
Audit log of admin actions. |
| PostgreSQL | _sqlx_migrations |
Applied migrations: version, description, checksum, success. |
| Valkey | keys under FASTMOCK_VALKEY_PREFIX |
Scenario states, counters, delayed deliveries and caches. |
How migrations run¶
Migrations are SQL files compiled into the binary (crates/fastmock-store/migrations). With
FASTMOCK_DATABASE_MIGRATE=auto (the default) every replica applies them at start-up, before it opens its ports:
- It takes a PostgreSQL session advisory lock (
pg_advisory_lock, the key is derived from the database name), so when several replicas start together only one migrates; the others wait for the lock and then find nothing to do. - It reads
_sqlx_migrations. A migration recorded as failed stops start-up; so does an applied migration whose checksum differs from the file in the binary (an edited migration). - It applies each pending migration in its own transaction together with its
_sqlx_migrationsrow, so a failed migration leaves nothing behind. - It releases the lock. If the process dies, PostgreSQL releases the lock with the session.
FASTMOCK_DATABASE_MIGRATION_TIMEOUT (default 120s) limits the whole step, including the wait for the lock. A
replica that runs out of time exits and is restarted; the replica holding the lock carries on. With the Helm
chart the startup probe allows two minutes by default (startupProbe.periodSeconds × .failureThreshold); raise
it together with the timeout, or run long migrations as a separate Job.
Applied migrations that the binary does not know (written by a newer FastMock) are accepted. During a rolling upgrade the first new pod migrates and the old pods keep working; an old pod that restarts, or a rollback to the previous image, starts against the newer schema. This relies on the migration policy.
In auto mode the database user needs CREATE on the schema even when nothing is pending, because the
migration table is created with create table if not exists.
Running migrations separately¶
To keep DDL rights away from the server, or to migrate once per release instead of in every pod:
- Run
fastmock migratewith the new image and a user that owns the schema. It reads only theFASTMOCK_DATABASE_*variables (URL, password, TLS settings,FASTMOCK_DATABASE_MIGRATION_TIMEOUT) and exits with status 0 once the schema is current. - Start the server with
FASTMOCK_DATABASE_MIGRATE=skip. It applies nothing and checks at start-up that every migration it needs is applied and unchanged; otherwise it stops with a message such asthe database schema is older than this FastMock version expects (version 4): migration(s) 4 (admin queries) not applied; run fastmock migrate from this version before starting it with FASTMOCK_DATABASE_MIGRATE=skip. The server user then needs onlyUSAGEon the schema andSELECT,INSERT,UPDATE,DELETEon its tables.
With the Helm chart, set storage.database.migrations.mode: job: a pre-install/pre-upgrade hook Job runs step 1
with the image of the release, optionally with the owner's credentials from
storage.database.migrations.job.existingSecret, and the pods start in skip mode
(Helm chart). Without the chart, a Job for step 1 run before the Deployment is updated (for
example as a pipeline step) looks like this:
apiVersion: batch/v1
kind: Job
metadata:
name: fastmock-migrate-1-2-3
spec:
backoffLimit: 2
template:
spec:
restartPolicy: Never
containers:
- name: migrate
image: registry.example.com/fastmock:1.2.3
args: ["migrate"]
env:
- name: FASTMOCK_DATABASE_URL
value: postgres://fastmock_owner@db.example.com:5432/fastmock
- name: FASTMOCK_DATABASE_PASSWORD
valueFrom:
secretKeyRef:
name: fastmock-db-owner
key: password
- name: FASTMOCK_DATABASE_SSL_MODE
value: verify-full
- name: FASTMOCK_DATABASE_SSL_ROOT_CERT
value: /etc/fastmock/db-ca/ca.crt
volumeMounts:
- name: db-ca
mountPath: /etc/fastmock/db-ca
readOnly: true
volumes:
- name: db-ca
secret:
secretName: fastmock-db-ca
With the Helm chart, add FASTMOCK_DATABASE_MIGRATE=skip through extraEnv; the chart does not create the Job.
Writing migrations¶
FastMock runs old and new versions side by side during a rolling upgrade, so every migration must work with the previous release still running:
- Never edit, rename or delete a migration that has been released. The checksum check stops every replica
(and
fastmock migrate) against a database where it was applied. Fix mistakes with a new migration. - Additive changes only in one release: new tables, new indexes, new nullable columns or columns with a constant default. Code must tolerate rows written by the previous release.
- Expand and contract for anything destructive. To rename or drop a column, or to tighten a constraint: add the new structure and write both (release N), switch reads (release N+1), then drop the old structure in a later release, once no supported version reads it.
- Large indexes:
create index concurrentlycannot run inside a transaction. Put it alone in its own file whose first line is-- no-transaction; sqlx then runs that file outside a transaction. Such a migration is not atomic, so useif not exists, and if it fails, drop the invalid index before running it again. - Files are named
<version>_<description>.sqlwith a new, higher version; gaps in the numbering are allowed. - Use only features of the oldest supported PostgreSQL version.
Supported versions¶
FastMock is tested with PostgreSQL 18 and Valkey 9.
PostgreSQL¶
The schema and queries need PostgreSQL 11 or later; use a major version that the PostgreSQL project still supports (see its versioning policy). The newest feature in use:
| Feature | Where | Since |
|---|---|---|
starts_with(text, text) |
journal path filter, audit action prefix filter | 11 |
generated always as identity |
fm_journal.id, fm_audit.id |
10 |
insert ... on conflict, for update skip locked, jsonb - text, create index if not exists |
stubs and data upserts, callback claiming, listing data without a field, migration 0004 |
9.5 |
LISTEN/NOTIFY, gin index on text[], partial indexes, jsonb |
stub reload, tag queries, journal and outbox indexes | 9.4 |
starts_with is the only reason for 11; every other construct works on 10. No extension is required.
Valkey and Redis¶
FastMock connects to one endpoint: a standalone server, or a managed endpoint that always points to the primary. Valkey Cluster mode is not supported. Commands used:
| Command | Purpose | Since (Redis) |
|---|---|---|
GET, SET, MGET, DEL, PING, SELECT |
key-value state, health check, database in the URL | 1.0 |
PSETEX, SET ... PX (inside a script) |
values with a time to live | 2.6 / 2.6.12 |
INCRBY, PEXPIRE (inside a script) |
counters with a time to live | 1.0 / 2.6 |
ZADD, ZRANGEBYSCORE ... LIMIT, ZREM with several members |
delayed-delivery queues | 2.4 |
EVALSHA, SCRIPT LOAD |
atomic compare-and-set, counter and queue pop (Lua) | 2.6 |
SCAN ... MATCH ... COUNT |
listing keys by prefix | 2.8 |
UNLINK |
deleting keys by prefix | 4.0 |
AUTH <user> <password> |
ACL user (FASTMOCK_VALKEY_USERNAME) |
6.0 |
TLS (rediss://) |
encrypted connections | 6.0 |
GETEX, HEXPIRE, SET ... GET, Redis Functions and modules are not used. CLIENT SETINFO (7.2) is sent by
the client library at connect time; errors from it are ignored, so it needs no ACL permission.
Minimum versions: Redis 4.0 without TLS and ACL users, Redis 6.0 with TLS or an ACL user (ACL rules also apply to the commands the Lua scripts call). Every Valkey release (7.2 and later) supports everything FastMock uses.
PostgreSQL major upgrades¶
FastMock needs nothing special for a major upgrade: no extensions, and the schema is the same on every supported version. After the upgrade FastMock starts as usual; its migrations find nothing to do.
What to carry over: stubs, body files and settings matter; the journal, callbacks and audit log are history that
you may accept to lose. Stubs and body files can also be moved through the admin API, independently of the
database: GET /__admin/export (with an editor or admin token, so credentials are not masked) and
POST /__admin/stubs/import for stubs, GET and PUT /__admin/files/{name} for body files. Settings, gRPC
descriptors, async mocks, the service catalog, the journal, callbacks and the audit log are not moved that way.
CloudNativePG (1.26 and later) upgrades a cluster in place, offline: change the major version in
imageName (or the image catalog), using an image of the same operating system family. The operator stops all
instances, runs pg_upgrade in a Job, then clones the replicas again; the database is unavailable for the whole
operation, so scale FastMock to zero first or accept failing requests. Take a backup before and a new base backup
after: the upgraded cluster has a new system identifier and point-in-time recovery does not cross the upgrade.
If the upgrade fails, setting the old image back restarts the cluster on the old version. Run ANALYZE afterwards,
because pg_upgrade does not carry planner statistics over. See the
CloudNativePG documentation.
A single PostgreSQL instance (for example the one the Helm chart can install) cannot be upgraded in place by changing the image: the data directory of one major version does not start on another. Dump and restore:
kubectl -n mocks scale deploy/fastmock --replicas=0
pg_dump -Fc -h db-old.example.com -U fastmock -d fastmock -f fastmock.dump
pg_restore -h db-new.example.com -U fastmock -d fastmock --no-owner fastmock.dump
kubectl -n mocks scale deploy/fastmock --replicas=2
Point FASTMOCK_DATABASE_URL at the new server before scaling up. Use pg_dump from the newer major version.
For test environments where history does not matter, exporting stubs and body files, starting on an empty new
database and importing them is the shorter path.