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 |