Implementing SQLite Database Migrations in .NET MAUI

Creating the initial SQLite database is easy; evolving it safely across app updates is where things break. Jorge Perales Diaz shows why CreateTableAsync<T>() only ever creates missing tables and builds a real migration system with schema versioning for .NET MAUI’s offline-first realities.

What you’ll learn

• Why migrations matter — the existing-installation problem, and why table creation doesn’t alter, backfill, or index an evolving schema
• A versioned migration contract — schema PRAGMA user_version, individual immutable migrations, and a runner that applies them incrementally inside transactions
• Schema and data migrations — adding columns and indexes, transforming existing rows, and validating the migration chain
• Users skip versions — handling installs that jump many app versions at once, preventing duplicate execution, and recovering from failures
• Startup done right — separating cache vs user-data databases, logging and timing migrations, running them at startup without freezing the UI, and testing every supported starting version

Read the full article for the migration runner, DI wiring, immutability rules, and the down-migration discussion.