Database Migrations

Marqov uses Supabase (hosted PostgreSQL) for its database. Migrations are SQL files applied via the Supabase SQL Editor.

Migration File Location


platform/supabase/migrations/

Naming Convention


NNN_description.sql

NNN: Three-digit zero-padded sequence number (e.g., 001, 059)
description: Snake-case description of the change

Examples:

001_initial_schema.sql
047_team_suspension.sql
054_inline_code_on_job_runs.sql

Current Schema Version

059 (059_add_quantum_brilliance_backends.sql)

How to Apply Migrations

Migrations are applied manually via the Supabase SQL Editor since the platform uses a remote Supabase instance (not local).

Open the Supabase Dashboard: https://supabase.com/dashboard
Navigate to your project
Open SQL Editor
Copy the contents of the migration file
Run the SQL
Verify the migration applied successfully

There is no automated migration runner. Each migration must be applied in sequence.

Writing a New Migration

Determine the next sequence number by checking the last file in platform/supabase/migrations/.
Create a new file: NNN_description.sql
Write idempotent SQL where possible (use IF NOT EXISTS, IF EXISTS, OR REPLACE).
Test in a development environment before applying to production.
Commit the migration file to version control.

Best Practices

Use ALTER TABLE ... ADD COLUMN IF NOT EXISTS for column additions.
Use CREATE OR REPLACE for functions and views.
When adding new columns to a view, you must DROP and CREATE it (cannot insert columns in the middle).
Wrap multi-statement migrations in BEGIN; ... COMMIT; for atomicity.
Add COMMENT ON COLUMN for new columns to document their purpose.
Use NOT VALID on constraints to skip checking existing rows.

Important Migrations

#	Description	Tables Affected
001	Initial schema	teams, team_members, scripts, job_runs, job_results, webhook_endpoints, webhook_deliveries
002	Team invitations	team_invitations
005	RLS fix with security definer	RLS policies
006	Backends table	backends (seeded with 11 devices)
010	Benchmark suites	benchmark_suites, benchmark_suite_jobs
012	Capsules	capsules, capsule_artifacts, capsule_task_executions
014	Invitation codes	invitation_codes
042	Providers table	providers
045	Cost tracking	cost tracking columns and RPC functions
047	Team suspension	teams.suspended_at, team_stats_summary view
048	Security hardening	RLS policy updates
050	Simulation events	simulation_events
051	Template migration	scripts.framework, job_runs.execution_mode, slug+framework unique constraint
052-053	Seed scripts	scripts (Bell State variants, VQE, QAOA)
054	Inline code	job_runs.inline_code, job_runs.framework, scripts INSERT policy
055	Script requirements	scripts.requirements fixes
056	Marqov simulator	backends (marqov-sim)
058	Workflow metadata	job_runs.workflow_metadata
059	Quantum Brilliance	backends (qb-sim-*)

Troubleshooting

db:types command warning: The Supabase CLI command supabase db:types redirects output to database.types.ts. If the command fails (e.g., lacking access), it empties the file. Always git restore platform/src/lib/database.types.ts if the command fails.

Column type mismatches: If generated types do not include recently added columns (e.g., framework, inline_code), use as any casts in TypeScript until types are regenerated.

View recreation: CREATE OR REPLACE VIEW cannot change the column order or insert new columns in the middle. New columns must be appended at the end, or the view must be dropped and recreated.