jobtrackingapp/docs/database/mariadb-standardisation/PLAN.md

MariaDB standardisation implementation plan

Execute autonomously under the product owner's explicit instruction, using focused independent tasks and final review. No additional design approval or integration menu is required.

Goal: Make MariaDB the standard application database, provide reproducible local/CI persistence tests and qualify the existing RD21 repair on a real server.

Baseline: 0d16a691e0249fe1264bf960de5e59eaa9b87fed, branch codex/rd21-mariadb-standardisation.

Architecture: Reuse Pomelo 9.0.0, EF Core 9.0.14 and the existing startup migration/reconciliation chain. Use a standalone local Compose project with separate persistent development and disposable integration storage. Primary production-version target is owner-verified 12.2.2-MariaDB-ubu2404, currently running floating mariadb:latest. Official 12.2.2 Linux/amd64 manifest sha256:42a27baaba3e8f3f0159d16381d5a7156661aa91dcc65f663cabb6a6f9503c00 and all image blobs were obtained and verified. Its config digest differs from the owner's running image ID; exact image equality is not claimed. Native 12.2.2 may supply separately labelled local evidence if Docker cannot start. Investigate 12.3.3 LTS as a future staging target; never upgrade production in this task.

Constraints: No main merge, production deployment/migration/database access, live service restart, Phase 10, historical-data deletion or alteration of existing migration history. Do not label SQLite/InMemory or generated SQL as MariaDB runtime evidence. Preserve auth/CSRF/tenant/document boundaries.

Tasks and ownership

1. Coordinator: inspect current configuration, use verified official MariaDB 12.2.2 image/runtime pin, create standalone Compose development/test services, explicit provider configuration and startup tests. Never silently fall back to SQLite. Preserve explicit transitional SQLite access to existing data. Provide safe test setup/reset guardrails and local instructions.
2. Persistence implementer: own JobTrackerApi.MariaDb.Tests/ only. Create an explicit real-MariaDB integration project, unique disposable database fixture using loopback-only development credentials, actual startup migration/reconciliation, independent contexts and persisted-state assertions. Missing/unreachable server fails this explicit lane, never skips. Cover Career/job revisions, first-save and overlapping writes, atomic rollback/failure recovery, related text writers, tenant isolation, legacy missing revisions and held readers/writers. Do not alter existing production migration files. Report provider inconsistencies with exact failures before fixes.
3. Audit/fixture implementer: own the three obsolete Phase 9 diagnostic/volume fixture sources and new SQLite audit/retirement documentation. Inventory all tracked SQLite references and classify required historical/preservation, temporary transition, or obsolete current guidance/defaults. Repair source revision seeds and stale-write expectations to the correct safety contract without deleting or weakening safety assertions. Keep historical acceptance reports unchanged. Propose staged retirement; no data/package/migration deletion.
4. Coordinator: wire the same integration command to CI without deployment, run isolated actual MariaDB qualification and complete backend/frontend/affected browser/static checks, fix verified provider inconsistencies at their owner, review final diff, update current architecture/setup guidance and repo TODO. Commit/push validated checkpoints and verify remote equality/clean tree/main unchanged. Record all nine owner-requested readiness decisions and remaining blockers.

Verification and stopping conditions

• Capture actual server version, provider/EF versions, migration state and fresh/repeated/populated startup results.
• New tests fail before relevant fixes; pass with independent persisted-state assertions after fixes. Concurrency uses controlled synchronization rather than arbitrary sleeps/retries.
• Test resources must be newly generated jt_it_* databases on loopback with dedicated local test credentials. Never reuse development volumes/databases or connection secrets. Cleanup may target only databases created by that fixture/run; retain useful failure artifacts.
• No SQLite dependency removal until its replacement coverage and required data-preservation path exist. Full retirement may remain a staged follow-up.
• RD21 closure requires actual supported MariaDB concurrency, constraints and rollback evidence, plus existing client/browser proof. Other Phase 9/manual/provider/production gates remain independent.
• Review failure behavior for missing/unknown provider, unavailable server, retry/repeated initialization, SQL dialect/type/index differences, and accidental selection of a non-disposable database.

Initial findings

Baseline default/fallback provider: SQLite. MariaDB options hardcoded 11.0.0. Existing application dependencies: Pomelo 9.0.0, EF Core 9.0.14, SQLite 9.0.14/native 2.1.12. Historical migration chain includes dialect branches plus startup reconciliation. Repository did not record deployed patch; deploy/deploy.sh uses mariadb:11. Owner subsequently verified production12.2.2 and image configID sha256:e0236fc6386e7eacd9359e59d0a078bd7aa0d18280d36d13061121bedeaee903; this is NOT a pullable registry digest. The initial11.4 candidate/archive was abandoned before runtime tests and provides no qualification. Docker Desktop initially failed creating its inference-manager Unix listener. That local failure was subsequently resolved by preserving verified socket-only runtime directories; see recovery. No factory reset or production service operation occurred.

Completed qualification checkpoint

• Official pinned12.2.2 Docker image obtained, verified and executed.
• Persistent development service, actual API migrations and row preservation across restart.
• Reproducible disposable integration runner32/32 and CI workflow; hosted run843 is blocked before tests by missing Docker CLI.
• Provider defects reproduced and minimally repaired; current Release backend1123/1123.
• Native MariaDB browser recovery1/1; canonical target guards10/10; runner guards5/5.
• Three obsolete fixtures repaired; diagnostics18/18 and volume3/3.
• Complete baseline SQLite classification, staged preservation-first retirement and12.3LTS investigation.
• Independent review findings resolved; acceptance and explicit remaining gates recorded.

Publication is on the dedicated development branch only. The acceptance record contains the nine separate decisions; wider Phase9, Phase10 and production remain NO-GO.