From d191c107e5250cc2ca4c6058d9ebfe26b7cfc6f8 Mon Sep 17 00:00:00 2001 From: Aakash Kattelu Date: Thu, 6 Aug 2026 10:23:43 -0400 Subject: [PATCH] docs: document pgvector preinstall for least-privilege DB roles (#984) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: document pgvector preinstall for least-privilege DB roles Honcho issues CREATE EXTENSION IF NOT EXISTS vector before migrations and again at server startup, both using the DB_CONNECTION_URI role. On deployments where that role deliberately cannot create extensions (managed Postgres, Kubernetes operators, NixOS), both statements fail with a privilege error — IF NOT EXISTS does not save you, because Postgres checks the privilege before checking for the extension. Document preinstalling pgvector as a privileged role as the supported path, and add a troubleshooting entry keyed to the exact error string. Note that docker compose is unaffected, since the bundled database service creates the extension via an initdb script. Refs #614 Co-Authored-By: Claude Opus 5 * docs: clarify why docker compose avoids the pgvector privilege error The previous wording pinned the claim entirely on database/init.sql, which only runs on first boot of an empty data volume. The load-bearing reason is that the bundled stack connects as the postgres superuser, so it can create the extension regardless of volume state. Name that first and keep init.sql as the secondary reason. Co-Authored-By: Claude Opus 5 --------- Co-authored-by: Claude Opus 5 --- docs/v3/contributing/self-hosting.mdx | 6 ++++++ docs/v3/contributing/troubleshooting.mdx | 14 ++++++++++++++ 2 files changed, 20 insertions(+) diff --git a/docs/v3/contributing/self-hosting.mdx b/docs/v3/contributing/self-hosting.mdx index b062a766..f78d2217 100644 --- a/docs/v3/contributing/self-hosting.mdx +++ b/docs/v3/contributing/self-hosting.mdx @@ -178,6 +178,12 @@ CREATE EXTENSION IF NOT EXISTS vector; \q ``` + +**Least-privilege database roles.** Honcho runs `CREATE EXTENSION IF NOT EXISTS vector` before migrations and again at startup, so if the role in `DB_CONNECTION_URI` can't create extensions, both fail with a privilege error — `IF NOT EXISTS` doesn't help, because Postgres checks the privilege first. + +Run the statement above once as a superuser (or `rds_superuser`) and the application role needs no extension privileges. See [Troubleshooting](/v3/contributing/troubleshooting) if you hit this. + + ### 4. Configure Environment Create a `.env` file with your settings: diff --git a/docs/v3/contributing/troubleshooting.mdx b/docs/v3/contributing/troubleshooting.mdx index d9b745a1..ffb73417 100644 --- a/docs/v3/contributing/troubleshooting.mdx +++ b/docs/v3/contributing/troubleshooting.mdx @@ -204,6 +204,20 @@ uv run alembic history uv run alembic upgrade head ``` +### "permission denied to create extension \"vector\"" + +**Cause:** The role in `DB_CONNECTION_URI` is not a superuser and lacks privileges to create extensions. Honcho issues `CREATE EXTENSION IF NOT EXISTS vector` both before running migrations and again at server startup, so this fails in both places. `IF NOT EXISTS` does not help — Postgres checks the privilege before checking whether the extension exists. + +**Fix:** Preinstall pgvector once with a privileged role (superuser, or `rds_superuser` on RDS) in the Honcho database: + +```sql +CREATE EXTENSION IF NOT EXISTS vector; +``` + +The `IF NOT EXISTS` calls then short-circuit and the application role needs no extension privileges. This is the supported path for deployments where the platform, not the application, owns extension management. + +You won't hit this with `docker compose` — the bundled stack connects as `postgres`, a superuser, and its database service also creates the extension from `database/init.sql` on first boot. It comes up on managed Postgres, Kubernetes operators, and other setups where you bring your own database and its role is deliberately not a superuser. + ## Cache & Redis ### Redis is optional