feat: implement hybrid timestamp/sequence based migration versioning (#128)

Adds hybrid versioning for migrations: timestamps in development (no conflicts), sequential in production (deterministic ordering). Includes an automated `sqlspec fix` command to convert between formats.

Closes #116

Author: cofin

AGENTS.md

@@ -1,4 +1,4 @@
-# AGENS.md
+# AGENTS.md
 
 This file provides guidance to Gemini, Claude Code, Codex, and other agents when working with code in this repository.
 
@@ -11,6 +11,96 @@ This file provides guidance to Gemini, Claude Code, Codex, and other agents when
 - **Propose improvements**: Suggest better patterns, more robust solutions, or cleaner implementations when appropriate
 - **Be a thoughtful collaborator**: Act as a good teammate who helps improve the overall quality and direction of the project
 
+## Pull Request Guidelines
+
+### PR Description Standards (MANDATORY)
+
+Pull request descriptions MUST be concise, factual, and human-readable. Avoid excessive detail that should live in documentation or commit messages.
+
+**Maximum length**: ~30-40 lines for typical features
+**Tone**: Direct, clear, professional - no marketing language or excessive enthusiasm
+
+**Required sections**:
+
+1. **Summary** (2-3 sentences): What does this do and why?
+2. **The Problem** (2-4 lines): What issue does this solve?
+3. **The Solution** (2-4 lines): How does it solve it?
+4. **Key Features** (3-5 bullet points): Most important capabilities
+5. **Example** (optional): Brief code example if it clarifies usage
+6. **Link to docs** (if comprehensive guide exists)
+
+**PROHIBITED content**:
+
+- Extensive test coverage tables (this belongs in CI reports)
+- Detailed file change lists (GitHub shows this automatically)
+- Quality metrics and linting results (CI handles this)
+- Commit-by-commit breakdown (git history shows this)
+- Implementation details (belongs in code comments/docs)
+- Excessive formatting (tables, sections, subsections)
+- Marketing language or hype
+
+**Example of GOOD PR description**:
+
+```markdown
+## Summary
+
+Adds hybrid versioning for migrations: timestamps in development (no conflicts),
+sequential in production (deterministic ordering). Includes an automated
+`sqlspec fix` command to convert between formats.
+
+Closes #116
+
+## The Problem
+
+- Sequential migrations (0001, 0002): merge conflicts when multiple devs create migrations
+- Timestamp migrations (20251011120000): no conflicts, but ordering depends on creation time
+
+## The Solution
+
+Use timestamps during development, convert to sequential before merging:
+
+    $ sqlspec create-migration -m "add users"
+    Created: 20251011120000_add_users.sql
+
+    $ sqlspec fix --yes
+    ✓ Converted to 0003_add_users.sql
+
+## Key Features
+
+- Automated conversion via `sqlspec fix` command
+- Updates database tracking to prevent errors
+- Idempotent - safe to re-run after pulling changes
+- Stable checksums through conversions
+
+See [docs/guides/migrations/hybrid-versioning.md](docs/guides/migrations/hybrid-versioning.md)
+for full documentation.
+```
+
+**Example of BAD PR description**:
+
+```markdown
+## Summary
+[800+ lines of excessive detail including test counts, file changes,
+quality metrics, implementation details, commit lists, etc.]
+```
+
+**CI Integration examples** - Keep to 5-10 lines maximum:
+
+```yaml
+# GitHub Actions example
+- run: sqlspec fix --yes
+- run: git add migrations/ && git commit && git push
+```
+
+**When to include more detail**:
+
+- Breaking changes warrant a "Breaking Changes" section
+- Complex architectural changes may need a "Design Decisions" section
+- Security fixes may need a "Security Impact" section
+
+Keep it focused: the PR description should help reviewers understand WHAT and WHY quickly.
+Implementation details belong in code, commits, and documentation.
+
 ## Common Development Commands
 
 ### Building and Installation
@@ -53,7 +143,7 @@ SQLSpec is a type-safe SQL query mapper designed for minimal abstraction between
 2. **Adapters (`sqlspec/adapters/`)**: Database-specific implementations. Each adapter consists of:
    - `config.py`: Configuration classes specific to the database
    - `driver.py`: Driver implementation (sync/async) that executes queries
-   - `_types.py`: Type definitions specific to the adapter or other uncompilable mypyc onbjects
+   - `_types.py`: Type definitions specific to the adapter or other uncompilable mypyc objects
    - Supported adapters: `adbc`, `aiosqlite`, `asyncmy`, `asyncpg`, `bigquery`, `duckdb`, `oracledb`, `psqlpy`, `psycopg`, `sqlite`
 
 3. **Driver System (`sqlspec/driver/`)**: Base classes and mixins for all database drivers:

docs/changelog.rst

@@ -10,6 +10,58 @@ SQLSpec Changelog
 Recent Updates
 ==============
 
+Hybrid Versioning with Fix Command
+-----------------------------------
+
+Added comprehensive hybrid versioning support for database migrations:
+
+- **Fix Command** - Convert timestamp migrations to sequential format
+- **Hybrid Workflow** - Use timestamps in development, sequential in production
+- **Automatic Conversion** - CI integration for seamless workflow
+- **Safety Features** - Automatic backup, rollback on errors, dry-run preview
+
+Key Features:
+
+- **Zero merge conflicts**: Developers use timestamps (``20251011120000``) during development
+- **Deterministic ordering**: Production uses sequential format (``0001``, ``0002``, etc.)
+- **Database synchronization**: Automatically updates version tracking table
+- **File operations**: Renames files and updates SQL query names
+- **CI-ready**: ``--yes`` flag for automated workflows
+
+.. code-block:: bash
+
+   # Preview changes
+   sqlspec --config myapp.config fix --dry-run
+
+   # Apply conversion
+   sqlspec --config myapp.config fix
+
+   # CI/CD mode
+   sqlspec --config myapp.config fix --yes --no-database
+
+Example conversion:
+
+.. code-block:: text
+
+   Before:                              After:
+   migrations/                          migrations/
+   ├── 0001_initial.sql                ├── 0001_initial.sql
+   ├── 0002_add_users.sql              ├── 0002_add_users.sql
+   ├── 20251011120000_products.sql →   ├── 0003_add_products.sql
+   └── 20251012130000_orders.sql   →   └── 0004_add_orders.sql
+
+**Documentation:**
+
+- Complete CLI reference: :doc:`usage/cli`
+- Workflow guide: :ref:`hybrid-versioning-guide`
+- CI integration examples for GitHub Actions and GitLab CI
+
+**Use Cases:**
+
+- Teams with parallel development avoiding migration number conflicts
+- Projects requiring deterministic migration ordering in production
+- CI/CD pipelines that standardize migrations before deployment
+
 Shell Completion Support
 -------------------------
 

docs/conf.py

@@ -62,7 +62,6 @@
     "sphinx_paramlinks",
     "sphinxcontrib.mermaid",
 ]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "guides/*"]
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "msgspec": ("https://jcristharif.com/msgspec/", None),
@@ -156,7 +155,15 @@
 templates_path = ["_templates"]
 html_js_files = ["versioning.js"]
 html_css_files = ["custom.css"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "PYPI_README.md", "STYLE_GUIDE.md", "VOICE_AUDIT_REPORT.md"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "PYPI_README.md",
+    "STYLE_GUIDE.md",
+    "VOICE_AUDIT_REPORT.md",
+    "guides/**",
+]
 html_show_sourcelink = True
 html_copy_source = True
 

