Skip to main content

Confiture 🍓

PostgreSQL migrations, sweetly done.

Build from DDL. Adopt on day one against a database that already has migrations applied. Preflight every deploy by replaying the pending migrations against a parallel database, rolled back. Sync production data with PII anonymization.

PyPI Quality Gate Python Version Matrix Examples Python 3.14+ PostgreSQL 16+ License: MIT


In 30 seconds

# 1. You already have a database at migration 004 (applied by hand or by another tool).
#    Tell Confiture about that history without re-running the SQL:
$ confiture migrate baseline --through 004 -c db/environments/production.yaml
  ✅ 001 create_users (marked as applied)
  ✅ 002 create_orders (marked as applied)
  ✅ 003 add_user_email (marked as applied)
  ✅ 004 add_user_preferences (marked as applied)
✅ Marked 4 migration(s) as applied, skipped 0 already applied

# 2. Machine-readable proof that the tracking is healthy:
$ confiture migrate status -c db/environments/production.yaml --format json | jq '.applied | length'
4

# 3. Preflight: replay the pending migrations on a parallel DB, inside a rollback.
$ confiture migrate preflight --against "$PREFLIGHT_URL" -c db/environments/production.yaml
Execution check: 1 migration(s) against postgresql://preflight-host/app

  ✓  20260520143015  add_user_bio                              (0.02s)

  ✓ All 1 migration(s) passed.
  (Rolled back — preflight DB unchanged)
exit 0

That's the loop. Baseline once → status to confirm → preflight every deploy.


Already have migrations?

The single biggest reason migration tools fail adoption is the day-one cliff: existing tables already exist, so any tool that tries to apply migrations from scratch crashes on the first CREATE TABLE. Confiture's answer is migrate baseline:

confiture migrate baseline --through <last-applied-version>

The walkthrough — including failure modes, the integration test that backs the recipe, and what tb_confiture ends up looking like — is in docs/guides/legacy-bootstrap.md.


No db/schema/ directory? That works too.

confiture migrate up, down, down-to, status, current, baseline, and preflight are the migration runner — they don't require a db/schema/ directory (migrate current prints the latest applied revision as a narrow "what's deployed?" contract; migrate down --steps N rolls back relatively while migrate down-to <revision> rolls back to a specific revision, refusing atomically if any required .down.sql is missing). The "Build from DDL" pitch above the fold sells one of confiture's four strategies; the other three (incremental migrations, production sync, schema-to-schema FDW migration) work against a project whose only source of truth is the migration chain itself.

If you're evaluating confiture against Flyway / Alembic / dbmate / sqlx-cli as a pure migration runner, skip confiture build and use everything else. Walkthrough: docs/guides/02-incremental-migrations.md.


When to use Confiture?

Capability Confiture Flyway Alembic dbmate sqlx-cli plain psql
Source of truth DDL files or migration chain migration chain model classes migration chain migration chain DDL files
Tracking table yes yes yes yes yes no
Rollback (down.sql) yes paid yes yes yes no
Preflight against a copy DB yes (replayed, rolled back) no no no no no
Build from scratch in <1s yes no no no no yes (manual)
Production sync + anonymization yes no no no no no
Zero-downtime via FDW yes no no no no no
Ecosystem maturity / stars early very mature mature mature mature n/a

Note on "source of truth": confiture can run as a pure migration tool against a project that has no db/schema/ directory — the DDL workflow is opt-in. See No db/schema/ directory? above.

Confiture wins on build-from-DDL, replayed preflight, and production sync. It loses on ecosystem age — Flyway and Alembic have a decade of community knowledge. Pick honestly.

Adoption checklist

Situation Recommended tool
1 environment + 1 contributor, schema rarely changes plain psql
2+ environments, schema changes weekly Confiture, Flyway, Alembic, or dbmate
Multi-agent / AI-driven development on shared schemas Confiture with the pgGit plugin (plugins/fraiseql-confiture-pggit/)
You have a migration chain (no db/schema/) and want preflight + tracking Confiture (use everything except confiture build)
You want db/schema/ to be source of truth, not a migration chain Confiture
You need zero-downtime schema swaps with postgres_fdw Confiture (Medium 4)
You're committed to SQLAlchemy ORM Alembic
You're committed to a JVM stack Flyway

CI integration

A migrate preflight gate on every PR, a migrate up step on deploy. Exit codes are semantic, so the CI configuration stays simple:

# .github/workflows/db.yml
name: DB

on:
  pull_request:
    paths:
      - 'db/**'
  push:
    branches: [main]

