garsync 0.2.3__tar.gz → 0.3.1__tar.gz

{garsync-0.2.3 → garsync-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: garsync
-Version: 0.2.3
+Version: 0.3.1
 Summary: 
 License-File: LICENSE
 Author: Manu
@@ -11,13 +11,15 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3.15
-Requires-Dist: fastapi (>=0.141.1,<1.0.0)
-Requires-Dist: garminconnect (>=0.3.16,<0.4.0)
+Requires-Dist: alembic (>=1.20.0,<2.0.0)
+Requires-Dist: fastapi (>=0.142.2,<1.0.0)
+Requires-Dist: garminconnect (>=0.3.17,<0.4.0)
 Requires-Dist: pydantic (>=2.13.5,<3.0.0)
 Requires-Dist: rich (>=15.0.0,<16.0.0)
+Requires-Dist: sqlalchemy (>=2.1.1,<3.0.0)
 Requires-Dist: tenacity (>=9.1.4,<10.0.0)
 Requires-Dist: typer (>=0.27.2,<0.28.0)
-Requires-Dist: uvicorn[standard] (>=0.53.0,<1.0.0)
+Requires-Dist: uvicorn[standard] (>=0.54.0,<1.0.0)
 Description-Content-Type: text/markdown
 
 # GarSync
@@ -60,9 +62,12 @@ make setup
 ```
 
 ### 3. Configure Secrets
-Edit your Garmin credentials using SOPS:
+Edit your Garmin credentials using SOPS. The file is encrypted to garsync's dedicated age identity
+(see [`docs/runbooks/onboard-new-machine.md`](docs/runbooks/onboard-new-machine.md)), and sops must
+be told the format, because it cannot infer it from `.enc`:
 ```bash
-sops secrets.env.enc
+SOPS_AGE_KEY_FILE=~/.config/age/garsync.txt \
+  sops --input-type dotenv --output-type dotenv secrets.env.enc
 ```
 
 ### 4. Sync & Launch

{garsync-0.2.3 → garsync-0.3.1}/README.md

@@ -38,9 +38,12 @@ make setup
 ```
 
 ### 3. Configure Secrets
-Edit your Garmin credentials using SOPS:
+Edit your Garmin credentials using SOPS. The file is encrypted to garsync's dedicated age identity
+(see [`docs/runbooks/onboard-new-machine.md`](docs/runbooks/onboard-new-machine.md)), and sops must
+be told the format, because it cannot infer it from `.enc`:
 ```bash
-sops secrets.env.enc
+SOPS_AGE_KEY_FILE=~/.config/age/garsync.txt \
+  sops --input-type dotenv --output-type dotenv secrets.env.enc
 ```
 
 ### 4. Sync & Launch

{garsync-0.2.3 → garsync-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "garsync"
-version = "0.2.3"
+version = "0.3.1"
 description = ""
 authors = [
     {name = "Manu",email = "mlorentedev@gmail.com"}
@@ -8,13 +8,15 @@ authors = [
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
-    "garminconnect (>=0.3.16,<0.4.0)",
+    "garminconnect (>=0.3.17,<0.4.0)",
     "pydantic (>=2.13.5,<3.0.0)",
     "tenacity (>=9.1.4,<10.0.0)",
     "typer (>=0.27.2,<0.28.0)",
     "rich (>=15.0.0,<16.0.0)",
-    "fastapi (>=0.141.1,<1.0.0)",
-    "uvicorn[standard] (>=0.53.0,<1.0.0)",
+    "fastapi (>=0.142.2,<1.0.0)",
+    "uvicorn[standard] (>=0.54.0,<1.0.0)",
+    "alembic (>=1.20.0,<2.0.0)",
+    "sqlalchemy (>=2.1.1,<3.0.0)",
 ]
 
 
@@ -33,8 +35,8 @@ dev = [
     "pytest (>=9.1.1,<10.0.0)",
     "pytest-cov (>=7.1.0,<8.0.0)",
     "mypy (>=2.3.1,<3.0.0)",
-    "ruff (>=0.16.8,<0.17.0)",
-    "pytest-mock (>=3.15.1,<4.0.0)",
+    "ruff (>=0.16.9,<0.17.0)",
+    "pytest-mock (>=3.16.0,<4.0.0)",
     "httpx (>=0.28.1,<1.0.0)"
 ]
 

{garsync-0.2.3 → garsync-0.3.1}/src/garsync/__init__.py

@@ -1,3 +1,3 @@
 """Garmin Sync Microservice"""
 
-__version__ = "0.2.3"
+__version__ = "0.3.1"

{garsync-0.2.3 → garsync-0.3.1}/src/garsync/api/deps.py

@@ -7,8 +7,8 @@ from fastapi import Request
 from garsync.db.repository import (
     ActivityRepository,
     BiometricsRepository,
+    IngestRunRepository,
     SleepRepository,
-    SyncLogRepository,
 )
 
 
@@ -33,6 +33,6 @@ def get_sleep_repo(request: Request) -> SleepRepository:
     return SleepRepository(get_db(request))
 
 
-def get_sync_log_repo(request: Request) -> SyncLogRepository:
-    """Factory for SyncLogRepository."""
-    return SyncLogRepository(get_db(request))
+def get_ingest_run_repo(request: Request) -> IngestRunRepository:
+    """Factory for IngestRunRepository."""
+    return IngestRunRepository(get_db(request))

{garsync-0.2.3 → garsync-0.3.1}/src/garsync/api/main.py

@@ -23,8 +23,7 @@ from garsync.api.auth import (
     verify_session_token,
 )
 from garsync.api.routes import activities, biometrics, sleep, stats, sync
-from garsync.db.connection import get_connection
-from garsync.db.schema import init_db
+from garsync.db.schema import open_database
 
 logger = logging.getLogger("garsync.auth")
 
@@ -38,8 +37,9 @@ MAX_LOGIN_BODY_BYTES = 4096
 async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
     """Manage database connection lifecycle."""
     db_path = os.environ.get("GARSYNC_DB_PATH", "data/garsync.db")
-    conn = get_connection(db_path)
-    init_db(conn)
+    # Snapshot-then-migrate: the file is the only copy of this history, and this is the function that
+    # knows a migration is about to rewrite it.
+    conn = open_database(db_path)
     app.state.db = conn
     yield
     conn.close()

{garsync-0.2.3 → garsync-0.3.1}/src/garsync/api/routes/sync.py

@@ -5,15 +5,15 @@ from fastapi import APIRouter, Depends
 from garsync.api.deps import (
     get_activity_repo,
     get_biometrics_repo,
+    get_ingest_run_repo,
     get_sleep_repo,
-    get_sync_log_repo,
 )
 from garsync.api.schemas import SyncStatus
 from garsync.db.repository import (
     ActivityRepository,
     BiometricsRepository,
+    IngestRunRepository,
     SleepRepository,
-    SyncLogRepository,
 )
 
 router = APIRouter(prefix="/api", tags=["sync"])
@@ -24,15 +24,15 @@ def sync_status(
     activity_repo: ActivityRepository = Depends(get_activity_repo),
     biometrics_repo: BiometricsRepository = Depends(get_biometrics_repo),
     sleep_repo: SleepRepository = Depends(get_sleep_repo),
-    sync_log_repo: SyncLogRepository = Depends(get_sync_log_repo),
+    ingest_run_repo: IngestRunRepository = Depends(get_ingest_run_repo),
 ) -> SyncStatus:
     """Get current sync status and record counts."""
-    latest = sync_log_repo.get_latest()
+    latest = ingest_run_repo.get_latest()
     return SyncStatus(
         last_sync_time=latest["created_at"] if latest else None,
         last_sync_status=latest["status"] if latest else None,
         total_activities=activity_repo.count(),
         total_biometrics=biometrics_repo.count(),
         total_sleep=sleep_repo.count(),
-        total_sync_logs=sync_log_repo.count(),
+        total_sync_logs=ingest_run_repo.count(),
     )

{garsync-0.2.3 → garsync-0.3.1}/src/garsync/cli.py

@@ -9,8 +9,7 @@ import typer
 from rich.console import Console
 
 from garsync.client import GarminClient
-from garsync.db.connection import get_connection
-from garsync.db.schema import init_db
+from garsync.db.schema import open_database
 from garsync.pipeline import SyncService
 
 app = typer.Typer(help="GarSync: Garmin Connect data extraction pipeline")
@@ -61,8 +60,9 @@ def sync(
 
     conn = None
     if db:
-        conn = get_connection(db)
-        init_db(conn)
+        # `open_database` snapshots the file first when a migration is pending: this is the only
+        # place that knows it is a file rather than a fixture, which is what a backup needs.
+        conn = open_database(db)
         service = SyncService(client, conn)
 
         latest_date = service.get_latest_synced_date()

{garsync-0.2.3 → garsync-0.3.1}/src/garsync/db/__init__.py

@@ -4,17 +4,18 @@ from garsync.db.connection import get_connection
 from garsync.db.repository import (
     ActivityRepository,
     BiometricsRepository,
+    IngestRunRepository,
     SleepRepository,
-    SyncLogRepository,
 )
-from garsync.db.schema import CURRENT_VERSION, init_db
+from garsync.db.schema import init_db, migrate, open_database
 
 __all__ = [
-    "CURRENT_VERSION",
     "ActivityRepository",
     "BiometricsRepository",
+    "IngestRunRepository",
     "SleepRepository",
-    "SyncLogRepository",
     "get_connection",
     "init_db",
+    "migrate",
+    "open_database",
 ]

garsync-0.3.1/src/garsync/db/backup.py

@@ -0,0 +1,65 @@
+"""Pre-migration snapshots of the database file.
+
+ADR-009 §4.1 requires a backup before the migration runs. Written as an instruction, that is a rule
+nobody executes at the moment it matters — so it is a function the upgrade path calls, and a target
+an operator can run by hand (`make db-backup`).
+
+`VACUUM INTO` rather than a file copy: it writes a consistent snapshot of a live database, including
+anything still in the write-ahead log, and it cannot produce the torn file that `cp` produces when a
+writer is mid-commit. A checkpoint is deliberately *not* issued first — `VACUUM INTO` already reads
+through the connection, so a checkpoint would only add a write to a database this code is otherwise
+only reading.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+#: Snapshots live beside the database, inside the directory that is already gitignored.
+BACKUP_DIRNAME = "backups"
+
+
+def snapshot_path(db_path: Path, taken_at: datetime | None = None) -> Path:
+    """Where a snapshot taken now would go. UTC, so the names sort as they were written."""
+    stamp = (taken_at or datetime.now(UTC)).strftime("%Y%m%dT%H%M%SZ")
+    return db_path.parent / BACKUP_DIRNAME / f"{db_path.stem}-{stamp}.db"
+
+
+def snapshot(conn: sqlite3.Connection, db_path: Path, taken_at: datetime | None = None) -> Path:
+    """Write a snapshot of `conn`'s database next to `db_path` and return where it landed.
+
+    Refuses to overwrite: a second snapshot in the same second is a name collision, and silently
+    replacing the earlier one is exactly the outcome a backup exists to prevent.
+    """
+    target = snapshot_path(db_path, taken_at)
+    if target.exists():
+        raise FileExistsError(f"refusing to overwrite an existing snapshot: {target}")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    conn.commit()  # `VACUUM INTO` cannot run inside a transaction
+    conn.execute("VACUUM INTO ?", (str(target),))
+    return target
+
+
+def main(argv: list[str] | None = None) -> int:
+    """`python -m garsync.db.backup [db_path]` — the same snapshot, on demand."""
+    from garsync.db.connection import get_connection
+
+    args = sys.argv[1:] if argv is None else argv
+    db_path = Path(args[0] if args else "data/garsync.db")
+    if not db_path.exists():
+        print(f"db-backup: no database at {db_path}", file=sys.stderr)
+        return 1
+    conn = get_connection(str(db_path))
+    try:
+        written = snapshot(conn, db_path)
+    finally:
+        conn.close()
+    print(written)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

garsync-0.3.1/src/garsync/db/migrations/env.py

@@ -0,0 +1,44 @@
+"""Alembic environment — driven by the caller's connection, never by a URL.
+
+The connection is required. Alembic opening one from a URL would be a *second* connection, and for
+SQLite `:memory:` a second connection is a second, empty database: the fixtures in this suite would
+then assert against nothing while the whole suite stayed green. A run with no connection is a
+configuration error and says so.
+"""
+
+from __future__ import annotations
+
+from alembic import context
+
+
+def run_migrations_offline() -> None:
+    """Offline mode is not supported, and refusing is the point.
+
+    `--sql` output cannot be reviewed the way this chain is reviewed: it issues its own SQL and is
+    only ever run against a database somebody has already backed up (see `make db-backup`).
+    """
+    raise RuntimeError(
+        "Offline mode is not supported. The garsync chain is run by "
+        "`garsync.db.schema.init_db` on a live connection, so that the schema lands on the same "
+        "database the application is about to use."
+    )
+
+
+def run_migrations_online() -> None:
+    connection = context.config.attributes.get("connection")
+    if connection is None:
+        raise RuntimeError(
+            "No connection was supplied to the migration chain. Pass the connection the "
+            "application already holds via `config.attributes['connection']` — that is what "
+            "`garsync.db.schema.init_db` does. Alembic is deliberately not given a URL here: a "
+            "connection it opened itself would be a different database from the caller's."
+        )
+    context.configure(connection=connection, target_metadata=None)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

garsync-0.3.1/src/garsync/db/migrations/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+Migrations in this project do not import application code: a revision has to keep working after the
+module it would import has changed shape, so anything it needs is written out here.
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+${imports if imports else ""}
+
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

garsync-0.3.1/src/garsync/db/migrations/versions/0001_v1_baseline.py

@@ -0,0 +1,105 @@
+"""v1 baseline — the schema exactly as it existed before Alembic.
+
+This revision is not a migration; it is the *starting point*, and it exists so that an existing v1
+database can be stamped rather than recreated. Everything depends on it being faithful: if it
+disagrees with what is on disk, `alembic stamp 0001_v1` records a lie and the next revision
+transforms a schema nobody has. `TestAlembicSeam::test_the_baseline_reproduces_the_v1_schema` holds
+it against the frozen DDL in `tests/fixtures/schema_v1.sql`.
+
+Two details are load-bearing and easy to get wrong:
+
+* `activity_id`/`date`/`id` are primary keys with ``nullable=True``. SQLAlchemy otherwise renders
+  ``INTEGER NOT NULL`` where v1 wrote ``INTEGER PRIMARY KEY`` — a different table, since a rowid
+  alias accepts an omitted value and a NOT NULL column does not.
+* ``server_default=sa.text(...)`` is the expression form. Passed as a plain string it is quoted and
+  becomes a *literal*, so `created_at` would default to the text of a function call.
+
+Revision ID: 0001_v1
+Revises:
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0001_v1"
+down_revision: str | None = None
+branch_labels: Sequence[str] | None = None
+depends_on: Sequence[str] | None = None
+
+_TIMESTAMP = sa.text("(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))")
+
+
+def _timestamps() -> list[sa.Column[Any]]:
+    return [
+        sa.Column("created_at", sa.Text(), nullable=False, server_default=_TIMESTAMP),
+        sa.Column("updated_at", sa.Text(), nullable=False, server_default=_TIMESTAMP),
+    ]
+
+
+def upgrade() -> None:
+    op.create_table(
+        "activities",
+        sa.Column("activity_id", sa.Integer(), primary_key=True, nullable=True),
+        sa.Column("activity_name", sa.Text(), nullable=True),
+        sa.Column("activity_type", sa.Text(), nullable=True),
+        sa.Column("start_time", sa.Text(), nullable=True),
+        sa.Column("duration_seconds", sa.REAL(), nullable=True),
+        sa.Column("distance_meters", sa.REAL(), nullable=True),
+        sa.Column("average_heart_rate", sa.Integer(), nullable=True),
+        sa.Column("max_heart_rate", sa.Integer(), nullable=True),
+        sa.Column("calories", sa.REAL(), nullable=True),
+        sa.Column("raw_data", sa.Text(), nullable=True),
+        *_timestamps(),
+    )
+    op.create_table(
+        "biometrics",
+        sa.Column("date", sa.Text(), primary_key=True, nullable=True),
+        sa.Column("resting_heart_rate", sa.Integer(), nullable=True),
+        sa.Column("hrv_balance", sa.Text(), nullable=True),
+        sa.Column("body_battery_highest", sa.Integer(), nullable=True),
+        sa.Column("body_battery_lowest", sa.Integer(), nullable=True),
+        sa.Column("stress_average", sa.Integer(), nullable=True),
+        sa.Column("raw_data", sa.Text(), nullable=True),
+        *_timestamps(),
+    )
+    op.create_table(
+        "sleep",
+        sa.Column("date", sa.Text(), primary_key=True, nullable=True),
+        sa.Column("sleep_start", sa.Text(), nullable=True),
+        sa.Column("sleep_end", sa.Text(), nullable=True),
+        sa.Column("total_sleep_seconds", sa.Integer(), nullable=True),
+        sa.Column("deep_sleep_seconds", sa.Integer(), nullable=True),
+        sa.Column("light_sleep_seconds", sa.Integer(), nullable=True),
+        sa.Column("rem_sleep_seconds", sa.Integer(), nullable=True),
+        sa.Column("awake_sleep_seconds", sa.Integer(), nullable=True),
+        sa.Column("sleep_score", sa.Integer(), nullable=True),
+        sa.Column("raw_data", sa.Text(), nullable=True),
+        *_timestamps(),
+    )
+    op.create_table(
+        "sync_log",
+        sa.Column("id", sa.Integer(), primary_key=True, nullable=True),
+        sa.Column("sync_type", sa.Text(), nullable=False),
+        sa.Column("records_synced", sa.Integer(), nullable=False, server_default=sa.text("0")),
+        sa.Column("status", sa.Text(), nullable=False, server_default="success"),
+        sa.Column("error_message", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.Text(), nullable=False, server_default=_TIMESTAMP),
+        sqlite_autoincrement=True,
+    )
+    op.create_table(
+        "schema_version",
+        sa.Column("version", sa.Integer(), primary_key=True, nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("schema_version")
+    op.drop_table("sync_log")
+    op.drop_table("sleep")
+    op.drop_table("biometrics")
+    op.drop_table("activities")