trainlog/docs/database.md

Desktop database

1. Status

TRAINLOG_DATABASE_SCHEMA_VERSION=5
DATABASE_SCHEMA_V5=PASS
TRAINLOG_FORMAT_V1=FROZEN

The desktop SQLite database is the canonical long-term Trainlog history.

Its schema evolves independently from all JSON exchange-format versions.

2. Versioning

Schema version uses:

PRAGMA user_version;

Current value:

5

Supported historical databases are migrated explicitly through the implemented migration chain. A database newer than the running binary understands is rejected.

A schema fixture must represent the real historical structure. Rewriting only user_version is not an acceptable migration test.

3. Connection invariants

Every connection enables:

PRAGMA foreign_keys = ON;

A bounded SQLite busy timeout is configured by the core.

4. Tables

exercises

Canonical desktop exercise catalog.

id
exercise_id          UNIQUE stable identity
name
normalized_name      UNIQUE normalized display form
tracking_mode        reps | duration
recording_mode       sets | continuous
data_fields          bounded bit mask

Rules include:

• continuous implies duration tracking;
• unknown supplemental field bits are rejected;
• normalized names remain unique.

sessions

id
session_id           UNIQUE stable identity
started_at
ended_at             nullable
session_type         training | max_test
notes                nullable

session_exercises

Ordered exercise occurrence inside one session.

session_row_id
exercise_row_id
recording_mode
data_fields
position
load_mode
rest_seconds
target_sets
target_reps
target_duration_seconds
target_weight_kg
notes

Current desktop history snapshots recording_mode and data_fields in the session row. tracking_mode remains associated with the referenced exercise catalog identity.

SETS rows support two target shapes in schema v5:

explicit planned target
    target_sets + exactly one target metric

actual-only mobile observation
    target_sets = NULL
    target_reps = NULL
    target_duration_seconds = NULL

This v5 rule is what permits heterogeneous mobile performed sets without inventing a fake uniform target.

CONTINUOUS rows are targetless and require:

load_mode = none
rest_seconds = 0
target_weight_kg = NULL

performed_sets

Ordered actual set records.

session_exercise_row_id
position
reps                 nullable
duration_seconds     nullable
weight_kg            nullable

Exactly one primary actual metric is present:

reps
or
duration_seconds

Actual repetitions may be zero.

Each row is independent; heterogeneous repetition sequences are first-class data.

continuous_activity

One-to-one actual record for a continuous session exercise.

session_exercise_row_id  UNIQUE
duration_seconds
speed_kmh                nullable
distance_km              nullable

Continuous activity never creates a fake performed set.

body_observations

observation_id       UNIQUE
observed_at
session_row_id       optional UNIQUE link
body_weight_kg
neck_cm
shoulders_cm
chest_cm
waist_cm
hips_cm
left_arm_cm
right_arm_cm
left_forearm_cm
right_forearm_cm
left_thigh_cm
right_thigh_cm
left_calf_cm
right_calf_cm
notes

At least one body metric must be present.

5. Identifier generation

Official desktop creator prefixes:

ex_   exercise
se_   session
bo_   body observation
sy_   synchronization run

All use random UUIDv4 values.

Exchange parsers may accept other schema-valid opaque identities where their contract explicitly permits it.

6. Transactions

Multi-row user operations are atomic.

Persisted session correction replaces session child rows transactionally while preserving the parent:

session_id
started_at
ended_at
session_type
session notes
linked body observation

Removing an exercise from a persisted session is therefore a transactional replacement of the remaining child set.

A failed replacement rolls back to the previously persisted session.

Body-observation editing preserves its stable identity, timestamp, and optional session link.

7. Mobile import semantics

tools/import_mobile_export.py validates the complete mobile snapshot before committing database changes.

Properties:

schema-v5 aware
transactional
idempotent by stable IDs
profile-aware catalog reconciliation
heterogeneous performed sets preserved
no fake target generated
continuous activity kept separate

8. Units

Canonical desktop persistence:

weight/load          kg
body circumference   cm
duration/rest         seconds
speed                 km/h
distance              km

9. Android database

The Android SQLite database is independent.

Current Android-local version: 4. The explicit v3 -> v4 migration only adds structured draft tables; it does not rebuild or delete existing domain tables.

Table	Ownership
active_session_draft	Single id = 1 row, session type, selected catalog row, raw form text, update time
draft_session_exercises	Ordered draft exercises and profile snapshots
draft_performed_sets	Ordered heterogeneous repetition or duration actuals
draft_continuous_activity	Duration and configured speed/distance without synthetic sets

Foreign keys remain enabled. Draft deletion cascades only through draft child tables; it cannot delete catalog entries or completed history. The repository commits completed-session insertion and draft removal together, rolling back both on failure. Repeating finalization after success cannot create another completed session. Completed started_at semantics are unchanged by this repair.

Migration tests use a real v3-shaped fixture. The physical Samsung upgrade also preserved every existing domain row, with successful integrity and foreign-key checks. Device backup files are outside the repository; no SQLite files are used as synchronization artifacts.

Desktop and Android schema versions are not required to match.

Do not synchronize SQLite database files.

10. Validation

meson compile -C build
meson test -C build --print-errorlogs

Migration-specific regression coverage includes:

schema_v5_migration

The current normal desktop suite contains 22 tests.

11. Measured-max derivation

Measured maxima require no desktop schema v6.

The existing sessions.session_type = max_test classification plus actual performed_sets are sufficient.

Exercise performance points carry the originating session type so the measured-max layer can distinguish explicit tests from ordinary training.

Rules:

training session
    never becomes measured max implicitly

max_test + external
    greatest successful actual load
    tie -> greatest reps/duration

max_test + assistance
    lowest successful assistance
    tie -> greatest reps/duration

max_test + no load
    greatest successful reps/duration

A zero-repetition failed attempt is not a successful measurement.

The current measured result is the newest successful max-test point. The record is the best max-test point using the same load mode.

No extra maximum row is persisted; results are derived from canonical history.

12. Body analytics persistence rule

Body analytics require no schema v6.

Canonical persistence continues to contain only measurements actually entered by the user.

These values remain derived at display time and are not persisted:

body-fat estimate
estimated fat mass
estimated lean mass
waist/hip ratio
shoulder/waist ratio
chest/waist ratio
left/right asymmetry percentages

The optional estimation profile is desktop configuration, not database history.