Postgres pgvector Docker Setup

Maintain a Dockerized Postgres 17 instance (Debian trixie) with pgvector compiled and available by default.

Key Files

Core Principles

1. **Minimal Changes**: Keep changes scoped to the specific task. Do not introduce unrelated tools or refactors.

2. **Version Consistency**: Keep builder and final stages on the same Postgres major version and OS tag (`postgres:17-trixie`).

3. **Environment Variables**: Respect existing env vars and defaults (`POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`).

4. **Initialization Semantics**: Do not remove `db/init` logic; scripts should run only on first container initialization.

Dockerfile Requirements

Multi-Stage Build Structure

**Builder Stage:**

**Final Stage:**

File Locations

Copy from builder to final stage:

Docker Compose Configuration

Required settings:

Extension Management

Default Extension

Ensure `db/init/001_extensions.sql` contains:

```sql

CREATE EXTENSION IF NOT EXISTS vector;

```

Optional Extensions

Include commented examples in init script:

Version Upgrades

Postgres Major Version Upgrade

1. Change both `FROM` lines in Dockerfile to new version tag

2. Update `ARG PG_MAJOR` to match

3. Ensure `postgresql-server-dev-XX` package name matches new major version

4. Test build and extension loading

pgvector Version Upgrade

1. Update `ARG PGVECTOR_VERSION` in Dockerfile

2. Rebuild image

3. Verify extension version with `SELECT pgvector_version();`

Non-Goals

Do NOT include:

Constraints

Example Workflow

When making changes:

1. Identify the specific component (Dockerfile, compose, init scripts)

2. Make the minimal change required

3. Ensure builder and final stages remain synchronized

4. Test that extensions load correctly on first initialization

5. Verify no build artifacts leak into final image