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.
- 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/@producesdecorators, 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.
pip install pgcraft # or: uv add pgcraftfrom 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.
pgcraft migrate revision --autogenerate -m "add users"
pgcraft migrate upgrade headpgcraft 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.
Full documentation is available at roddarjohn.github.io/pgcraft.
- Setup & installation
- Built-in dimensions
- Plugin system
- Extensions
- API reference
- Development guide
- Playground
# 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 docsTests require a running PostgreSQL instance:
DATABASE_URL=postgresql+psycopg:///pgcraft just dev-testSee 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.
See LICENSE for details.