Confiture 🍓

PostgreSQL migrations, sweetly done.

Build from DDL. Adopt on day one against a database that already has migrations applied. Preflight every deploy against a parallel database with structural diff. Sync production data with PII anonymization.

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 pending migrations on a parallel DB, emit a structural diff vs. db/schema/.
$ confiture migrate preflight --against "$PREFLIGHT_URL" -c db/environments/production.yaml
▸ Replaying pending migrations on preflight DB …
  ✓ 20260520143015_add_user_bio                 applied in 24 ms
▸ Comparing resulting schema vs. db/schema/ …
  ✓ No drift — preflight matches db/schema/
✓ Preflight passed. Safe to deploy.
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 (structural diff)	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
Multi-agent coordination	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, structural-diff preflight, production sync, and multi-agent coordination. 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
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")

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

Getting started — first 5 minutes.
Legacy bootstrap guide — adopting on an existing database.
Prerequisites — PostgreSQL version, roles, secret stores.

Guides

Build from DDL
Incremental Migrations — up, down, rollback.
Parallel, cacheable CI provisioning — build --dump artifacts, test-db template/clone, per-worker xdist fixtures, slim seed profiles.
Production Data Sync
Zero-Downtime Migrations
Dry-Run + Preflight
Replica-safe migrations — replica_001 / PFLIGHT_REPLICA_* forward-compatibility lint under streaming replication.
Bootstrap — confiture bootstrap for one-shot env ownership setup.
Superuser Migrations — requires_superuser = True + migrate apply-as recovery workflow.
Function Uniqueness — func_001 catches duplicate CREATE FUNCTION across DDL files.
Security-Definer Lint — sec_002 flags SECURITY DEFINER functions/procedures that don't pin search_path (CVE-2018-1058); static DDL scan and live pg_proc path; --emit-remediation generates ALTER scripts.
Named Schemas
Hooks
Multi-Agent Coordination

Reference

Tracking table (tb_confiture)
Transaction & SAVEPOINT contract — what migration bodies may and may not do under the wrapping transaction.
Exit-code convention — the stable, wrapper-facing exit codes.
CLI
Configuration YAML
Complete feature list

For agents and tooling

Every machine-readable CLI output has a published JSON schema, shipped in the package (python/confiture/schemas/) and mirrored under docs/reference/json-schemas/ — see docs/reference/json-schemas.md.
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 🍓

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

Release files for fraiseql-confiture 0.52.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 0.52.0
File	Size	Uploaded
fraiseql_confiture-0.52.0.tar.gz	2.6 MB	Sep 6, 2026	Details

Built distributions (wheels)

Table of built distributions (wheels) for fraiseql-confiture 0.52.0
File	Interpreter	ABI	Platform	Reset
fraiseql_confiture-0.52.0-cp314-cp314-win_amd64.whl 1.2 MB Sep 6, 2026	CPython 3.14	CPython 3.14	Windows x86-64	Details
fraiseql_confiture-0.52.0-cp313-cp313-win_amd64.whl 1.2 MB Sep 6, 2026	CPython 3.13	CPython 3.13	Windows x86-64	Details
fraiseql_confiture-0.52.0-cp313-cp313-manylinux_2_28_x86_64.whl 1.3 MB Sep 6, 2026	CPython 3.13	CPython 3.13	Linux glibc 2.28+ x86-64	Details
fraiseql_confiture-0.52.0-cp313-cp313-macosx_11_0_arm64.whl 1.2 MB Sep 6, 2026	CPython 3.13	CPython 3.13	macOS 11.0+ ARM64	Details
fraiseql_confiture-0.52.0-cp312-cp312-win_amd64.whl 1.2 MB Sep 6, 2026	CPython 3.12	CPython 3.12	Windows x86-64	Details
fraiseql_confiture-0.52.0-cp312-cp312-manylinux_2_28_x86_64.whl 1.3 MB Sep 6, 2026	CPython 3.12	CPython 3.12	Linux glibc 2.28+ x86-64	Details
fraiseql_confiture-0.52.0-cp312-cp312-macosx_11_0_arm64.whl 1.2 MB Sep 6, 2026	CPython 3.12	CPython 3.12	macOS 11.0+ ARM64	Details
fraiseql_confiture-0.52.0-cp311-cp311-win_amd64.whl 1.2 MB Sep 6, 2026	CPython 3.11	CPython 3.11	Windows x86-64	Details
fraiseql_confiture-0.52.0-cp311-cp311-manylinux_2_28_x86_64.whl 1.3 MB Sep 6, 2026	CPython 3.11	CPython 3.11	Linux glibc 2.28+ x86-64	Details
fraiseql_confiture-0.52.0-cp311-cp311-macosx_11_0_arm64.whl 1.2 MB Sep 6, 2026	CPython 3.11	CPython 3.11	macOS 11.0+ ARM64	Details

Total release size: 14.9 MB

Release files / fraiseql_confiture-0.52.0.tar.gz

Download URL	fraiseql_confiture-0.52.0.tar.gz
Size	2.6 MB
Tags	Source
SHA-256 checksum How to use checksums	`fad113844b66ebbffe3b8ecd06560c9f3825e0359cc40811c4721d2fee6f9f73`
BLAKE2b-256 checksum How to use checksums	`0989fa6abb27722506a6f1d9913ac1a59f82a620e2875e13d0fc20bef3e8e316`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

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

