From 8352c3ab7ca25d57750ab9d8e2561f7f07dde51f Mon Sep 17 00:00:00 2001 From: Phil Skentelbery Date: Tue, 25 Nov 2025 09:59:17 -0700 Subject: [PATCH] refactor: Rename SCHEMA_SQL to INITIAL_SCHEMA_SQL MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This aligns with ADR-033's migration system redesign. The initial schema represents the v1.0.0 baseline and should not be modified. All schema changes after v1.0.0 must go in migration files. Changes: - Renamed SCHEMA_SQL → INITIAL_SCHEMA_SQL in database.py - Updated all references in migrations.py comments - Added comment: "DO NOT MODIFY - This represents the v1.0.0 schema state" - No functional changes, purely documentation improvement Part of v1.1.0 migration system redesign (Phase 2). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- starpunk/database.py | 8 +++++--- starpunk/migrations.py | 30 +++++++++++++++--------------- 2 files changed, 20 insertions(+), 18 deletions(-) diff --git a/starpunk/database.py b/starpunk/database.py index 03cfee8..d8f9819 100644 --- a/starpunk/database.py +++ b/starpunk/database.py @@ -7,8 +7,10 @@ import sqlite3 from pathlib import Path -# Database schema -SCHEMA_SQL = """ +# Initial database schema (v1.0.0 baseline) +# DO NOT MODIFY - This represents the v1.0.0 schema state +# All schema changes after v1.0.0 must go in migration files +INITIAL_SCHEMA_SQL = """ -- Notes metadata (content is in files) CREATE TABLE IF NOT EXISTS notes ( id INTEGER PRIMARY KEY AUTOINCREMENT, @@ -107,7 +109,7 @@ def init_db(app=None): # Create database and initial schema conn = sqlite3.connect(db_path) try: - conn.executescript(SCHEMA_SQL) + conn.executescript(INITIAL_SCHEMA_SQL) conn.commit() if logger: logger.info(f"Database initialized: {db_path}") diff --git a/starpunk/migrations.py b/starpunk/migrations.py index 4ea96ff..490ff7b 100644 --- a/starpunk/migrations.py +++ b/starpunk/migrations.py @@ -7,7 +7,7 @@ Migrations are numbered SQL files in the migrations/ directory. Fresh Database Detection: - If schema_migrations table is empty AND schema is current - Marks all migrations as applied (skip execution) -- This handles databases created with current SCHEMA_SQL +- This handles databases created with current INITIAL_SCHEMA_SQL Existing Database Behavior: - Applies only pending migrations @@ -56,14 +56,14 @@ def create_migrations_table(conn): def is_schema_current(conn): """ - Check if database schema is current (matches SCHEMA_SQL + all migrations) + Check if database schema is current (matches INITIAL_SCHEMA_SQL + all migrations) Uses heuristic: Check for presence of latest schema features Checks for: - code_verifier column NOT in auth_state (removed in migration 003) - - authorization_codes table (migration 002 or SCHEMA_SQL >= v1.0.0-rc.1) + - authorization_codes table (migration 002 or INITIAL_SCHEMA_SQL >= v1.0.0-rc.1) - token_hash column in tokens table (migration 002) - - Token indexes (migration 002 only, removed from SCHEMA_SQL in v1.0.0-rc.2) + - Token indexes (migration 002 only, removed from INITIAL_SCHEMA_SQL in v1.0.0-rc.2) Args: conn: SQLite connection @@ -87,10 +87,10 @@ def is_schema_current(conn): return False # Check for token indexes (created by migration 002 ONLY) - # These indexes were removed from SCHEMA_SQL in v1.0.0-rc.2 + # These indexes were removed from INITIAL_SCHEMA_SQL in v1.0.0-rc.2 # to prevent conflicts when migrations run. # A database with tables/columns but no indexes means: - # - SCHEMA_SQL was run (creating tables/columns) + # - INITIAL_SCHEMA_SQL was run (creating tables/columns) # - But migration 002 hasn't run yet (no indexes) # So it's NOT fully current and needs migrations. if not index_exists(conn, 'idx_tokens_hash'): @@ -166,7 +166,7 @@ def is_migration_needed(conn, migration_name): """ Check if a specific migration is needed based on database state - This is used for fresh databases where SCHEMA_SQL may have already + This is used for fresh databases where INITIAL_SCHEMA_SQL may have already included some migration features. We check the actual database state rather than just applying all migrations blindly. @@ -175,11 +175,11 @@ def is_migration_needed(conn, migration_name): migration_name: Migration filename to check Returns: - bool: True if migration should be applied, False if already applied via SCHEMA_SQL + bool: True if migration should be applied, False if already applied via INITIAL_SCHEMA_SQL """ # Migration 001: Adds code_verifier column to auth_state if migration_name == "001_add_code_verifier_to_auth_state.sql": - # Check if column already exists (was added to SCHEMA_SQL in v0.8.0) + # Check if column already exists (was added to INITIAL_SCHEMA_SQL in v0.8.0) return not column_exists(conn, 'auth_state', 'code_verifier') # Migration 002: Creates new tokens/authorization_codes tables with indexes @@ -197,7 +197,7 @@ def is_migration_needed(conn, migration_name): # If tables exist with correct structure, check indexes # If indexes are missing but tables exist, this is a fresh database from - # SCHEMA_SQL that just needs indexes. We CANNOT run the full migration + # INITIAL_SCHEMA_SQL that just needs indexes. We CANNOT run the full migration # (it will fail trying to CREATE TABLE). Instead, we mark it as not needed # and apply indexes separately. has_all_indexes = ( @@ -209,7 +209,7 @@ def is_migration_needed(conn, migration_name): ) if not has_all_indexes: - # Tables exist but indexes missing - this is a fresh database from SCHEMA_SQL + # Tables exist but indexes missing - this is a fresh database from INITIAL_SCHEMA_SQL # We need to create just the indexes, not run the full migration # Return False (don't run migration) and handle indexes separately return False @@ -323,7 +323,7 @@ def run_migrations(db_path, logger=None): Fresh Database Behavior: - If schema_migrations table is empty AND schema is current - Marks all migrations as applied (skip execution) - - This handles databases created with current SCHEMA_SQL + - This handles databases created with current INITIAL_SCHEMA_SQL Existing Database Behavior: - Applies only pending migrations @@ -457,13 +457,13 @@ def run_migrations(db_path, logger=None): conn.execute(index_sql) logger.info(f"Created {len(indexes_to_create)} missing indexes from migration 002") - # Mark as applied without executing full migration (SCHEMA_SQL already has table changes) + # Mark as applied without executing full migration (INITIAL_SCHEMA_SQL already has table changes) conn.execute( "INSERT INTO schema_migrations (migration_name) VALUES (?)", (migration_name,) ) skipped_count += 1 - logger.debug(f"Skipped migration {migration_name} (already in SCHEMA_SQL)") + logger.debug(f"Skipped migration {migration_name} (already in INITIAL_SCHEMA_SQL)") else: # Apply the migration (within our transaction) try: @@ -497,7 +497,7 @@ def run_migrations(db_path, logger=None): if skipped_count > 0: logger.info( f"Migrations complete: {pending_count} applied, {skipped_count} skipped " - f"(already in SCHEMA_SQL), {total_count} total" + f"(already in INITIAL_SCHEMA_SQL), {total_count} total" ) else: logger.info(