Skip to content

feat(quality): add MariaDB to the PHPUnit database matrix so migrations run on MariaDB in CI #937

Open

Description

@WilcoLouwerse

Problem

The shared quality.yml workflow never runs an app's migrations on MariaDB. PHPUnit runs on PostgreSQL 16 by default, and the opt-in matrix only knows pgsql, mysql (MySQL 8.4) and sqlite. A migration that is invalid on MariaDB therefore passes CI in every app and only fails on a real MariaDB install.

Evidence

ConductionNL/openregister#4909: a migration created a column named row_number. ROW_NUMBER is a reserved word on MariaDB, and the schema tooling used by Nextcloud (Doctrine DBAL 3.10.4, per the investigation in that issue) does not quote it for MariaDB, so occ app:update openregister failed with SQLSTATE[42000] 1064 on a MariaDB 11.3 installation. Fix: column renamed to source_row (openregister#5879 on main, openregister#5957 on stable2.1), plus a unit test on reserved column names in the app.

Why CI did not catch it:

  • phpunit runs occ maintenance:install and occ app:enable <app> per leg, so the app's migrations do run, but only on the leg's database (default pgsql).
  • A mysql leg would not have caught this either: according to the #4909 investigation the word is in DBAL's MySQL 8 keyword list (so it is quoted there) but not in its MariaDB list. Only a real MariaDB server reproduces it.
  • openregister's own caller (.github/workflows/code-quality.yml, calls ConductionNL/.github/.github/workflows/quality.yml@main) sets neither database nor database-test-matrix.

