[Samuel Hassine (SamuelHassine)]

Proposed changes

• OpenAEV and XTM One share one pgsql service on pgvector/pgvector:pg17, with one database each (openaev, xtm_one). The pgsql-xtm-one service and its volume are gone.
• New one-shot xtm-one-db-init service, same pattern as opencrq-db-init in feat(compose): add OpenCRQ to the XTM stack (#49) #50. On every start it:
  • refuses an XTM_ONE_POSTGRES_USER equal to POSTGRES_USER before psql runs: the init would otherwise reset the superuser's password, or leave XTM One running as a superuser;
  • creates the XTM_ONE_POSTGRES_USER role, which is no longer a superuser, and keeps its password in sync with .env;
  • creates the xtm_one database, owned by that role;
  • creates the vector extension in it. pgvector is not a trusted extension, so only a superuser can create it, and XTM One's own CREATE EXTENSION IF NOT EXISTS vector then finds it already there.
  • xtm-one waits for it (service_completed_successfully).
• pgsql changes:
  • It runs with max_connections=200, the value XTM One's own compose file uses. OpenAEV (Hikari, 20) and XTM One (up to 35 per process with its tracing pool, over 2 web workers and the worker) go past the default of 100.
  • Its healthcheck goes over TCP (pg_isready -h localhost). On a new volume, the temporary server that initialises it listens on the Unix socket only, so the socket check could report healthy before any TCP client can connect.
• The data lives on a new pgsqlshareddata volume (see Further comments).
• README:
  • PostgreSQL + pgvector moves into "Shared Infrastructure" in the overview and the diagram, and the "Dedicated databases" group is removed.
  • A new "Upgrade from separate PostgreSQL instances" section gives the dump and restore procedure. It also covers a deployment that already started the new version: removing the new volume deletes what the platforms wrote since, so it says to dump it first.
• .env.sample: comments for POSTGRES_USER and XTM_ONE_POSTGRES_USER. No variable is added, renamed or removed.

Related issues

• Closes chore(compose): share one pgvector PostgreSQL instance between OpenAEV and XTM One #51
• Related feat(compose): add OpenCRQ to the XTM stack (#49) #50 (OpenCRQ also uses the shared pgsql)

How to test this PR

1. docker compose -f docker-compose.yml --env-file .env.sample config -q passes, and config --services lists 29 services, as on main (one removed, one added).
2. Fresh install: docker compose up -d. xtm-one-db-init exits 0, xtm-one turns healthy, and OpenAEV starts on the openaev database.
3. Run docker compose up -d again: xtm-one-db-init replays without error.
4. Upgrade: from a deployment on main, follow the README section, then check that OpenAEV and XTM One show their data.

Already checked locally (Docker 29.8.2, Compose 5.5.1), under throwaway project names, all removed afterwards:

• Fresh volume:
  • xtm-one-db-init exits 0 on the first run and on a re-run.
  • xtmone can log in but is not a superuser, and owns xtm_one.
  • vector 0.8.6 exists in xtm_one only, and max_connections reads 200.
  • Over TCP, xtmone can create and query a vector(3) table, but gets permission denied for schema public in openaev.
  • With XTM_ONE_POSTGRES_USER equal to POSTGRES_USER, xtm-one-db-init exits 1 with its message, the superuser still logs in with its own password, and no xtm_one database is created.
• xtmone/platform:latest on the shared instance, with Redis and Silo:
  • It turns healthy and logs "pgvector extension ensured", "Fresh database - stamped Alembic migration head" and "Database migrations applied".
  • Its pool check reads "75 estimated max connections (PostgreSQL max_connections=200, usable=197)".
  • 127 tables, all owned by xtmone. No error-level log line, and no permission error.
  • OpenAEV itself was not started, since its connection settings are unchanged.
• Upgrade, with the README commands verbatim (Git Bash):
  • Started from main's pgsql and pgsql-xtm-one with sample data: 500 rows behind unique text indexes in openaev, 200 rows behind an HNSW index plus alembic_version in xtm_one.
  • Dumped, down, switched to this branch, ran xtm-one-db-init, then restored. Both pg_restore runs exit 0 with no errors.
  • Row counts and table owners (openaev, xtmone) are preserved, a nearest-neighbour query returns the expected row, and xtmone can insert.
  • The two old volumes are untouched, and the README's docker volume rm removes them.

Checklist

• The PR title follows the Conventional Commits convention type(scope?): description (#issue)
• I signed my commits
• This PR is linked to an issue
• I consider the submitted work as finished
• I tested the code for its functionality
• I added/updated the relevant documentation
• Where necessary, I refactored code to improve the overall quality

Further comments

• Why a new volume rather than reusing pgsqldata. That volume was initialised by the Alpine image, which uses musl, while the pgvector image is Debian, which uses glibc. With the en_US.utf8 collation the two sort text differently, so text indexes built under musl would be silently wrong under glibc. PostgreSQL records no collation version for musl, so nothing would warn. A dump and restore rebuilds every index. A fresh volume also means that skipping the procedure leaves the old data intact instead of half-migrated. This is why the title carries !.
• feat(compose): add OpenCRQ to the XTM stack (#49) #50 (OpenCRQ) is stacked on this PR, so the two no longer overlap:
  • This branch was merged into feat(compose): add OpenCRQ to the XTM stack (#49) #50's, and feat(compose): add OpenCRQ to the XTM stack (#49) #50's base is now chore/shared-postgres-51, so its diff holds only OpenCRQ.
  • On the shared instance, OpenCRQ gets its own role and database. opencrq-db-init runs on the same pgvector image, and refuses a role name equal to POSTGRES_USER or XTM_ONE_POSTGRES_USER.
  • Its roughly 50 peak connections still fit under 200 alongside OpenAEV and XTM One.
  • Merge this PR first. GitHub moves feat(compose): add OpenCRQ to the XTM stack (#49) #50's base back to main when this branch is deleted, and merging main into feat(compose): add OpenCRQ to the XTM stack (#49) #50 then leaves its diff to OpenCRQ alone.
• Renovate PR [docker] Update postgres Docker tag to v18 - autoclosed #14 (postgres 18) no longer applies to this file once this merges, since postgres:17-alpine is gone.

[Copilot]

Copilot review overview

🟡 Changes recommended

Matching database usernames can overwrite shared administrator credentials and leave XTM One running as a superuser.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Reject equal PostgreSQL usernames to prevent shared superuser overwrite · New
• Warn before deleting volumes containing post-upgrade application data · New

What changed in this PR

Consolidates OpenAEV and XTM One onto one PostgreSQL + pgvector instance with separate databases.

Changes:

• Adds XTM One database initialization and shared connection settings.
• Uses a new shared volume and documents migration.
• Clarifies PostgreSQL role credentials.

File	Description
README.md	Updates architecture and adds upgrade instructions.
docker-compose.yml	Shares PostgreSQL and adds database initialization.
.env.sample	Clarifies role credentials in comments.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The breaking database migration needs human validation with a live OpenAEV deployment, which the reported testing did not cover.

Review effort: Balanced
Findings: None

Resolved since last review (2)

• Reject equal PostgreSQL usernames to prevent shared superuser overwrite
• Warn before deleting volumes containing post-upgrade application data

[Samuel Hassine (SamuelHassine)]

Live validation of the upgrade with the real openaev/platform:latest image (version 3.261005.0), done after the merge, under a throwaway project:

• Started on main before this PR, with OpenAEV on postgres:17-alpine: it applied 453 migrations (176 tables), and a tag was created through its API.
• Followed the README section verbatim: dump, down, switch to this version, docker compose run --rm xtm-one-db-init, restore, up -d. Both pg_restore runs exit 0.
• On the shared pgvector/pgvector:pg17 instance, OpenAEV turned healthy in 40 s:
  • same migration history (453, none failed), tables (176), users and tags as before;
  • the tag read back through the API;
  • no error line in its log.

Not from this PR, but found on the way: with the current OpenAEV image, /actuator/health/ping answers 401. So on main, openaev stays unhealthy and the collectors and injectors that wait for it never start. #40 fixes it with /api/health?health_access_key=..., which the test above used in an override.