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.
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 Nodb/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'sconn.transaction(), or wrapDO $$ … 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
- 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 --dumpartifacts,test-dbtemplate/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 bootstrapfor one-shot env ownership setup. - Superuser Migrations —
requires_superuser = True+migrate apply-asrecovery workflow. - Function Uniqueness —
func_001catches duplicateCREATE FUNCTIONacross DDL files. - Security-Definer Lint —
sec_002flagsSECURITY DEFINERfunctions/procedures that don't pinsearch_path(CVE-2018-1058); static DDL scan and livepg_procpath;--emit-remediationgenerates ALTER scripts. - Named Schemas
- Hooks
- pgGit branching and multi-agent coordination — a plugin since 1.16, not part of confiture's core.
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
- JSON schemas are published for the
--format jsonoutput ofbuild,drift,introspect,lint,schema dump-model,sync,validate-config,verify-checksumsand, in the migrate family,migrate up,migrate down-to,migrate status,migrate current,migrate diff,migrate fix,migrate introspect,migrate preflight,migrate steps,migrate validateandmigrate verify. They ship in the package (python/confiture/schemas/) and are mirrored underdocs/reference/json-schemas/; a test asserts the mirror equals the packaged source (seedocs/reference/json-schemas.md). The other commands' JSON payloads are stable but not schema-backed yet. - On an error path in
--format jsonmode, 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 jsonexposes 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. 🍓→🍯
1 maintainer
Release files for fraiseql-confiture 1.21.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| fraiseql_confiture-1.21.0.tar.gz | 3.5 MB | Details |
Built distributions (wheels)
Total release size: 17.5 MB
Release files / fraiseql_confiture-1.21.0.tar.gz
| Download URL | fraiseql_confiture-1.21.0.tar.gz |
|---|---|
| Size | 3.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0846000866e1f43c27b75136b2cc689d5a1d2c850754508e5df725602bd64e94
|
|
BLAKE2b-256 checksum How to use checksums |
4dcd640bc3a2ce6c0e59ab79250ccf2491300b1df850743c822a2bed96c7a472
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-1.21.0-cp314-cp314-win_amd64.whl
| Download URL | fraiseql_confiture-1.21.0-cp314-cp314-win_amd64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.14 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
64a9097b0eea822c51d2bbc91da3de604fd83c90511dfce29ada46fcf2903f65
|
|
BLAKE2b-256 checksum How to use checksums |
f13a634912fd1dba6f19dc14c2f8c684ccd5ff7d75c8fc075d4697cb3f96d27d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-1.21.0-cp313-cp313-win_amd64.whl
| Download URL | fraiseql_confiture-1.21.0-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
abf35bb1029334eb6a4d724c48c1832f1f402fece5d8dd8dcfe578f690d39276
|
|
BLAKE2b-256 checksum How to use checksums |
f0ca2a6c88090c7c815d97edcdfbdba3b03ae175bee39caa28d37b1a198efcc2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-1.21.0-cp313-cp313-manylinux_2_28_x86_64.whl
| Download URL | fraiseql_confiture-1.21.0-cp313-cp313-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
a26beca4e55791eba16d9309238a31bdde4942edac209be253cfd7ccb952dea4
|
|
BLAKE2b-256 checksum How to use checksums |
c5f770fc2bd05c49fa2337088743f16301ca8d02e3ded3b2a6a04fe2eee70397
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-1.21.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | fraiseql_confiture-1.21.0-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
1df8df6129422bc8a4432574c6db2427b133368577c6467ba52c2a3ca86b10c9
|
|
BLAKE2b-256 checksum How to use checksums |
6b5f0d5208b0bb1cddde1df88e7b8598176cf5e139a0ddf8a6b9e7d92e4fc3f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-1.21.0-cp312-cp312-win_amd64.whl
| Download URL | fraiseql_confiture-1.21.0-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
02d620d3dab6cd4ac3592346a5efaeacca3d307d2ea1206170f94e43682b7486
|
|
BLAKE2b-256 checksum How to use checksums |
059101973a770311efea1c9771c4f9e0eed1341a76d73928d478ebcb337217f4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-1.21.0-cp312-cp312-manylinux_2_28_x86_64.whl
| Download URL | fraiseql_confiture-1.21.0-cp312-cp312-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
6b06bd21ad6bb3c1adf121e85b15052a330fde3192ea6c65c528bba518c126cb
|
|
BLAKE2b-256 checksum How to use checksums |
0f2e63f8a2f72fed9a2e6ad4a7e3bf6015fc51b75f06257abf32ceb076d44a6f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-1.21.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | fraiseql_confiture-1.21.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
0289946cc909a6e392ab88a3a52930530f3f1ae3a748d70e93798d6cf7386f0e
|
|
BLAKE2b-256 checksum How to use checksums |
1892acb21e5aed4a6210047f5fc2a88385843b31148e30d2f611a1c5fc887c04
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-1.21.0-cp311-cp311-win_amd64.whl
| Download URL | fraiseql_confiture-1.21.0-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
ac11df8025a3fe0dad635fa6699361e0a34f77a3400838510466d042e5184926
|
|
BLAKE2b-256 checksum How to use checksums |
c248da6e7edbae9b7eba9c2805198e6ee0c9f6bde06ece26b1a2a9579ae9dd2a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-1.21.0-cp311-cp311-manylinux_2_28_x86_64.whl
| Download URL | fraiseql_confiture-1.21.0-cp311-cp311-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
fc33fd46fc41ce4bfe637f1d84eb70109f0159e91e764e80dfe11d357c8dac01
|
|
BLAKE2b-256 checksum How to use checksums |
86affdca1ca792517ecdfe5dd263dd47a66cf389e117e077aab0788a6361d09c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-1.21.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | fraiseql_confiture-1.21.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
a42d5dfeaad97511166600a33be7dc6d3ccb49b4a585a5e7ab48101184f734b1
|
|
BLAKE2b-256 checksum How to use checksums |
23952d833767d76c47cabe35f346ab8b690cf6f24193df550089e91050af1bf6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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}
|
