How billuc/cigogne works
Project type and purpose
• This is an open-source CLI tool and library (not a full-stack app) written in Gleam that manages Postgres database migrations. It reads SQL files from disk, parses “up”/“down” sections, and applies or rolls back migrations against a Postgres database, tracking applied migrations (with hashes) and updating a local schema file.
File structure
• Top level:
• src/cigogne.gleam – CLI entrypoint module, exposes commands (up, down, last, apply, show, new, to_v3).
• src/cigogne/internal/ – four responsibility-driven modules:
– database.gleam: Connects to Postgres, runs SQL, reads/writes migrations history table.
– fs.gleam: Reads the migrations directory (priv/migrations), reads/writes schema file.
– migrations.gleam: Parses .sql files into up/down statements.
– utils.gleam: Common helpers (hashing, error formatting).
• src/cigogne/to_v3.gleam – migration helper for upgrading older migration formats to v3.
• src/cigogne/types.gleam – core data types (Migration, Query, etc.).
• Tests mirror the internal modules, confirming separation of concerns.
README insights
• Commands are invoked via gleam run -m cigogne <command>.
• Environment: reads DATABASE_URL.
• Workflow: read .sql files named <timestamp>-<name>.sql, split sections by --- migration:up/down/end, apply to DB, record hashes, update schema file.
• Integrates well with squirrel (a SQL builder).
1. CLI Entrypoint (cigogne.gleam)
2. Configuration Loader (reads env var, CLI args)
3. Migration Service / Manager (core orchestrator)
4. File System Module (fs)
5. Parser Module (migrations)
6. Database Module (database)
7. Schema File Updater (also fs)
8. Hash & Utils Module (utils)
9. Legacy Script (to_v3)
10. External Systems: Postgres DB, Local Filesystem, Environment Variables
• CLI → Configuration Loader: “parse command & options”
• Configuration Loader → Migration Service: “command + config”
• Migration Service → File System Module: “list & read .sql files”
• File System → Parser Module: “raw SQL text”
• Parser → Migration Service: “up/down queries list”
• Migration Service → Database Module: “execute SQL batch”
• Database Module ↔ Postgres: “SQL over TCP”
• Database Module → Utils: “compute/check hash”
• Migration Service → Schema File Updater: “write updated schema file”
• Migration Service → CLI: “return result or error”
• CLI → stdout/stderr: “display status or errors”
• CLI → Legacy Script (to_v3): “if invoked”
c. Architectural patterns & principles
• Layered architecture:
• Presentation/CLI layer
• Service/Orchestration layer (Migration Service)
• Data Access layers (File System & DB modules)
• Single-Responsibility modules (internal/internal)
• Dependency injection of DB connection into Migration Service
• Extensibility point: adding new commands or file formats (to_v3)
d. Key technologies & frameworks
• Gleam (language & build)
• Postgres (external DB)
• Squirrel (optional SQL builder integration)
• File I/O via Gleam’s fs module
• CLI via gleam run -m