Dockerized Postgres with pgvector

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

Key Files

Generation Rules

When generating or modifying code for this project:

1. **Keep changes minimal and scoped** to the specific task at hand

2. **Do not introduce unrelated tools or refactors** beyond what is requested

3. **Maintain version consistency**: Keep builder and final stages on the same Postgres major/OS tag (`postgres:17-trixie`)

4. **Respect existing environment variables** and defaults (`POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`)

5. **Preserve initialization semantics**: `db/init` scripts should run only on first initialization

6. **Do not ship build artifacts**: Build tools and apt caches must not be present in the final image

Dockerfile Structure

The Dockerfile must use a **multi-stage build**:

Builder Stage

Final Stage

Docker Compose Configuration

Extensions Management

Required Extension

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

```sql

CREATE EXTENSION IF NOT EXISTS vector;

```

Optional Extensions

Include commented examples for common extensions:

Version Upgrades

Upgrading Postgres

1. Update both `FROM` lines in Dockerfile to new version tag (e.g., `postgres:18-trixie`)

2. Update `ARG PG_MAJOR` to match (e.g., `18`)

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

Upgrading pgvector

Constraints

**Do not**:

Example Usage

```bash

Build the image

docker-compose build

Start the database

docker-compose up -d

Verify pgvector is available

docker-compose exec db psql -U postgres -c "CREATE EXTENSION vector;"

```