feat: enforce non-zero completed count in torrents table

Add CHECK constraint to ensure the `completed` column in the `torrents`
table is always >= 1, preventing invalid zero values. This change
reflects the semantic meaning that a torrent entry should only exist
once it has been completed at least once.

Changes:
- Add migration scripts for both SQLite and MySQL to:
  - Delete any existing rows with completed = 0
  - Add CHECK constraint (completed >= 1)
  - Change default value from 0 to 1
- Update hardcoded table creation SQL in database drivers to include
  the new constraint and default value
- Document the new constraint in migrations README with complete
  table schema reference for all 4 tracker tables
- Update module documentation to clarify permanent keys support

The migration handles SQLite's limitation by recreating the table,
while MySQL can add the constraint directly (requires MySQL 8.0.16+).

Author: da2ce7

packages/tracker-core/migrations/README.md

@@ -3,3 +3,66 @@
 We don't support automatic migrations yet. The tracker creates all the needed tables when it starts. The SQL sentences are hardcoded in each database driver.
 
 The migrations in this folder were introduced to add some new changes (permanent keys) and to allow users to migrate to the new version. In the future, we will remove the hardcoded SQL and start using a Rust crate for database migrations. For the time being, if you are using the initial schema described in the migration `20240730183000_torrust_tracker_create_all_tables.sql` you will need to run all the subsequent migrations manually.
+
+## Database Tables
+
+The tracker uses 4 tables:
+
+### 1. `whitelist`
+
+Stores whitelisted torrent infohashes for private/whitelisted mode.
+
+| Column | SQLite Type | MySQL Type | Description |
+|--------|-------------|------------|-------------|
+| `id` | INTEGER PRIMARY KEY AUTOINCREMENT | integer PRIMARY KEY AUTO_INCREMENT | Auto-increment ID |
+| `info_hash` | TEXT NOT NULL UNIQUE | VARCHAR(40) NOT NULL UNIQUE | BitTorrent V1 infohash (40-char hex string) |
+
+### 2. `torrents`
+
+Stores per-torrent metrics (completed download count).
+
+| Column | SQLite Type | MySQL Type | Description |
+|--------|-------------|------------|-------------|
+| `id` | INTEGER PRIMARY KEY AUTOINCREMENT | integer PRIMARY KEY AUTO_INCREMENT | Auto-increment ID |
+| `info_hash` | TEXT NOT NULL UNIQUE | VARCHAR(40) NOT NULL UNIQUE | BitTorrent V1 infohash (40-char hex string) |
+| `completed` | INTEGER DEFAULT 1 NOT NULL CHECK (completed >= 1) | INTEGER DEFAULT 1 NOT NULL CHECK (completed >= 1) | Number of times the torrent has been fully downloaded (minimum 1) |
+
+### 3. `keys`
+
+Stores authentication keys for private trackers.
+
+| Column | SQLite Type | MySQL Type | Description |
+|--------|-------------|------------|-------------|
+| `id` | INTEGER PRIMARY KEY AUTOINCREMENT | INT NOT NULL AUTO_INCREMENT | Auto-increment ID |
+| `key` | TEXT NOT NULL UNIQUE | VARCHAR(32) NOT NULL UNIQUE | Authentication token (32-char alphanumeric string) |
+| `valid_until` | INTEGER (nullable) | INT(10) (nullable) | Unix timestamp for key expiration; NULL means permanent key |
+
+### 4. `torrent_aggregate_metrics`
+
+Stores global/aggregate metrics not tied to specific torrents (e.g., total downloads across all torrents).
+
+| Column | SQLite Type | MySQL Type | Description |
+|--------|-------------|------------|-------------|
+| `id` | INTEGER PRIMARY KEY AUTOINCREMENT | integer PRIMARY KEY AUTO_INCREMENT | Auto-increment ID |
+| `metric_name` | TEXT NOT NULL UNIQUE | VARCHAR(50) NOT NULL UNIQUE | Unique metric identifier (e.g., `torrents_downloads_total`) |
+| `value` | INTEGER DEFAULT 0 NOT NULL | INTEGER DEFAULT 0 NOT NULL | The metric value |
+
+## Migration Files
+
+### SQLite
+
+| Migration | Description |
+|-----------|-------------|
+| `20240730183000_torrust_tracker_create_all_tables.sql` | Creates initial tables: `whitelist`, `torrents`, `keys` |
+| `20240730183500_torrust_tracker_keys_valid_until_nullable.sql` | Makes `valid_until` column nullable in `keys` table (for permanent keys) |
+| `20250527093000_torrust_tracker_new_torrent_aggregate_metrics_table.sql` | Creates `torrent_aggregate_metrics` table for global metrics |
+| `20260206120000_torrust_tracker_torrents_completed_non_zero.sql` | Removes rows with completed=0 and adds CHECK constraint (completed >= 1) |
+
+### MySQL
+
+| Migration | Description |
+|-----------|-------------|
+| `20240730183000_torrust_tracker_create_all_tables.sql` | Creates initial tables: `whitelist`, `torrents`, `keys` |
+| `20240730183500_torrust_tracker_keys_valid_until_nullable.sql` | Makes `valid_until` column nullable in `keys` table (for permanent keys) |
+| `20250527093000_torrust_tracker_new_torrent_aggregate_metrics_table.sql` | Creates `torrent_aggregate_metrics` table for global metrics |
+| `20260206120000_torrust_tracker_torrents_completed_non_zero.sql` | Removes rows with completed=0 and adds CHECK constraint (completed >= 1) |

