pgembed: Embedded PostgreSQL for Agents

pgembed makes it easy to add a full-featured PostgreSQL database to your Python application—no server setup required. Your users simply run pip install yourapp, and PostgreSQL comes bundled automatically.

Think of it like SQLite, but with the power of PostgreSQL. Just pip install pgembed, call pgembed.get_server(...), and you're ready to go.

What pgembed gives you

• Pip-installable PostgreSQL binaries: Pre-built wheels for Linux, macOS (Apple Silicon & Intel), and Windows
• No admin rights needed: Runs without sudo or root access
• Handles edge cases: Works in Docker containers, Google Colab, and environments with multiple PostgreSQL installations
• Simple initialization: pgembed.get_server(MY_DATA_DIR) handles initdb, port management, and process cleanup automatically
• Vector search ready: Includes pgvector and pgvectorscale extensions for vector similarity queries and high-performance vector storage
• Text search ready: Includes pg_textsearch extension for BM25-based full-text search with ranking

Quick start

import pgembed

# Initialize and start the server
pgembed.get_server("/path/to/my/data/dir")

# Connect and use like any PostgreSQL database
# ... your database code here
# Look in examples/*.py for more complete examples that could be run via uv

PostgreSQL binaries are available at pgembed.POSTGRES_BIN_PATH if you need direct access to tools like initdb, pg_ctl, psql, or pg_config.

Extensions

pgembed supports optional PostgreSQL extensions as separate packages. Install the extensions you need:

# Base installation (PostgreSQL only)
pip install pgembed

# With specific extensions (separate wheels)
pip install pgembed-pgvector
pip install pgembed-pgvectorscale
pip install pgembed-pgtextsearch

# Multiple extensions
pip install pgembed-pgvector pgembed-pgvectorscale pgembed-pgtextsearch

Available extensions:

• pgembed-pgvector: Vector similarity search (works on all platforms)
• pgembed-pgvectorscale: High-performance vector storage (requires Rust, not available on Alpine/Windows)
• pgembed-pgtextsearch: BM25-based full-text search (requires Rust, not available on Alpine/Windows)

Checking available extensions

import pgembed

# Check which extensions are available
print(pgembed.list_extensions())
# {'pgvector': True, 'pgvectorscale': True, 'pgtextsearch': False, 'pg_duckdb': True}

# Check if a specific extension is available
if pgembed.has_extension('pgvector'):
    # Create the extension
    server.create_extension('vector')

Platform Support

• pgvector: Works on Linux, macOS (Intel & Apple Silicon), Windows
• pgvectorscale: Works on Linux, macOS (Intel & Apple Silicon). NOT available on Alpine Linux or Windows (requires Rust)
• pgtextsearch: Works on Linux, macOS (Intel & Apple Silicon). NOT available on Alpine Linux or Windows (requires Rust)

Building specific extensions

To build only specific extensions:

# Build only pgvector
make pgvector

# Build only pgvectorscale
make pgvectorscale

# Build only pgtextsearch
make pgtextsearch

# Build specific combination
make EXTENSIONS="pgvector pgtextsearch" all

History

pgembed is a fork of pgserver, which was inspired by postgresql-wheel. While those projects focused primarily on Linux wheels, pgembed extends the approach with:

• Multi-platform support (Linux, macOS, Windows)
• Robust process management and cleanup
• Built-in pgvector, pgvectorscale, and pg_textsearch extensions