Add Alembic for database migrations and update dependencies

Author: clstaudt

pyproject.toml

@@ -41,6 +41,7 @@ dependencies = [
     "flet>=0.81.0,<0.82.0",
     "pycountry",
     "icloudpy",
+    "alembic>=1.18.4",
 ]
 
 [project.urls]

tuttle/app/core/database_storage_impl.py

@@ -6,6 +6,7 @@
 from loguru import logger
 
 from ... import demo
+from ...migrations.run import run_migrations
 
 from .abstractions import DatabaseStorage
 
@@ -21,18 +22,21 @@ def __init__(self, store_demo_timetracking_dataframe: Callable, debug_mode: bool
         self.store_demo_dataframe_callback = store_demo_timetracking_dataframe
         self.debug_mode = debug_mode
 
+    @property
+    def db_url(self) -> str:
+        return f"sqlite:///{self.db_path}"
+
     def create_model(self):
-        logger.info("Creating database model")
-        sqlmodel.SQLModel.metadata.create_all(self.db_engine, checkfirst=True)
+        logger.info("Creating/migrating database model")
+        run_migrations(self.db_url)
 
     def ensure_database(self):
         if not self.db_path.exists():
-            self.db_engine = sqlmodel.create_engine(
-                f"sqlite:///{self.db_path}", echo=True
-            )
+            self.db_engine = sqlmodel.create_engine(self.db_url, echo=True)
             self.create_model()
         else:
-            logger.info("Database exists, skipping creation")
+            logger.info("Database exists, running pending migrations")
+            run_migrations(self.db_url)
 
     def reset_database(self):
         logger.info("Clearing database")
@@ -41,7 +45,7 @@ def reset_database(self):
         except FileNotFoundError:
             logger.info("Database file not found, skipping delete")
         self.db_engine = sqlmodel.create_engine(
-            f"sqlite:///{self.db_path}",
+            self.db_url,
             echo=self.debug_mode,
         )
         self.create_model()

tuttle/demo.py

@@ -15,6 +15,7 @@
 
 from tuttle import rendering
 from tuttle.calendar import Calendar, ICSCalendar
+from tuttle.migrations.run import run_migrations
 from tuttle.model import (
     Address,
     BankAccount,
@@ -402,12 +403,12 @@ def install_demo_data(
     db_path (str): The path to the database.
     on_cache_timetracking_dataframe (Optional[Callable], optional): A callback function to be called when the timetracking dataframe is cached. Defaults to None.
     """
-    db_path = f"""sqlite:///{db_path}"""
-    logger.info(f"Installing demo data in {db_path}...")
-    logger.info(f"Creating database engine at: {db_path}...")
-    db_engine = create_engine(db_path)
-    logger.info("Creating database tables...")
-    SQLModel.metadata.create_all(db_engine)
+    db_url = f"""sqlite:///{db_path}"""
+    logger.info(f"Installing demo data in {db_url}...")
+    logger.info(f"Creating database engine at: {db_url}...")
+    db_engine = create_engine(db_url)
+    logger.info("Creating database tables via migrations...")
+    run_migrations(db_url)
 
     logger.info("Creating demo user...")
     with Session(db_engine) as session:

tuttle/migrations/__init__.py

@@ -0,0 +1 @@
+"""Database migrations for Tuttle using Alembic."""

tuttle/migrations/alembic.ini

@@ -0,0 +1,48 @@
+# Alembic configuration for Tuttle
+#
+# The database URL is set programmatically at runtime,
+# not from this file. See env.py for details.
+
+[alembic]
+# path to migration scripts — relative to this file
+script_location = %(here)s
+
+# template used to generate migration file names
+file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(rev)s_%%(slug)s
+
+# output encoding
+output_encoding = utf-8
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

tuttle/migrations/env.py

@@ -0,0 +1,95 @@
+"""Alembic environment configuration for Tuttle.
+
+This env.py is designed to work with SQLModel and the Tuttle data model.
+The database URL is injected programmatically (not from alembic.ini)
+so that the app can resolve ~/.tuttle/tuttle.db at runtime.
+"""
+
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+from sqlmodel import SQLModel
+
+# Import all models so that SQLModel.metadata is fully populated
+from tuttle.model import (  # noqa: F401
+    Address,
+    User,
+    ICloudAccount,
+    GoogleAccount,
+    Bank,
+    BankAccount,
+    Contact,
+    Client,
+    Contract,
+    Project,
+    TimeTrackingItem,
+    Timesheet,
+    Invoice,
+    InvoiceItem,
+    TimelineItem,
+)
+
+
+# This is the Alembic Config object
+config = context.config
+
+# Interpret the config file for Python logging, if present
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# The target metadata for autogenerate support
+target_metadata = SQLModel.metadata
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode.
+
+    Configures the context with just a URL and not an Engine.
+    Calls to context.execute() will emit the given string to the script output.
+    """
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        render_as_batch=True,  # Required for SQLite ALTER TABLE support
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode.
+
+    Creates an Engine and associates a connection with the context.
+    """
+    # Support URL via -x sqlalchemy.url=... CLI option (overrides config)
+    url = context.get_x_argument(as_dictionary=True).get("sqlalchemy.url")
+    if url:
+        config.set_main_option("sqlalchemy.url", url)
+
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            render_as_batch=True,  # Required for SQLite ALTER TABLE support
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+
+    connectable.dispose()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

tuttle/migrations/run.py

@@ -0,0 +1,91 @@
+"""Programmatic migration runner for Tuttle.
+
+This module provides functions to run Alembic migrations from within
+the application (e.g. at startup), without requiring the alembic CLI.
+
+Usage:
+    from tuttle.migrations.run import run_migrations
+    run_migrations("sqlite:///path/to/tuttle.db")
+"""
+
+from pathlib import Path
+
+from alembic import command
+from alembic.config import Config
+from alembic.runtime.migration import MigrationContext
+from alembic.script import ScriptDirectory
+from loguru import logger
+from sqlalchemy import create_engine, inspect
+
+
+# Directory containing this module (= the migrations package)
+_MIGRATIONS_DIR = Path(__file__).parent
+
+
+def _get_alembic_config(db_url: str) -> Config:
+    """Create an Alembic Config pointing at the bundled migrations."""
+    ini_path = _MIGRATIONS_DIR / "alembic.ini"
+    cfg = Config(str(ini_path))
+    cfg.set_main_option("script_location", str(_MIGRATIONS_DIR))
+    cfg.set_main_option("sqlalchemy.url", db_url)
+    return cfg
+
+
+def get_head_revision() -> str | None:
+    """Return the head revision from the migration scripts."""
+    script = ScriptDirectory(str(_MIGRATIONS_DIR))
+    return script.get_current_head()
+
+
+def run_migrations(db_url: str) -> None:
+    """Run all pending Alembic migrations on the database.
+
+    Handles three scenarios:
+    1. **New database** (no tables): Alembic creates everything via migrations.
+    2. **Pre-Alembic database** (tables exist, no alembic_version):
+       Stamps the DB at the baseline revision, then applies new migrations.
+    3. **Migrated database** (alembic_version exists): Applies pending migrations.
+    """
+    head = get_head_revision()
+    if head is None:
+        logger.info("No migration scripts found, skipping migrations")
+        return
+
+    cfg = _get_alembic_config(db_url)
+    engine = create_engine(db_url)
+
+    try:
+        insp = inspect(engine)
+        table_names = insp.get_table_names()
+        has_version_table = "alembic_version" in table_names
+        has_app_tables = any(t != "alembic_version" for t in table_names)
+
+        # Get current revision
+        with engine.connect() as conn:
+            ctx = MigrationContext.configure(conn)
+            current = ctx.get_current_revision()
+
+        if has_app_tables and not has_version_table:
+            # Pre-Alembic database: stamp at baseline so future migrations apply
+            script = ScriptDirectory(str(_MIGRATIONS_DIR))
+            base = script.get_base()
+            if base is None:
+                logger.warning("No migration scripts found, nothing to stamp")
+                return
+            logger.info(
+                "Pre-existing database detected without Alembic version table. "
+                f"Stamping at baseline revision: {base}"
+            )
+            command.stamp(cfg, base)
+            current = base
+
+        if current == head:
+            logger.debug(f"Database is already at head revision ({head})")
+            return
+
+        logger.info(f"Running migrations: {current} → {head}")
+        command.upgrade(cfg, "head")
+        logger.info("Migrations completed successfully")
+
+    finally:
+        engine.dispose()

tuttle/migrations/script.py.mako

@@ -0,0 +1,27 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+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"}