From ae5e9a528bb27c7878f0669632fd8d33d50a99fb Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Mon, 15 Jun 2026 16:20:54 +0200 Subject: [PATCH] docs: document 'codex migrate' + MIGRATION_DATABASE_URL as the schema-sync path README step 4 used an inline apply_schema over the app DATABASE_URL, which fails under the privilege model (least-privilege app role cannot run DDL). Replace it with 'codex migrate' and document MIGRATION_DATABASE_URL (owner/superuser) in the README env table and .env.example, so the privileged migrate path is the standard for future schema upgrades. Co-Authored-By: Claude Fable 5 --- .env.example | 6 ++++++ README.md | 15 +++++++-------- 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/.env.example b/.env.example index f7b60ed..8bd512a 100644 --- a/.env.example +++ b/.env.example @@ -5,6 +5,12 @@ # Example: postgresql://researcher:change_me@localhost:5432/papers DATABASE_URL=postgresql://researcher:change_me@localhost:5432/papers +# Optional: privileged connection used by `codex migrate` to apply schema DDL. +# The app DATABASE_URL is often a least-privilege DML role that cannot CREATE/ +# ALTER owner-held tables; point this at an owner/superuser connection. +# Falls back to DATABASE_URL when unset. +# MIGRATION_DATABASE_URL=postgresql://postgres:change_me@localhost:5432/papers + # GROBID service base URL (containerised — see infra/docker-compose.yml) GROBID_URL=http://localhost:8070 diff --git a/README.md b/README.md index a68202e..b794cd0 100644 --- a/README.md +++ b/README.md @@ -19,13 +19,11 @@ $EDITOR .env # 3. Install Python dependencies (requires uv) uv sync -# 4. Apply the database schema (first run only) -uv run python -c " -from codex.db import get_conn, apply_schema -with get_conn() as conn: - apply_schema(conn) -print('Schema applied.') -" +# 4. Apply the database schema (idempotent — safe to re-run after upgrades) +# Needs a role that can run DDL. If DATABASE_URL is a least-privilege app +# role, point MIGRATION_DATABASE_URL at an owner/superuser connection first: +# MIGRATION_DATABASE_URL=postgresql://postgres:...@host:5432/papers +uv run codex migrate ``` --- @@ -34,7 +32,8 @@ print('Schema applied.') | Variable | Default | Description | |---|---|---| -| `DATABASE_URL` | `postgresql://researcher:change_me@localhost:5432/papers` | libpq connection string | +| `DATABASE_URL` | `postgresql://researcher:change_me@localhost:5432/papers` | libpq connection string (app role; DML) | +| `MIGRATION_DATABASE_URL` | *(falls back to `DATABASE_URL`)* | Privileged connection used by `codex migrate` for schema DDL (owner/superuser) | | `GROBID_URL` | `http://localhost:8070` | GROBID HTTP API base URL | | `OLLAMA_BASE_URL` | `http://localhost:11434` | Local Ollama endpoint (optional) | | `EMBEDDING_MODEL` | `BAAI/bge-m3` | sentence-transformers model name |