DB Migrate TypeScript Plugin

2.0.0 · maintenance · verified Sun Apr 19

This package provides a plugin for `db-migrate` that enables the use of TypeScript for database migration files. It automatically transpiles `.ts` files found in the migration directory using your project's `tsconfig.json`. The current stable version is 2.0.0, released in December 2017. As a plugin, its release cadence is tied to the `db-migrate` ecosystem, but its own updates have been infrequent. Key differentiators include seamless integration with `db-migrate` for TypeScript-based migrations, leveraging existing `tsconfig.json` configurations, and simplifying database schema management for TypeScript projects without requiring manual transpilation steps. It requires `ts-node` as a peer dependency for runtime TypeScript compilation.

Common errors

```
Error: Cannot find module 'ts-node' from '<path>'
```
cause The `ts-node` package, a peer dependency, is not installed in the project.

fix Install `ts-node` explicitly: `npm install ts-node` or `yarn add ts-node`.
```
Migration file '<filename>' not found or could not be loaded
```
cause The plugin might not be correctly recognized by `db-migrate`, or the migration file does not end with the expected `.ts` extension.

fix Ensure `db-migrate-plugin-typescript` is installed and listed in your `package.json`. Verify that your migration files are named with a `.ts` extension (e.g., `123456789_create_table.ts`).
```
SyntaxError: Cannot use import statement outside a module
```
cause `ts-node` or your `tsconfig.json` is misconfigured, preventing proper transpilation of ES module syntax to CommonJS (which Node.js typically expects outside of explicit ESM projects).

fix Verify that `ts-node` is installed and that your `tsconfig.json` is correctly set up. Ensure `compilerOptions.module` is set to `"CommonJS"` (or compatible) if you are running Node.js in a CJS context, and `compilerOptions.esModuleInterop` is `true`.

Warnings

breaking In version 2.0.0, `ts-node` was changed from a direct dependency to a peer dependency. If you upgrade to v2.0.0 or later, `ts-node` must be explicitly installed in your project.
Fix: Explicitly install `ts-node` as a direct or dev dependency: `npm install ts-node` or `yarn add ts-node`.
gotcha The `db-migrate create <name>` command does not generate TypeScript files. It will create a `.js` file, even with this plugin installed.
Fix: After running `db-migrate create MyMigration`, manually rename the generated JavaScript file (e.g., `MyMigration.js`) to a TypeScript file (e.g., `MyMigration.ts`) and convert its contents to TypeScript.
gotcha The last release (v2.0.0) was in December 2017. This may lead to compatibility issues with newer Node.js, TypeScript versions, or recent `db-migrate` updates.
Fix: Test thoroughly with your current environment (Node.js, TypeScript, `db-migrate` versions). Be prepared for potential compatibility problems and consider contributing to the project or seeking alternatives if persistent issues arise.

Install

npm install db-migrate-plugin-typescript npm
yarn add db-migrate-plugin-typescript yarn
pnpm add db-migrate-plugin-typescript pnpm

Imports

db-migrate-plugin-typescript
```
npm install db-migrate-plugin-typescript ts-node
```
This package is a db-migrate plugin and is not directly imported into user code. It is loaded by db-migrate automatically once installed. Its primary interaction is via the file system for migration files and its configuration via tsconfig.json.
Migration interface
```
import { Migration } from 'db-migrate';
```
While this plugin enables TypeScript, the core Migration interface comes from `db-migrate` itself (or its associated types). Ensure `@types/db-migrate` is installed if you want type checking within your migration files.

Quickstart

This quickstart demonstrates how to configure `tsconfig.json` for TypeScript migrations and provides an example of a `.ts` migration file. It also shows the npm commands to install the plugin and `ts-node`.

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "CommonJS",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./migrations"
  },
  "include": ["./migrations/**/*.ts"]
}

// migrations/1678886400000_create_users_table.ts
import { Migration } from 'db-migrate';

export const up: Migration = async (db) => {
  await db.createTable('users', {
    id: { type: 'int', primaryKey: true, autoIncrement: true },
    name: { type: 'string', length: 50, notNull: true },
    email: { type: 'string', length: 100, notNull: true, unique: true },
    created_at: { type: 'timestamp', notNull: true, defaultValue: new Date() }
  });
};

export const down: Migration = async (db) => {
  await db.dropTable('users');
};

// To install: npm install db-migrate db-migrate-plugin-typescript ts-node @types/db-migrate --save-dev
// To run: db-migrate up

view raw JSON →