Write script migrations
Use JavaScript or TypeScript for data transformations that are easier to express in code. Scripts run synchronously in an embedded engine without a Node.js runtime. Follow the installation instructions before continuing.
Create a script
migrate new version "normalize names" --format tsSupported formats are js, ts and mjs; .mjs has the same runtime restrictions as .js. Files use V<version>__<description>.<format> and share their version sequence and history with SQL files.
Implement the entrypoints
For a SQLite users table containing a text name column:
export function up(db) {
for (const row of db.query("SELECT id, name FROM users")) {
db.exec("UPDATE users SET name=? WHERE id=?", [row.name.trim(), row.id]);
}
}Generated up functions throw until implemented. Entrypoints must be synchronous: async functions, generators and Promise results are unsupported. Ordinary synchronous return values are ignored. SQL placeholders are dialect specific; see the database API.
Export down(db) only when you have implemented reversal. Trimming whitespace loses information, so this example deliberately has no down function. A rollback range containing a script without down is blocked. Preserve original values if you need that transformation to be reversible.
Preview and run
migrate up --dry-run
migrate up
migrate statusDry-run checks scripts and their imports and lists planned files without running them, so it cannot show dynamically generated SQL. Put database operations inside up(db) or down(db), not at module top level. Do not rely on global variables to share data between migrations.
Editor hints and script requirements
Generated JS templates annotate db with JSDoc; TS templates include equivalent type declarations. Transpilation does not type-check. The shared migration-api.d.ts can replace local declarations and be referenced with a triple-slash path comment.
Scripts can use JavaScript and the database API above, but cannot use Node built-ins, network, filesystem, environment or timer APIs, or load modules dynamically. Before importing an npm package, check that it does not depend on these features.
Continue with shared modules, transactions and limits, or the runnable examples.