Download URL	fraiseql_confiture-0.52.0-cp314-cp314-win_amd64.whl
Size	1.2 MB
Tags	CPython 3.14 Windows x86-64
SHA-256 checksum How to use checksums	`0ae1013520052f7838a22446ddf24dc9ad8bb92b2fe79c6057b408e48fccab2c`
BLAKE2b-256 checksum How to use checksums	`5f48a097e6e9801b6b6d03ae45472a2bf4c88839c5e793986578157acda4bebb`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / fraiseql_confiture-0.52.0-cp313-cp313-win_amd64.whl

Download URL	fraiseql_confiture-0.52.0-cp313-cp313-win_amd64.whl
Size	1.2 MB
Tags	CPython 3.13 Windows x86-64
SHA-256 checksum How to use checksums	`1c5e59bfc90946bbe1e496ac2b74d2d64b294e2f3d9a63f59cadc6dd4bfe60c8`
BLAKE2b-256 checksum How to use checksums	`70f25c836bbc11d13249b8b9664dba67f705f58971e7a3325cbc31b739b87d92`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / fraiseql_confiture-0.52.0-cp313-cp313-manylinux_2_28_x86_64.whl

Download URL	fraiseql_confiture-0.52.0-cp313-cp313-manylinux_2_28_x86_64.whl
Size	1.3 MB
Tags	CPython 3.13 Linux glibc 2.28+ x86-64
SHA-256 checksum How to use checksums	`23cd5127fc4ba14a48b8f3149c5dab5453e49164ef872138275fb9a27b79285b`
BLAKE2b-256 checksum How to use checksums	`ced16014881fc2be9a2b29b99f6f52f08624dba9d02b9812614beab59bd285fc`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / fraiseql_confiture-0.52.0-cp313-cp313-macosx_11_0_arm64.whl

Download URL	fraiseql_confiture-0.52.0-cp313-cp313-macosx_11_0_arm64.whl
Size	1.2 MB
Tags	CPython 3.13 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`3bdd01182284b447c973ce8b14b3d9e8fd7439f865840c587de5dd59c1466059`
BLAKE2b-256 checksum How to use checksums	`7357adea55e06f4849ac57f1a82552b5c0b23f66b8f3c369f5e2af72e2c4302a`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / fraiseql_confiture-0.52.0-cp312-cp312-win_amd64.whl

Download URL	fraiseql_confiture-0.52.0-cp312-cp312-win_amd64.whl
Size	1.2 MB
Tags	CPython 3.12 Windows x86-64
SHA-256 checksum How to use checksums	`45be4b64182e0e2746714c9bd44608f464bdb95387d19da2f6c6842e007bc9a8`
BLAKE2b-256 checksum How to use checksums	`a68983225efd6dbef1d205a77f2be986d35977d64b15879f5965e452dd7f5639`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / fraiseql_confiture-0.52.0-cp312-cp312-manylinux_2_28_x86_64.whl

Download URL	fraiseql_confiture-0.52.0-cp312-cp312-manylinux_2_28_x86_64.whl
Size	1.3 MB
Tags	CPython 3.12 Linux glibc 2.28+ x86-64
SHA-256 checksum How to use checksums	`b5c3df8fd1d303783c92e1f142b0308baf795cae35bfccb743fc50ce487ce79b`
BLAKE2b-256 checksum How to use checksums	`41e6530e863f543071924664e303c6ede91da9a24b8c04806b77f27b3a8d0765`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / fraiseql_confiture-0.52.0-cp312-cp312-macosx_11_0_arm64.whl

Download URL	fraiseql_confiture-0.52.0-cp312-cp312-macosx_11_0_arm64.whl
Size	1.2 MB
Tags	CPython 3.12 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`450c3e85213d52343192c1eb2a168cf50f279735745cdd0b75b550d066f5e06f`
BLAKE2b-256 checksum How to use checksums	`0965d199c3739c0feb82dd461d6257350c5ceed348c7c9759ac53c4de9938fe0`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / fraiseql_confiture-0.52.0-cp311-cp311-win_amd64.whl

Download URL	fraiseql_confiture-0.52.0-cp311-cp311-win_amd64.whl
Size	1.2 MB
Tags	CPython 3.11 Windows x86-64
SHA-256 checksum How to use checksums	`1e9ccacdc419d5dc7edcf5792da92d07043a15d6dd69edb0e469bc22f3a994da`
BLAKE2b-256 checksum How to use checksums	`b7a3f511ce2c133c6890ccd59200c033a20cc473e427d8de2674fa0972b825ad`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / fraiseql_confiture-0.52.0-cp311-cp311-manylinux_2_28_x86_64.whl

Download URL	fraiseql_confiture-0.52.0-cp311-cp311-manylinux_2_28_x86_64.whl
Size	1.3 MB
Tags	CPython 3.11 Linux glibc 2.28+ x86-64
SHA-256 checksum How to use checksums	`47cbaa1e93c1c66f48127265f7aa5d1e003c9696eff0c06ac17430fe50bebe7c`
BLAKE2b-256 checksum How to use checksums	`14639c7ddf9c4232a18167b963c5e031fa6b55dc7042cf6a944ce4e9dabd6aa3`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / fraiseql_confiture-0.52.0-cp311-cp311-macosx_11_0_arm64.whl

Download URL	fraiseql_confiture-0.52.0-cp311-cp311-macosx_11_0_arm64.whl
Size	1.2 MB
Tags	CPython 3.11 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`82e1b8c035dce2d13fb1b4302f9594d17274b3c4cd3c3c75ceb1d786bddd65a9`
BLAKE2b-256 checksum How to use checksums	`e1f6bc739afa3ff27bec530e6e34d31b7f147d737e803033d2341854c214c26f`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`