The app-level unit test stops this one word list from regressing in one app. It does not cover other MariaDB-specific failures (other reserved words missing from DBAL's list, index length, charset, syntax), and it does not exist in the other apps.

What the shared workflow does today (quality.yml on main)

  • Input database (default pgsql) and input database-test-matrix (JSON array, default []). An empty matrix collapses to the single database value; the matrix is documented as inert until an app opts in.
  • The phpunit job (name PHPUnit (PHP x, NC y, <database>)) has the matrix dimensions php-version x nextcloud-ref (derived from the app's appinfo/info.xml) x database.
  • Service containers: postgres:16 when matrix.database == 'pgsql', mysql:8.4 when 'mysql'. There is no MariaDB service container and no mariadb image anywhere in the file.
  • The "Install Nextcloud" step already has a mysql|mariadb) branch (installs with --database mysql, host 127.0.0.1:3306) and a positive control mapping mariadb to dbtype=mysql. So a mariadb value is accepted by the install step but would start no database today and fail to connect.
  • newman, playwright and journeydoc-capture use only inputs.database and start only a postgres service; they cannot take a MariaDB leg without more work and are out of scope here.
  • The PHPUnit result is part of quality / Quality Report, which is the required check on the fleet's protected branches.
  • No app in the org appears to set database-test-matrix yet (code search found only docs and notes; not exhaustive).

Proposal

  1. Add a mariadb service container to the phpunit job: image: ${{ matrix.database == 'mariadb' && 'mariadb:<version>' || '' }}, same credentials, port 3306 and health check as the mysql service. Both services bind 3306, but only one starts per leg.
  2. Accept mariadb in database-test-matrix (the install step and positive control already handle it) and document it on the input.
  3. Decide how apps get the leg without a leg explosion (options in "Open design points").
  4. Opt openregister in first; roll out to other apps whose migrations are run in CI after that.
  5. Update docs/WayOfWork/development-pipeline.md (row "Database": "PostgreSQL 16 by default; MySQL 8.4 and SQLite opt-in").

Open design points (decide before building)

  • Opt-in or default? Opt-in per app via database-test-matrix keeps today's behaviour for everyone; a default MariaDB leg catches the bug class fleet-wide but turns apps with an existing MariaDB problem red at once.
  • Leg count. Adding mariadb to the matrix multiplies every php x NC combination (openregister on a push: 2 PHP x 4 NC = 8 legs today, so 16 with MariaDB; on a pull request with reduce-pr-matrix it is 1 leg, so 2). Alternative: one MariaDB leg only (primary PHP, newest NC), e.g. via an include entry.
  • MariaDB version. The only known MariaDB installation (directory.opencatalogi.nl) runs 11.3.2, per the #4909 investigation. Which MariaDB versions Nextcloud 32-35 supports, and whether to also test an LTS line such as 10.11, is not verified; info.xml declares no MariaDB version. Settle with the Nextcloud admin manual's database requirements for each declared server version.
  • Image pinning. mysql:8.4 and postgres:16 are tags, not digests; follow the same convention for the new service.

Acceptance criteria

  • database-test-matrix: '["pgsql", "mariadb"]' (or the chosen shape) starts a MariaDB service and the phpunit leg installs Nextcloud on it; the positive control reports dbtype=mysql and the job log shows the server is MariaDB.
  • A migration that uses a MariaDB reserved word as a column name that DBAL does not quote (reproduce with row_number) turns the MariaDB leg red, and the same change keeps the pgsql leg green. Shown on a throwaway branch of a caller repo.
  • The MariaDB leg's result is included in quality / Quality Report (a red leg makes the report red) and visible by name in the checks list of an app PR.
  • Without the input, nothing changes for existing callers (same jobs, same names).
  • The chosen MariaDB version(s) are stated in the workflow comment with the reason, and the decision on opt-in versus default is written down.
  • openregister opts in; its run on MariaDB is green on the current main and stable2.1, or the failures are listed as separate issues.
  • docs/WayOfWork/development-pipeline.md describes the new option.

Risks

  • More CI minutes and slower runs (measured by the workflow's own comments: about 2.2 min per PHPUnit leg, of which most is container init and Nextcloud install).
  • An app whose migrations already fail on MariaDB turns red when it opts in (or when this becomes a default).
  • Unit tests that hard-code PostgreSQL behaviour may fail on MariaDB for reasons unrelated to migrations.

Not verified

  • Which MariaDB versions are supported for NC 32-35 (see above).
  • Whether any app already sets database-test-matrix (full check: search every repo's .github/workflows/*.yml for the key).
  • Whether the quality-selftest.yml of this repository can cover a multi-database case (a grep for "database" in it found nothing).

Activity

  1. WilcoLouwerse commented on Nov 13, 2026

    @WilcoLouwerse
    ContributorAuthor

    Status 2026-11-13 — Steps 1 and 2 done

    • Design decisions: the leg is opt-in per app via database-test-matrix (openregister first), it runs the full PHPUnit suite on MariaDB with a fallback to a short install job if the suite turns out red for other reasons, and mariadb is a plain extra matrix value (no include rule for now; I will measure the minutes first). I build all of it myself.
    • MariaDB version: 11.4 and 12.3. I first proposed 11.3, but that dropped out on checking: 11.3 has been end-of-life since 2024-05-29 and is not listed in the Nextcloud admin manual for NC 32-35. The manual lists 11.4 for NC 32-35 and 12.3 (recommended) for NC 35. My proposal for the legs, to be confirmed in the PR: no extra legs, mariadb:12.3 on the NC 35 leg and mariadb:11.4 on NC 32-34.
    • No self-test case is possible: quality-selftest.yml runs with enable-phpunit: false and a permanent PHPUnit fixture caller was deliberately rejected earlier. The proof therefore comes from a throwaway caller branch in openregister (reserved column name: MariaDB leg red, pgsql leg green).
    • Checked on current main: quality.yml is unchanged, all 21 swept apps call it with enable-phpunit: true and none sets database-test-matrix. Note that reduce-pr-matrix does not reduce the database dimension, so the leg count doubles on a PR as well.

    Full plan: .github-937-plan-13-11.txt

  2. WilcoLouwerse commented on Nov 13, 2026

    @WilcoLouwerse
    ContributorAuthor

    Status 2026-11-13 — Steps 3 and 4 (first part) done, scope extended

    • Branch feature/937-mariadb-matrix-leg is cut from main and pushed. First commit: ae05674 (MariaDB service container, input text and the pipeline docs).
    • Scope extension, decided today: the PR matrix reduction gets an input so it also applies to repositories whose mainline is main (default unchanged, so no change for other apps). Each extra database in database-test-matrix costs exactly one leg (primary PHP x newest Nextcloud) instead of multiplying the whole matrix. MySQL is included for openregister in the same work.
    • Follow-up apps: the seven apps with their own schema migrations (integriq, keepiq, larpinq, opencatalogi, launchpad, planninq, versioniq), one issue per app, MariaDB first, once openregister is green.
    • The proof runs are still pending because the runner queue is long; I will add the results when they are in.

    Full plan: .github-937-plan-13-11.txt

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions