Database Migrations
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Database Migrations in the Duplicator project represent a unified system for managing structural changes and data transformations across different database environments (MySQL and SQLite). The system ensures that the database schema remains consistent across deployments by automatically checking for and applying pending updates while maintaining data integrity through integrated backup mechanisms.
The architecture supports both a fully automated migration path for existing schemas and a template-based initialization for new database instances. This is primarily handled by the DatabaseMigrationManager for schema evolution and specialized managers like SQLiteDatabaseManager or AdminDatabaseManager for initial setup and lifecycle management.
Sources: app/models/migrations/DatabaseMigrationManager.php:1-10, app/models/admin/DatabaseManager.php:1-10
Migration Lifecycle and Execution
The migration process is governed by a tracking system that prevents the duplicate execution of scripts. Every migration is registered in a dedicated table, and the system follows a strict "backup-apply-verify" workflow.
Automated Migration Flow
When runMigrations() is invoked, the system iterates through a predefined list of migration tasks. For each task, it checks the schema_migrations table to determine if the update has been previously applied.
The diagram shows the logic within the DatabaseMigrationManager where each migration is executed within a transaction to ensure atomicity.
Sources: app/models/migrations/DatabaseMigrationManager.php:26-55
Tracking Schema
The system uses a specific internal table to maintain a history of structural changes.
| Field | Type | Description |
|---|---|---|
id | INTEGER | Primary key, autoincrement. |
migration_name | TEXT | Unique identifier for the migration task. |
applied_at | DATETIME | Timestamp of when the migration was executed. |
Sources: app/models/migrations/DatabaseMigrationManager.php:61-65
Core Migration Tasks
The project currently implements several critical migrations focused on search optimization and data consistency.
Full-Text Search (FTS5) Integration
To improve document retrieval, a migration creates virtual tables utilizing the SQLite FTS5 engine. This includes setting up triggers to keep the search index synchronized with the primary bibliotheque_files table.
Triggers ensure that any manual or programmatic changes to file metadata are reflected in the search index immediately.
Sources: app/models/migrations/DatabaseMigrationManager.php:115-155
Data Normalization
The migrateTirageGlobalId task introduces a standardized identifier across printing tables (dupli and photocop). This involves adding a tirage_global_id column and populating it using a normalization function that combines dates, contact names, and machine types.
Sources: app/models/migrations/DatabaseMigrationManager.php:171-190
Database Initialization and Setup
For fresh installations, the system provides a "Setup" mode that initializes the required tables. This process can occur through manual creation or by importing an existing .sqlite file.
| Feature | Method | Source File |
|---|---|---|
| Essential Tables | createEssentialTables() | SQLiteDatabaseManager.php:235-373 |
| Initial Data | insertInitialData() | SQLiteDatabaseManager.php:388-406 |
| Template Copy | copyFromDatabase() | SQLiteDatabaseManager.php:79-93 |
Sources: app/models/admin/SQLiteDatabaseManager.php, app/view/setup.html.php
Table Structure (Standard Schema)
The migration and management tools ensure the creation of core tables such as dupli, photocop, prix, site_settings, and aide_machines.
This diagram illustrates the relational structure maintained by the migration managers.
Sources: app/models/admin/DatabaseManager.php:316-520, app/models/admin/SQLiteDatabaseManager.php:235-373
Safety and Maintenance
Prior to applying any migration, the DatabaseMigrationManager triggers a mandatory backup using the BackupManager. This creates a copy of the database file named with the prefix before_[migration_name]_[timestamp].
Synchronization Scripts
Maintenance scripts like sync_aide_tables.php are used to verify and create specific tables (e.g., aide_machines, aide_machines_qa) if they are missing in the local environment, ensuring the help system remains functional.
Sources: app/models/migrations/DatabaseMigrationManager.php:86-113, app/maintenance/sync_aide_tables.php:13-75
Summary
The Database Migrations system provides a robust framework for schema evolution and initialization. By combining automated migration tracking, virtual tables for search, and mandatory backups, the project maintains high data reliability while allowing the application to grow and add new features without manual database intervention.