Migrations

Migrations live in db/migrations/. Run them in filename order for a fresh project. The onboarding wizard can apply them automatically via one-click schema install.

Migration files

File	Domain
`001_extensions.sql`	Postgres extensions (pgvector, pg_cron, pgcrypto)
`002_enums.sql`	Shared enum types
`003_shared_functions.sql`	Common trigger functions and schema version tracking
`004_tenants.sql`	Tenant registry, default tenant, JWT signup trigger
`005_workspace.sql`	Workspace settings, pipeline stages, field definitions
`006_crm.sql`	Contacts, organizations, campaigns, templates, draft sets
`007_gateways.sql`	Gateway registry, registration tokens, `consume_gateway_token()` RPC
`008_agents.sql`	Agent metadata, org chart, `agent_reports_chain()` RPC
`009_interactions.sql`	Contact interaction timeline and sync triggers
`010_tasks_streams.sql`	Streams, tasks, recurring task series, and scheduling
`011_comments.sql`	Polymorphic comments with @-mention triggers
`012_knowledge.sql`	Knowledge items, chunks, semantic/full-text search RPCs
`013_audit_notifications.sql`	Audit log and notification tables
`014_agent_inbox.sql`	Agent inbox queue, lease RPCs, and task/comment triggers
`015_agent_commands.sql`	Command queue and lifecycle RPCs
`016_usage_budgets.sql`	LLM usage logging, per-agent budgets, and enforcement
`017_rls_realtime_storage.sql`	Storage bucket setup
`018_setup_wizard.sql`	`complete_setup()` RPC for the first-run wizard
`019_entity_links.sql`	Universal polymorphic entity linking
`020_routines.sql`	Routines (scheduled and event-driven agent workflows)
`021_collections.sql`	Custom collections, fields, records, and views
`022_file_processing.sql`	File processing pipeline for knowledge items
`023_source_connections.sql`	External source connections (Notion, Google Drive)
`024_routines_extension.sql`	Event triggers for collections, knowledge, and tasks
`025_modular_workspace.sql`	Modular workspace onboarding
`026_secrets.sql`	Encrypted secrets (AES-256-GCM), agent/gateway scoping, Realtime, `source_connections.secret_id` FK
`027_plugins.sql`	Plugin system: `hq_plugins`, `hq_plugin_events`, `hq_plugin_state`, `hq_plugin_event_queue`, event triggers, pg_cron cleanup
`028_task_relations.sql`	Task dependencies (`task_relations`), `get_task_relations()` RPC, `notify_blocker_resolved` trigger
`029_labels.sql`	Managed labels with color/description, `task_labels` junction table
`030_task_templates.sql`	Reusable task group templates with dependency graphs (JSONB items)
`031_overdue_escalation.sql`	pg_cron job to mark overdue tasks `missed`, inbox notification for assigned agents
`032_notification_gaps.sql`	Notifications for deliverable submissions and overdue task events
`033_knowledge_chunk_pipeline.sql`	Knowledge chunk creation, embedding pipeline, and source item indexing fixes
`034_crm_search_index.sql`	Full-text search index on CRM contacts and organizations
`035_interactions_nullable_contact.sql`	Allow interactions without a linked contact
`036_collection_agent_commands.sql`	Agent commands for collection record operations
`037_source_plugin_support.sql`	Extended source connector plugin support
`038_gateway_backups.sql`	Gateway backup storage bucket (`gateway-backups`), backup metadata columns on `gateways` (`last_backup_at`, `last_backup_size_bytes`), `backup_gateway` command action
`039_knowledge_library_scope.sql`	`library` scope for `knowledge_items`, migration of unpinned workspace items to library scope, `pinned` column removal, index rebuild

Migration CLI

The @yourhq/migrate package provides a CLI for applying schema migrations directly against Postgres (session mode, port 5432).

cd apps/migrate && npm install

npx yourhq-migrate --list
npx yourhq-migrate --dry-run --connection-string "postgres://postgres:[email protected]:5432/postgres"
npx yourhq-migrate --connection-string "postgres://postgres:[email protected]:5432/postgres"
npx yourhq-migrate --bundle > schema.sql

The runner tracks applied migrations in a _yourhq_migrations table (version, checksum, applied_at). It verifies checksums on already-applied migrations to detect drift. Each migration runs in a transaction — if one fails, it rolls back and stops. For Cloud Supabase users who can’t access port 5432, the onboarding wizard provides a “Copy SQL → Open SQL Editor” manual flow.

Applying migrations

Fresh project
Existing project

Run every .sql file in order from the Supabase SQL Editor, or use the onboarding wizard which concatenates them into a single copy-paste blob.

Back up first. All migration files are idempotent (IF NOT EXISTS, CREATE OR REPLACE) and safe to re-run.

Always include explicit GRANT statements for authenticated and service_role in any new migrations. Supabase does not grant these by default.

Start here

Hosted

Self-host

Use Your HQ

Concepts

Design

Reference

Development

Security and troubleshooting

Migrations

Migration files

Migration CLI

Applying migrations

​Migration files

​Migration CLI

​Applying migrations

Migration files

Migration CLI

Applying migrations