From 66c80a5da6d9c9dec067351ac54ee41ea4e48656 Mon Sep 17 00:00:00 2001 From: Aakash Kattelu Date: Wed, 5 Aug 2026 18:34:30 -0400 Subject: [PATCH] docs: document pgvector preinstall for least-privilege DB roles MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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/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..29748e2f 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 database service runs `database/init.sql` as an initdb script, which creates the extension before Honcho ever connects. 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