Deploying pgvector with Docker and Building a Container for RAG Applications

Deploying pgvector with Docker

pgvector is an open source PostgreSQL extension to store, index, and search vector embeddings efficiently. It provides the necessary database features to handle high-dimensional vectors directly within PostgreSQL. pgvector supports common vector operations, such as distance measurement and similarity search, using built-in SQL functions.

Deploying pgvector with Docker typically involves either pulling a prebuilt Docker image that bundles PostgreSQL with the pgvector extension, or building a custom image using a Dockerfile that compiles the extension from source. 

For retrieval-augmented generation (RAG) use cases, deploying PostgreSQL with pgvector in Docker provides a portable and reproducible environment for embedding storage and similarity search. By building a custom Docker image with the pgvector extension compiled in. Combined with OpenAI’s embedding APIs, this enables end-to-end RAG pipelines that can be spun up quickly in local or cloud environments.

This is part of a series of articles about vector database.

Benefits of using pgvector with Docker

Running pgvector in a Docker environment offers several practical advantages for development, testing, and deployment:

• Easy setup and isolation: Docker allows you to spin up a self-contained PostgreSQL instance with pgvector pre-installed, eliminating dependency issues and avoiding interference with local configurations.
• Reproducible environments: You can define your entire database setup, including pgvector, using Dockerfiles or docker-compose. This ensures consistent environments across teams and stages (dev, test, prod).
• Portability: Containerized pgvector instances can be deployed on any platform that supports Docker, enabling migration between machines or cloud providers.
• Faster testing and cleanup: Temporary containers make it easy to test new features or configurations without affecting your main database. Containers can be quickly started or removed without persistent side effects.
• Simplified CI/CD integration: Docker-based workflows are easily integrated into CI/CD pipelines, allowing automated tests against a known pgvector setup and reducing manual configuration.
• Resource control and scaling
  Containers can be tuned with resource limits and orchestrated using tools like Kubernetes, allowing better control over resource usage and scaling of vector-based services.

Tutorial #1: Installing pgvector with Docker

Let’s review the steps involved in installing pgvector on a local machine with Docker. These instructions are adapted from the pgvector documentation.

1. Pull pgvector image

To get started with pgvector using Docker, you can pull a prebuilt image that includes both PostgreSQL and the pgvector extension. However, we will build a custom Postgres image with the pgvector extension compiled in. Create a Dockerfile with:

This uses Postgres 16.4, installs build tools and server headers, compiles pgvector from source, then removes build dependencies to keep the image smaller.

Step 2: Build the Image

From the directory with the Dockerfile, build the image:

This tags the image as postgres-pgvector so you can reference it when running containers.

Step 3: Run the Container

Start Postgres with pgvector enabled and expose it on port 5432:

Use a strong password in POSTGRES_PASSWORD. The container runs detached and is reachable on localhost:5432.

Tutorial #2: Setting Up Postgres and pgvector with Docker for RAG Applications

This tutorial walks through creating a containerized PostgreSQL instance with pgvector, enabling you to store and search embeddings for retrieval-augmented generation (RAG) use cases. You’ll learn how to build a custom Docker image, connect to the database, store vector data, and run similarity queries using OpenAI-generated embeddings.

For this tutorial, we will use the Docker Image created in the previous section.

Step 1: Connect with psql

We will start with establishing a connection with Postgres database running in the Docker container (created in the previous section). Open an interactive shell inside the running container:

You’ll connect as the postgres user and will be prompted for the password you set.

Step 2: Create a Database for RAG

Create and switch to a dedicated database:

Keeping embeddings in their own database makes schema management and access control simpler.

Step 3: Enable the Extension

Install pgvector in the current database:

This adds the vector type and similarity operators.

Step 4: Basic Vector Storage and Search

Create a table with a vector column, insert sample data, and run a nearest-neighbor query:

Run the following commands:

Note: The <-> operator computes distance and orders results by similarity.

Step 5: Generate Embeddings With OpenAI

Create embeddings for your content before storing them. Example using JavaScript and text-embedding-3-small:

A typical response structure:

By default, text-embedding-3-small returns vectors of length 1536. You can reduce dimensions via the dimensions parameter if needed.

Create a table sized to your embedding length and insert:

Step 6: Retrieve the Most Relevant Documents

Embed the user’s query with the same model, then rank documents by vector distance:

Use the returned vector in your SQL:

This query orders by Euclidean distance using <-> and returns the top matches to ground your generation step.

AI Potential: Using Instaclustr for PostgreSQL and pgvector

In the dynamic landscape of artificial intelligence and machine learning, the ability to work with high-dimensional vector data is a game-changer. This is where the power of pgvector shines. When combined with the robust, enterprise-ready platform of Instaclustr for PostgreSQL, pgvector transforms your trusted relational database into a powerful engine for advanced AI applications. We make it simple to unlock sophisticated capabilities like vector similarity search directly within your existing PostgreSQL environment.

The pgvector extension is expertly designed to store and query vector embeddings—numerical representations of data like text, images, or audio. This functionality is the bedrock of modern AI, powering everything from semantic search and recommendation systems to facial recognition and anomaly detection. Instead of relying on separate, specialized vector databases, you can now perform these complex operations inside PostgreSQL. This integration streamlines your architecture, reduces operational complexity, and allows you to leverage your team’s existing PostgreSQL expertise. With pgvector, you can find the “closest” or most similar items in your dataset with incredible speed and efficiency using exact and approximate nearest neighbor searches.

Leveraging pgvector becomes even more powerful with Instaclustr’s managed PostgreSQL service. We handle the complexities of database management so you can focus on building innovative applications. Our platform is built for unwavering reliability and seamless scalability, ensuring that as your AI workloads grow, your database performance keeps pace without interruption. We provide expert, 24/7 support and proactive monitoring to guarantee your PostgreSQL instances, supercharged with pgvector, are always optimized for peak performance. With Instaclustr, you get a secure, scalable, and fully managed solution that empowers you to confidently build the next generation of AI-driven features.

For more information:

• Vector search benchmarking: Setting up embeddings, insertion, and retrieval with PostgreSQL®
• How To Improve Your LLM Accuracy and Performance With PGVector and PostgreSQL®: Introduction to Embeddings and the Role of PGVector
• pgvector: Key features, tutorial, and pros and cons [2026 guide]