Files
aevolution/docs/infrastructure/POSTGRESQL.md
T
dingoandClaude Opus 5.5 2496649a9b Complete M7.3 fenced region ownership
ADR-0060 and schema v2 add database-time region leases and a fenced head
advance. Acquire/renew/release/advance lock the lease row, check holder,
epoch and expiry with clock_timestamp() after the lock wait, and the
advance compares the exact predecessor. Holders are DB-generated tokens;
epochs never wrap or repeat. The runtime group role gets EXECUTE on five
SECURITY DEFINER functions only - no table, provisioning or CREATE rights.
Migration history admits clean->v2, v1->v2 and a v2 no-op, and refuses
privileged runtime roles.

Host side: portable LeaseAuthority fences from send-time deadlines on
CLOCK_BOOTTIME, keeps the earlier deadline on unknown renewal and stays
fenced until a newer epoch. Selected timings: 20s lease, 5s renew, 2s
margin, 2s renew and 5s commit deadlines. Linux evo::postgres wraps the
functions with typed LeaseStoreError results.

Validated: Windows CTest 55/55; WSL Release, clang-tidy and ASan/UBSan
private-PostgreSQL suites (contenders, expiry, paused/queued stale
writers, unknown renewal, exhaustion, bypass denial, upgrade path).
Three SQL mutations were each caught. Docker/Gitea CI, remote TLS and
cluster runs were not executed. No director, host or deployment added.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 11:14:32 -04:00

7.2 KiB

PostgreSQL bootstrap (M7.2) and region fencing (M7.3)

ADR-0059 pins server/libpq 18.6. evo::postgres is optional, Linux-only and separate from all simulation targets. Preparation explicitly downloads a verified source archive; ordinary CMake configure does not fetch anything. PostgreSQL license is permissive; source COPYRIGHT and system TLS license information must accompany distributed tooling. No custom hashing/cryptography is introduced.

Local isolated verification

Linux prerequisites: GCC14, CMake>=3.28, Ninja, make, bison, flex, curl, bzip2, OpenSSL development headers and zlib development headers. Optional clang19 tools support analysis/ASan. Run as a normal user, not root:

bash tools/prepare-postgres.sh
cmake --preset release -B build/postgres -DCMAKE_CXX_COMPILER=g++-14 \
  -DEVO_BUILD_POSTGRES=ON -DPostgreSQL_ROOT="$PWD/.cache/postgres/install"
cmake --build build/postgres --target evo-postgres-tests --parallel 2
bash tools/ci/postgres-check.sh "$PWD/build/postgres/evo-postgres-tests"

The test script overrides all connection coordinates and creates a new private 0700 /tmp directory, private Unix socket and disposable local cluster. It creates the evo_runtime_test group and the evo_runtime_login member, then runs fencing tests as that real runtime login. TCP is off; local trust applies only inside that private directory. Cluster stops on exit; logs/data are retained there for diagnosis. It never uses production PG credentials or deletes a pre-existing database. Do not point this script at a shared server.

Adapter contract

One connection belongs to one I/O owner; one outstanding parameterized statement. No hidden threads, pool, transaction replay or automatic reconnect. Connections and queries take 1..30000ms deadlines on a steady clock. Remote hostaddr must be numeric, host supplies TLS identity, CA file is explicit, TLS verify-full required. Local sockets require no PGHOSTADDR/PGSERVICE override. GSS negotiation is disabled. Query SQL <=16KiB, <=16 parameters of <=4KiB, response <=128 rows/16 columns/64KiB decoded values; single-row mode prevents accumulating a whole result set. A single server field is allocated by libpq before its length can be checked: this is not an arbitrary-query memory sandbox. Only trusted bounded persistence SQL is admitted. Server statement/lock timeouts default to 10s/5s; callers choose shorter I/O deadlines.

Admission config/bounds errors send nothing. SQL errors include only SQLSTATE and require caller rollback when inside a transaction. Receive bounds, network errors and deadlines close the connection and report unknown: a mutation may have committed. Resolve durable request IDs at M7.5; never treat disconnect as rollback. Allocation exceptions propagate to the host boundary; do not catch and reuse an incomplete session. No PostgreSQL diagnostic strings or connection values are logged.

