metapg

Meta PostgreSQL pools and raw SQL migrations for multi-database applications

metapg is a metapackage that provides a unified interface for PostgreSQL operations through independently installable components.

Installation

Install Everything

pip install metapg[all]

Install Individual Components

# Connection pooling only
pip install metapg[pool]

# Migrations only  
pip install metapg[migration]

# CLI tools only
pip install metapg[cli]

# Custom combination
pip install metapg[pool,migration]

Quick Start

import metapg

# 🎯 Smart cursor - works with both sync and async!

# Synchronous usage
with metapg.cursor() as cur:
    cur.execute("SELECT * FROM users")
    users = cur.fetchall()

# Asynchronous usage (same interface!)
async with metapg.cursor() as cur:
    await cur.execute("SELECT * FROM users")
    users = await cur.fetchall()

# Migrations
runner = metapg.migration.MigrationRunner()
await runner.apply_pending()

Components

metapg.pool - Connection Pooling

High-performance async and sync PostgreSQL connection pooling.

# Smart interface adapts to context
async with metapg.pool.cursor() as cur:
    await cur.execute("SELECT * FROM users")

with metapg.pool.cursor() as cur:  # Sync version
    cur.execute("SELECT * FROM users")

metapg.migration - Schema Migrations

Raw SQL migrations with dependency tracking and rollback support.

runner = metapg.migration.MigrationRunner()
status = await runner.get_status()
await runner.apply_pending()

metapg.cli - Command Line Interface

Beautiful terminal interface for database operations.

metapg migration status
metapg migration apply
metapg pool init mydb --dsn postgresql://localhost/mydb

Features

• 🎯 Smart Cursor - Same interface works with both with (sync) and async with (async)
• ⚡ Async-first - Built on psycopg3 with full async/await support
• 🔄 Sync Support - Full synchronous API when you don't need async
• 🎛️ Multi-database - Manage multiple PostgreSQL databases with named pools
• 📜 Raw SQL migrations - Simple, powerful migrations using plain SQL files
• 🧠 Context-aware - Smart connection reuse with contextvars
• ⚙️ Zero-config - Works out of the box with sensible defaults
• 🚀 Production-ready - Proper connection pooling, transactions, and error handling
• 💻 Rich CLI - Beautiful terminal interface for migration management
• 📦 Modular - Install only what you need

Package Architecture

metapg/                    # Metapackage (this package)
├── metapg.pool           # Connection pooling
├── metapg.migration      # Schema migrations
└── metapg.cli           # Command-line interface

Each component is independently installable and maintained, but they work seamlessly together through the metapackage interface.

Usage Patterns

Full Stack (All Components)

pip install metapg[all]

import metapg

# Connection pooling
async with metapg.cursor() as cur:
    await cur.execute("SELECT * FROM users")

# Migrations
runner = metapg.migration.MigrationRunner()
await runner.apply_pending()

# CLI access
metapg.cli.app()  # For programmatic CLI access

Minimal (Pool Only)

pip install metapg[pool]

import metapg

# Only pooling functionality available
async with metapg.cursor() as cur:
    await cur.execute("SELECT * FROM users")

# migration and cli will be None
print(metapg.migration)  # None
print(metapg.cli)        # None

Migration Focus

pip install metapg[pool,migration]

import metapg

# Pooling + migrations available
async with metapg.cursor() as cur:
    await cur.execute("SELECT * FROM users")

runner = metapg.migration.MigrationRunner()
await runner.apply_pending()

# CLI not available
print(metapg.cli)  # None

Environment Variables

• DATABASE_URL - Default database connection string
• DATABASE_URL_{NAME} - Connection string for named database

Error Handling

The metapackage provides helpful error messages when components aren't installed:

import metapg

# If metapg.pool not installed
metapg.cursor()  # ImportError: metapg.pool is required. Install with: pip install metapg.pool

License

MIT License - see LICENSE file for details.

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

Individual Package Documentation

• metapg.pool - Connection pooling
• metapg.migration - Schema migrations
• metapg.cli - Command-line interface