Schema Migrations

When you modify your database structure in SchemaStack — changing a column type, toggling nullable, adding or removing columns — the platform automatically generates and applies the necessary database migration. This page explains how that works, what to expect, and how the system keeps your data safe throughout.

How It Works

SchemaStack separates changes into two categories:

• Display changes (rename a column, reorder, hide/show) are applied instantly — no database changes needed.
• Schema changes (column type, nullable, unique, default value) require an actual ALTER TABLE on your database. These are processed asynchronously.

When you make a schema change, here's what happens behind the scenes:

You make a change           The system detects            Your database is
in the SchemaStack    →     what needs to change    →     updated safely
interface                   and queues the work           in the background
       │                           │                            │
       │                           │                            │
       ▼                           ▼                            ▼
  ┌─────────┐            ┌──────────────────┐          ┌──────────────┐
  │  Edit a  │            │  Analyze impact:  │          │  Generate &   │
  │  column  │            │  How long? What   │          │  execute the  │
  │  setting │            │  gets locked?     │          │  SQL migration│
  └─────────┘            └──────────────────┘          └──────────────┘
                                                              │
                                                              ▼
                                                       ┌──────────────┐
                                                       │  Notify you   │
                                                       │  when done    │
                                                       └──────────────┘

The Migration Lifecycle

1. You make a change

In the column properties panel, you modify a setting that affects the database — for example, changing a column from Text to Number, or toggling Nullable off.

2. Impact analysis

Before anything happens, SchemaStack analyzes the impact:

• How many rows does this table have?
• How long will this migration take?
• Will it block other users from reading or writing data?
• Are other tables affected through foreign key relationships?

If the change is significant (large table, blocking operation), you'll see a confirmation dialog with these details before proceeding.

3. Migration is queued

Once confirmed, the change is queued for processing. You'll see a visual indicator on the affected column:

Impact Level	What You See	What It Means
Transparent	Nothing changes	Migration is instant (< 100ms)
Brief	Lock icon on column	Editing paused for a few seconds
Blocking	Migration overlay	Table is temporarily unavailable while the change is applied

4. Migration executes

The migration processor generates the correct SQL for your database (PostgreSQL or MySQL) and applies it. For longer migrations, you'll see a progress bar with:

• Percentage complete
• Current phase (e.g., "Rewriting table", "Building index")
• Estimated time remaining

5. Completion

When the migration finishes:

• The column unlocks automatically
• Your data is updated and ready to use
• All connected users see the change in real time via live updates
• If something went wrong, the column unlocks with an error notification and your data remains unchanged

What Happens to Your Data During a Migration

Can I still read my data?

It depends on the operation and your database:

Database	Column type change	Add NOT NULL	Add unique constraint
PostgreSQL	Reads blocked	Reads blocked	Reads allowed
MySQL (InnoDB)	Reads allowed	Reads allowed	Reads allowed

When reads are blocked, SchemaStack shows a migration overlay. When only writes are blocked, you can still browse your data in read-only mode.

Can other users still work?

Other users connected to the same workspace see the migration state in real time. If the migration blocks writes, they'll see a banner explaining what's happening and when it's expected to finish.

What about my API integrations?

If you have external tools connected via the Workspace API or MCP API, they'll receive a 503 Service Unavailable response with a Retry-After header during blocking migrations. Well-behaved HTTP clients will automatically retry after the specified delay.

Instant vs. Long-Running Changes

Not all schema changes are equal. Here's a quick reference for common operations:

Instant changes (you won't even notice)

• Adding a nullable column
• Dropping a column
• Changing a default value
• Renaming a column

Brief pauses (a few seconds at most)

• Adding a unique constraint (index needs to be built)
• Adding a foreign key (existing data needs to be validated)

Longer migrations (depends on table size)

• Changing a column's data type (entire table is rewritten)
• Adding NOT NULL to an existing column (all rows need to be checked)

For tables with under 10,000 rows, even "long" migrations typically complete in under a second. The impact scales with data volume.

Schema Sync

Sometimes your database is modified outside of SchemaStack — perhaps by a DBA running SQL directly, or another tool making changes. Schema sync detects these differences and updates SchemaStack's understanding of your database to match reality.

Your actual database              SchemaStack's              After sync, they
may have changed           →      metadata may be     →      match again
outside SchemaStack               out of date

Quick check vs. full sync

• Quick check: Compares a fingerprint (hash) of your schema — answers "has anything changed?" in under a second
• Full sync: Walks through every table and column, reports exactly what's different, and updates the metadata

What sync does and doesn't do

• Does: Updates SchemaStack's metadata to match your actual database
• Does NOT: Modify your database in any way
• Does NOT: Create or drop tables (only syncs column-level changes)

Migration History

Every migration is tracked and auditable:

• What changed: The exact SQL that was generated and executed
• When: Timestamps for start and completion
• Duration: How long the migration actually took
• Who: Which user initiated the change
• Status: Whether it succeeded or failed

This history also helps SchemaStack improve its duration estimates over time — the more migrations you run, the more accurate the "estimated time remaining" becomes.

Multi-Database Support

SchemaStack generates the correct migration SQL for your specific database:

Feature	PostgreSQL	MySQL (InnoDB)
Column type changes	Full table rewrite	Full table copy
Nullable changes	Table scan required	Online (concurrent reads/writes)
Add column	Near-instant	Truly instant (8.0.12+)
Unique constraints	Blocks writes during index build	Online index build
Progress tracking	Real-time from PostgreSQL internals	Time-based estimation

The system automatically detects your database type and version to provide accurate impact predictions and generate optimal SQL.

Tips

• Small tables are fast: If your table has fewer than 10,000 rows, almost any schema change will be near-instant.
• Check before you change: Use the impact preview (shown before confirmation) to understand what will happen before committing to a change.
• One at a time: Only one blocking migration can run per table at a time. If you need multiple changes, they'll be processed sequentially.
• Connected users are informed: All users viewing the affected data see real-time migration status — no one is left wondering why their edits aren't saving.
• Your data is safe: If a migration fails, your data and schema remain in their pre-migration state. Nothing is partially applied.