Crucible PostgreSQL Walkthrough

This walkthrough provisions three synchronized PostgreSQL 16 containers, sends production-like reads through one stable Eve interlay, inspects request-level evidence, selects the fastest contender, and proves the same interlay address now routes only to that endpoint.

The walkthrough exercises one released adapter in depth. PostgreSQL is not a dependency of the generic Crucible control plane; MySQL, MongoDB, Redis, and LLM adapters register through the same runtime contract.

Prerequisites

• Docker.
• psql.
• A local Eden service built with endpoint-comparison,postgres or a production runtime bundle.
• An administrator bearer token in EDEN_TOKEN.
• Optional pgbench for the performance gate.

Start Eden

Use the normal local Eden startup path with a database and analytics configuration. Confirm that /api/v1/endpoint-comparisons/arenas is reachable before running the script.

Run The Walkthrough

cd local-demo/endpoint-comparison
export EDEN_BASE_URL=http://127.0.0.1:8000
export EDEN_TOKEN=...
python3 run_demo.py --duration 30

Use --duration 0 to continue until Ctrl-C. Use --no-complete to leave the run active for dashboard inspection.

What The Script Does

1. Starts three PostgreSQL containers and seeds identical synthetic claims data.
2. Adds controlled server delays so equivalent results have distinct performance profiles.
3. Registers all three databases as normal Eden endpoints.
4. Creates and starts one stable PostgreSQL interlay.
5. Creates a homogeneous Crucible arena and starts an indefinite run.
6. Sends repeated reads through the interlay, never directly to contenders.
7. Writes the arena, run, summary, request drill-down, and selected endpoint to artifacts/.
8. Calls completion preflight with warning acknowledgement.
9. Completes the run with the fastest successful p95 contender.
10. Verifies the unchanged interlay now names the selected endpoint and still accepts the same query.

Inspect The Evidence

Review:

• artifacts/arena.json
• artifacts/run_started.json
• artifacts/summary.json
• artifacts/request_comparisons.json
• artifacts/selected_endpoint.json
• artifacts/completion_preflight.json
• artifacts/run_completed.json
• artifacts/final_interlay.json

Request artifacts contain safe identifiers, timings, counts, statuses, and keyed digests. They do not contain SQL or returned claims data.

Run The Serving-Path Gate

python3 run_demo.py --performance-gate --benchmark-seconds 30

The script runs matched pgbench workloads before and after attaching Crucible. It fails if added p99 exceeds 25 microseconds or throughput loss exceeds 1 percent and writes the benchmark evidence under artifacts/.

Cleanup

docker compose down -v

The identical seed represents external data readiness. Crucible itself does not synchronize the databases.

Run The Protocol Matrix

The companion local-demo/endpoint-comparison-protocol-matrix harness starts two PostgreSQL, MySQL, MongoDB, and Redis backends plus two fake OpenAI-compatible providers. It creates real Eden endpoints, interlays, arenas, and runs for every released adapter and validates promptless per-target evidence.

python3 local-demo/endpoint-comparison-protocol-matrix/run_matrix.py --protocol all