Skip to content

Commit 6f38ffd

Browse files
josecelanojosecelano
committed
feat: [#232] implement MySQL database configuration in tracker template
This commit completes Phase 3 of MySQL support by extending the tracker configuration template to support both SQLite and MySQL databases. Changes: - Extended TrackerContext with database driver and MySQL connection fields - Updated tracker.toml.tera to conditionally render database paths: * SQLite: file path format * MySQL: connection string format (mysql://user:pass@host:port/database) - Added comprehensive tests for both SQLite and MySQL configurations - Fixed long namespace paths following module organization conventions - Created ADR documenting database configuration structure decision The template now exposes structured database configuration (host, port, user, password) rather than pre-resolved connection strings, aligning with planned Torrust Tracker API improvements and hiding ORM implementation details. All 1469 unit tests passing. All pre-commit checks passing.
1 parent d4c86c4 commit 6f38ffd

File tree

5 files changed

+377
-43
lines changed

5 files changed

+377
-43
lines changed

‎docs/decisions/README.md‎

Lines changed: 26 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -4,31 +4,32 @@ This directory contains architectural decision records for the Torrust Tracker D
44

55
## Decision Index
66

7-
| Status | Date | Decision | Summary |
8-
| ------------- | ---------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
9-
| ✅ Accepted | 2025-12-13 | [Environment Variable Injection in Docker Compose](./environment-variable-injection-in-docker-compose.md) | Use .env file injection instead of hardcoded values for runtime configuration changes |
10-
| ✅ Accepted | 2025-12-11 | [Cloud-Init SSH Port Configuration with Reboot](./cloud-init-ssh-port-reboot.md) | Use cloud-init with reboot pattern to configure custom SSH ports during VM provisioning |
11-
| ✅ Accepted | 2025-12-10 | [Single Docker Image for Sequential E2E Command Testing](./single-docker-image-sequential-testing.md) | Use single Docker image with sequential command execution instead of multi-image phases |
12-
| ✅ Accepted | 2025-12-09 | [Register Command SSH Port Override](./register-ssh-port-override.md) | Add optional --ssh-port argument to register command for non-standard SSH ports |
13-
| ✅ Accepted | 2025-11-19 | [Disable MD060 Table Formatting Rule](./md060-table-formatting-disabled.md) | Disable MD060 to allow flexible table formatting and emoji usage |
14-
| ✅ Accepted | 2025-11-19 | [Test Command as Smoke Test](./test-command-as-smoke-test.md) | Test command validates running services, not infrastructure components |
15-
| ✅ Accepted | 2025-11-13 | [Migration to AGENTS.md Standard](./agents-md-migration.md) | Adopt open AGENTS.md standard for multi-agent compatibility while keeping GitHub redirect |
16-
| ✅ Accepted | 2025-11-11 | [Use ReentrantMutex Pattern for UserOutput Reentrancy](./reentrant-mutex-useroutput-pattern.md) | Use Arc<ReentrantMutex<RefCell<UserOutput>>> to fix same-thread deadlock in issue #164 |
17-
| ❌ Superseded | 2025-11-11 | [Remove UserOutput Mutex](./user-output-mutex-removal.md) | Remove Arc<Mutex<UserOutput>> pattern for simplified, deadlock-free architecture |
18-
| ✅ Accepted | 2025-11-07 | [ExecutionContext Wrapper Pattern](./execution-context-wrapper.md) | Use ExecutionContext wrapper around Container for future-proof command signatures |
19-
| ✅ Accepted | 2025-11-03 | [Environment Variable Prefix](./environment-variable-prefix.md) | Use `TORRUST_TD_` prefix for all environment variables |
20-
| ✅ Accepted | 2025-10-15 | [External Tool Adapters Organization](./external-tool-adapters-organization.md) | Consolidate external tool wrappers in `src/adapters/` for better discoverability |
21-
| ✅ Accepted | 2025-10-10 | [Repository Rename to Deployer](./repository-rename-to-deployer.md) | Rename from "Torrust Tracker Deploy" to "Torrust Tracker Deployer" for production use |
22-
| ✅ Accepted | 2025-10-03 | [Error Context Strategy](./error-context-strategy.md) | Use structured error context with trace files for complete error information |
23-
| ✅ Accepted | 2025-10-03 | [Command State Return Pattern](./command-state-return-pattern.md) | Commands return typed states (Environment<S> → Environment<T>) for compile-time safety |
24-
| ✅ Accepted | 2025-10-03 | [Actionable Error Messages](./actionable-error-messages.md) | Use tiered help system with brief tips + .help() method for detailed troubleshooting |
25-
| ✅ Accepted | 2025-10-01 | [Type Erasure for Environment States](./type-erasure-for-environment-states.md) | Use enum-based type erasure to enable runtime handling and serialization of typed states |
26-
| ✅ Accepted | 2025-09-29 | [Test Context vs Deployment Environment Naming](./test-context-vs-deployment-environment-naming.md) | Rename TestEnvironment to TestContext to avoid conflicts with multi-environment feature |
27-
| ✅ Accepted | 2025-09-10 | [LXD VMs over Containers](./lxd-vm-over-containers.md) | Use LXD virtual machines instead of containers for production alignment |
28-
| ✅ Accepted | 2025-09-09 | [Tera Minimal Templating Strategy](./tera-minimal-templating-strategy.md) | Use Tera with minimal variables and templates to avoid complexity and delimiter conflicts |
29-
| ✅ Accepted | - | [LXD over Multipass](./lxd-over-multipass.md) | Choose LXD containers over Multipass VMs for deployment testing |
30-
| ✅ Resolved | - | [Docker Testing Evolution](./docker-testing-evolution.md) | Evolution from Docker rejection to hybrid approach for split E2E testing |
31-
| ✅ Accepted | - | [Meson Removal](./meson-removal.md) | Remove Meson build system from the project |
7+
| Status | Date | Decision | Summary |
8+
| ------------- | ---------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
9+
| ✅ Accepted | 2025-12-14 | [Database Configuration Structure in Templates](./database-configuration-structure-in-templates.md) | Expose structured database fields in templates rather than pre-resolved connection strings |
10+
| ✅ Accepted | 2025-12-13 | [Environment Variable Injection in Docker Compose](./environment-variable-injection-in-docker-compose.md) | Use .env file injection instead of hardcoded values for runtime configuration changes |
11+
| ✅ Accepted | 2025-12-11 | [Cloud-Init SSH Port Configuration with Reboot](./cloud-init-ssh-port-reboot.md) | Use cloud-init with reboot pattern to configure custom SSH ports during VM provisioning |
12+
| ✅ Accepted | 2025-12-10 | [Single Docker Image for Sequential E2E Command Testing](./single-docker-image-sequential-testing.md) | Use single Docker image with sequential command execution instead of multi-image phases |
13+
| ✅ Accepted | 2025-12-09 | [Register Command SSH Port Override](./register-ssh-port-override.md) | Add optional --ssh-port argument to register command for non-standard SSH ports |
14+
| ✅ Accepted | 2025-11-19 | [Disable MD060 Table Formatting Rule](./md060-table-formatting-disabled.md) | Disable MD060 to allow flexible table formatting and emoji usage |
15+
| ✅ Accepted | 2025-11-19 | [Test Command as Smoke Test](./test-command-as-smoke-test.md) | Test command validates running services, not infrastructure components |
16+
| ✅ Accepted | 2025-11-13 | [Migration to AGENTS.md Standard](./agents-md-migration.md) | Adopt open AGENTS.md standard for multi-agent compatibility while keeping GitHub redirect |
17+
| ✅ Accepted | 2025-11-11 | [Use ReentrantMutex Pattern for UserOutput Reentrancy](./reentrant-mutex-useroutput-pattern.md) | Use Arc<ReentrantMutex<RefCell<UserOutput>>> to fix same-thread deadlock in issue #164 |
18+
| ❌ Superseded | 2025-11-11 | [Remove UserOutput Mutex](./user-output-mutex-removal.md) | Remove Arc<Mutex<UserOutput>> pattern for simplified, deadlock-free architecture |
19+
| ✅ Accepted | 2025-11-07 | [ExecutionContext Wrapper Pattern](./execution-context-wrapper.md) | Use ExecutionContext wrapper around Container for future-proof command signatures |
20+
| ✅ Accepted | 2025-11-03 | [Environment Variable Prefix](./environment-variable-prefix.md) | Use `TORRUST_TD_` prefix for all environment variables |
21+
| ✅ Accepted | 2025-10-15 | [External Tool Adapters Organization](./external-tool-adapters-organization.md) | Consolidate external tool wrappers in `src/adapters/` for better discoverability |
22+
| ✅ Accepted | 2025-10-10 | [Repository Rename to Deployer](./repository-rename-to-deployer.md) | Rename from "Torrust Tracker Deploy" to "Torrust Tracker Deployer" for production use |
23+
| ✅ Accepted | 2025-10-03 | [Error Context Strategy](./error-context-strategy.md) | Use structured error context with trace files for complete error information |
24+
| ✅ Accepted | 2025-10-03 | [Command State Return Pattern](./command-state-return-pattern.md) | Commands return typed states (Environment<S> → Environment<T>) for compile-time safety |
25+
| ✅ Accepted | 2025-10-03 | [Actionable Error Messages](./actionable-error-messages.md) | Use tiered help system with brief tips + .help() method for detailed troubleshooting |
26+
| ✅ Accepted | 2025-10-01 | [Type Erasure for Environment States](./type-erasure-for-environment-states.md) | Use enum-based type erasure to enable runtime handling and serialization of typed states |
27+
| ✅ Accepted | 2025-09-29 | [Test Context vs Deployment Environment Naming](./test-context-vs-deployment-environment-naming.md) | Rename TestEnvironment to TestContext to avoid conflicts with multi-environment feature |
28+
| ✅ Accepted | 2025-09-10 | [LXD VMs over Containers](./lxd-vm-over-containers.md) | Use LXD virtual machines instead of containers for production alignment |
29+
| ✅ Accepted | 2025-09-09 | [Tera Minimal Templating Strategy](./tera-minimal-templating-strategy.md) | Use Tera with minimal variables and templates to avoid complexity and delimiter conflicts |
30+
| ✅ Accepted | - | [LXD over Multipass](./lxd-over-multipass.md) | Choose LXD containers over Multipass VMs for deployment testing |
31+
| ✅ Resolved | - | [Docker Testing Evolution](./docker-testing-evolution.md) | Evolution from Docker rejection to hybrid approach for split E2E testing |
32+
| ✅ Accepted | - | [Meson Removal](./meson-removal.md) | Remove Meson build system from the project |
3233

3334
## ADR Template
3435

‎docs/decisions/database-configuration-structure-in-templates.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Decision: Database Configuration Structure in Templates
2+
3+
## Status
4+
5+
✅ Accepted
6+
7+
## Date
8+
9+
2025-12-14
10+
11+
## Context
12+
13+
When implementing MySQL support for the Torrust Tracker deployer (Issue #232), we needed to decide how to represent database connection information in the `tracker.toml.tera` template. There were two main approaches:
14+
15+
1. **Pre-resolved connection string approach**: Pass a single `database_path` variable to the template containing the complete connection string (e.g., `"mysql://user:pass@host:3306/db"` or `"/var/lib/torrust/tracker/sqlite3.db"`).
16+
17+
2. **Structured configuration approach**: Expose the database configuration structure in the template with separate variables for each database type (driver, host, port, user, password, database_name) and construct the connection string within the template.
18+
19+
The choice impacts:
20+
21+
- Template clarity and readability
22+
- Alignment with future Torrust Tracker API design
23+
- Maintainability and understanding of configuration
24+
- Abstraction of ORM implementation details
25+
26+
## Decision
27+
28+
We will use the **structured configuration approach** - exposing database configuration fields in templates and constructing connection strings within the template using conditional logic based on `database_driver`.
29+
30+
Example implementation in `tracker.toml.tera`:
31+
32+
```toml
33+
[database]
34+
driver = "{{ database_driver }}"
35+
{% if database_driver == "sqlite3" %}
36+
path = "/var/lib/torrust/tracker/{{ database_name }}"
37+
{% elif database_driver == "mysql" %}
38+
path = "mysql://{{ database_user }}:{{ database_password }}@{{ database_host }}:{{ database_port }}/{{ database_name }}"
39+
{% endif %}
40+
```
41+
42+
## Consequences
43+
44+
### Positive
45+
46+
- **Alignment with future Tracker API design**: The Torrust Tracker project is considering exposing structured database configuration (host, port, user, password, database) rather than connection strings in its public API. This template structure aligns with that future direction.
47+
48+
- **Abstraction of implementation details**: Connection string format (using URLs) is an internal implementation detail of the SQLx ORM. By exposing structured fields, we hide this detail and make the configuration more intuitive.
49+
50+
- **Clear configuration structure**: Template readers can immediately see what database parameters are required for each database type without parsing connection strings.
51+
52+
- **Type-specific validation**: Each database type's required fields are explicit in the template, making validation and error messages clearer.
53+
54+
- **Easier to extend**: Adding new database types (e.g., PostgreSQL) requires adding a new conditional block with appropriate fields, rather than complex string manipulation logic.
55+
56+
### Negative
57+
58+
- **Template complexity**: The template contains conditional logic for constructing connection strings, making it slightly more complex than passing a pre-resolved string.
59+
60+
- **Duplication of connection logic**: If multiple templates need database configuration, the connection string construction logic may be duplicated (though this is currently only in `tracker.toml.tera`).
61+
62+
- **Temporary disconnect**: Until the Tracker implements structured configuration API, there's a mismatch between our exposed structure and the Tracker's actual API (connection string in TOML).
63+
64+
### Risks and Mitigations
65+
66+
- **Risk**: Connection string format changes in SQLx or Tracker dependencies.
67+
68+
- **Mitigation**: All connection string construction is centralized in templates. Changes only require template updates, not Rust code changes.
69+
70+
- **Risk**: Template maintainers may not understand ORM connection string requirements.
71+
- **Mitigation**: Add comprehensive comments in the template explaining the format for each database type and linking to relevant documentation.
72+
73+
## Alternatives Considered
74+
75+
### Alternative 1: Pre-resolved Connection String
76+
77+
**Description**: Pass a single `database_path` variable containing the complete connection string resolved in Rust code before template rendering.
78+
79+
**Pros**:
80+
81+
- Simpler template with no conditional logic
82+
- Connection string construction in type-safe Rust code
83+
- Single source of truth for connection format
84+
85+
**Cons**:
86+
87+
- Exposes ORM implementation details in high-level configuration
88+
- Doesn't align with planned Tracker API improvements
89+
- Less clear what configuration parameters are required
90+
- Connection strings are opaque to template readers
91+
92+
**Why rejected**: Prioritizing alignment with future Tracker design and configuration clarity over template simplicity.
93+
94+
### Alternative 2: Hybrid Approach
95+
96+
**Description**: Pass both structured fields and pre-resolved connection string, allowing templates to choose which to use.
97+
98+
**Pros**:
99+
100+
- Maximum flexibility
101+
- Easy migration path
102+
103+
**Cons**:
104+
105+
- Redundant data in context
106+
- Confusion about which to use
107+
- Increased maintenance burden
108+
109+
**Why rejected**: Adds complexity without clear benefit. We should commit to one approach.
110+
111+
## Related Decisions
112+
113+
- [Environment Variable Injection in Docker Compose](./environment-variable-injection-in-docker-compose.md) - Similar principle of exposing configuration structure rather than pre-computed values
114+
- Issue #232: MySQL slice release/run commands - The implementation that motivated this decision
115+
116+
## References
117+
118+
- [SQLx Database URLs](https://docs.rs/sqlx/latest/sqlx/trait.Database.html) - Connection string format documentation
119+
- [Torrust Tracker Configuration](https://github.com/torrust/torrust-tracker/blob/develop/docs/config.md) - Current configuration format
120+
- Future Tracker configuration API discussion (planned improvement, no reference yet)
121+
- [Tera Minimal Templating Strategy](./tera-minimal-templating-strategy.md) - Our template philosophy and variable usage approach

0 commit comments

Comments
 (0)