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>
122 lines
7.2 KiB
Markdown
122 lines
7.2 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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.
|