feat(adk): Implement Google ADK Session Backend (#101)

Introduce a Google ADK session backend extension for SQLSpec. This enhances the framework's capabilities for managing sessions and events in applications using the Google Agent Development Kit.

Author: cofin

.github/workflows/docs.yml

@@ -1,4 +1,4 @@
-name: Documentation Building
+name: Documentation Build
 
 on:
   release:
@@ -24,18 +24,26 @@ jobs:
       - name: Install dependencies
         run: uv sync --all-extras --dev
 
-      - name: Fetch gh pages
-        run: git fetch origin gh-pages --depth=1
-
-      - name: Build release docs
+      - name: Build documentation
         run: uv run python tools/build_docs.py docs-build
+
+      - name: Package documentation artifact
+        run: tar -czvf docs-build.tar.gz docs-build
+
+      - name: Upload Release Asset
         if: github.event_name == 'release'
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ github.event.release.upload_url }}
+          asset_path: ./docs-build.tar.gz
+          asset_name: docs-build-${{ github.ref_name }}.tar.gz
+          asset_content_type: application/gzip
 
-      - name: Build dev docs
-        run: uv run python tools/build_docs.py docs-build
+      - name: Upload 'latest' docs artifact
         if: github.event_name == 'push'
-
-      - name: Deploy
-        uses: JamesIves/github-pages-deploy-action@v4
+        uses: actions/upload-artifact@v4
         with:
-          folder: docs-build
+          name: latest-docs
+          path: docs-build.tar.gz

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.13.3"
+    rev: "v0.14.0"
     hooks:
       - id: ruff
         args: ["--fix"]

NOTICE

@@ -6,3 +6,73 @@ All commits to this project will be documented in this file.
 
 SQLSpec Changelog
 ==================
+
+Recent Updates
+==============
+
+Extension Migration Configuration
+----------------------------------
+
+Extension migrations now receive automatic version prefixes and configuration has been simplified:
+
+1. **Version Prefixing** (Automatic)
+
+   Extension migrations are automatically prefixed to prevent version collisions:
+
+   .. code-block:: text
+
+      # User migrations
+      0001_initial.py       → version: 0001
+
+      # Extension migrations (automatic prefix)
+      0001_create_tables.py → version: ext_adk_0001
+      0001_create_session.py → version: ext_litestar_0001
+
+2. **Configuration Format** (Important)
+
+   Extension settings must be in ``extension_config`` only:
+
+   .. code-block:: python
+
+      # Incorrect format
+      migration_config={
+          "include_extensions": [
+              {"name": "adk", "session_table": "custom"}
+          ]
+      }
+
+      # Correct format
+      extension_config={
+          "adk": {"session_table": "custom"}
+      },
+      migration_config={
+          "include_extensions": ["adk"]  # Simple string list
+      }
+
+**Configuration Guide**: See :doc:`/migration_guides/extension_config`
+
+Features
+--------
+
+- Extension migrations now automatically prefixed (``ext_adk_0001``, ``ext_litestar_0001``)
+- Eliminated version collision between extension and user migrations
+- Simplified extension configuration API
+- Single source of truth for extension settings (``extension_config``)
+
+Bug Fixes
+---------
+
+- Fixed version collision when extension and user migrations had the same version number
+- Fixed duplicate key violation in ``ddl_migrations`` table when using extensions
+- Improved migration tracking with clear extension identification
+
+Technical Changes
+-----------------
+
+- ``_load_migration_metadata()`` now accepts optional ``version`` parameter
+- ``_parse_extension_configs()`` rewritten to read from ``extension_config`` only
+- Extension migration version prefixing handled in ``_get_migration_files_sync()``
+- Removed dict format support from ``include_extensions``
+
+**Previous Versions**
+=====================

docs/changelog.rst

@@ -155,7 +155,7 @@
 templates_path = ["_templates"]
 html_js_files = ["versioning.js"]
 html_css_files = ["custom.css"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "PYPI_README.md"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "PYPI_README.md", "STYLE_GUIDE.md", "VOICE_AUDIT_REPORT.md"]
 html_show_sourcelink = True
 html_copy_source = True
 

docs/conf.py