Migrations and privilege boundary

tools/migrate-postgres.sh uses psql environment/service files, no URI arguments. It requires exactly server 18.6 and serializes migrations with a transaction advisory lock. It hashes each checked-in SQL file and applies everything in one transaction. The recorded history must be an exact prefix: clean->v1->v2, v1->v2, or a v2 no-op. Unknown versions, checksum changes and partial foreign schemas fail closed. There is no down migration or destructive repair. The u64 domain rejects fractional, negative and above-u64 values without signed truncation.

Use a dedicated owner/migrator login with CREATE on the database. Before migrating, operators create a NOLOGIN runtime group role and pass its name as EVO_PG_RUNTIME_ROLE. The migration refuses a role that is missing, is the owner, inherits the owner, or has superuser/CREATEROLE/CREATEDB/replication/BYPASSRLS. The runtime login is a separate member of that group only, with no database CREATE or public schema CREATE. Bootstrap revokes PUBLIC access to the schema, tables and default function execution. Operators own database/role provisioning; the migration never creates logins or passwords, and never grants superuser.

Fenced region ownership (schema v2, ADR-0060)

The runtime role has schema USAGE and EXECUTE on five SECURITY DEFINER functions: acquire_region_lease, renew_region_lease, release_region_lease, load_region_head and advance_region_head. It cannot read or write tables, create objects, call check_region_lease or provision regions. Each mutation locks the lease row and checks holder, epoch and expiry with clock_timestamp() after the lock wait. Clients never send times. Rejections: EVL01 busy, EVL02 fenced, EVL03 head mismatch, EVL04 not provisioned, EVL05 epoch/sequence exhausted, 22023 invalid arguments. evo::postgres maps them to LeaseStoreError; a timeout or broken connection is unknown.

Genesis is operator-only (owner login), never done by recovery or runtime: SELECT evolution.provision_region(world, region, frame, genesis_commit_uuid, '\x<64 hex digest>');. In schema v2 the head is an identity/digest pointer with no payload binding. Do not provision real world state before M7.4 publication.

Hosts use LeaseAuthority with LeasePolicy defaults: 20 s lease, 5 s renewal interval, 2 s safety margin, 2 s renewal deadline and 5 s commit deadline. The local deadline runs from request send time on CLOCK_BOOTTIME. If a renewal outcome is unknown, keep the earlier deadline and reconnect. Once fenced, stop admission, simulation and output, then acquire a new epoch and recover. Never resume the old epoch.

Kubernetes Secrets

Create Secret evolution-postgres-migrator in evolution-dev outside Git. Keys: pg_service.conf, pgpass, ca.crt. The service file has section [evolution-migrator] with host, numeric hostaddr, port, dbname, user, sslmode=verify-full, sslrootcert=/run/postgres/ca.crt and connect_timeout=5. pgpass uses libpq's escaped host:port:database:user:password format. Do not paste values into chat, manifests or image arguments. Configure cluster Secret RBAC and encryption at rest through the existing platform policy.

The example Job mounts the Secret read-only; the entrypoint copies pgpass into a private 0600 temporary file because libpq rejects group-readable password files. The copy is removed on exit. Use a distinct evolution-postgres-runtime Secret with a restricted login for the later region pod; never mount migrator credentials into it. Rotation requires a new connection/Job; no hot reload is claimed.

deploy/kubernetes/postgres-migration/job.yaml.example is intentionally outside the active Argo overlay: select a built immutable postgres-tools digest and verify DB target/role before adding it. Existing default-deny egress needs a specific DB and DNS allowance chosen for the actual endpoint. No live database/Secret was created and no World0 resources are touched by this bootstrap.

CI builds the postgres-tools Docker target and publishes it when Gitea variable HARBOR_POSTGRES_REPOSITORY is set (for example aevolution-postgres-tools). It uses the existing HARBOR_PROJECT and Harbor robot secrets. Pin the reported registry digest in the example Job; do not use the simulation image. See deploy/README.md. Local Unix-socket integration is qualified; remote TLS/authentication, actual Secret mounts and container execution still require environment-specific verification.