Migrations

Migrations

Migrations are optional in jsorm. If a database already exists, you can connect and use models immediately.

Define a migration source

import {
  addColumn,
  createTable,
  defineMigration,
  defineMigrationSource,
  migrate,
  t,
} from 'jsorm';
import { pgAdapter } from 'jsorm-pg';

const initUsers = defineMigration('init-users', [createTable(User)]);
const addActive = defineMigration('add-user-active', [
  addColumn('users', 'isActive', t.boolean().default(true).index()),
]);

const source = defineMigrationSource({
  adapter: pgAdapter({
    name: 'main',
    connectionString: process.env.DATABASE_URL!,
  }),
  migrations: [initUsers, addActive],
  migrationTable: 'jsorm_migrations',
});

await migrate(source);

Why optional matters

• legacy databases can be onboarded faster
• teams can adopt the query layer before schema automation
• runtime safety stays separated from schema evolution concerns

Best practices

1. Keep migration files ordered and small.
2. Use explicit down SQL when a step is not automatically reversible.
3. Treat destructive commands as environment-sensitive operations.