Dbmigration

.cursor/rules/schema-migrations.mdc

@@ -0,0 +1,89 @@
+---
+description: Database schema changes must go through Alembic
+globs: tuttle/model.py,tuttle/db_schema.py,tuttle/migrations/**/*.py,tuttle/app_db.py
+alwaysApply: false
+---
+
+# Database Schema Changes
+
+`tuttle/model.py` is the SINGLE SOURCE OF TRUTH for the database schema.
+Alembic in `tuttle/migrations/` derives all DDL from `SQLModel.metadata`.
+
+## Critical: versions/*.py are frozen snapshots, NOT source of truth
+
+Files in `tuttle/migrations/versions/` are APPEND-ONLY historical
+records. They look like schema definitions because they contain
+`op.create_table(...)` calls, but they capture the schema at a point
+in time — not the current schema.
+
+DO NOT:
+- Read `versions/*.py` to learn the current schema. Read `model.py`.
+- Edit any existing file in `versions/`. Once committed, a revision is
+  immutable.
+- Hand-write a new revision file. Always go through `just migrate`.
+
+DO:
+- Edit `tuttle/model.py` for schema changes, then `just migrate "<msg>"`
+  to ADD a new revision.
+- Treat each `versions/NNNN_*.py` as a sealed migration step. The chain
+  of all revisions applied in order reproduces the current schema.
+
+## When editing tuttle/model.py
+
+After ANY change to a SQLModel class (new column, renamed field, new
+table, new relationship) you MUST:
+
+  1. `just migrate "<describe change>"`   (alias for `alembic revision --autogenerate`)
+  2. Open the generated `tuttle/migrations/versions/*.py`
+  3. CHECK FOR `drop_column` + `add_column` PAIRS — autogenerate misreads
+     renames as drop+add, which destroys data. Use `op.alter_column(...,
+     new_column_name=...)` for renames.
+  4. Commit `model.py` AND the new migration script TOGETHER.
+
+## Inside tuttle/migrations/versions/*.py
+
+NEVER `from tuttle.model import ...`. Models drift; migration scripts
+must be pinned to the schema at their point in history.
+
+For data transformations use a local `sa.table()` snapshot with only the
+columns this revision touches:
+
+```python
+invoice = sa.table("invoice",
+                   sa.column("id", sa.Integer),
+                   sa.column("document_type", sa.String))
+op.execute(invoice.update().values(document_type="invoice"))
+```
+
+After a batch op on a table with foreign keys (`invoice`, `client`,
+`project`, `contract`, `timesheet`, `timetrackingitem`), verify
+integrity inside the revision:
+
+```python
+op.execute("PRAGMA foreign_key_check")
+```
+
+## tuttle/db_schema.py
+
+Thin Alembic caller (backup → `command.upgrade` → restore on failure).
+NEVER add `ALTER TABLE` strings or column dicts here. If you find
+yourself wanting to, you are working against the design.
+
+## Downgrades are not supported
+
+The `downgrade()` function in every revision must raise
+`NotImplementedError`. Tuttle is a single-user desktop app: rolling back
+a schema is destructive (data in dropped columns is gone) and offers
+nothing over restoring a `.bak-<ts>` snapshot taken by
+`ensure_schema()` before the upgrade.
+
+If you're iterating on a migration during development and want to
+"undo": delete the revision file in `versions/`, run `just reset` to
+wipe `~/.tuttle`, and regenerate.
+
+## tuttle_tests/test_migrations.py
+
+Don't bypass these tests. They catch silent data-loss bugs that the
+autogenerator cannot detect on its own.
+
+See `tuttle/migrations/README.md` for the full rationale.

AGENTS.md

@@ -16,3 +16,10 @@ OUTPUT STYLE: dense
 - No narration, no filler, no hedging
 - BUDGET: ≤200 tokens per response unless code block required
 <!-- /lean-ctx-compression -->
+
+## Schema changes
+
+Schema lives in `tuttle/model.py`. Migrations are Alembic in `tuttle/migrations/`.
+Any change to a SQLModel class requires `just migrate "<msg>"` + reviewing the
+generated revision for rename-as-drop+add traps. See
+`.cursor/rules/schema-migrations.mdc` and `tuttle/migrations/README.md`.

alembic.ini

