fraiseql-confiture 0.3.2

PostgreSQL migrations, sweetly done 🍓

Confiture 🍓

PostgreSQL migrations, sweetly done

Confiture is the official migration tool for FraiseQL, designed with a build-from-scratch philosophy and 4 migration strategies to handle every scenario from local development to zero-downtime production deployments.

Part of the FraiseQL ecosystem - While Confiture works standalone for any PostgreSQL project, it's designed to integrate seamlessly with FraiseQL's GraphQL-first approach.

---

Why Confiture?

Traditional migration tools (Alembic, Django migrations) replay migration history to build databases. This is slow and brittle.

Confiture treats DDL source files as the single source of truth:

• ✅ Fresh databases in <1 second (not minutes)
• ✅ 4 migration strategies (simple ALTER to zero-downtime FDW)
• ✅ Production data sync built-in (with PII anonymization)
• ✅ Python + Rust performance (10-50x faster than pure Python)
• ✅ Perfect with FraiseQL, useful for everyone

---

The Four Mediums

1️⃣ Build from DDL

confiture build --env production

Build fresh database from db/schema/ DDL files in <1 second.

2️⃣ Incremental Migrations (ALTER)

confiture migrate up

Apply migrations to existing database (simple schema changes).

3️⃣ Production Data Sync

confiture sync --from production --anonymize users.email

Copy production data to local/staging with PII anonymization.

4️⃣ Schema-to-Schema Migration (Zero-Downtime)

confiture migrate schema-to-schema --strategy fdw

Complex migrations via FDW with 0-5 second downtime.

---

Quick Start

Installation

pip install fraiseql-confiture

# Or with FraiseQL integration
pip install fraiseql-confiture[fraiseql]

Initialize Project

confiture init

Creates:

db/
├── schema/           # DDL: CREATE TABLE, views, functions
│   ├── 00_common/
│   ├── 10_tables/
│   └── 20_views/
├── seeds/            # INSERT: Environment-specific test data
│   ├── common/
│   ├── development/
│   └── test/
├── migrations/       # Generated migration files
└── environments/     # Environment configurations
    ├── local.yaml
    ├── test.yaml
    └── production.yaml

Build Schema

# Build local database
confiture build --env local

# Build production schema
confiture build --env production

Create Migration

# Edit schema
vim db/schema/10_tables/users.sql

# Generate migration
confiture migrate generate --name "add_user_bio"

# Apply migration
confiture migrate up

---

Documentation

📖 User Guides

• Medium 1: Build from DDL - Fresh databases in <1 second
• Medium 2: Incremental Migrations - ALTER-based changes
• Medium 3: Production Data Sync - Copy and anonymize data
• Medium 4: Zero-Downtime Migrations - Schema-to-schema via FDW
• Migration Decision Tree - Choose the right strategy

📚 API Reference

• CLI Reference - All commands documented
• Configuration Reference - Environment configuration
• Schema Builder API - Building schemas programmatically
• Migrator API - Migration execution
• Syncer API - Production data sync
• Schema-to-Schema API - Zero-downtime migrations

💡 Examples

• Examples Overview - 5 complete production examples
• Basic Migration - Learn the fundamentals (15 min)
• FraiseQL Integration - GraphQL workflow (20 min)
• Zero-Downtime - Production deployment (30 min)
• Production Sync - PII anonymization (25 min)
• Multi-Environment Workflow - Complete CI/CD (30 min)

---

Features

✅ Complete (Phases 1-3)

Core Migration System:

• ✅ Build from DDL (Medium 1) - Fresh databases in <1 second
• ✅ Incremental migrations (Medium 2) - Simple ALTER-based changes
• ✅ Production data sync (Medium 3) - Copy with PII anonymization
• ✅ Zero-downtime migrations (Medium 4) - Schema-to-schema via FDW

Performance & Distribution:

• ✅ Rust performance layer (10-50x speedup) 🚀
• ✅ Binary wheels for Linux, macOS, Windows
• ✅ Parallel migration execution
• ✅ Progress tracking with resumability

Developer Experience:

• ✅ Environment-specific seed data (development/test/production)
• ✅ Schema diff detection with auto-generation
• ✅ CLI with rich terminal output and colors
• ✅ --force flag for migration reapplication
• ✅ Comprehensive documentation (5 guides, 4 API docs)
• ✅ Production-ready examples (5 complete scenarios)

Integration & Safety:

• ✅ FraiseQL GraphQL integration
• ✅ Multi-environment configuration
• ✅ Transaction safety with rollback support
• ✅ PII anonymization with compliance tools
• ✅ CI/CD pipeline examples (GitHub Actions)

