pgcraft 0.9.0

Configuration-driven PostgreSQL framework

pgcraft

Pre-alpha — pgcraft is under active development. APIs may change between releases. Feedback and contributions are welcome.

Configuration-driven PostgreSQL data schemas, migrations, and APIs.

pgcraft generates SQLAlchemy models and Alembic migrations from declarative dimension configurations. Define your schema once; pgcraft handles the rest. An optional PostgREST extension adds API views, roles, and grants.

---

Features

• Dimension types — Simple, Append-Only (SCD Type 2), and Entity-Attribute-Value, each with generated backing tables, views, and triggers.
• Plugin architecture — Composable plugins with @requires / @produces decorators, executed in topological order.
• Automatic migrations — Alembic integration with SQL-formatted migration scripts via sqlglot.
• Extension system — Opt-in extensions for PostgREST API views, roles, and grants. Third-party extensions via entry points.
• Postgres is king — Logic lives in the database (views, triggers, check constraints). Python orchestrates; Postgres enforces.

Quick start

Install

pip install pgcraft            # or: uv add pgcraft

Define a dimension

from sqlalchemy import Column, MetaData, String
from pgcraft.factory import PGCraftSimple

metadata = MetaData()

users = PGCraftSimple(
    tablename="users",
    schemaname="public",
    metadata=metadata,
    schema_items=[
        Column("name", String, nullable=False),
        Column("email", String),
    ],
)

This creates a public.users table with id, name, and email columns, with Alembic migration support out of the box.

Generate migrations

pgcraft migrate revision --autogenerate -m "add users"
pgcraft migrate upgrade head

Dimension types

pgcraft ships with three built-in dimension types:

Type	Use case	History?
Simple	Static reference data	No
Append-Only (SCD Type 2)	Track changes over time	Yes
EAV	Flexible / sparse attributes with full audit trail	Yes

See the dimensions documentation for ERD diagrams, schema details, and worked examples.

Documentation

Full documentation is available at roddarjohn.github.io/pgcraft.

• Setup & installation
• Built-in dimensions
• Plugin system
• Extensions
• API reference
• Development guide
• Playground

Development

# Clone and install
git clone https://github.com/<username>/pgcraft.git
cd pgcraft
uv sync --all-groups

# Run checks
just lint          # ruff check + format
just type-check    # ty check src/
just dev-test      # pytest (fast, needs DATABASE_URL)
just test          # tox (full isolation)
just docs          # build Sphinx HTML docs

Tests require a running PostgreSQL instance:

DATABASE_URL=postgresql+psycopg:///pgcraft just dev-test

Design philosophy

See PLAN.md for the full design philosophy. The short version:

• Explicit over implicit. No magic — if behavior is not obvious from reading the code, it needs a docstring explaining why.
• Simple over clever. Three similar lines are better than a premature abstraction.

License

See LICENSE for details.