jobs:
  preflight:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env: { POSTGRES_PASSWORD: x }
        ports: ['5432:5432']
        options: >-
          --health-cmd pg_isready --health-interval 10s
          --health-timeout 5s --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - run: uv pip install --system fraiseql-confiture
      - name: Restore production snapshot to preflight DB
        run: ./scripts/restore-snapshot.sh   # your own; pg_restore from S3/GCS
      - name: Confiture preflight
        env:
          PREFLIGHT_URL: postgresql://postgres:x@localhost:5432/preflight
        run: |
          confiture migrate preflight \
            --against "$PREFLIGHT_URL" \
            -c db/environments/preflight.yaml \
            --format json --output preflight.json
      - uses: actions/upload-artifact@v4
        with:
          name: preflight-report
          path: preflight.json

  deploy:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - run: uv pip install --system fraiseql-confiture
      # No YAML needed in CI — the migrate family reads DATABASE_URL directly
      # (or pass --database-url "$DSN"). See the connection-source docs below.
      - run: confiture migrate up
        env:
          DATABASE_URL: ${{ secrets.PROD_DATABASE_URL }}

migrate up/down/status/verify/preflight accept --database-url <dsn> (or read CONFITURE_DATABASE_URL / DATABASE_URL) so runtime-resolved DSNs need no temp YAML — precedence and details in the CLI reference.

Exit codes are a documented stability contract — see the exit-code reference. The most operationally important: 2 tracking table absent, 3 DB connection failed, 5 config invalid, 6 lock contention. For migrate preflight's drift-gate codes specifically, see the dry-run guide.

Migrations that open their own SAVEPOINTs, use psycopg's conn.transaction(), or wrap DO $$ … EXCEPTION WHEN … $$ blocks are supported under all three modes. The rules a migration body must follow for the SAVEPOINT-based rollback to stay clean are documented in the transaction & SAVEPOINT contract.


Python project snippet

