# Migrate SDK

> TypeScript SDK for defining and running resumable data migrations between APIs, databases, files, and CMSes using Effect.

Migrate SDK is an open-source TypeScript library by Alexei Gorobet for moving data between APIs, databases, files, and CMSes. Migrations are defined in code with Effect, using your own clients and mapping logic. Progress is saved per item so interrupted runs can resume.

## What It Is

Migrate SDK is a data migration framework where each migration is a single definition connecting a Source, a processing pipeline, tracking, optional rollback, and a Migration Store. A Source emits typed items with a payload schema, stable identity, and version. The process step decodes each item and calls a destination helper that validates its own schema-defined input.

## How Runs Work

A Tracking Record Contract defines the durable result each successful item must preserve, such as a destination path. Saved state lets later runs skip unchanged items, retry failures, and resume where they stopped. A Rollback Pipeline uses the saved tracking evidence to undo destination work without reading the source again.

Migrations can be selected individually, by group, or all at once, with declared requirements determining execution order. Runs can be limited by item count or targeted at specific source IDs.

## Deployment Model

The SDK can run directly inside an application, a cron job, or a webhook, or through the bundled `migrate` CLI and an optional terminal UI. A migration server can be added for remote access, and the TUI can follow runs started elsewhere. With Workflow SDK, execution is durable and can continue after the starting request ends. Code and migration state stay in your own infrastructure, with file, SQL, or custom store options. A Files SDK integration adds a file Source, Destination helpers, and an optional store.

## Setup Path

Install with pnpm along with Effect; Node.js 22.19.0 or newer is required. The optional TUI is distributed as compiled executables for macOS, Linux, and Windows x64. The documentation includes a getting-started guide and a cookbook of complete recipes, and a live demo runs PostgreSQL catalog migrations through Vercel Workflow.

## Features
- Typed sources with schema, stable identity, and versioning
- Per-item progress tracking with resume and skipping of unchanged items
- Retry of failures with exponential backoff
- Rollback from saved tracking records
- Dependency-aware migration ordering
- Run selection by group, item limit, or specific source IDs
- CLI and terminal UI for local or remote operation
- Optional migration server for remote runs
- Durable execution with Workflow SDK
- Pluggable migration stores (file, SQL, custom)
- Files SDK integration for file migrations

## Integrations
Effect, Workflow SDK, Vercel Workflow, PostgreSQL, Files SDK, Node.js, Bun, Deno

## Platforms
WINDOWS, MACOS, LINUX, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
0.17.1

## Links
- Website: https://www.migrate-sdk.dev
- Documentation: https://www.migrate-sdk.dev/docs
- Repository: https://github.com/asgorobets/migrate-sdk
- EveryDev.ai: https://www.everydev.ai/tools/migrate-sdk