Skip to content
This repository was archived by the owner on Oct 10, 2025. It is now read-only.

Commit 13f03d8

Browse files
josecelanojosecelano
committed
docs: [#12] add ADR-003 for MySQL vs MariaDB decision
- Document rationale for choosing MySQL over MariaDB - Reference official Torrust Tracker support and testing - Include technical compatibility considerations - Update documentation cross-references
1 parent b0b779b commit 13f03d8

File tree

4 files changed

+183
-1
lines changed

4 files changed

+183
-1
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,8 @@ make destroy # Clean up
112112
main Makefile is at repository root
113113
- [ADR-002: Docker for All Services](docs/adr/002-docker-for-all-services.md) -
114114
Why we use Docker for all services including UDP tracker
115+
- [ADR-003: Use MySQL Over MariaDB](docs/adr/003-use-mysql-over-mariadb.md) -
116+
Why we chose MySQL instead of MariaDB for the database backend
115117

116118
## 🛠️ Development
117119

‎docs/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,10 @@ This directory currently contains cross-cutting documentation:
1818

1919
- [ADR-001: Makefile Location](adr/001-makefile-location.md) - Decision to keep
2020
Makefile at repository root level
21+
- [ADR-002: Docker for All Services](adr/002-docker-for-all-services.md) - Decision
22+
to use Docker for all services including UDP tracker
23+
- [ADR-003: Use MySQL Over MariaDB](adr/003-use-mysql-over-mariadb.md) - Decision
24+
to use MySQL instead of MariaDB for database backend
2125

2226
### 📅 [`plans/`](plans/) (Ongoing Plans and Roadmaps)
2327

‎docs/adr/003-use-mysql-over-mariadb.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# ADR-003: Use MySQL Over MariaDB for Database Backend
2+
3+
## Status
4+
5+
Accepted
6+
7+
## Context
8+
9+
As part of the migration from SQLite to a production-ready database backend for the Torrust
10+
Tracker Demo, we needed to choose between MySQL and MariaDB. Both are popular open-source
11+
relational database management systems, with MariaDB being a fork of MySQL that aims to
12+
maintain compatibility while offering additional features and performance improvements.
13+
14+
### Key Considerations
15+
16+
1. **Official Torrust Tracker Support**: The Torrust Tracker project officially documents
17+
and tests specific database drivers
18+
2. **Compatibility and Reliability**: Ensuring maximum compatibility with the tracker
19+
application and minimal integration issues
20+
3. **Community and Documentation**: Availability of support, documentation, and
21+
troubleshooting resources
22+
4. **Future Maintenance**: Long-term maintainability and alignment with upstream project
23+
decisions
24+
5. **Performance**: Database performance for BitTorrent tracker workloads (primarily CRUD
25+
operations)
26+
27+
### Technical Requirements
28+
29+
The Torrust Tracker requires:
30+
31+
- Support for connection pooling via `r2d2_mysql` Rust crate
32+
- MySQL-specific connection string format: `mysql://user:password@host:port/database`
33+
- Compatibility with tracker's database schema and SQL syntax
34+
- Auto-increment primary keys and foreign key constraints
35+
- UTF-8 character encoding support
36+
37+
## Decision
38+
39+
We will use **MySQL 8.0** as the default database backend for the Torrust Tracker Demo instead of MariaDB.
40+
41+
## Rationale
42+
43+
### 1. Official Torrust Tracker Support
44+
45+
- **Documented Support**: Torrust Tracker documentation explicitly mentions "SQLite and
46+
MySQL" support, with no mention of MariaDB
47+
- **Default Configuration**: All official examples, Docker configurations, and test
48+
setups use MySQL 8.0
49+
- **Codebase Implementation**: The tracker uses the `r2d2_mysql` crate specifically
50+
designed for MySQL, not a generic MariaDB-compatible driver
51+
52+
### 2. Testing and Validation
53+
54+
- **Integration Tests**: Torrust Tracker's test suite specifically uses MySQL 8.0
55+
containers for database driver testing
56+
- **CI/CD Pipeline**: The official project's continuous integration validates against
57+
MySQL, ensuring compatibility
58+
- **Environment Variable**: Tests are controlled via
59+
`TORRUST_TRACKER_CORE_RUN_MYSQL_DRIVER_TEST=true`, indicating MySQL-specific testing
60+
61+
### 3. Community and Ecosystem Alignment
62+
63+
- **BitTorrent Community Standard**: The broader BitTorrent tracker community
64+
predominantly uses MySQL
65+
- **Documentation Consistency**: All troubleshooting guides, configuration examples, and
66+
community solutions reference MySQL
67+
- **Upstream Alignment**: Following the same database choice as the upstream Torrust
68+
Tracker project ensures consistent behavior
69+
70+
### 4. Technical Implementation Benefits
71+
72+
- **Connection String Compatibility**: MySQL connection strings are guaranteed to work
73+
with the tracker's database driver
74+
- **SQL Syntax Alignment**: The tracker's SQL queries are written and tested against
75+
MySQL 8.0 specifically
76+
- **Migration Path**: Future updates to Torrust Tracker will be tested against MySQL,
77+
ensuring smooth upgrades
78+
79+
### 5. Reduced Risk Profile
80+
81+
- **Known Configuration**: Using MySQL eliminates uncertainty about MariaDB compatibility edge cases
82+
- **Proven Compatibility**: MySQL 8.0 is the tested and validated database backend for Torrust Tracker
83+
- **Support Availability**: Issues and solutions are more readily available for MySQL configurations
84+
85+
## Consequences
86+
87+
### Positive
88+
89+
- **Maximum Compatibility**: Guaranteed compatibility with current and future Torrust Tracker versions
90+
- **Better Documentation**: All configuration examples and troubleshooting guides apply directly
91+
- **Simplified Maintenance**: No need to test or validate MariaDB-specific compatibility issues
92+
- **Community Support**: Easier to get help from the Torrust community when using the standard database
93+
- **Future-Proof**: Alignment with upstream project decisions reduces migration risks
94+
95+
### Neutral
96+
97+
- **Performance**: Both MySQL and MariaDB would provide similar performance for tracker workloads
98+
- **Resource Usage**: Memory and CPU usage are comparable between the two databases
99+
- **Feature Set**: The tracker uses basic SQL features available in both databases
100+
101+
### Negative
102+
103+
- **Vendor Lock-in**: Choosing MySQL over MariaDB means following Oracle's MySQL development path
104+
- **License Considerations**: MySQL has Oracle's commercial licensing model (though GPL version is used)
105+
- **Missing MariaDB Features**: We won't benefit from MariaDB-specific performance improvements or features
106+
107+
## Implementation
108+
109+
The MySQL 8.0 configuration is implemented as follows:
110+
111+
### Docker Compose Configuration
112+
113+
```yaml
114+
mysql:
115+
image: mysql:8.0
116+
environment:
117+
- MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
118+
- MYSQL_DATABASE=${MYSQL_DATABASE}
119+
- MYSQL_USER=${MYSQL_USER}
120+
- MYSQL_PASSWORD=${MYSQL_PASSWORD}
121+
command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
122+
```
123+
124+
### Tracker Configuration
125+
126+
```toml
127+
[core.database]
128+
driver = "mysql"
129+
path = "mysql://torrust:password@mysql:3306/torrust_tracker"
130+
```
131+
132+
### Environment Variables
133+
134+
```env
135+
TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__DRIVER=mysql
136+
TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__PATH=mysql://torrust:password@mysql:3306/torrust_tracker
137+
```
138+
139+
## Alternative Considered
140+
141+
### MariaDB 10.x
142+
143+
**Pros:**
144+
145+
- Generally faster than MySQL in some benchmarks
146+
- More storage engines and advanced features
147+
- Fully open-source governance model
148+
- Active development and regular releases
149+
150+
**Cons:**
151+
152+
- Not officially supported or tested by Torrust Tracker
153+
- Potential compatibility issues with MySQL-specific driver code
154+
- Less documentation and community support for tracker use cases
155+
- Risk of subtle differences causing issues in production
156+
- May require additional validation and testing
157+
158+
**Conclusion:** While MariaDB offers technical advantages, the benefits don't outweigh
159+
the risks and compatibility concerns for this specific use case.
160+
161+
## References
162+
163+
- [Torrust Tracker Documentation](https://docs.rs/torrust-tracker/)
164+
- [Torrust Tracker Database Configuration](https://docs.rs/torrust-tracker-configuration/latest/torrust_tracker_configuration/v2_0_0/database/struct.Database.html)
165+
- [Torrust Tracker MySQL Driver Implementation](https://github.com/torrust/torrust-tracker/blob/main/packages/tracker-core/src/databases/driver/mysql.rs)
166+
- [Torrust Tracker Docker Compose Example](https://github.com/torrust/torrust-tracker/blob/develop/docs/containers.md)
167+
- [Issue #12: Use MySQL instead of SQLite by default](../issues/12-use-mysql-instead-of-sqlite-by-default.md)
168+
169+
## Revision History
170+
171+
- **2025-07-08**: Initial decision document created
172+
- **Decision maker**: Development team
173+
- **Reviewed by**: N/A (initial implementation)

‎docs/issues/12-use-mysql-instead-of-sqlite-by-default.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,10 @@ This document outlines the detailed implementation plan for migrating from SQLit
66
as the default database for the Torrust Tracker Demo deployment.
77

88
**Parent Issue**: Phase 1: Database Migration to MySQL
9-
**Migration Plan Reference**: [docs/plans/hetzner-migration-plan.md](../plans/hetzner-migration-plan.md)
9+
**Migration Plan Reference**:
10+
[docs/plans/hetzner-migration-plan.md](../plans/hetzner-migration-plan.md)
11+
**Database Choice Decision**:
12+
[ADR-003: Use MySQL Over MariaDB](../adr/003-use-mysql-over-mariadb.md)
1013

1114
## 📋 Implementation Steps
1215

0 commit comments

Comments
 (0)