# Production Migration Guide: SQLite → MySQL This runbook moves the application's production database from SQLite to MySQL 8, preserving existing data. It mirrors the local cutover and relies on the `db:transfer-sqlite` command added in `app/Console/Commands/TransferSqliteData.php`. Read the whole guide before starting. Every step assumes you can SSH into the production server and run commands from the app root. --- ## 0. Preconditions - MySQL 8 server reachable from the app server (5.7+ and MariaDB also work, but MySQL 8 is the tested target). - A database user with privileges to create the database and tables. - **Put the app into read-only/maintenance mode during the cutover** so no new writes land in SQLite while you migrate: ```bash php artisan down ``` - Record the size and location of the current database: ```bash ls -lh database/database.sqlite ``` Note the path. If it is not `database/database.sqlite`, you will pass it to the transfer command with `--source`. --- ## 1. Back up the SQLite database Keep the SQLite file intact all the way through. Copy it to a timestamped backup and move the original aside (it is the documented rollback path): ```bash cp database/database.sqlite database/database.sqlite.bak-$(date +%Y%m%d%H%M%S) ``` The transfer command reads the file directly, so the original must still be at `database/database.sqlite` (or referenced via `--source`) during the cutover. --- ## 2. Create the MySQL database and user Run from a MySQL client with admin access: ```sql CREATE DATABASE mytodos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'mytodos'@'%' IDENTIFIED BY ''; GRANT ALL PRIVILEGES ON mytodos.* TO 'mytodos'@'%'; FLUSH PRIVILEGES; ``` Use a user scoped to `mytodos.*` — **do not grant global privileges**. Restrict `'mytodos'@'localhost'` instead of `'%'` if the app always connects via the local socket/host. --- ## 3. Deploy the MySQL-compatible code The code changes from the local migration must be on the server: ```bash git pull --ff-only origin main composer install --no-dev --prefer-dist --optimize-autoloader npm ci --no-audit --no-fund npm run build ``` Relevant changes in this release: - `config/database.php` — MySQL default connection + `sqlite_source` connection. - `app/Console/Commands/TransferSqliteData.php` — the `db:transfer-sqlite` command. - `phpunit.xml`, `.env.testing(.example)`, `.github/workflows/tests.yml` — test/CI only, no production impact. --- ## 4. Update the environment Switch the application to MySQL, using the credentials from step 2: ```dotenv DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=mytodos DB_USERNAME=mytodos DB_PASSWORD= ``` - Keep the old `database/database.sqlite` file in place (see step 6). - If you previously ran `php artisan config:cache`, the config is cached and will not pick up the new `.env` until step 8. Run `php artisan config:clear` before the next `config:cache`, or rely on the cache rebuild in step 8. --- ## 5. Run the migrations against the empty MySQL database The MySQL database is still empty. Apply the schema: ```bash php artisan migrate --force ``` Do not seed yet — the data comes from SQLite in the next step. --- ## 6. Transfer the data Run the transfer command. It copies the domain tables (`users`, `folders`, `todos`, `passkeys`, `password_reset_tokens`) from SQLite into MySQL, preserving IDs, then resets MySQL auto-increment counters. If the SQLite file is at the default path: ```bash php artisan db:transfer-sqlite --force ``` If it lives elsewhere: ```bash php artisan db:transfer-sqlite --source=/var/www/app/database/database.sqlite --force ``` The `--force` flag is required because `APP_ENV` is `production`. The command: - aborts unless the destination connection is MySQL; - truncates the destination domain tables before inserting (it is idempotent); - skips framework/transient tables (`cache`, `sessions`, `jobs`, `migrations`, …). Expected output: ``` Copying data from /var/www/app/database/database.sqlite into the 'mysql' connection. transferred N row(s) into users. transferred N row(s) into folders. ... Data transfer complete. ``` --- ## 7. Verify the transfer Compare row counts and spot-check a sample: ```bash php artisan tinker --execute ' $source = DB::connection("sqlite_source"); foreach (["users", "folders", "todos", "passkeys"] as $table) { echo $table.": ".$source->table($table)->count()." -> ".DB::table($table)->count().PHP_EOL; } ' ``` Manually confirm a few rows and the max IDs on MySQL: ```bash php artisan tinker --execute ' foreach (["users", "folders", "todos", "passkeys"] as $table) { echo $table." max id: ".DB::table($table)->max("id").PHP_EOL; } ' ``` Then re-create the admin/administrator account that `BaseDatabaseSeeder` owns: ```bash php artisan db:seed --class=BaseDatabaseSeeder --force ``` --- ## 8. Finalize ```bash php artisan config:cache php artisan route:cache php artisan view:cache php artisan queue:restart php artisan up ``` Smoke-test from outside: log in, load the dashboard, run a search, toggle a status filter, and drag-reorder a todo. --- ## 9. Post-migration cleanup (optional, after a soak period) Once you are confident MySQL is healthy: - Archive the SQLite backup off the server (or delete it) after you have confirmed there are no rollback triggers. - Consider deleting the one-time `app/Console/Commands/TransferSqliteData.php` command so it can never truncate production tables by accident. - Update `deploy.sh`'s comments if they reference SQLite. --- ## Rollback 1. `php artisan down`. 2. Point the app back at SQLite: ```dotenv DB_CONNECTION=sqlite # remove the DB_HOST/DB_PORT/DB_DATABASE/DB_USERNAME/DB_PASSWORD MySQL lines ``` 3. Replace the (unmigrated) original with your backup: ```bash cp database/database.sqlite.bak- database/database.sqlite ``` 4. `php artisan config:clear && php artisan up`. Note: any rows written into MySQL after step 5 are not on the SQLite backup and will be lost on rollback. --- ## Production notes - **Ordering matters**: migrate → transfer → seed. Running `db:seed` before the transfer would create a conflicting admin user truncated by the transfer's destination-table wipe. - **Timezone**: SQLite stores Laravel timestamps as `YYYY-MM-DD HH:MM:SS` text. Those strings transfer verbatim and MySQL interprets them as-is; ensure the MySQL session timezone matches the app's `app.timezone`/`APP_TIMEZONE` if you observe hour shifts. - **Search behavior**: `LIKE` becomes case- and accent-insensitive under `utf8mb4_unicode_ci` — a deliberate, generally desirable change from SQLite's ASCII-only behavior. - **Index/key limits**: the schema requires MySQL 5.7.7+ / 8.0 (InnoDB 3072-byte key limit). Do not run this against MySQL 5.6.