Understanding the DeskcommCRM Migration Triad: Baseline SQL, MANIFEST, and Versioned Files

The DeskcommCRM migration triad—comprising baseline.sql, MANIFEST.md, and individual versioned migration files—provides a dual-path database setup that supports both fresh installations via a single idempotent script and incremental upgrades for existing deployments through Supabase CLI orchestration.

DeskcommCRM implements a robust database versioning strategy through three interconnected components stored in the supabase/ directory. This migration triad ensures deterministic schema creation for self-hosted VPS deployments while maintaining a clear audit trail of schema evolution for multi-tenant SaaS operations.

The Three Pillars of the DeskcommCRM Migration Triad

Baseline SQL (supabase/baseline.sql)

The baseline script serves as the foundation of the migration triad. Located at supabase/baseline.sql, this file contains the complete database schema, default data, and the initial migration 0001 (platform_base) applied on a fresh install.

According to the DeskcommCRM source code, this file provides a single, idempotent script that self-hosting installers execute via install.sh or update.sh. Rather than replaying dozens of incremental migrations sequentially, new deployments run this one file to establish a complete, consistent schema instantly.

Migration Manifest (supabase/migrations/MANIFEST.md)

The MANIFEST.md file acts as the authoritative ledger for the migration triad. This human-readable document lists every migration version with its timestamp, human-readable name, and description of schema changes (tables, functions, policies).

The manifest specifically documents critical metadata including:

• Special handling instructions for timestamp collisions that occurred in August 2026
• The mapping between file timestamps and version identifiers (e.g., 20260428195354 → 0001_platform_base)
• An Applied table showing all versions pushed to Supabase's supabase_migrations.schema_migrations table

As implemented in melgarafael/DeskcommCRM, this file informs developers which migrations must be present and explains that the baseline remains the only reliable path for fresh installations.

Versioned Migration Files (supabase/migrations/*.sql)

The individual migration files contain incremental DDL (Data Definition Language) and DML (Data Manipulation Language) changes. These files follow Supabase's timestamp-naming convention and reside in supabase/migrations/.

These scripts handle specific schema modifications such as:

• Adding new tables and columns
• Creating triggers and Row Level Security (RLS) policies
• Applying data fixes and seed updates

Existing installations use these files for incremental updates while the baseline remains immutable for new hosts.

How the Migration Triad Handles Different Deployment Scenarios

Fresh Installations with baseline.sql

For brand-new VPS deployments, the migration triad bypasses individual migration files entirely. The installer executes baseline.sql directly against the database:

# install.sh excerpt

psql "$DATABASE_URL" -f supabase/baseline.sql

This approach guarantees that new deployments end with a complete schema even if the migration history contains gaps or ordering quirks. The baseline includes migration 0001 (platform_base) in its final state, eliminating the need to replay migration history.

Incremental Upgrades for Existing Tenants

Existing installations utilize Supabase's CLI tooling to read MANIFEST.md and apply only missing migrations. The system determines which versions exist in supabase_migrations.schema_migrations versus which files remain unapplied:

supabase db push   # reads MANIFEST.md, applies missing migrations in order

This incremental approach allows production databases to evolve without downtime or full schema recreation.

Resolving Timestamp Collisions

The migration triad includes specific protocols for handling timestamp collisions. When two migration files shared identical timestamps in August 2026, the manifest records the resolution: adding one second to the later file (e.g., 20260717190000 becomes 20260717190001).

For environments that ran db push before the rename, the manifest provides this conflict-resolution SQL:

-- Run only once if you have already run `db push` before the rename
INSERT INTO supabase_migrations.schema_migrations (version) VALUES
  ('20260717190001'), ('20260718160001'), ('20260721120001'), ('20260722160001')
ON CONFLICT (version) DO NOTHING;

This prevents db push failures due to primary-key conflicts in the schema migrations table.

Code Examples and Implementation Details

The interplay between components appears throughout the DeskcommCRM codebase. The baseline script includes the complete initial schema:

-- From supabase/baseline.sql
-- Contains full schema definition plus:
-- INSERT INTO supabase_migrations.schema_migrations (version) VALUES ('0001');
-- representing the platform_base migration

The MANIFEST.md structure follows this pattern:

## Applied

| Version | Name |
|---------|------|
| 0001 | platform_base |
| 20260428195354 | ... |

For collision handling, the manifest explicitly notes: when two files share a timestamp, rename the later file by adding one second to its timestamp string, then record both the original and corrected versions in the resolution SQL.

Summary

• The migration triad consists of supabase/baseline.sql, supabase/migrations/MANIFEST.md, and individual supabase/migrations/*.sql files.
• Fresh installs use only baseline.sql for immediate, idempotent schema creation.
• Existing installations use supabase db push to read the manifest and apply incremental migrations in order.
• Timestamp collisions are resolved via documented SQL fixes that insert corrected version identifiers into the schema migrations table.
• This architecture ensures deterministic, reproducible database states across all DeskcommCRM deployment scenarios.

Frequently Asked Questions

What is the purpose of the migration triad in DeskcommCRM?

The migration triad provides a dual-path database setup mechanism that accommodates both fresh installations and incremental upgrades. It ensures new VPS deployments receive a complete schema instantly via baseline.sql, while existing tenants receive incremental updates through versioned migration files orchestrated by MANIFEST.md.

How does the baseline.sql file differ from individual migration files?

baseline.sql contains the complete database schema and initial data as a single idempotent script, whereas individual migration files contain incremental changes (DDL/DML) applied sequentially. The baseline is designed for fresh installs to avoid replaying migration history, while versioned files handle ongoing schema evolution for existing databases.

What causes timestamp collisions in Supabase migrations and how does DeskcommCRM fix them?

Timestamp collisions occur when two migration files are created with identical timestamps (down to the second), causing primary-key conflicts in supabase_migrations.schema_migrations. DeskcommCRM resolves this by renaming the later file (adding one second to its timestamp) and documenting the fix in MANIFEST.md with specific SQL to insert the corrected version identifiers for environments that already applied the conflicting migrations.

Can I run individual migration files on a fresh install instead of baseline.sql?

While technically possible, running individual migrations on a fresh install is not recommended. The baseline.sql file is the only reliable path for fresh installations because it guarantees a consistent schema state even if the migration history contains gaps or deprecated intermediate steps. Individual migrations are designed for incremental upgrades (db push) on existing databases only.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}