PostgreSQL 17 with pgvector on Alpine Linux

A lightweight Docker image providing PostgreSQL 17 with the pgvector extension on Alpine Linux. This image is ideal for applications requiring vector similarity search capabilities alongside traditional relational database features.

Overview

This Docker image packages PostgreSQL 17 with the pgvector extension, enabling efficient vector operations and similarity searches directly within your database. Built on Alpine Linux for minimal footprint and fast startup times.

Key Features:

• PostgreSQL 17 with pgvector extension pre-installed
• Alpine Linux base for minimal image size
• Pre-configured for external connections
• Optimized for vector similarity search operations
• Ready-to-use with sensible defaults

Quick Start

Pull Pre-built Image

docker pull ghcr.io/your-username/postgres17-pgvector:latest

Run Container

docker run -d \
  --name postgres-vector \
  -e POSTGRES_PASSWORD=yourpassword \
  -p 5432:5432 \
  ghcr.io/your-username/postgres17-pgvector:latest

Build Locally

git clone <your-repo-url>
cd postgres17-pgvector
docker build -t postgres17-pgvector .

Usage

Basic Usage

docker run -d \
  --name my-postgres \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=myapp \
  -e POSTGRES_USER=myuser \
  -p 5432:5432 \
  postgres17-pgvector

With Persistent Storage

docker run -d \
  --name my-postgres \
  -e POSTGRES_PASSWORD=secret \
  -p 5432:5432 \
  -v postgres_data:/var/lib/postgresql/data \
  postgres17-pgvector

Using Docker Compose

version: '3.8'
services:
  postgres:
    image: postgres17-pgvector
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: myapp
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Configuration

Environment Variables

• POSTGRES_PASSWORD - Required: Password for the PostgreSQL superuser
• POSTGRES_USER - Optional: PostgreSQL superuser (default: postgres)
• POSTGRES_DB - Optional: Default database (default: same as POSTGRES_USER)

Default Configuration

• Listens on all interfaces (listen_addresses = '*')
• Accepts connections from any host with password authentication
• Unix socket directory: /var/lib/postgresql
• Encoding: UTF8
• Locale: C

Using pgvector Extension

Once your container is running, enable the pgvector extension in your database:

-- Connect to your database
psql -h localhost -U postgres -d your_database

-- Enable the vector extension
CREATE EXTENSION vector;

-- Create a table with a vector column
CREATE TABLE items (
    id BIGSERIAL PRIMARY KEY,
    embedding VECTOR(1536)
);

-- Insert vectors
INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]');

-- Perform similarity search
SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;

Vector Operations Examples

Basic Vector Operations

-- Euclidean distance (L2)
SELECT * FROM items ORDER BY embedding <-> '[1,2,3]' LIMIT 10;

-- Inner product
SELECT * FROM items ORDER BY embedding <#> '[1,2,3]' LIMIT 10;

-- Cosine distance
SELECT * FROM items ORDER BY embedding <=> '[1,2,3]' LIMIT 10;

Indexing for Performance

-- Create HNSW index for faster similarity search
CREATE INDEX ON items USING hnsw (embedding vector_l2_ops);

-- Or IVFFlat index
CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100);

Management

Access the Database

# Connect from host
psql -h localhost -U postgres

# Connect from within container
docker exec -it postgres-vector psql -U postgres

View Logs

docker logs postgres-vector

Backup and Restore

# Backup
docker exec postgres-vector pg_dump -U postgres mydb > backup.sql

# Restore
cat backup.sql | docker exec -i postgres-vector psql -U postgres

Technical Details

Image Contents

• PostgreSQL 17: Latest stable PostgreSQL version
• pgvector: Official Alpine package for vector operations
• Alpine Linux: Lightweight base image from edge repository
• su-exec: For proper process privilege handling

Ports

• 5432: PostgreSQL default port

Volumes

• /var/lib/postgresql/data: PostgreSQL data directory

Development

Building from Source

git clone <repository>
cd postgres17-pgvector
docker build -t postgres17-pgvector .

Testing

# Test basic functionality
docker run --rm -e POSTGRES_PASSWORD=test postgres17-pgvector pg_isready -U postgres

# Test pgvector extension
docker run --rm -e POSTGRES_PASSWORD=test postgres17-pgvector psql -U postgres -c "CREATE EXTENSION vector;"

Troubleshooting

Common Issues

Connection refused:

• Ensure PostgreSQL has fully started (wait 5-10 seconds after container start)
• Check if port 5432 is available on the host

Authentication failed:

• Verify POSTGRES_PASSWORD environment variable is set
• Check pg_hba.conf configuration

Extension not found:

• Confirm you're using the correct database
• Check if pgvector package installed correctly

License

[Add your license information here]

Contributing

[Add contribution guidelines here]

Support

• PostgreSQL Documentation
• pgvector GitHub
• Docker PostgreSQL Image

---

Note: This image uses Alpine Edge repository which may contain less stable packages. For production use, consider using a tagged Alpine version or the official PostgreSQL image with pgvector added.