pg-here

Run a local PostgreSQL instance in your project folder with one command.

uvx pg-here

That's it. No Docker, no Homebrew, no system-wide installation. PostgreSQL runs from ./pg_local/ inside your project and shuts down cleanly with Ctrl+C.

Python port of pg-here (Node.js) by @mayfer. Same concept, independent implementation — rewritten from scratch in Python for the uv/uvx ecosystem.

Why?

Setting up PostgreSQL for local development is annoying:

pg-here does all of that in one command. Each project gets its own PostgreSQL binary and data directory. No conflicts. No configuration.

Features

• One command: uvx pg-here — nothing else needed
• Zero config: Sensible defaults, works out of the box
• Per-project isolation: Data lives in ./pg_local/, easily gitignored
• Auto-download: Fetches a pre-built PostgreSQL binary on first run (~30MB)
• Instant restart: Binary is cached — subsequent runs start in seconds
• pg_stat_statements: Pre-configured for query performance analysis
• Python API: Use as a library in tests and scripts
• Cross-platform: macOS (Apple Silicon & Intel) and Linux (x86_64 & ARM64)
• Clean shutdown: Ctrl+C stops PostgreSQL gracefully

Install

# Run directly — no install needed
uvx pg-here

# Or install globally
uv tool install pg-here

# Or add to your project
uv add --dev pg-here

Requires Python 3.10+ and uv.

Usage

Quick start

uvx pg-here

Output:

PostgreSQL 17.4.0 running on port 55432

  psql postgresql://postgres:postgres@localhost:55432/postgres

Press Ctrl+C to stop.

Copy the connection string and use it with any PostgreSQL client.

Custom database

uvx pg-here -d myapp

Creates the myapp database automatically if it doesn't exist.

All options

Usage: pg-here [OPTIONS]

Options:
  -u, --username TEXT   PostgreSQL superuser name (default: postgres)
  --password TEXT       Password for connection string (default: postgres)
  --port INTEGER        Port number (default: 55432)
  -d, --database TEXT   Database name (default: postgres)
  --pg-version TEXT     PostgreSQL version, e.g. 17.4.0
  --help                Show this message and exit.

Use in a project

Add to your pyproject.toml:

[dependency-groups]
dev = ["pg-here"]

Then:

uv run pg-here

Connect from your app

import psycopg

conn = psycopg.connect("postgresql://postgres:postgres@localhost:55432/myapp")

psql postgresql://postgres:postgres@localhost:55432/myapp

Python API

Use pg-here programmatically in tests or scripts:

from pg_here import start_pg_here

# Start a local PostgreSQL instance
handle = start_pg_here(port=55432, database="myapp")
print(handle.connection_string)
# postgresql://postgres:postgres@localhost:55432/myapp

# Create additional databases
handle.ensure_database("testdb")

# Get connection strings for other databases
uri = handle.connection_string_for("testdb")

# Stop when done
handle.stop()

pytest fixture example

import pytest
from pg_here import start_pg_here

@pytest.fixture
def pg(tmp_path):
    handle = start_pg_here(project_dir=tmp_path, port=0)  # 0 = auto
    yield handle
    handle.stop()

def test_my_app(pg):
    conn = psycopg.connect(pg.connection_string)
    # ...

How it works

uvx pg-here
    │
    ├─ 1. Download PostgreSQL binary from Maven Central (Zonky)
    ├─ 2. Extract to ./pg_local/bin/17.4.0/
    ├─ 3. initdb → initialize data cluster in ./pg_local/data/
    ├─ 4. pg_ctl start → run PostgreSQL on port 55432
    ├─ 5. Create database + install pg_stat_statements
    └─ 6. Wait for Ctrl+C → pg_ctl stop (graceful shutdown)

All files live under ./pg_local/. Add it to your .gitignore:

# .gitignore
pg_local/

Directory structure

your-project/
├── pg_local/              ← created by pg-here (gitignored)
│   ├── bin/17.4.0/        ← PostgreSQL binaries (cached)
│   │   ├── bin/
│   │   ├── lib/
│   │   └── share/
│   └── data/              ← database cluster
│       ├── PG_VERSION
│       ├── postgresql.conf
│       └── ...
└── ...

Comparison

Acknowledgments

• Inspired by pg-here (Node.js) by @mayfer. This is an independent Python implementation — no code was copied. We share the same vision: one-command local PostgreSQL for any project.
• Uses Zonky embedded-postgres-binaries (Apache 2.0) for pre-built PostgreSQL distributions via Maven Central.

License

MIT