Migrations & Seeds

Every time you need to change the database schema — add a table, add a column, modify a constraint — you write a migration. Every time you need consistent starting data (default roles, plans, admin users), you write a seed. Both use the same TypeScript file format and are run via Makefile commands inside Docker.

The file format

Both migrations and seeds export two functions: up (apply the change) and down (reverse it). They receive Sequelize’s queryInterface via the context object:

// apps/backend/src/tools/rds/sequelize/migrations/20250303045013-createUserTable.ts
import { Sequelize, DataTypes } from 'sequelize';

const TABLE_NAME = 'users';

export const up = async ({ context: { queryInterface } }) => {
  await queryInterface.createTable(TABLE_NAME, {
    id: {
      type: DataTypes.UUID,
      defaultValue: Sequelize.literal('uuid_generate_v4()'),
      primaryKey: true,
      allowNull: false,
    },
    email: {
      type: DataTypes.STRING,
      allowNull: false,
    },
    created_at: {
      type: DataTypes.DATE,
      allowNull: false,
      defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'),
    },
    updated_at: {
      type: DataTypes.DATE,
      allowNull: false,
      defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'),
    },
  });
};

export const down = async ({ context: { queryInterface } }) => {
  await queryInterface.dropTable(TABLE_NAME);
};

A few conventions to follow:

Column names use snake_case — that’s what Sequelize maps to camelCase in models.
Always include created_at and updated_at on new tables.
Always write a down function, even if it just drops the table. You’ll thank yourself when you need to roll back.

Make commands

# Apply all pending migrations
make migrate-up

# Roll back the last migration
make migrate-down

# Apply all pending seeds
make seed-up

# Roll back seeds
make seed-down

# Generate a new migration file with the right timestamp prefix
make create-migration name=addStripeCustomerIdToOrganizations

# Generate a new seed file
make create-seed name=createAdminUser

These all run inside the Docker container — Sequelize needs a live Postgres connection to work, and the container has it.

Adding a new table (step by step)

Generate the migration file
make create-migration name=createWidgets
This creates a timestamped file in apps/backend/src/tools/rds/sequelize/migrations/. Open it and fill in the up and down functions.

Write the migration Use queryInterface.createTable in up and queryInterface.dropTable in down:

export const up = async ({ context: { queryInterface } }) => {
  await queryInterface.createTable('widgets', {
    id: {
      type: DataTypes.UUID,
      defaultValue: Sequelize.literal('uuid_generate_v4()'),
      primaryKey: true,
      allowNull: false,
    },
    name: { type: DataTypes.STRING, allowNull: false },
    organization_id: {
      type: DataTypes.UUID,
      allowNull: false,
      references: { model: 'organizations', key: 'id' },
      onDelete: 'CASCADE',
    },
    created_at: {
      type: DataTypes.DATE,
      allowNull: false,
      defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'),
    },
    updated_at: {
      type: DataTypes.DATE,
      allowNull: false,
      defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'),
    },
  });
};

export const down = async ({ context: { queryInterface } }) => {
  await queryInterface.dropTable('widgets');
};

Run the migration
make migrate-up
Create a Sequelize model Add a new file in apps/backend/src/tools/rds/sequelize/models/widget.ts following the pattern of existing models.
Register the model Add it to the models index in apps/backend/src/tools/rds/sequelize/models/index.ts.
Verify
make test module=backend
The globalSetup in Jest runs migrate-up automatically before tests, so your new table will be present in the test database.

Adding a column to an existing table

For schema changes to existing tables, use addColumn / removeColumn:

export const up = async ({ context: { queryInterface } }) => {
  await queryInterface.addColumn('organizations', 'stripe_customer_id', {
    type: DataTypes.STRING,
    allowNull: true,
  });
};

export const down = async ({ context: { queryInterface } }) => {
  await queryInterface.removeColumn('organizations', 'stripe_customer_id');
};

⚠️ Watch out: if you’re adding a NOT NULL column to a table that already has rows, you need to either provide a defaultValue or do it in two steps: add the column as nullable, backfill data, then add a NOT NULL constraint. Doing it in one step on a table with existing data will fail.

Seeds

Seeds are for data that should always exist — default roles, product plans, an initial admin user. They follow the same up / down format:

// Prefer paymentProcessor.createProduct in app code (creates Stripe Product + Price
// and persists both products and prices rows).
// Manual seed sketch — products.external_id = prod_*; prices.external_id = price_*:
export const up = async ({ context: { queryInterface } }) => {
  await queryInterface.bulkInsert('products', [
    {
      name: 'Starter',
      type: 'recurring',
      external_id: 'prod_starter',
      metadata: JSON.stringify({ model: 'seat_based' }),
      is_default: false,
      // …
    },
  ]);
  await queryInterface.bulkInsert('prices', [
    {
      product_id: /* starter products.id */,
      external_id: 'price_starter',
      is_default: true,
      unit_amount: 2900,
      currency: 'USD',
      billing_period: 'month',
      quantity_based: 'manual',
      metadata: JSON.stringify({ resourceName: 'seat' }),
      // …
    },
  ]);
};

export const down = async ({ context: { queryInterface } }) => {
  await queryInterface.bulkDelete('prices', { external_id: 'price_starter' });
  await queryInterface.bulkDelete('products', { external_id: 'prod_starter' });
};

For new catalog work, use paymentProcessor.createProduct rather than hand-written seeds — it creates the Stripe Product + Price and persists both products and prices rows. See Billing — Product vs Price. Seeds run in timestamp order, just like migrations. make fresh-start runs both migrate-up and seed-up in sequence.

Operational one-offs are different. Schema migrations and seeds are not the place for targeted backfills or provider reconciliation. Use Operational Scripts for those CLIs (docker compose exec backend pnpx ts-node … locally, node apps/backend/dist/scripts/… in production).

What’s next?

Sequelize tooling — how the Sequelize model layer is set up.
Monorepo — workspace structure and how packages reference each other.
Testing — how Jest’s globalSetup automatically applies migrations before tests.

Getting Started

Architecture

Frontend

Deployment

Quality

Reference

Migrations & Seeds

Migrations & Seeds

The file format

Make commands

Adding a new table (step by step)

Adding a column to an existing table

Seeds

What’s next?

​Migrations & Seeds

​The file format

​Make commands

​Adding a new table (step by step)

​Adding a column to an existing table

​Seeds

​What’s next?

Migrations & Seeds

The file format

Make commands

Adding a new table (step by step)

Adding a column to an existing table

Seeds

What’s next?