MySQL Slice - Release and Run Commands

[josecelano]

MySQL Slice - Release and Run Commands

Overview

Add MySQL as a database option for Torrust Tracker deployment. This task extends the docker-compose stack with a MySQL service and allows users to choose between SQLite (default) and MySQL through environment configuration, providing production-ready database scalability while maintaining backward compatibility.

Specification

See detailed specification: docs/issues/mysql-slice-release-run-commands.md

(Link will be updated to include issue number after file rename)

🏗️ Architecture Requirements

DDD Layers: Infrastructure + Domain
Module Paths:

• src/infrastructure/templating/docker_compose/ - Docker Compose template rendering with MySQL service
• src/infrastructure/templating/tracker/ - Tracker configuration template updates for MySQL
• src/domain/config/environment/ - Environment configuration schema extensions

Pattern: Template System with Project Generator pattern + Configuration-driven service selection

Module Structure Requirements

• Follow template system architecture (see docs/technical/template-system-architecture.md)
• Use Project Generator pattern for MySQL-related templates
• Register static templates explicitly in renderer
• Use .tera extension for dynamic templates
• Environment config drives database driver selection

Architectural Constraints

• MySQL service optional - enabled only when user selects MySQL driver
• SQLite remains default and requires no configuration changes
• Database selection controlled through environment configuration
• Tracker container configuration adapts to selected database driver
• MySQL credentials managed through environment variables

Anti-Patterns to Avoid

• ❌ Breaking SQLite deployments when adding MySQL support
• ❌ Hardcoding MySQL credentials in templates
• ❌ Making MySQL mandatory for all deployments
• ❌ Duplicating tracker configuration for each database type
• ❌ Mixing database initialization logic across multiple templates

Implementation Plan

Phase 1: Add MySQL Service to Docker Compose (2-3 hours)

• Create conditional MySQL service definition in templates/docker-compose/docker-compose.yml
• Add volume definition for MySQL data (conditional)
• Test MySQL service starts when driver is mysql
• Test MySQL service excluded when driver is sqlite3
• Verify MySQL service accessible from tracker container network

Phase 2: Extend Environment Configuration (1-2 hours)

• Add database.driver field to environment schema
• Update environment JSON schema file
• Update environment template examples
• Add validation tests for database driver selection

Phase 3: Conditional Tracker Configuration (2-3 hours)

• Update tracker.toml template with Tera conditionals
• Update docker-compose template with conditional tracker environment variables
• Test template rendering for both database drivers
• Verify tracker.toml correctness for both paths

Phase 4: Service Dependencies and Integration (1-2 hours)

• Add conditional depends_on in docker-compose
• Update Ansible playbook to handle MySQL configuration
• Update project generator to include MySQL templates

Phase 5: Manual E2E Testing (2-3 hours)

• Test SQLite path (backward compatibility)
• Test MySQL path (new feature)
• Test tracker functionality with MySQL

Phase 6: Progressive Configuration Exposure (2-3 hours)

• Expose MySQL credentials to environment configuration
• Update templates to use environment variables
• Update documentation with MySQL configuration examples
• Test with custom MySQL credentials

Phase 7: Documentation and Cleanup (1 hour)

• Update user documentation with MySQL option
• Add troubleshooting guide for MySQL connections
• Document MySQL-specific environment variables
• Add examples for both SQLite and MySQL deployments

Acceptance Criteria

Note for Contributors: These criteria define what the PR reviewer will check. Use this as your pre-review checklist before submitting the PR to minimize back-and-forth iterations.

Quality Checks:

• Pre-commit checks pass: ./scripts/pre-commit.sh

Functional Requirements:

• MySQL service can be added to docker-compose stack via environment config
• SQLite remains default when database driver not specified
• Tracker successfully connects to MySQL when MySQL driver selected
• Tracker successfully uses SQLite when SQLite driver selected (backward compatibility)
• MySQL database tables created automatically on first tracker startup
• Docker volume persists MySQL data across container restarts

Configuration Requirements:

• Environment configuration supports database.driver field
• Environment configuration defaults to sqlite3 if driver not specified
• Environment configuration validates driver values (only sqlite3 or mysql)
• Tracker configuration correctly rendered for both database drivers
• Docker compose environment variables correctly set based on driver selection

Testing Requirements:

• Manual E2E test passes for SQLite path (backward compatibility verified)
• Manual E2E test passes for MySQL path (new feature verified)
• Tracker announce endpoints work with both database drivers
• Tracker API health check passes with both database drivers

Documentation Requirements:

• User guide updated with database driver selection documentation
• Environment configuration examples include MySQL option
• Troubleshooting guide includes MySQL connection issues

Related

• Parent: Implement ReleaseCommand and RunCommand with vertical slices #216 (Epic: Implement ReleaseCommand and RunCommand with vertical slices)
• Previous Task: Tracker Slice - Release and Run Commands #220 (Torrust Tracker slice)
• Roadmap: Roadmap #1 (Project Roadmap) - Task 3.2.3
• Specification: docs/issues/mysql-slice-release-run-commands.md
• Reference: torrust/torrust-demo