pg-here 0.1.0

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

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:

Approach	Problem
Docker	Heavy, slow startup, daemon required, port mapping headaches
Homebrew / apt	System-wide install, version conflicts between projects
Cloud databases	Network latency, costs, can't work offline
Manual binary	Download, extract, initdb, pg_ctl, configure... every time

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

	pg-here (Python)	pg-here (Node.js)	Docker Postgres	Homebrew
One command	uvx pg-here	bunx pg-here	docker run ...	brew install + config
Per-project isolation	Yes	Yes	Volume mounts	No
No daemon required	Yes	Yes	No (Docker daemon)	No (brew services)
Offline after first run	Yes	Yes	Needs image	Yes
Python API	Yes	No	No	No
Size	~30MB binary	~30MB binary	~400MB image	~100MB

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