> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yourhq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrations
> Ordered Supabase migration files and how to apply them.
Migrations live in [`db/migrations/`](https://github.com/yourhq/yourhq/tree/main/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).
```bash theme={null}
cd apps/migrate && npm install
npx yourhq-migrate --list
npx yourhq-migrate --dry-run --connection-string "postgres://postgres:PASSWORD@db.xxxx.supabase.co:5432/postgres"
npx yourhq-migrate --connection-string "postgres://postgres:PASSWORD@db.xxxx.supabase.co: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
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.