migrations_skill

Overview

This skill helps you run and manage database migrations for stripe-sync-engine to create the PostgreSQL schema and tables required for syncing Stripe data. It guides on running migrations via a script or as a serverless API endpoint, and includes verification and troubleshooting steps. Use it to reliably provision the stripe schema and migration tracking table.

How this skill works

It verifies that stripe-sync-engine is installed, DATABASE_URL is configured, and the DB user can create schemas. You can run migrations using a standalone TypeScript script that calls runMigrations or expose an API endpoint (Next.js or Hono) to trigger migrations in serverless environments. The runMigrations call accepts configuration options like schema, tablePrefix, and migrationTableName.

When to use it

• Setting up the database schema for stripe-sync-engine for the first time
• When you need to create stripe tables or run pending stripe_migrations
• Automating migrations in CI/CD or deployment pipelines
• Triggering migrations from a serverless app or admin endpoint
• After upgrading stripe-sync-engine to apply new schema changes

Best practices

• Ensure stripe-sync-engine is installed before running migrations
• Set DATABASE_URL in your environment and verify it points to the intended database
• Use a dedicated schema name (default: stripe) to isolate Stripe tables
• Run migrations from a controlled environment or CI job rather than ad-hoc production endpoints
• Grant the DB user CREATE privileges or create and pre-grant the schema to avoid permission errors

Example use cases

• Add scripts/run-migrations.ts and npm script (stripe:migrate) to run migrations locally or in CI
• Create a Next.js API route that calls runMigrations for on-demand serverless migration runs
• Expose a Hono endpoint to trigger migrations during deployments
• Manually verify migration results with information_schema queries and inspect stripe.stripe_migrations
• Resolve permission errors by granting CREATE on the database or pre-creating the stripe schema