Operate / Run Veefore

Database

Migrations, connection pooling, row-level security, backups, and what to restore when.

One PostgreSQL database, shared by the control plane, the gateway and the worker. PostgreSQL 14 or newer.

#Migrations

Nine migrations, applied in order, forward-only.

bashCopy
npm run migrate           # apply
npm run migrate:check     # apply to a throwaway database and verify it comes out clean

migrate:check is the CI gate. It proves every migration applies to an empty database — which is the thing that breaks when someone edits an already-applied migration instead of adding a new one.

#Pooling

iniCopy
DATABASE_POOL_MAX=20
DATABASE_STATEMENT_TIMEOUT_MS=15000

DATABASE_POOL_MAX is per process instance. Three control plane instances, two gateway instances and one worker at 20 each is 120 connections. Size PostgreSQL's max_connections for the total, and consider PgBouncer in transaction mode once you are past a handful of instances.

DATABASE_STATEMENT_TIMEOUT_MS bounds a single statement. The gateway is on the latency path for every protected action, so a query that runs away must be cut off rather than holding a connection.

#Row-level security

iniCopy
DATABASE_ENABLE_RLS=true

Turns on PostgreSQL row-level security as a second, independent isolation layer beneath the application-level tenant scoping.

See Tenant isolation.

#The embedded driver

Veefore ships PGlite, an embedded PostgreSQL, selected by PGLITE_DATA_DIR when DATABASE_URL is absent.

Use it for: isolated unit and integration tests, where a private per-process database is exactly what you want.

Do not use it for: running the stack.

Related: close() on the embedded driver is now terminal. It previously booted a fresh empty database on the next query, which made the gateway's readiness check stay green with no data behind it.

#Backups

Standard PostgreSQL practice, with one Veefore-specific consideration.

bashCopy
pg_dump --format=custom --no-owner --no-privileges veefore > veefore.dump

Point-in-time recovery is worth configuring. The audit trail is append-only in practice, so PITR gives you a consistent view of decisions as of any moment — which is the thing an investigation needs.

#Restoring

1. Restore the database.
2. Ensure the four keys match the ones in use when the backup was taken.
3. npm run migrate — bringing a restored older snapshot up to the current schema.
4. veefore audit verify — confirms the chain survived the round trip.
5. Start the processes.

Step 4 is the one people skip and it is the one that tells you whether the restore is sound.

#Retention and growth

The two tables that grow without bound are actions and audit_events, roughly proportional to protected action volume.

Audit retention is configurable, and changing it requires audit:configure_retention — step-up gated, writing a CRITICAL audit event. Shortening retention destroys evidence, so a request to "clean up old audit data" leaves a mark explaining who asked and why.

Export before you shorten:

bashCopy
veefore audit export --format csv \
  --reason "Pre-retention-change archive" --out archive.csv

The export is watermarked and hashed, so the archive is verifiable later.

#Health

/health/ready on both planes checks database reachability. A readiness probe pointed at it will pull an instance out of rotation when its database connection is gone, rather than letting it serve errors.

#Related