Add Confiture as a dev dependency. pglast (PostgreSQL's own parser) comes with it since 0.50.0.

# pyproject.toml
[dependency-groups]
dev = [
  "fraiseql-confiture>=0.50",
  "pytest>=8",
]
# justfile
default:
    just --list

db-build:
    confiture build --env local

db-up:
    confiture migrate up

db-status:
    confiture migrate status

db-preflight:
    confiture migrate preflight --against "$PREFLIGHT_URL"

Or as a Makefile:

db-build:
	confiture build --env local

db-up:
	confiture migrate up

db-status:
	confiture migrate status

Library API

Confiture is a CLI first, but the migrator is fully usable from Python:

from confiture import Migrator

with Migrator.from_config("db/environments/prod.yaml") as m:
    status = m.status()
    if status.has_pending:
        result = m.up()
        print(f"Applied {len(result.applied)} migrations")

Building on confiture

What confiture knows about a schema is a public seam, confiture.platform: read a schema from DDL or from a live database into one model, diff two schemas into typed changes, order tables by their foreign keys, say which columns a writer supplies and what each must respect, and write, apply and validate seed files. Every name and signature is pinned by a contract test, and no signature exposes a parser or driver type.

from confiture.platform import dependency_order, parse_schema, writable_columns

model = parse_schema(env="local")
for table in dependency_order(model):
    print(table.display, [c.name for c in writable_columns(model, table)])

confiture schema dump-model writes the same model as byte-stable JSON. Its consumers: fraisier, which drives confiture at deploy time through the adapter contract, and fraiseql-semis (in development), which generates seed data on the seam. See Building on confiture and the platform API reference.


The Four Strategies

Strategy Use Case Command
Build from DDL Fresh databases, testing, CI confiture build --env local
Incremental Migrations Existing databases, production confiture migrate up
Production Sync Copy data with PII anonymization confiture sync --from prod --anonymize users.email
Zero-Downtime Complex migrations via FDW confiture migrate schema-to-schema

Documentation

Start here

Guides

Reference

For agents and tooling

  • JSON schemas are published for the --format json output of every command, which tests/unit/json_schemas/test_every_json_command_has_a_schema.py holds to. They ship in the package (python/confiture/schemas/) and are mirrored under docs/reference/json-schemas/, one section per command in docs/reference/json-schemas.md; a test asserts the mirror equals the packaged source, and each schema is validated against payloads the command wrote.
  • On an error path in --format json mode, the migrate family emits a structured error envelope on stdout — {"ok": false, "error": {code, message, severity, actionable, details, migration, file, line}} — and exits with the exit code for that error. The full code list and the envelope schema are in the error-code codebook.
  • confiture migrate validate --list-patterns --format json exposes the full idempotency-detection catalog (read-only, no DB / config / migrations directory needed).
  • Quiet-success ambiguities surface advisory hints in payload["hints"] (or on stderr in text mode) — exit codes are unaffected.

Contributing

git clone https://github.com/fraiseql/confiture.git
cd confiture
uv sync --all-extras
uv run pytest

See CONTRIBUTING.md and CLAUDE.md.


Author & License

Vibe-engineered by Lionel Hamayon 🍓

MIT License — Copyright (c) 2025 Lionel Hamayon


Making jam from strawberries, one migration at a time. 🍓→🍯

Metadata

Release files for fraiseql-confiture 1.40.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fraiseql-confiture 1.40.0
File Size Uploaded Provenance Actions
fraiseql_confiture-1.40.0.tar.gz 4.2 MB Without provenance Details for fraiseql_confiture-1.40.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for fraiseql-confiture 1.40.0
File Actions
fraiseql_confiture-1.40.0-cp315-cp315-win_amd64.whl CPython 3.15 CPython 3.15 Windows x86-64 Details for fraiseql_confiture-1.40.0-cp315-cp315-win_amd64.whl
fraiseql_confiture-1.40.0-cp315-cp315-macosx_11_0_arm64.whl CPython 3.15 CPython 3.15 macOS 11.0+ ARM64 Details for fraiseql_confiture-1.40.0-cp315-cp315-macosx_11_0_arm64.whl
fraiseql_confiture-1.40.0-cp314-cp314-win_amd64.whl CPython 3.14 CPython 3.14 Windows x86-64 Details for fraiseql_confiture-1.40.0-cp314-cp314-win_amd64.whl
fraiseql_confiture-1.40.0-cp314-cp314-manylinux_2_28_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.28+ x86-64 Details for fraiseql_confiture-1.40.0-cp314-cp314-manylinux_2_28_x86_64.whl
fraiseql_confiture-1.40.0-cp314-cp314-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 macOS 11.0+ ARM64 Details for fraiseql_confiture-1.40.0-cp314-cp314-macosx_11_0_arm64.whl

Total release size: 12.7 MB

Release files / fraiseql_confiture-1.40.0.tar.gz

Download URL fraiseql_confiture-1.40.0.tar.gz
Size 4.2 MB
Tags Source
SHA-256 checksum
How to use checksums
f4730980bfc9d37a0efabbc8464f642e488ea91a698655872840d37a8b2a1a3e
BLAKE2b-256 checksum
How to use checksums
0c5ce5cb133271464ea2d7e5dd7e137082c62f20f2b15d028b7ee7d9f6a46545
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / fraiseql_confiture-1.40.0-cp315-cp315-win_amd64.whl

Download URL fraiseql_confiture-1.40.0-cp315-cp315-win_amd64.whl
Size 1.7 MB
Tags CPython 3.15 Windows x86-64
SHA-256 checksum
How to use checksums
42f0edd93639626a3b354fae020794b38e2c44d17b23c84f3f274a91176c1581
BLAKE2b-256 checksum
How to use checksums
07f8d7b9786cb46bcfa91485bab9f60057a30cfcde414e166b1bd9b31de32358
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / fraiseql_confiture-1.40.0-cp315-cp315-macosx_11_0_arm64.whl

Download URL fraiseql_confiture-1.40.0-cp315-cp315-macosx_11_0_arm64.whl
Size 1.7 MB
Tags CPython 3.15 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
06c1ca10a5721b6e471d38aea0715c4a5c5e0d2d4a7518feb1ab15954da3b4a3
BLAKE2b-256 checksum
How to use checksums
615df8c7c84e85364690985b8bc7ba10ce1b531df6648f5d02bfee464f5bdf53
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / fraiseql_confiture-1.40.0-cp314-cp314-win_amd64.whl

Download URL fraiseql_confiture-1.40.0-cp314-cp314-win_amd64.whl
Size 1.7 MB
Tags CPython 3.14 Windows x86-64
SHA-256 checksum
How to use checksums
0e4a2f50a588969ce8d66dfa3891b926e86ace2a9b948f55d6812350cda01ec6
BLAKE2b-256 checksum
How to use checksums
76055076b05aec138b4481d6cf561f658d00e3dda1e1aeb14244c4be1f5ba37d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / fraiseql_confiture-1.40.0-cp314-cp314-manylinux_2_28_x86_64.whl

Download URL fraiseql_confiture-1.40.0-cp314-cp314-manylinux_2_28_x86_64.whl
Size 1.7 MB
Tags CPython 3.14 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
fc97d39a08ebf8a759724fb2e4fc3297fb7f6bc5eab523c208b84924139d02e0
BLAKE2b-256 checksum
How to use checksums
f71903d8359f23dbdbe1fba051fb7990618fe045cf7bc31b26fc8733d9612b6c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / fraiseql_confiture-1.40.0-cp314-cp314-macosx_11_0_arm64.whl

Download URL fraiseql_confiture-1.40.0-cp314-cp314-macosx_11_0_arm64.whl
Size 1.7 MB
Tags CPython 3.14 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
ae0ee64e7ac231391c857a88fcf8cd1a35452f5e1e451b9bbe6022899134c183
BLAKE2b-256 checksum
How to use checksums
1356f0a1712978fed5b292b6ec4c665c88923f6a3178bd4388c5033f855934e2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for fraiseql-confiture 1.40.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.40.0 This release

6 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page