trainlog/docs/database.md

Database

1. Purpose

SQLite is the canonical long-term data store used by the TUI.

The database is not the Android exchange format.

2. Initial entities

The initial data model is expected to contain:

• schema metadata;
• exercises;
• sessions;
• session exercises;
• performed sets;
• body measurements;
• optional maximum-performance records.

The exact SQL schema will be frozen before implementation.

3. Exercise identity

The database must preserve a stable external exercise identifier.

Conceptually:

exercises
  id              internal SQLite primary key
  exercise_id     stable Trainlog identifier
  name            mutable display name

exercise_id must be unique.

4. Session identity

session_id must be unique.

This is the primary anti-duplication barrier for imported sessions.

5. Foreign keys

SQLite foreign-key enforcement must be enabled explicitly for every connection:

PRAGMA foreign_keys = ON;

Tests must verify that the expected constraints are actually active.

6. Schema versioning

The database must store an explicit schema version.

Schema changes must be classified as:

• additive and compatible;
• migration required;
• destructive and therefore forbidden without explicit migration logic.

7. Transactions

Multi-table imports must use transactions.

A failed import must not leave a partially inserted session.

Expected behavior:

BEGIN
  validate
  insert missing exercises
  insert session
  insert workout rows
  insert performed sets
COMMIT

On failure:

ROLLBACK

8. Units

Canonical storage units:

• body weight: kilograms;
• load: kilograms;
• body measurements: centimeters;
• duration: seconds.

The UI may format values differently later, but persistent units remain explicit and stable.

9. Migration policy

A schema migration must:

• be deterministic;
• preserve user data;
• be testable from the previous supported version;
• update the stored schema version only after success.