A database migration solution for use with the libSQL client in Node
npm install @deadcode-uk/mutatioA database migration solution for use with the libSQL client in Node
Installation
``
npm install @deadcode-uk/mutatio
Peer Dependencies
Your project will need to include the following packages:
`
@libsql/client
dotenv
Environment Variables
Mutatio depends on the following environment variables being available:
`
DATABASE_URL // required
DATABASE_AUTH_TOKEN // required for hosted databases, e.g. Turso
DATABASE_ENCRYPTION_KEY // optional
These variables should be in a .env file in the project root directory, they are used to create a libSQL client when applying and reverting migrations
Mutatio has primarily been created for my own use in projects that use libSQL, so it is opinionated for consistency reasons
Database migrations will be created in a migrations directory in the project root
`
/migrations <- migrations live in this directory
/node_modules
/src
/readme.md
/package.json
Migration files are JavaScript modules that export two functions, apply and revert, both of which must return a Promise
`js
import { sqlite } from "@deadcode-uk/archivum"
/**
* @param {import("@libsql/client").Client} client
* @returns {Promise
*/
export async function apply(client) {
await client.execute(sqlite
CREATE TABLE example (
id INTEGER PRIMARY KEY AUTOINCREMENT,
created_at INTEGER DEFAULT (unixepoch()),
updated_at INTEGER DEFAULT (unixepoch())
)
)
}
/**
* @param {import("@libsql/client").Client} client
* @returns {Promise
*/
export async function revert(client) {
await client.execute(sqlite
DROP TABLE IF EXISTS example
)`
}
You can do whatever you need to do in those functions to apply migrations and revert migrations
Within your database, a table called migrations will be created the first time migrations are applied, and will be used to track which migrations have been applied
Use the following command to create a migration, where is the name of the migration to create:
`
npx mutatio create
For example, npx mutatio create add-core-tables would create a file similar to this:
`
/migrations/20250706123456-add-core-tables.js
File names can contain alpha-numeric characters and dashes. The name will be converted to lowercase automatically, dashes will be removed from the start and end of the name, and multiple dashes will be collapsed
An error will be thrown if the name is invalid or if the generated filename conflicts with an existing one
Use the following command to apply pending migrations:
`
npx mutatio apply
Use the following command to revert the latest batch of migrations that were applied with the apply command:
`
npx mutatio revert
You will more than likely want to apply migrations after the npm install command has been run, either locally or during a deployment. That is easy enough to setup in your package.json file:
`
{
"scripts": {
"postinstall": "npx mutatio apply",
...
}
}