sc-migrate# sc-migrate

A CLI to simplify creating and running TypeORM migrations (ESM) for Node 20+ projects.A CLI to simplify creating and running TypeORM migrations (ESM) for Node 20+ projects.

Installation## Installation (Development)

You can use the CLI directly via npx (recommended) or install it as a development dependency in your project.You can use the CLI directly via npx (recommended) or install it as a development dependency in your project.

Using npx (recommended)- Using npx (without installing):

npx sc-migrate --help  - `npx sc-migrate --help`

• Install in the project (dev):

Install as dev dependency - npm i -D sc-migrate

npm i -D sc-migrateAfter installation, you can run it via:

• npx sc-migrate <command>

After installation, you can run it via:- or add scripts to your package.json (the init command suggests some scripts automatically).

• npx sc-migrate <command>

• Or add scripts to your package.json (the init command suggests some scripts automatically)## Configuration

Configuration- Set the DATABASE_URL variable in your .env file.

• The database type is inferred from the URL protocol (postgres:// or mysql://).

• Set the DATABASE_URL variable in your .env file- Example:

• The database type is inferred from the URL protocol (postgres:// or mysql://) - Postgres: DATABASE_URL=postgres://user:pass@host:5432/db?schema=public

  • MySQL: DATABASE_URL=mysql://user:pass@host:3306/db

Examples:

• Postgres: DATABASE_URL=postgres://user:pass@host:5432/db?schema=publicNotes:

• MySQL: DATABASE_URL=mysql://user:pass@host:3306/db

• Migrations folder: always src/migrations in your project.

Notes:- For column helpers, use the utilities exported directly from the library: import { idColumn, timestampColumn } from 'sc-migrate/utils'.

• Migrations folder: now src/typeorm/migrations in your project- Drivers: pg and mysql2 are already included in this library.

• For column helpers, use: import { idColumn, timestampColumn } from 'sc-migrate/utils'

• Drivers: pg and mysql2 are already included## Commands

Commands- init

init - Creates the src/migrations/ folder and suggests scripts for package.json.

Creates the typeorm/migrations/ folder and suggests scripts for package.json. - If DATABASE_URL is missing, it prints instructions for you to set it up in your .env file.

If DATABASE_URL is missing, it prints instructions for setup in your .env file.

• create <name>

create <name>

Creates a manual migration file in src/typeorm/migrations/ with an ESM/TypeScript template.

show- show

Lists migrations (applied/pending) using the TypeORM CLI.

• Lists migrations (applied/pending) using the TypeORM CLI.

up

Applies pending migrations.- up

down - Applies pending migrations.

Reverts the last applied migration.

• down

check

Tests the database connection. - Reverts the last applied migration.

Quick Start## Quick Start

1. **Initialize the structure:**1. Initialize the structure:

   
   npx sc-migrate init    - `npx sc-migrate init`
   

2. Configure your .env with DATABASE_URL:

3. Configure your .env with DATABASE_URL:

   
   DATABASE_URL=postgres://user:pass@host:5432/db?schema=public
   
   ```3.  Create your first migration:
   

4. Create your first migration: - npx sc-migrate create add-users-table

   
   npx sc-migrate create add-users-table4.  Apply migrations:
   

   • npx sc-migrate up

5. Apply migrations:

   
   npx sc-migrate up    - `npx sc-migrate show`
   

Imports (Types and Utils)

5. Check status:

   
   npx sc-migrate show
   
   ```- Root:

Imports (Types and Utils) - import { idColumn, timestampColumn } from 'sc-migrate'

• import type { TimestampColumnName, CommonDataSourceOptions } from 'sc-migrate'

You can import helpers and types from the root or subpaths:

• Subpaths:

Root imports: - import { idColumn, timestampColumn } from 'sc-migrate/utils'

```typescript - import type { TimestampColumnName } from 'sc-migrate/types'

import { idColumn, timestampColumn } from 'sc-migrate'

import type { TimestampColumnName, CommonDataSourceOptions } from 'sc-migrate'If VS Code doesn't suggest auto-imports at first, run “TypeScript: Restart TS server” and reinstall the dependency (npm i sc-migrate@latest).

## Technical Notes

### Subpath imports:

```typescript- ESM: This CLI is ESM-native and uses `ts-node/esm` to orchestrate the TypeORM CLI.

import { idColumn, timestampColumn } from 'sc-migrate/utils'- Duplicate migrations: The CLI selects only `.ts` files if they exist, otherwise `.js`, to avoid duplication.

import type { TimestampColumnName } from 'sc-migrate/types'- Drivers: Postgres uses `pg`; MySQL uses `mysql2` (both are included).

```- Node: Tested on Node 20+.



## Technical Notes## Common Issues



- **ESM**: This CLI is ESM-native and uses `ts-node/esm` to orchestrate the TypeORM CLI- Duplicate migrations: Ensure that only one extension (`.ts` or `.js`) is present in `src/migrations/`.

- **Duplicate migrations**: The CLI selects only `.ts` files if they exist, otherwise `.js`, to avoid duplication- `DATABASE_URL` missing: Add it to your `.env` file. The CLI does not prompt for it; it only instructs on the correct format.
- **Drivers**: Postgres uses `pg`; MySQL uses `mysql2` (both are included)
- **Node**: Requires Node 20+

## Troubleshooting

- **Duplicate migrations**: Ensure that only one extension (`.ts` or `.js`) is present in `typeorm/migrations/`
- **`DATABASE_URL` missing**: Add it to your `.env` file. The CLI does not prompt for it; it only instructs on the correct format
- **VS Code auto-import**: If auto-imports don't work initially, run "TypeScript: Restart TS server" and reinstall the dependency (`npm i sc-migrate@latest`)