scribase-migrate/bin/scribase-migrate.mjs
2026-11-17 20:19:20 +03:00

309 lines
13 KiB
JavaScript
Executable File

#!/usr/bin/env node
/**
* scribase-migrate — one command to move a team onto Scribase from
* Supabase, Neon, Clerk and Resend. See README.md for the full flag
* reference; `scribase-migrate <source> --help` prints that source's.
*/
import { parseArgs } from 'node:util';
import { writeFile, mkdir, readFile } from 'node:fs/promises';
import { dirname } from 'node:path';
import { scribaseClient } from '../lib/client.mjs';
import { ensureProject } from '../lib/project.mjs';
import { migrateSupabase } from '../lib/sources/supabase.mjs';
import { migrateNeon, verifyRowCounts } from '../lib/sources/neon.mjs';
import { exportClerkUsers, createGoTrueUsers } from '../lib/sources/clerk.mjs';
import { exportResend } from '../lib/sources/resend.mjs';
const CTA_URL = 'https://scribase.com/migrate?utm_source=cli&utm_medium=cli-output&utm_campaign=scribase-migrate';
const CTA_LINE = `Scribase: Postgres, auth, storage and email on one account. Migration guide: ${CTA_URL}`;
const SIGNUP_URL = 'https://console.scribase.com/signup?utm_source=cli&utm_medium=cli-output&utm_campaign=scribase-migrate';
const REGION_DEFAULT = 'us-east';
const KIND_DEFAULT = 'production';
const SOURCES = ['supabase', 'neon', 'clerk', 'resend', 'project-info'];
const USAGE = `scribase-migrate <source> [flags]
Sources:
supabase Postgres schema+data, auth.users (password hashes), storage — one real API call
neon Postgres schema+data (branches -> branch_<name> schemas)
clerk Users (email/phone/metadata), created with a one-time password + reset flag
resend Sending domains + broadcast templates, exported as a re-importable JSON bundle
Shared destination flags:
--to <org>/<project>/<environment> Scribase destination (default environment: production)
Not needed for resend, or for clerk with both --target-* flags
--create-project Create the project+environment first if missing
--region <region> Region for --create-project (default us-east)
--kind <preview|staging|production> Environment kind for --create-project (default production;
note: production cannot be deleted later — use preview to try this out)
--dry-run Plan only, write nothing
--out <path> Write the full JSON result here too
--json Print only the JSON result to stdout
supabase flags:
--source-ref <ref> --source-url <postgres://...> --source-service-key <key>
--verify-login-email <email> [--verify-login-password <password>]
--no-storage
neon flags (also works for any plain Postgres; needs pg_dump installed):
--source-url <postgres://...>
--schema <name> (repeatable; default public)
--migrate-auth-users Also copy an auth.users-shaped table's rows
--branch name=<url> (repeatable; each lands in branch_<name>)
--verify-row-counts <schema.table> (repeatable)
clerk flags:
--secret-key <sk_...>
--target-api-url <url> --target-service-key <key> (from \`scribase-migrate project-info\`)
resend flags (no Scribase account needed; pair with --out <file>):
--api-key <re_...>
Also: scribase-migrate project-info --to <org>/<project>/<environment>
prints the destination's api_url + keys (never the secrets to stdout
unless --reveal-secrets), the inputs clerk needs.
Needs a Scribase access token for everything except resend: run
\`npx scribase login\` once, or export SCRIBASE_ACCESS_TOKEN.
No account yet? It is free to start: ${SIGNUP_URL}
${CTA_LINE}
`;
function fail(message) {
process.stderr.write(`scribase-migrate: ${message}\n`);
process.exit(1);
}
async function version() {
try {
return JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version;
} catch {
return 'unknown';
}
}
/** The SDK client, or a plain exit that tells a brand-new user where to get an account. */
function clientOrExit() {
try {
return scribaseClient().client;
} catch (error) {
process.stderr.write(`scribase-migrate: ${error.message}\n`);
process.stderr.write(`No Scribase account yet? It is free to start: ${SIGNUP_URL}\n`);
process.exit(1);
}
}
function parseTo(value) {
if (!value) fail('--to <org>/<project>/<environment> is required');
const parts = value.split('/');
if (parts.length < 2 || parts.length > 3) fail(`--to "${value}" must be org/project or org/project/environment`);
const [organizationId, projectId, environmentId = 'production'] = parts;
return { organizationId, projectId, environmentId };
}
async function writeResult(opts, result) {
if (opts.out) {
await mkdir(dirname(opts.out), { recursive: true }).catch(() => {});
await writeFile(opts.out, JSON.stringify(result, null, 2));
}
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
if (opts.json) return;
// stdout stays pure JSON for pipes; the human-facing lines go to stderr.
if (opts.out) process.stderr.write(`\nFull result also written to ${opts.out}\n`);
process.stderr.write(`\n${CTA_LINE}\n`);
}
async function resolveDestination(client, dest, values) {
if (values['create-project']) {
const region = values.region ?? REGION_DEFAULT;
const kind = values.kind ?? KIND_DEFAULT;
if (!['preview', 'staging', 'production'].includes(kind)) fail(`--kind "${kind}" must be preview, staging or production`);
// snapshot/sanitized copy production data, so the control plane refuses
// them for a project with no production environment yet (verified live:
// `source_environment_missing`). A try-it-out preview starts empty.
const dataMode = kind === 'production' ? 'snapshot' : 'schema_only';
return ensureProject(client, { ...dest, region, kind, dataMode });
}
const environment = await client.environments.get(dest);
const connection = await client.environments.connection(dest);
const apiKeys = await client.environments.apiKeys(dest);
return { ...dest, environment, connection, apiKeys };
}
async function main() {
const [source, ...rest] = process.argv.slice(2);
if (!source || source === '--help' || source === '-h' || rest.includes('--help') || rest.includes('-h')) {
process.stdout.write(USAGE);
process.exit(source ? 0 : 1);
}
if (source === '--version' || source === '-v') {
process.stdout.write(`${await version()}\n`);
return;
}
if (!SOURCES.includes(source)) {
fail(`unknown source "${source}". Use one of: ${SOURCES.join(', ')}. Run scribase-migrate --help.`);
}
const { values } = parseArgs({
args: rest,
options: {
to: { type: 'string' },
'create-project': { type: 'boolean' },
region: { type: 'string' },
kind: { type: 'string' },
'dry-run': { type: 'boolean' },
out: { type: 'string' },
json: { type: 'boolean' },
'source-ref': { type: 'string' },
'source-url': { type: 'string' },
'source-service-key': { type: 'string' },
'verify-login-email': { type: 'string' },
'verify-login-password': { type: 'string' },
'no-storage': { type: 'boolean' },
'migrate-auth-users': { type: 'boolean' },
'secret-key': { type: 'string' },
'target-api-url': { type: 'string' },
'target-service-key': { type: 'string' },
'api-key': { type: 'string' },
'reveal-secrets': { type: 'boolean' },
schema: { type: 'string', multiple: true },
branch: { type: 'string', multiple: true },
'verify-row-counts': { type: 'string', multiple: true },
},
allowPositionals: false,
strict: false,
});
// Resend is a pure export: it needs neither a destination nor a Scribase
// account, so it must not ask for either.
if (source === 'resend') {
if (!values['api-key']) fail('resend needs --api-key');
const result = await exportResend({
apiKey: values['api-key'],
onLog: (line) => process.stderr.write(` ${line}\n`),
});
await writeResult(values, result);
return;
}
// Clerk with both --target-* flags talks to the environment directly.
if (source === 'clerk' && values['target-api-url'] && values['target-service-key']) {
if (!values['secret-key']) fail('clerk needs --secret-key');
await runClerk(values, values['target-api-url'], values['target-service-key']);
return;
}
// Check a source's own required flags before asking for a token, so the
// first error a new user sees is about the command they typed.
if (source === 'supabase' && (!values['source-ref'] || !values['source-url'] || !values['source-service-key'])) {
fail('supabase needs --source-ref, --source-url and --source-service-key');
}
if (source === 'neon' && !values['source-url']) fail('neon needs --source-url');
if (source === 'clerk' && !values['secret-key']) fail('clerk needs --secret-key');
const target = parseTo(values.to);
if (source === 'project-info') {
const client = clientOrExit();
const dest = await resolveDestination(client, target, values);
const out = {
organizationId: dest.organizationId,
projectId: dest.projectId,
environmentId: dest.environmentId,
apiUrl: dest.apiKeys.api_url,
anonKey: dest.apiKeys.anon_key,
...(values['reveal-secrets']
? { serviceRoleKey: dest.apiKeys.service_role_key, connectionUri: dest.connection.connection_uri }
: { serviceRoleKey: '(hidden, pass --reveal-secrets)', connectionUri: '(hidden, pass --reveal-secrets)' }),
};
await writeResult(values, out);
return;
}
const client = clientOrExit();
const dest = await resolveDestination(client, target, values);
const destination = {
organizationId: dest.organizationId,
projectId: dest.projectId,
environmentId: dest.environmentId,
};
if (source === 'supabase') {
const result = await migrateSupabase(client, {
sourceProjectRef: values['source-ref'],
sourceConnectionString: values['source-url'],
sourceServiceKey: values['source-service-key'],
destination,
includeStorage: !values['no-storage'],
dryRun: values['dry-run'],
...(values['verify-login-email']
? { verifyLogin: { email: values['verify-login-email'], password: values['verify-login-password'] } }
: {}),
onProgress: (job) => process.stderr.write(` ${job.status}${job.phase ? ` (${job.phase})` : ''}\n`),
});
await writeResult(values, result);
return;
}
if (source === 'neon') {
const schemas = values.schema ?? [];
const branches = (values.branch ?? []).map((pair) => {
const at = pair.indexOf('=');
return { name: pair.slice(0, at), url: pair.slice(at + 1) };
});
const result = await migrateNeon(client, {
sourceUrl: values['source-url'],
destination,
schemas: schemas.length ? schemas : undefined,
migrateAuthUsers: values['migrate-auth-users'],
branches,
apply: !values['dry-run'],
onLog: (line) => process.stderr.write(` ${line}\n`),
});
const verifyTables = values['verify-row-counts'] ?? [];
if (verifyTables.length) {
result.rowCounts = await verifyRowCounts(client, destination, values['source-url'], verifyTables);
}
await writeResult(values, result);
return;
}
if (source === 'clerk') {
const apiUrl = values['target-api-url'] ?? dest.apiKeys.api_url;
const serviceRoleKey = values['target-service-key'] ?? dest.apiKeys.service_role_key;
if (!apiUrl || !serviceRoleKey) fail('could not resolve the destination api_url/service_role_key. Pass --target-api-url and --target-service-key');
await runClerk(values, apiUrl, serviceRoleKey);
}
}
async function runClerk(values, apiUrl, serviceRoleKey) {
const onLog = (line) => process.stderr.write(` ${line}\n`);
const users = await exportClerkUsers({ secretKey: values['secret-key'], onLog });
if (values['dry-run']) {
await writeResult(values, { exported: users.length, dryRun: true, wouldCreate: users.map((u) => u.email ?? u.phone ?? u.clerkId) });
return;
}
const result = await createGoTrueUsers({ apiUrl, serviceRoleKey, users, onLog });
await writeResult(values, { exported: users.length, ...result });
}
/** The control plane's own detail line, plus the one fix that applies, for errors a new user hits first. */
function explain(error) {
const detail = error?.problem?.detail;
const lines = [detail ? `${error.message} (${detail})` : error.message];
if (error?.code === 'migration_conflict') {
lines.push(
'This environment already has migrations that are not in ./supabase/migrations here. ' +
'Run from the folder that holds them (your app repo), or pick a new environment in --to.',
);
}
return lines;
}
main().catch((error) => {
for (const line of explain(error)) process.stderr.write(`scribase-migrate: ${line}\n`);
process.exitCode = 1;
});