packages/tracker-core/migrations/mysql/20260206120000_torrust_tracker_torrents_completed_non_zero.sql

@@ -0,0 +1,9 @@
+-- Remove any rows with completed = 0 (should not exist in normal operation)
+DELETE FROM torrents WHERE completed = 0;
+
+-- Add CHECK constraint to enforce completed >= 1
+-- Note: MySQL 8.0.16+ enforces CHECK constraints
+ALTER TABLE torrents ADD CONSTRAINT chk_completed_non_zero CHECK (completed >= 1);
+
+-- Change the default value from 0 to 1
+ALTER TABLE torrents ALTER completed SET DEFAULT 1;

packages/tracker-core/migrations/sqlite/20260206120000_torrust_tracker_torrents_completed_non_zero.sql

@@ -0,0 +1,16 @@
+-- Remove any rows with completed = 0 (should not exist in normal operation)
+DELETE FROM torrents WHERE completed = 0;
+
+-- SQLite doesn't support adding CHECK constraints to existing tables directly.
+-- We need to recreate the table with the new constraint.
+CREATE TABLE IF NOT EXISTS torrents_new (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    info_hash TEXT NOT NULL UNIQUE,
+    completed INTEGER DEFAULT 1 NOT NULL CHECK (completed >= 1)
+);
+
+INSERT INTO torrents_new (id, info_hash, completed) SELECT id, info_hash, completed FROM torrents;
+
+DROP TABLE torrents;
+
+ALTER TABLE torrents_new RENAME TO torrents;

packages/tracker-core/src/databases/driver/mysql.rs

@@ -83,7 +83,7 @@ impl Database for Mysql {
         CREATE TABLE IF NOT EXISTS torrents (
             id integer PRIMARY KEY AUTO_INCREMENT,
             info_hash VARCHAR(40) NOT NULL UNIQUE,
-            completed INTEGER DEFAULT 0 NOT NULL
+            completed INTEGER DEFAULT 1 NOT NULL CHECK (completed >= 1)
         );"
         .to_string();
 

packages/tracker-core/src/databases/driver/sqlite.rs

@@ -98,7 +98,7 @@ impl Database for Sqlite {
         CREATE TABLE IF NOT EXISTS torrents (
             id INTEGER PRIMARY KEY AUTOINCREMENT,
             info_hash TEXT NOT NULL UNIQUE,
-            completed INTEGER DEFAULT 0 NOT NULL
+            completed INTEGER DEFAULT 1 NOT NULL CHECK (completed >= 1)
         );"
         .to_string();
 

packages/tracker-core/src/databases/mod.rs

@@ -43,9 +43,22 @@
 //! |---------------|------------------------------------|--------------------------------------|
 //! | `id`          | 1                                  | Auto-increment id                    |
 //! | `key`         | `IrweYtVuQPGbG9Jzx1DihcPmJGGpVy82` | Authentication token (32 chars)      |
-//! | `valid_until` | 1672419840                         | Timestamp indicating expiration time |
+//! | `valid_until` | 1672419840                         | Unix timestamp for expiration; NULL for permanent keys |
 //!
-//! > **NOTICE**: All authentication keys must have an expiration date.
+//! > **NOTICE**: Authentication keys can be permanent (no expiration) by setting
+//! > `valid_until` to NULL.
+//!
+//! # Torrent Aggregate Metrics
+//!
+//! A table for storing global/aggregate metrics that are not tied to a specific
+//! torrent. Currently used for tracking the total number of downloads across
+//! all torrents.
+//!
+//! | Field         | Sample data                              | Description                              |
+//! |---------------|------------------------------------------|------------------------------------------|
+//! | `id`          | 1                                        | Auto-increment id                        |
+//! | `metric_name` | `torrents_downloads_total`               | Unique identifier for the metric         |
+//! | `value`       | 12345                                    | The metric value (integer)               |
 pub mod driver;
 pub mod error;
 pub mod setup;