mutastructura

This tool ensures your relational schema and database state is exactly as you decree, incrementally.

Compatible with SQLite3, MySQL and PostgreSQL. Write your schema migrations and seeding easily, and in your native database dialect.

Mutastructura provides a declarative, transactional approach to managing your database states:

• Written purely in Guile Scheme, bringing functional programming and S-expression elegance to your database migrations.
• Native dbi support: sqlite3 (TO FINALIZE! TBD! PostgreSQL and MySQL)
• Auto-installs the schema management migrations_history.
• Every migration is executed within a with-transaction block and so, transactionally (from BEGIN to COMMIT you could say).
• If a migration fails, the legion retreats (ROLLBACK), ensuring your database is never left in a corrupted, half-migrated state.
• Intelligent Parsing with a finite-state-machine-based SQL lexer (string-split-to-queries).
• Computes SHA256 checksums of your migration files and tracks them in a migrations_history table, ensuring your schema evolution is strictly linear and tamper-evident.

mutastructura is officially distributed via:

• Guix package manager - as mutastructura from (gnu packages databases) - or from the source code here
• Podman/Docker images.

That being said, feel free to use it as you wish, within the terms of the GNU Affero General Public License v3 or newer.

guix package --install-from-file=./guix.scm

guix time-machine --channels=channels.scm -- shell -f guix.scm

guix time-machine --channels=channels.scm -- \
     shell -f guix.scm -- mutastructura \
     --database sqlite3 \
     --connection ./lucidplan-test.sqlite  \
     --migrations ./migrations/lucidplan

guix time-machine --channels=channels.scm -- \
     shell -m manifest.scm -- guile -L ./src -c '((@(mutastructura main) main))' \
     --database sqlite3 \
     --connection ./lucidplan-test.sqlite \
     --migrations ./migrations/lucidplan \
     --resources ./resources

 docker container run -v /home/joe:/home/joe \
     docker.io/jjba23/mutastructura:latest mutastructura --help

The project is written mostly in Lisp (Guile Scheme) and uses Maak, the infinitely extensible command-runner as automation system with GNU Guix package manager and build system, making reproducibility and devex first-class concerns, not afterthoughts.

See a quick help page:

Run easily and reproducibly with Maak + Guix, or use directly Guile, or load a REPL (like Arei)

maak run # or maak dev-run
# or
guix time-machine --channels=channels.scm -- \
     shell -f guix.scm -- mutastructura \
     --database sqlite3 \
     --connection ./lucidplan-test.sqlite \
     --migrations ./migrations/lucidplan

When invoked, Mutastructura:

• Opens a connection to your specified database engine.
• Queries the historical ledger (migrations_history) to see which migrations have already run, and crossed the Rubicon.
• If no history exists, it initializes the schema via platform-specific genesis files (mutastructura-init.sql).
• Scans your provided migrations directory, and gets migrations to run, in chronological + alphabetical order based on filename (anything works, but the best naming for this purpose is in the shape of YYYY-MM-DD_HH:MM:SS_some-name.sql, e.g. 2026-04-01_21:54:00_init.sql)
• Generates SHA256 hashes for each file. Changing the file contents means changing the SHA and will trigger a WARNING
• Safely splits the SQL files into individual statements.
• Executes the statements synchronously.
• Commits the transaction and gracefully closes the connection.

Mutastructura follows a classic functional-core, imperative-shell architecture, divided into distinct modules that handle specific responsibilities.

Migrations whose name ends in *.repeatable.sql will be deemed as repeatable and thus always executed.

mutastructura and all of its source code are free software, licensed under the GNU Affero General Public License v3 (or newer at your convenience).

https://www.gnu.org/licenses/agpl-3.0.html

The documentation and examples, including this document, which are provided with mutastructura, are all licensed under the GNU Free Documentation License v1.3 (or newer at your convenience).

https://www.gnu.org/licenses/fdl-1.3.html

A REPL (Read-Eval-Print Loop) is an interactive environment, which can be used connected to your console, running application, language compiler and more, which gives you superpowers as an engineer 🦸🏼.

Lisp dialects, more specifically Guile Scheme, have great support for this. I personally of course like to do this with Guix, Emacs, (Arei/Ares + sesman) you can get an ultimate extensible powerful editor experience, miles ahead of traditional IDEs 🐂 .

It fundamentally changes the development workflow by eliminating the slow edit, save, compile, run cycle. Instead of writing a whole program and then running it to see what happens, you get a fast, conversational workflow. What does this mean for in practice?

• Incremental Development: Write, test, inspect, evaluate one function or even one line at a time. Get immediate feedback without running the entire app.
• Powerful Debugging: Forget adding print statements and restarting. You can pause, inspect objects, change values, and even redefine a broken function on the fly to test a fix in any environment (yes even in production, while running).
• Fast Prototyping & Learning: Instantly experiment with a new library or API. Just load it and start calling functions to see how they work, which is much faster than only reading documentation.

When integrated into your code editor, you can execute any piece of code (a line, a selection, or a file) with a keyboard shortcut and see the result instantly, creating a seamless and powerful development experience.

This project adheres to the jointhefreeworld code of conduct. Find it here:

https://jointhefreeworld.org/blog/articles/personal/jointhefreeworld-code-of-conduct/index.html

In summary, we foster an inclusive, respectful, and cooperative environment for all contributors and users of this free software project. Inspired by the ideals of the GNU Project, we strive to uphold freedom, equality, and community as guiding principles. We believe that collaboration in a community of mutual respect is essential to creating excellent free software.