Feature/implement internal schema migration (#27)

* feat: Implement internal schema migration system

Adds a comprehensive migration framework for managing pgsqlite's internal schema evolution.

Key features:
- Migration runner with transaction-based execution and automatic rollback
- SHA256 checksum validation for migration integrity
- Migration locking to prevent concurrent migrations
- Support for SQL, SqlBatch, Function, and Combined migration types
- Version tracking in __pgsqlite_metadata table
- Migration history in __pgsqlite_migrations table

Migration behavior:
- NO automatic migrations on startup (safety first)
- Schema version is checked on database initialization
- Throws descriptive error if schema is outdated
- Explicit --migrate CLI flag to run migrations and exit
- Pre-migration databases (v1) are automatically detected

Current migrations:
- v1: Initial schema (creates system tables)
- v2: ENUM support (enum types, values, usage tracking)

Test mode handling:
- In-memory databases auto-migrate during tests
- Detects test environment via CARGO env variable
- All test suites updated and passing

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: Update documentation for schema migration system

Updates documentation to reflect the implemented schema migration behavior:

README.md:
- Added comprehensive Schema Migration section
- Documented explicit --migrate flag requirement
- Included usage examples and error messages
- Explained migration features (transactions, checksums, history)

TODO.md:
- Added note about explicit migration mode in completed tasks
- Confirmed all migration tasks are marked as completed

docs/schema-migration-plan.md:
- Added implementation status header (COMPLETED)
- Updated Migration Execution Timing section
- Changed from automatic to explicit migration approach
- Added example commands showing migration workflow

The documentation now clearly explains that migrations are never run
automatically (except for test in-memory databases) and users must
explicitly use the --migrate flag for safety.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: Add migration step to integration test script for file databases

The GitHub Actions integration tests were failing because file-based
database tests need to run migrations before starting the server.

Changes:
- Add migration execution for file-ssl and file-no-ssl modes
- Run `pgsqlite --migrate` before starting the server
- Ensure test database cleanup includes file databases
- Exit with error if migration fails

This fixes the CI/CD pipeline failure where tests failed with:
"Database schema is outdated. Current version: 0, Required version: 2"

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: Enable auto-migration for in-memory databases in integration tests

GitHub Actions was failing because in-memory databases weren't
auto-migrating in the release build used by integration tests.

Changes:
- Add PGSQLITE_TEST_AUTO_MIGRATE environment variable support
- In-memory databases auto-migrate when this env var is set
- Test script sets this for in-memory test modes (tcp-ssl, tcp-no-ssl, unix-socket)
- File-based test modes continue to use explicit --migrate

This allows integration tests to run successfully while maintaining
the safety of explicit migrations in production.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: erans

CLAUDE.md

@@ -39,6 +39,36 @@ pgsqlite is a PostgreSQL protocol adapter for SQLite databases. It allows Postgr
 - Avoid adding comments unless necessary
 - Keep code concise and idiomatic
 
+## Schema Migration System (2025-07-06)
+
+pgsqlite includes an internal schema migration system to handle schema evolution:
+
+### Migration Behavior
+- **No automatic migrations**: Migrations are NOT run automatically on startup
+- **Version checking**: Database schema version is checked on startup
+- **Error on outdated schema**: If the database schema is outdated, pgsqlite will exit with an error message
+- **Explicit migration**: Use `--migrate` command line flag to run pending migrations and exit
+
+### Usage
+```bash
+# Run migrations on a database
+pgsqlite --database mydb.db --migrate
+
+# Normal operation (will fail if schema is outdated)
+pgsqlite --database mydb.db
+```
+
+### Implementation Details
+- Migrations are embedded in the binary using lazy_static
+- Each migration has a SHA256 checksum for integrity verification
+- Migrations run in transactions with automatic rollback on failure
+- Migration locking prevents concurrent migrations
+- Pre-migration databases (with __pgsqlite_schema table) are detected as version 1
+
+### Current Migrations
+- **v1**: Initial schema (creates __pgsqlite_schema, metadata tables)
+- **v2**: ENUM support (creates enum types, values, and usage tracking tables)
+
 ## Recent Work (Condensed History)
 - Implemented comprehensive PostgreSQL type support (40+ types including ranges, network types, binary types)
 - Built custom DECIMAL type system with automatic query rewriting for proper numeric handling

Cargo.lock

@@ -58,6 +58,9 @@ config = "0.15"
 clap = { version = "4.5", features = ["derive", "env"] }
 lazy_static = "1.5"
 
+# Cryptography for migration checksums
+sha2 = "0.10"
+
 # Metrics
 prometheus = "0.14"
 

Cargo.toml

@@ -237,6 +237,37 @@ All SQLite functions are available, including:
 - Array operations (arrays are stored as JSON strings)
 - Advanced PostgreSQL features (stored procedures, triggers, etc.)
 
+## Schema Migration
+
+pgsqlite includes an internal schema migration system to manage its metadata tables. When pgsqlite evolves and requires changes to its internal schema, migrations ensure smooth upgrades.
+
+### Migration Behavior
+
+- **No automatic migrations**: For safety, migrations are NOT run automatically on startup
+- **Version checking**: Database schema version is checked on startup
+- **Explicit migration**: Use the `--migrate` flag to run pending migrations
+
+### Running Migrations
+
+```bash
+# Check if migrations are needed (will error if schema is outdated)
+cargo run -- --database mydb.db
+
+# Run pending migrations and exit
+cargo run -- --database mydb.db --migrate
+
+# Example output when migrations are needed:
+# Error: Failed to create database handler: Database schema is outdated. 
+# Current version: 0, Required version: 2. Please run with --migrate to update the schema.
+```
+
+### Migration Details
+
+- Migrations run in transactions with automatic rollback on failure
+- Each migration has a SHA256 checksum for integrity verification
+- Migration history is tracked in `__pgsqlite_migrations` table
+- Concurrent migrations are prevented via locking
+
 ## Building and Testing
 
 ```bash

README.md

@@ -215,6 +215,24 @@ This file tracks all future development tasks for the pgsqlite project. It serve
 
 ### Storage & Optimization
 
+#### Schema Migration System - COMPLETED (2025-07-06)
+- [x] Implement internal schema migration framework
+  - [x] Create migration module with runner and registry
+  - [x] Implement Migration and MigrationAction structs with SHA256 checksums
+  - [x] Build migration registry with lazy_static for embedded migrations
+  - [x] Create MigrationRunner with transaction-based execution
+  - [x] Add migration locking to prevent concurrent migrations
+  - [x] Integrate migrations into DbHandler initialization
+  - [x] Support for SQL, SqlBatch, Function, and Combined migration types
+  - [x] Version detection for pre-migration databases (v1 recognition)
+  - [x] Comprehensive test coverage for all migration scenarios
+  - [x] Migration history tracking in __pgsqlite_migrations table
+  - [x] Idempotent migrations - can run multiple times safely
+  - [x] Explicit migration mode - requires --migrate flag, errors if schema outdated
+  - [x] Current migrations:
+    - v1: Initial schema (__pgsqlite_schema, metadata tables)
+    - v2: ENUM support (enum types, values, usage tracking)
+
 #### Indexing
 - [ ] Support for expression indexes
 - [ ] Partial index support