pgvector (Postgres + vectors)

Curated name pgvector. A drop-in PostgreSQL 18 carrying the pgvector extension, in compose mode, with seeded dev credentials and a readiness healthcheck.

What it’s for

Everything a normal Postgres does, plus a vector column type and similarity search - for storing embeddings and doing nearest-neighbour queries (semantic search, RAG, recommendations). It is a full Postgres, so it loses nothing relative to the plain postgres service; reach for it when your app needs vectors. The extension is available but not enabled by default - turn it on once:

CREATE EXTENSION IF NOT EXISTS vector;

(in a migration, or by hand on first use).

Add it

At init, or to an existing workbench:

monoceros init acme --with-services=pgvector
monoceros add-service acme pgvector

Note

acme is just a sample workbench name - it’s whatever you passed to monoceros init. Substitute your own throughout.

You can even run it alongside a plain postgres (different service names, so no collision) if you want a relational DB and a vector store side by side. A second pgvector instance works the same way with --as:

monoceros add-service acme pgvector --as=embeddings

Remove it

monoceros remove-service acme pgvector

Or delete the service’s block from acme.yml by hand and re-run monoceros apply acme - the yml is the source of truth. (Its data volume monoceros-acme-data-pgvector is removed with the workbench on monoceros remove, which backs it up first.)

The yml entry

acme.yml

services:
  - name: pgvector # host name in the container + data dir name
    image: pgvector/pgvector:pg18
    port: 5432 # in-container port (feeds `monoceros tunnel`)
    env:
      POSTGRES_USER: ${POSTGRES_USER} # values live in acme.env
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - data:/var/lib/postgresql # the service's own Docker volume
    restart: unless-stopped
    healthcheck: # workspace waits for service_healthy
      test: [CMD, pg_isready, -U, '${POSTGRES_USER}', -d, '${POSTGRES_DB}']
      interval: 10s
      timeout: 5s
      retries: 5
    connectionEnv: # → the workspace env vars below
      URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${host}:${port}/${POSTGRES_DB}
      HOST: ${host}
      PORT: ${port}
      USER: ${POSTGRES_USER}
      PASSWORD: ${POSTGRES_PASSWORD}
      DB: ${POSTGRES_DB}

The credentials are ${VAR} references; the real values live in acme.env (dev default monoceros for user, password, and database), so the yml stays shareable without baking credentials in (see Workbench configuration).

What your code sees

Monoceros injects a connection env into the workspace container, prefixed with the service name:

Variable	Value (defaults)
PGVECTOR_URL	postgresql://monoceros:monoceros@pgvector:5432/monoceros
PGVECTOR_HOST	pgvector
PGVECTOR_PORT	5432
PGVECTOR_USER	monoceros
PGVECTOR_PASSWORD	monoceros
PGVECTOR_DB	monoceros

The prefix is the service name, uppercased - so a plain postgres next to it stays POSTGRES_* while this one is PGVECTOR_*, no collision.

Tips

Tip

psql is installed in the workspace for pgvector; enable the extension and sanity-check it from the container shell:

psql "$PGVECTOR_URL" -c 'CREATE EXTENSION IF NOT EXISTS vector;'
psql "$PGVECTOR_URL" -c "SELECT '[1,2,3]'::vector;"

Note

It is regular Postgres under the hood, so any Postgres client, ORM, or migration tool works - you only add the vector column type where you need it.