Setting up PostgreSQL with Apache AGE and pgvector using Docker

This guide will walk you through building and running a Docker container that includes PostgreSQL 17, Apache AGE (graph database extension), and pgvector (vector similarity search extension).

Image Metadata (Labels)

This image includes the following metadata for better identification and compliance, as specified in the Dockerfile:

• Maintainer: oopsyang@gmail.com
• Vendor: TinCan Lab
• Licenses: Apache-2.0
• Description: PostgreSQL image with pgvector and Apache AGE extensions

Prerequisites

• Docker Desktop (for Windows/macOS) or Docker Engine (for Linux) installed and running on your system.

1. Build the Docker Image

Navigate to your project directory (where the Dockerfile is located) in your terminal or command prompt, and run the following command to build the Docker image:

docker build -t postgres-age-pgvector:latest .

• This command will build an image named postgres-age-pgvector with the tag latest. The process might take a few minutes as it downloads dependencies and compiles the extensions.

2. Run the Docker Container (with Data Persistence using a Named Volume)

For robust data persistence, it is highly recommended to use a named Docker volume. This ensures your data is not lost if the container is removed or updated.

First, create a named Docker volume:

docker volume create pg_age_data

Then, run your container, mounting this named volume: Remember to change the password

docker run \
  --name postgres-custom \
  -e POSTGRES_PASSWORD=change_me \
  -d \
  -p 5432:5432 \
  -v pg_age_data:/var/lib/postgresql/data \
  postgres-age-pgvector:latest

• pg_age_data: The name of the Docker volume you created.

• -v pg_age_data:/var/lib/postgresql/data: Mounts the named volume to PostgreSQL's default data directory inside the container.

• --name postgres-custom: Assigns a readable name to your container.

• -e POSTGRES_PASSWORD=zhong: Sets the PostgreSQL superuser password to zhong. Change this to a stronger password for production!

• -d: Runs the container in detached mode (in the background).

• -p 5432:5432: Maps port 5432 of the container to port 5432 on your host machine.

• postgres-age-pgvector:latest: The name and tag of the Docker image you built.

• Automatic Initialization: The database will be automatically initialized with necessary extensions and an items table by init.sql on its first startup.

3. Verify the Setup

You can verify that PostgreSQL 17 is running with the extensions and graph by connecting to the database using psql (a PostgreSQL command-line client).

1. Connect to PostgreSQL: If you have psql installed on your host machine, run:

   psql -h localhost -p 5432 -U postgres -d postgres

   When prompted for the password, enter zhong (or whatever you set POSTGRES_PASSWORD to).

2. Check Extensions and Graph (inside psql): Once connected to psql, you can run these SQL commands:

   -- Check PostgreSQL version
   SELECT version();
   
   -- List installed extensions
   SELECT extname, extversion FROM pg_extension WHERE extname IN ('age', 'vector');

   You should see PostgreSQL 17 in the version output, age and vector in the extensions list.

Data Persistence (Revisited)

By using a named Docker volume like pg_age_data as shown above, your database data will persist even if the postgres-custom container is stopped, removed, or upgraded. This is the recommended approach for managing database data with Docker.

To inspect your Docker volumes, you can use:

docker volume ls
docker volume inspect pg_age_data

This completes the setup for PostgreSQL with Apache AGE and pgvector in Docker.