docs(issues): add implementation specs for EPIC #1525 overhaul persistence#1702
Merged
josecelano merged 3 commits intotorrust:developfrom Apr 22, 2026
Merged
Conversation
… persistence Add the EPIC planning doc and eight sub-issue specs covering the full persistence overhaul: - torrust#1525: EPIC – Overhaul Persistence (delivery strategy + ordering) - torrust#1525-01: Persistence test coverage (DB compatibility matrix) - torrust#1525-02: qBittorrent E2E test runner - torrust#1525-03: Persistence benchmarking framework - torrust#1525-04: Split persistence traits (narrow interfaces) - torrust#1525-05: Migrate SQLite and MySQL drivers to sqlx - torrust#1525-07: Align Rust and DB types (u32→u64, INTEGER→BIGINT) - torrust#1525-08: Add PostgreSQL driver Also adds new technical terms to project-words.txt (dbname, isready, VARCHAR) required for the cspell spell-checker to pass.
There was a problem hiding this comment.
Pull request overview
Adds a set of planning/specification documents for EPIC #1525 (“Overhaul Persistence”) so follow-up implementation PRs can be reviewed against a stable, agreed design.
Changes:
- Adds the EPIC plan plus sub-issue implementation specs (#1525-01 through #1525-08) under
docs/issues/. - Updates
project-words.txtwith new technical terms used in the specs.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| project-words.txt | Adds cspell allowlist entries for new persistence/migration terminology. |
| docs/issues/1525-overhaul-persistence.md | EPIC-level delivery strategy, ordering, and acceptance criteria for the persistence overhaul. |
| docs/issues/1525-01-persistence-test-coverage.md | Spec for a DB compatibility matrix runner to baseline persistence behavior across DB versions. |
| docs/issues/1525-02-qbittorrent-e2e.md | Spec for a qBittorrent-based end-to-end test harness (Docker Compose driven). |
| docs/issues/1525-03-persistence-benchmarking.md | Spec for a before/after persistence benchmark runner and baseline artifacts. |
| docs/issues/1525-04-split-persistence-traits.md | Spec for splitting the monolithic persistence trait into narrower context traits + aggregate supertrait. |
| docs/issues/1525-05-migrate-sqlite-and-mysql-to-sqlx.md | Spec for migrating SQLite/MySQL to async sqlx using a “green parallel” approach. |
| docs/issues/1525-06-introduce-schema-migrations.md | Spec for adopting sqlx::migrate!() and a legacy bootstrap path for pre-v4 DBs. |
| docs/issues/1525-07-align-rust-and-db-types.md | Spec for widening download counters (u32→u64, INTEGER→BIGINT) via migrations and explicit encode/decode helpers. |
| docs/issues/1525-08-add-postgresql-driver.md | Spec for adding PostgreSQL driver support, migrations, tests, and QA harness extensions. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- project-words.txt: sort newly-appended words alphabetically - 1525-06: fix double semicolon typo in MIGRATOR.run() snippet - 1525-07: replace "reversible" with "tracked as a forward schema change" — sqlx has no down/rollback migrations - 1525-08: fix migration-1 valid_until type (BIGINT → INTEGER to align with other backends; migration-4 widens to BIGINT) - 1525-08: fix Error::migration_error argument order (e, DRIVER) → (DRIVER, e) to match the signature used throughout 1525-06
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #1702 +/- ##
========================================
Coverage 86.42% 86.43%
========================================
Files 288 288
Lines 22672 22672
Branches 22672 22672
========================================
+ Hits 19594 19596 +2
+ Misses 2843 2838 -5
- Partials 235 238 +3 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Task 9 was missing two required steps: 1. share/container/entry_script_sh — the container bootstrap script hard-codes only sqlite3 and mysql; without a postgresql elif branch the container exits 1 when that driver is selected. Spec now includes the exact elif block and the updated error message. 2. compose.yaml — the demo compose file only had a mysql service; spec now adds a postgres service (postgres:16, with healthcheck, POSTGRES_DB env var, and a named volume) and updates the tracker's depends_on to include both mysql and postgres. Also extends the overall Acceptance Criteria section with checkboxes for entry_script_sh and compose.yaml.
Member
Author
|
ACK 0cc8528 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds the planning documentation for EPIC #1525 — Overhaul Persistence: an EPIC-level spec and eight sub-issue implementation specs that together define how the persistence layer will be completely overhauled.
The specs have been written, cross-reviewed for consistency, and linter-clean (
linter allexits 0). They are intended to be merged first so that the implementation sub-issues can be worked on and reviewed against a stable spec document.Specs included
docs/issues/1525-overhaul-persistence.mddocs/issues/1525-01-persistence-test-coverage.mddocs/issues/1525-02-qbittorrent-e2e.mdDockerComposewrapperdocs/issues/1525-03-persistence-benchmarking.md--before-image/--after-imageCLI)docs/issues/1525-04-split-persistence-traits.mdDatabaseinto 4 narrow traits + aggregate supertraitdocs/issues/1525-05-migrate-sqlite-and-mysql-to-sqlx.mdsqlxdocs/issues/1525-06-introduce-schema-migrations.mdsqlx::migrate!(), legacy bootstrap for pre-existing DBsdocs/issues/1525-07-align-rust-and-db-types.mdNumberOfDownloadsu32→u64,INTEGER→BIGINTmigrationsdocs/issues/1525-08-add-postgresql-driver.mdKey design decisions documented
sqlxhistory tracking.INSERT INTO _sqlx_migrationswith precondition guards — not a publicapply_fake()API.DROP TABLE IF EXISTS: chosen consistently for all five table drops across all backends.std::thread::spawn+ blockingreqwest(notrayon, which is wrong for I/O-bound work).DockerComposewrapper: shared atsrc/console/ci/compose.rs, reused by both the qBittorrent runner and the benchmark runner.CREATE DATABASE torrust_trackermust exist before connection.Checklist
linter allexits 0cargo machete— no unused dependenciesproject-words.txtupdated with new technical terms (dbname,isready,VARCHAR)