@@ -0,0 +1,149 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts.
+# this is typically a path given in POSIX (e.g. forward slashes)
+# format, relative to the token %(here)s which refers to the location of this
+# ini file
+script_location = %(here)s/tuttle/migrations
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
+# for all available tokens
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+# Or organize into date-based subdirectories (requires recursive_version_locations = true)
+# file_template = %%(year)d/%%(month).2d/%%(day).2d_%%(hour).2d%%(minute).2d_%%(second).2d_%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.  for multiple paths, the path separator
+# is defined by "path_separator" below.
+prepend_sys_path = .
+
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the tzdata library which can be installed by adding
+# `alembic[tz]` to the pip requirements.
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to <script_location>/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "path_separator"
+# below.
+# version_locations = %(here)s/bar:%(here)s/bat:%(here)s/alembic/versions
+
+# path_separator; This indicates what character is used to split lists of file
+# paths, including version_locations and prepend_sys_path within configparser
+# files such as alembic.ini.
+# The default rendered in new alembic.ini files is "os", which uses os.pathsep
+# to provide os-dependent path splitting.
+#
+# Note that in order to support legacy alembic.ini files, this default does NOT
+# take place if path_separator is not present in alembic.ini.  If this
+# option is omitted entirely, fallback logic is as follows:
+#
+# 1. Parsing of the version_locations option falls back to using the legacy
+#    "version_path_separator" key, which if absent then falls back to the legacy
+#    behavior of splitting on spaces and/or commas.
+# 2. Parsing of the prepend_sys_path option falls back to the legacy
+#    behavior of splitting on spaces, commas, or colons.
+#
+# Valid values for path_separator are:
+#
+# path_separator = :
+# path_separator = ;
+# path_separator = space
+# path_separator = newline
+#
+# Use os.pathsep. Default configuration used for new projects.
+path_separator = os
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+# database URL.  This is consumed by the user-maintained env.py script only.
+# other means of configuring database URLs may be customized within the env.py
+# file.
+sqlalchemy.url = driver://user:pass@localhost/dbname
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the module runner, against the "ruff" module
+# hooks = ruff
+# ruff.type = module
+# ruff.module = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Alternatively, use the exec runner to execute a binary found on your PATH
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Logging configuration.  This is also consumed by the user-maintained
+# env.py script only.
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+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

justfile

@@ -96,6 +96,36 @@ calendar-setup:
 test *args="":
     {{python}} -m pytest {{args}}
 
+
+# Create a new Alembic migration from the current SQLModel diff.
+#   just migrate "add foo to client"
+# Runs autogenerate against a throw-away temp DB and writes a new
+# revision to tuttle/migrations/versions/. ALWAYS review the result —
+# autogenerate misreads renames as drop+add (data loss).
+migrate message:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    tmp=$(mktemp -t tuttle_migrate.XXXXXX.db)
+    trap 'rm -f "$tmp"' EXIT
+    TUTTLE_DB_URL="sqlite:///$tmp" {{venv}}/bin/alembic upgrade head
+    TUTTLE_DB_URL="sqlite:///$tmp" {{venv}}/bin/alembic revision --autogenerate -m "{{message}}"
+    echo ""
+    echo "✓ Revision written. REVIEW it before committing:"
+    echo "  - any op.drop_column + op.add_column pair is a rename → use op.alter_column(new_column_name=...)"
+    echo "  - no \`from tuttle.model import ...\`"
+    echo "  - PRAGMA foreign_key_check after batch ops on FK tables"
+
+
+# Fail if tuttle/model.py and tuttle/migrations/versions/ disagree.
+# Wire this into CI to prevent silent schema drift.
+check-migrations:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    tmp=$(mktemp -t tuttle_check.XXXXXX.db)
+    trap 'rm -f "$tmp"' EXIT
+    TUTTLE_DB_URL="sqlite:///$tmp" {{venv}}/bin/alembic upgrade head
+    TUTTLE_DB_URL="sqlite:///$tmp" {{venv}}/bin/alembic check
+
 # ── Utilities ───────────────────────────────────────────────────────────────
 
 # Install/sync Python dependencies

pyproject.toml

@@ -42,6 +42,7 @@ dependencies = [
     "llama-index-llms-ollama",
     "llama-index-llms-openai-like",
     "drafthorse",
+    "alembic>=1.18.4",
 ]
 
 [project.scripts]

tuttle-rpc.spec

@@ -23,6 +23,14 @@ block_cipher = None
 datas = [
     ("templates", "templates"),
     ("tuttle/tax_data", "tuttle/tax_data"),
+    # Alembic migration scripts are loaded by path at runtime, so
+    # PyInstaller's import analyzer cannot discover them. Bundle the
+    # whole migrations tree (env.py, script.py.mako, versions/*.py)
+    # plus the alembic.ini so ensure_schema() can locate them via
+    # sys._MEIPASS when frozen. Without this, the packaged .app fails
+    # to migrate per-user DBs on first launch.
+    ("tuttle/migrations", "tuttle/migrations"),
+    ("alembic.ini", "."),
 ]
 
 # rfc3987_syntax ships non-Python data files that PyInstaller misses
@@ -70,6 +78,15 @@ hiddenimports = [
     # SQLModel / SQLAlchemy backends
     "sqlmodel",
     "sqlalchemy.dialects.sqlite",
+    # Alembic — env.py is imported by path at runtime; deps must be bundled
+    "alembic",
+    "alembic.config",
+    "alembic.command",
+    "alembic.script",
+    "alembic.runtime.migration",
+    "alembic.autogenerate",
+    "mako",
+    "mako.template",
     # WeasyPrint rendering chain
     "weasyprint",
     "cairocffi",

tuttle/app/users/intent.py

@@ -32,8 +32,7 @@ def _switch_to_user_db(self, db_file: str):
         db_path = self._app_db.get_user_db_path(db_file)
         reg = self._app_db.get_user_by_db_file(db_file)
         is_demo = reg and reg.is_demo if reg else False
-        if not is_demo:
-            self._ensure_user_db(db_path)
+        self._ensure_user_db(db_path)
         set_active_db(db_path)
         self._app_db.set_active(db_file)
         reset_all()