Skip to main content

Schema Migration

During BYOK onboarding, NearSync runs a one-time database migration against your Supabase project. This page explains what gets created, how updates work, and what to expect.

One-Time Initial Migration​

The initial migration creates the complete NearSync database schema in your Supabase project. This is an automated process that runs during the onboarding call via the client portal Setup tab.

What Gets Created​

The migration creates all database tables spanning all NearSync modules:

ModuleExample Tables
Authentication & UsersUser profiles, roles, permissions, role-permission mappings
CRMContacts, companies, deals/pipelines, stages, tasks, activities
CommunicationsEmail messages, WhatsApp messages, chat threads, templates
FinanceInvoices, company expenses, employee expenses, subscriptions, approval workflows
HR ManagementEmployees, departments, leave requests, attendance, payroll
ProjectsIssues, boards, sprints, time tracking, documents
SupportTickets, SLA configurations, knowledge base articles
MarketingCampaigns, email lists, analytics events
OperationsWorkflows, automation rules, audit logs
AI & KnowledgeKnowledge base entries with vector embeddings, AI configuration
PlatformGlobal settings, system manifest, staff invitations, integration sessions

Row-Level Security Policies​

Every table receives RLS policies during migration. These policies enforce data access rules at the PostgreSQL level, meaning even direct database queries respect your access controls. See Row-Level Security for details on how these policies work.

Database Functions​

The migration also creates PostgreSQL functions used by the application:

  • Vector similarity search - powers the AI knowledge base with semantic matching
  • Aggregation functions - used by dashboards and analytics views
  • Trigger functions - handle automated timestamps, status transitions, and cascading updates

Extensions​

The migration enables required PostgreSQL extensions:

  • pgvector - vector similarity search for AI/RAG features
  • pg_trgm - trigram matching for fuzzy text search
  • Standard extensions provided by Supabase (uuid, crypto, etc.)

Initial Data Seeding​

After schema creation, the migration seeds:

  • An initial admin user account (using the email you provide during setup)
  • A default system manifest with your organization's configuration
  • Default roles and permission sets

Schema Update Process​

When NearSync releases database schema changes, the process depends on your deployment model:

NearSync-Managed Deployments (Default)​

If NearSync manages your Vercel deployment:

  1. NearSync notifies you in advance of a scheduled maintenance window
  2. NearSync applies the migration during that window
  3. Migrations are provided as incremental SQL diff files (e.g., changes since the last release)
  4. No action required from you

Client Self-Hosted Deployments (Enterprise)​

If you manage your own deployment:

  1. Migration SQL diff files are provided with each release
  2. You apply them via the Supabase Dashboard SQL editor or the Supabase CLI
  3. You choose when to apply updates

Backward Compatibility​

  • Schema migrations are backward-compatible where possible
  • Breaking changes (rare) require coordinated upgrades - NearSync will work with you on timing
  • Migration files are idempotent and can be safely re-run

Verification​

After the initial migration, you can verify the schema was applied correctly:

  1. Open the Supabase Dashboard for your project
  2. Navigate to Table Editor - you should see tenant-scoped tables organized by module
  3. Navigate to Authentication > Users - your initial admin account should be present
  4. Check Database > Extensions - vector and pg_trgm should be enabled

Next Steps​