🚧 Coming Soon (Phase 4)

• Advanced migration hooks (before/after)
• Custom anonymization strategies
• Interactive migration wizard
• Migration dry-run mode
• Database schema linting

---

Comparison

Feature	Alembic	pgroll	Confiture
Philosophy	Migration replay	Multi-version schema	Build-from-DDL
Fresh DB setup	Minutes	Minutes	<1 second
Zero-downtime	❌ No	✅ Yes	✅ Yes (FDW)
Production sync	❌ No	❌ No	✅ Built-in
Language	Python	Go	Python + Rust

---

Development Status

Current Version: 0.3.2 (Production Release) 🎉

Recent Updates (v0.3.2):

• ✅ --force flag for migration reapplication
• ✅ Comprehensive troubleshooting guide with 400+ lines
• ✅ database_url connection format support
• ✅ Enhanced CLI warnings and safety messages

Previous Release (v0.3.0):

• ✅ Hexadecimal file sorting for better schema organization
• ✅ Enhanced dynamic SQL file discovery
• ✅ Recursive directory support with improved performance

Milestone Progress:

• ✅ Phase 1: Python MVP (Complete - Oct 2025)
• ✅ Phase 2: Rust Performance Layer (Complete - Oct 2025)
• ✅ Phase 3: Production Features (Complete - Oct 2025)
  • ✅ Zero-downtime migrations (FDW)
  • ✅ Production data sync with PII anonymization
  • ✅ Comprehensive documentation (5 guides, 4 API references)
  • ✅ Production examples (5 complete scenarios)
• ✅ CI/CD & Release Pipeline (Complete - Nov 2025)
  • ✅ Multi-platform wheel building (Linux, macOS, Windows)
  • ✅ PyPI Trusted Publishing
  • ✅ Quality gate with comprehensive checks
  • ✅ Python 3.11, 3.12, 3.13 support verified
• ✅ v0.3.0: Enhanced Schema Building (Complete - Nov 2025)
  • ✅ Hexadecimal file sorting (0x01_, 0x0A_, etc.)
  • ✅ Dynamic discovery with patterns and filtering
  • ✅ Recursive directory support
  • ✅ Advanced configuration options
  • ✅ Comprehensive feature documentation
• ⏳ Phase 4: Advanced Features (Q1 2026)
  • Migration hooks, wizards, dry-run mode

Statistics:

• 📦 4 migration strategies implemented
• 📖 5 comprehensive user guides + 3 feature guides
• 📚 4 API reference pages
• 💡 5 production-ready examples
• 🧪 89% test coverage (258 tests) - 3 new test files added
• ⚡ 10-50x performance with Rust
• 🚀 Production-ready CI/CD pipeline
• 🔧 Advanced file discovery with hex sorting support

See PHASES.md for detailed roadmap.

---

Contributing

Contributions welcome! We'd love your help making Confiture even better.

Quick Start:

# Clone repository
git clone https://github.com/fraiseql/confiture.git
cd confiture

# Install dependencies (includes Rust build)
uv sync --all-extras

# Build Rust extension
uv run maturin develop

# Run tests
uv run pytest --cov=confiture

# Format code
uv run ruff format .

# Type checking
uv run mypy python/confiture/

Resources:

• CONTRIBUTING.md - Contributing guidelines
• CLAUDE.md - AI-assisted development guide
• PHASES.md - Detailed roadmap

What to contribute:

• 🐛 Bug fixes
• ✨ New features
• 📖 Documentation improvements
• 💡 New examples
• 🧪 Test coverage improvements

---

Author

Vibe-engineered by Lionel Hamayon 🍓

Confiture was crafted with care as the migration tool for the FraiseQL ecosystem, combining the elegance of Python with the performance of Rust, and the sweetness of strawberry jam.

---

License

MIT License - see LICENSE for details.

Copyright (c) 2025 Lionel Hamayon

---

Acknowledgments

• Inspired by printoptim_backend's build-from-scratch approach
• Built for FraiseQL GraphQL framework
• Influenced by pgroll, Alembic, and Reshape
• Developed with AI-assisted vibe engineering ✨

---

FraiseQL Ecosystem

Confiture is part of the FraiseQL family:

• FraiseQL - Modern GraphQL framework for Python
• Confiture - PostgreSQL migration tool (you are here)

---

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

Vibe-engineered with ❤️ by Lionel Hamayon

Documentation • GitHub • PyPI