The mysql56-migrate component#
The mysql56-migrate component makes CREED's database rule runnable: an app MUST run its migrations in CI against a real MySQL 5.6, because Citadel's shared server is MySQL 5.6.51. A test suite on SQLite can pass DDL that 5.6 rejects, most famously a JSON column and a utf8mb4 index longer than 767 bytes. This component starts the exact Squire pin, mysql:5.6.51, as a GitLab service, waits for it, and runs the app's migration command. If the migration would fail on the shared server, the pipeline says so before release.
Add the include#
A Laravel app needs only the include: the default migrate_command is php artisan migrate --force --no-interaction, and the job sets the DB_* variables Laravel reads.
include:
- component: $CI_SERVER_FQDN/enterprise-apps/preflight/mysql56-migrate@<full commit SHA> # <tag>
Pin the full commit SHA of the release tag you use.
Inputs#
| Input | Type | Default | What it does |
|---|---|---|---|
stage |
string | test |
Pipeline stage for the mysql56-migrate job. |
job_name |
string | mysql56-migrate |
Name of the job. Set it when you include this component more than once. |
image |
string | php:8.5-cli-trixie@sha256:50956f094e90a716d43bea28087d447555ad80510e386ab8c9c10d8c70d781a9 |
Container image for the job. It needs PHP 8.3 or later; the job installs any missing php_extensions itself. |
image_prefix |
string | ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX} |
Registry path put in front of the image and service_image values. The default is this group's GitLab Dependency Proxy, so Docker Hub images are pulled once and then served from GitLab's cache. On a GitLab or group without the proxy, set it to docker.io. No trailing slash. |
service_image |
string | mysql:5.6.51@sha256:20575ecebe6216036d25dab5903808211f1e9ba63dc7825ac20cb975e34cfcae |
MySQL 5.6.51 service image, the same pin Squire runs locally. |
db_name |
string | app |
Database name created by the service. |
db_user |
string | app |
Database user created by the service. |
db_password |
string | preflight-mysql56-ci |
Throwaway password for the ephemeral service; nothing outside the job connects to it. |
migrate_command |
string | php artisan migrate --force --no-interaction |
Command that runs the app's migrations. |
tags |
array | ["amd64"] |
Runner tags for the job. The official MySQL 5.6 images are amd64 only; set an empty list on an amd64 or emulating default runner. |
php_extensions |
array | ["pdo_mysql"] |
PHP extensions installed with docker-php-ext-install unless php -m already lists them. |
An app whose composer.json needs extensions with system libraries (intl, zip, gd) sets image to one that has them, since docker-php-ext-install alone cannot build those.
How the job works#
The job is named by job_name (default mysql56-migrate). It runs in the test stage by default, is interruptible: true, and has a timeout of 30 minutes. In order, it:
- Installs every extension in
php_extensionsthatphp -mdoes not already list. The officialphp:*-cliimages shipPDOandmysqlndbut notpdo_mysql. - Runs
composer install --no-interaction --no-progresswhen acomposer.jsonexists, using the fixed Composer cache keypreflight-mysql56-migrateand the path.composer-cache/. When the image has no Composer, it installs Composer 2.11.1 first (verified by its SHA-256 checksum, with git and unzip through apt-get). - Waits for the MySQL service with a bounded loop: up to 60 tries, 2 seconds apart. Each try is a PDO connect through
php -r. On timeout it prints one clear line and exits 1. - Runs
migrate_commandwith the job'sDB_*variables:DB_CONNECTION=mysql,DB_HOST=mysql,DB_PORT=3306, and thedb_name,db_useranddb_passwordvalues.
The service is mysql:5.6.51, pinned by digest and reached through image_prefix, with alias: mysql. The service creates the database and user from the same inputs, so the job never points at a database outside the pipeline.
A raw PHP app#
An app without Laravel points migrate_command at the script that applies its migrations:
include:
- component: $CI_SERVER_FQDN/enterprise-apps/preflight/mysql56-migrate@<full commit SHA> # <tag>
inputs:
migrate_command: php database/migrate.php
The script reads the same DB_* environment variables. It does not need a framework, a queue worker or a running web server.
Gating#
The rules are baked into the component, like WELD's portability job:
- never on
schedulepipelines; - run on tags and on the default branch;
when: manualwithallow_failure: trueon merge requests;- nothing else.
That keeps a real 5.6 container off scheduled runs and off the small shared amd64 host except where a migration actually changed.
Verify locally#
Preflight's own pipeline includes the component on a clean fixture (tests/mysql56-migrate/clean) and runs tests/check-mysql56-migrate.sh as must-fail-mysql56-migrate. The check drops and recreates the database before each case, proves the clean fixture exits 0, and proves the two flawed fixtures fail with the server errors 5.6 reports: a JSON column (error 1064) and a too-long utf8mb4 index (error 1071). See Local checks for the commands.
Related#
- Include a component twice: the
job_nameinput. - Same instance only: components run only inside the GitLab instance that hosts this project.
- When the components run: the
workflow:rulesblock that belongs in the app's own file. - Reference: every component, with its inputs and defaults.