@@ -1,9 +1,18 @@
+# /// script
+# dependencies = [
+#   "sqlspec[adbc]",
+#   "rich",
+# ]
+# requires-python = ">=3.10"
+# ///
 """Example demonstrating ADBC driver usage with query mixins.
 
 This example shows how to use the ADBC (Arrow Database Connectivity) driver
 with the development PostgreSQL container started by `make infra-up`.
 """
 
+from rich import print
+
 from sqlspec import SQLSpec, sql
 from sqlspec.adapters.adbc import AdbcConfig
 
@@ -55,59 +64,59 @@ def adbc_example() -> None:
 
         # Select all metrics using query mixin
         metrics = driver.select("SELECT * FROM analytics_data ORDER BY recorded_at")
-        print(f"All metrics: {metrics}")
+        print(f"[cyan]All metrics:[/cyan] {metrics}")
 
         # Select one metric using query mixin
         revenue = driver.select_one("SELECT * FROM analytics_data WHERE metric_name = $1", "revenue")
-        print(f"Revenue metric: {revenue}")
+        print(f"[cyan]Revenue metric:[/cyan] {revenue}")
 
         # Select one or none (no match) using query mixin
         nothing = driver.select_one_or_none("SELECT * FROM analytics_data WHERE metric_name = $1", "nothing")
-        print(f"Nothing: {nothing}")
+        print(f"[cyan]Nothing:[/cyan] {nothing}")
 
         # Select scalar value using query mixin
         avg_value = driver.select_value("SELECT AVG(metric_value) FROM analytics_data WHERE metric_value > $1", 1.0)
-        print(f"Average metric value: {avg_value:.2f}")
+        print(f"[cyan]Average metric value:[/cyan] {avg_value:.2f}")
 
         # Update
         result = driver.execute(
             "UPDATE analytics_data SET dimensions = $1::jsonb WHERE metric_name = $2",
             '{"updated": true}',
             "bounce_rate",
         )
-        print(f"Updated {result.rows_affected} bounce rate records")
+        print(f"[yellow]Updated {result.rows_affected} bounce rate records[/yellow]")
 
         # Delete
         result = driver.execute("DELETE FROM analytics_data WHERE metric_value < $1", 1.0)
-        print(f"Removed {result.rows_affected} low-value metrics")
+        print(f"[yellow]Removed {result.rows_affected} low-value metrics[/yellow]")
 
         # Use query builder with driver - this demonstrates the QueryBuilder parameter fix
         query = sql.select("*").from_("analytics_data").where("metric_name = $1")
         page_view_metrics = driver.select(query, "page_views")
-        print(f"Page view metrics: {page_view_metrics}")
+        print(f"[cyan]Page view metrics:[/cyan] {page_view_metrics}")
 
         # JSON operations (PostgreSQL-specific) - using raw SQL due to SQLGlot JSON operator conversion
         mobile_metrics = driver.select(
             "SELECT metric_name, metric_value, dimensions->>'device' as device FROM analytics_data WHERE dimensions->>'device' = $1",
             "mobile",
         )
-        print(f"Mobile metrics: {mobile_metrics}")
+        print(f"[cyan]Mobile metrics:[/cyan] {mobile_metrics}")
 
         # Demonstrate pagination
         page_metrics = driver.select("SELECT * FROM analytics_data ORDER BY metric_value DESC LIMIT $1 OFFSET $2", 2, 0)
         total_count = driver.select_value("SELECT COUNT(*) FROM analytics_data")
-        print(f"Page 1: {page_metrics}, Total: {total_count}")
+        print(f"[cyan]Page 1:[/cyan] {page_metrics}, [cyan]Total:[/cyan] {total_count}")
 
 
 def main() -> None:
     """Run ADBC example."""
-    print("=== ADBC (Arrow Database Connectivity) Driver Example ===")
+    print("[bold cyan]=== ADBC (Arrow Database Connectivity) Driver Example ===[/bold cyan]")
     try:
         adbc_example()
-        print("✅ ADBC example completed successfully!")
+        print("[green]✅ ADBC example completed successfully![/green]")
     except Exception as e:
-        print(f"❌ ADBC example failed: {e}")
-        print("Make sure PostgreSQL is running with: make infra-up")
+        print(f"[red]❌ ADBC example failed: {e}[/red]")
+        print("[yellow]Make sure PostgreSQL is running with: make infra-up[/yellow]")
 
 
 if __name__ == "__main__":