docs/extensions/adk/migrations.rst

@@ -148,7 +148,7 @@ SQLSpec includes a built-in migration for ADK tables:
 
    from sqlspec.extensions.adk.migrations import create_adk_tables_migration
 
-Location: ``sqlspec/extensions/adk/migrations/0001_create_adk_tables.py``
+Location: ``sqlspec/extensions/adk/migrations/``
 
 You can copy this template for custom migrations:
 

docs/guides/README.md

@@ -28,6 +28,12 @@ Optimization guides for SQLSpec:
 - [**SQLglot Guide**](performance/sqlglot.md) - SQL parsing, transformation, and optimization with SQLglot
 - [**MyPyC Guide**](performance/mypyc.md) - Compilation strategies for high-performance Python code
 
+## Migrations
+
+Database migration strategies and workflows:
+
+- [**Hybrid Versioning**](migrations/hybrid-versioning.md) - Combine timestamp and sequential versioning for optimal workflows
+
 ## Testing
 
 Testing strategies and patterns:
@@ -91,6 +97,8 @@ docs/guides/
 │   ├── oracle.md
 │   ├── postgres.md
 │   └── ...
+├── migrations/                  # Migration workflows
+│   └── hybrid-versioning.md
 ├── performance/                 # Performance optimization
 │   ├── sqlglot.md
 │   └── mypyc.md