supabase-migrator

library1.1.4jsnpmunverified

Supabase Migrator (v1.1.4) is a comprehensive migration and cleanup toolkit for Supabase PostgreSQL databases. It provides automated schema migrations, backup/restore, and database cleanup operations specifically tailored for Supabase projects. Features include migration versioning, dry-run support, and built-in safety checks to prevent accidental data loss. Released regularly with fixes and updates. Differentiates from generic migration tools by understanding Supabase's specific object types (auth, storage, realtime) and offering cleanup commands for orphaned records.

database devops

npm install supabase-migrator

package ↗

INSTALL

IMPORT

SIG · SUPABASE-MIGRATOR

supabase-migrator

databasejavascriptv1.1.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

supabaseMigrator

✓ import { supabaseMigrator } from 'supabase-migrator'

✗ const { supabaseMigrator } = require('supabase-migrator')

ESM-only; named export. CJS require will fail.

runMigrations

✓ import { runMigrations } from 'supabase-migrator'

✗ import runMigrations from 'supabase-migrator'

Named export, not default.

cleanupDatabase

✓ import { cleanupDatabase } from 'supabase-migrator'

✗ import { cleanDatabase } from 'supabase-migrator'

Function is named cleanupDatabase, not cleanDatabase.

backupDatabase

✓ import { backupDatabase } from 'supabase-migrator'

Named export for backup functionality.

Initializes the migrator with a Supabase client, runs migrations with dry-run, then performs backup and cleanup.

import { supabaseMigrator } from 'supabase-migrator'; import { createClient } from '@supabase/supabase-js'; async function migrate() { const supabase = createClient(process.env.SUPABASE_URL ?? '', process.env.SUPABASE_KEY ?? ''); const migrator = supabaseMigrator({ supabase }); // Dry-run first await migrator.runMigrations({ dryRun: true }); // Apply migrations await migrator.runMigrations(); // Backup await migrator.backupDatabase({ output: './backup.sql' }); // Cleanup orphaned rows await migrator.cleanupDatabase(); } migrate().catch(console.error);

Debug

Known issues

breakingRequires @supabase/supabase-js v2 or higher. v1 will cause runtime errors.

fix

Upgrade @supabase/supabase-js to version 2+.

affects: <2.0.0

gotchaDry-run mode does not guarantee no side effects; some SQL triggers may still fire.

fix

Always test on a staging database first.

affects: >=1.0.0

deprecatedThe `supabaseMigrator` default export is deprecated; use named export instead.

fix

Replace `import supabaseMigrator from 'supabase-migrator'` with `import { supabaseMigrator } from 'supabase-migrator'`.

affects: >=1.1.0

gotchaThe `cleanupDatabase` function does not affect realtime subscriptions; you must clean them separately.

fix

Use Supabase Admin API to manage realtime subscriptions.

affects: >=1.0.0

Errors

Common errors & fixes

Error: supabaseMigrator is not a function

Using default import instead of named import.

fix

import { supabaseMigrator } from 'supabase-migrator';

Cannot find module 'supabase-migrator' (or its corresponding type declarations)

ESM-only module; installed as CommonJS or missing 'type': 'module' in package.json.

fix

Add "type": "module" to package.json and use import syntax.

TypeError: supabase is not defined

Missing or misconfigured Supabase client.

fix

Ensure createClient is called with valid SUPABASE_URL and SUPABASE_KEY.

Error: Migration already applied: 2023-01-01_init

Migration has already been run. Use --force or rollback first.

fix

Use migrator.rollback() to revert the migration or set force: true.

Upgrade

Version history

1.1.4latest on npm

Audit

Dependencies

@supabase/supabase-jsrequiredRequired for interacting with Supabase APIs beyond raw SQL.

Agent activity

21 hits · last 30 days

node