sqlspec 0.30.0__tar.gz → 0.30.2__tar.gz

{sqlspec-0.30.0 → sqlspec-0.30.2}/.claude/agents/expert.md

@@ -62,6 +62,31 @@ Read("AGENTS.md")
 Read("docs/guides/quick-reference/quick-reference.md")
 ```
 
+**Use SQLSpec skills for guidance:**
+
+```python
+# Main SQLSpec usage skill - configuration, queries, frameworks, migrations, testing
+Read(".claude/skills/sqlspec-usage/skill.md")
+
+# Detailed pattern guides
+Read(".claude/skills/sqlspec-usage/patterns/configuration.md")
+Read(".claude/skills/sqlspec-usage/patterns/queries.md")
+Read(".claude/skills/sqlspec-usage/patterns/frameworks.md")
+Read(".claude/skills/sqlspec-usage/patterns/migrations.md")
+Read(".claude/skills/sqlspec-usage/patterns/testing.md")
+Read(".claude/skills/sqlspec-usage/patterns/performance.md")
+Read(".claude/skills/sqlspec-usage/patterns/troubleshooting.md")
+
+# Adapter-specific skills
+Read(f".claude/skills/sqlspec-adapters/{adapter}.md")  # e.g., asyncpg.md
+
+# Working examples
+Read(".claude/skills/sqlspec-usage/examples/litestar-integration.py")
+Read(".claude/skills/sqlspec-usage/examples/fastapi-integration.py")
+Read(".claude/skills/sqlspec-usage/examples/multi-database.py")
+Read(".claude/skills/sqlspec-usage/examples/testing-patterns.py")
+```
+
 **Get library docs when needed:**
 
 ```python

{sqlspec-0.30.0 → sqlspec-0.30.2}/.claude/agents/testing.md

@@ -46,6 +46,10 @@ Glob("tests/**/test_asyncpg*.py")
 
 ```python
 Read("docs/guides/testing/testing.md")
+
+# SQLSpec testing skills
+Read(".claude/skills/sqlspec-usage/patterns/testing.md")
+Read(".claude/skills/sqlspec-usage/examples/testing-patterns.py")
 ```
 
 **Key testing principles from guide:**

{sqlspec-0.30.0 → sqlspec-0.30.2}/.claude/bootstrap.md

@@ -1290,6 +1290,226 @@ if not exists(".claude/agents/sync-guides.md"):
 
 ---
 
+## PHASE 4.6: SQLSPEC SKILLS CREATION (If SQLSpec Project)
+
+**Objective**: Auto-create comprehensive SQLSpec usage skills for database-focused projects.
+
+### Step 4.6.1: Detect if SQLSpec Project
+
+```python
+is_sqlspec_project = (
+    Grep(pattern=r'from sqlspec|import sqlspec', path='.', output_mode='count') > 5 or
+    exists("sqlspec/") or
+    (exists("pyproject.toml") and "sqlspec" in Read("pyproject.toml"))
+)
+
+if not is_sqlspec_project:
+    print("Not a SQLSpec project - skipping SQLSpec skills creation")
+    # Skip to Phase 5
+```
+
+### Step 4.6.2: Create SQLSpec Skills Directory
+
+```bash
+mkdir -p .claude/skills/sqlspec-usage/patterns
+mkdir -p .claude/skills/sqlspec-usage/examples
+mkdir -p .claude/skills/sqlspec-adapters
+```
+
+### Step 4.6.3: Generate Main SQLSpec Skill
+
+```python
+sqlspec_skill = '''# SQLSpec Usage Expert Skill
+
+**Version:** 1.0.0
+**Category:** Database, Python, SQLSpec
+**Status:** Active
+
+## Description
+
+Comprehensive guidance on using SQLSpec - a type-safe SQL query mapper for Python.
+Covers configuration, query execution, framework integration, migrations, testing,
+and performance optimization across all supported database adapters.
+
+## Activation Triggers
+
+- SQLSpec configuration or setup questions
+- Database connection management
+- Query execution patterns
+- Framework integration (Litestar, FastAPI, Starlette, Flask)
+- Migration management
+- Testing with SQLSpec
+- Performance optimization
+- Multi-database setups
+
+## Quick Reference
+
+See pattern guides for detailed information:
+- [Configuration Patterns](patterns/configuration.md)
+- [Query Execution Patterns](patterns/queries.md)
+- [Framework Integration](patterns/frameworks.md)
+- [Migration Patterns](patterns/migrations.md)
+- [Testing Best Practices](patterns/testing.md)
+- [Performance Optimization](patterns/performance.md)
+- [Troubleshooting Guide](patterns/troubleshooting.md)
+
+Working examples in `examples/` directory.
+'''
+
+Write(file_path=".claude/skills/sqlspec-usage/skill.md", content=sqlspec_skill)
+print("✓ Created .claude/skills/sqlspec-usage/skill.md")
+```
+
+### Step 4.6.4: Generate Pattern Guides
+
+Create comprehensive pattern guides:
+
+```python
+# Configuration patterns
+Write(file_path=".claude/skills/sqlspec-usage/patterns/configuration.md", content=config_patterns)
+
+# Query patterns
+Write(file_path=".claude/skills/sqlspec-usage/patterns/queries.md", content=query_patterns)
+
+# Framework integration
+Write(file_path=".claude/skills/sqlspec-usage/patterns/frameworks.md", content=framework_patterns)
+
+# Migration patterns
+Write(file_path=".claude/skills/sqlspec-usage/patterns/migrations.md", content=migration_patterns)
+
+# Testing patterns
+Write(file_path=".claude/skills/sqlspec-usage/patterns/testing.md", content=testing_patterns)
+
+# Performance patterns
+Write(file_path=".claude/skills/sqlspec-usage/patterns/performance.md", content=performance_patterns)
+
+# Troubleshooting
+Write(file_path=".claude/skills/sqlspec-usage/patterns/troubleshooting.md", content=troubleshooting_guide)
+
+print("✓ Created all SQLSpec pattern guides")
+```
+
+### Step 4.6.5: Generate Working Examples
+
+```python
+# Litestar integration example
+Write(file_path=".claude/skills/sqlspec-usage/examples/litestar-integration.py", content=litestar_example)
+
+# FastAPI integration example
+Write(file_path=".claude/skills/sqlspec-usage/examples/fastapi-integration.py", content=fastapi_example)
+
+# Multi-database example
+Write(file_path=".claude/skills/sqlspec-usage/examples/multi-database.py", content=multi_db_example)
+
+# Testing patterns example
+Write(file_path=".claude/skills/sqlspec-usage/examples/testing-patterns.py", content=testing_example)
+
+# Migration workflow shell script
+Write(file_path=".claude/skills/sqlspec-usage/examples/migration-workflow.sh", content=migration_script)
+
+print("✓ Created all SQLSpec example files")
+```
+
+### Step 4.6.6: Detect Project Adapters and Create Adapter Skills
+
+```python
+# Detect which adapters are used in this project
+adapters_used = []
+
+if Grep(pattern=r'from sqlspec.adapters.asyncpg', path='.', output_mode='count') > 0:
+    adapters_used.append("asyncpg")
+if Grep(pattern=r'from sqlspec.adapters.psycopg', path='.', output_mode='count') > 0:
+    adapters_used.append("psycopg")
+if Grep(pattern=r'from sqlspec.adapters.duckdb', path='.', output_mode='count') > 0:
+    adapters_used.append("duckdb")
+if Grep(pattern=r'from sqlspec.adapters.sqlite', path='.', output_mode='count') > 0:
+    adapters_used.append("sqlite")
+if Grep(pattern=r'from sqlspec.adapters.aiosqlite', path='.', output_mode='count') > 0:
+    adapters_used.append("aiosqlite")
+if Grep(pattern=r'from sqlspec.adapters.oracledb', path='.', output_mode='count') > 0:
+    adapters_used.append("oracledb")
+
+print(f"Detected adapters: {', '.join(adapters_used)}")
+
+# Create adapter-specific skills
+for adapter in adapters_used:
+    adapter_skill_content = generate_adapter_skill(adapter)
+    Write(file_path=f".claude/skills/sqlspec-adapters/{adapter}.md", content=adapter_skill_content)
+    print(f"✓ Created .claude/skills/sqlspec-adapters/{adapter}.md")
+
+# Create adapters README
+adapters_readme = '''# SQLSpec Adapter Skills
+
+Adapter-specific guidance for each database adapter used in this project.
+
+## Detected Adapters
+
+''' + '\n'.join([f'- [{adapter}.md]({adapter}.md)' for adapter in adapters_used]) + '''
+
+## Adapter Selection Guide
+
+See main skill documentation for complete adapter comparison.
+'''
+
+Write(file_path=".claude/skills/sqlspec-adapters/README.md", content=adapters_readme)
+print("✓ Created .claude/skills/sqlspec-adapters/README.md")
+```
+
+### Step 4.6.7: Update Agent Files to Reference Skills
+
+```python
+# Add skills reference to expert.md
+expert_skills_section = '''
+**Use SQLSpec skills for guidance:**
+
+```python
+# Main SQLSpec usage skill
+Read(".claude/skills/sqlspec-usage/skill.md")
+
+# Pattern guides
+Read(".claude/skills/sqlspec-usage/patterns/configuration.md")
+Read(".claude/skills/sqlspec-usage/patterns/queries.md")
+Read(".claude/skills/sqlspec-usage/patterns/frameworks.md")
+Read(".claude/skills/sqlspec-usage/patterns/testing.md")
+
+# Adapter-specific skills
+Read(f".claude/skills/sqlspec-adapters/{adapter}.md")
+
+# Working examples
+Read(".claude/skills/sqlspec-usage/examples/litestar-integration.py")
+```
+'''
+
+# Insert into expert.md after guides section
+# (Implementation details...)
+
+# Add skills reference to testing.md
+testing_skills_section = '''
+```python
+Read(".claude/skills/sqlspec-usage/patterns/testing.md")
+Read(".claude/skills/sqlspec-usage/examples/testing-patterns.py")
+```
+'''
+
+# Insert into testing.md
+# (Implementation details...)
+
+print("✓ Updated agent files to reference SQLSpec skills")
+```
+
+### Step 4.6.8: Summary
+
+```python
+print("\n=== SQLSPEC SKILLS CREATED ===\n")
+print("Main skill: .claude/skills/sqlspec-usage/skill.md")
+print("Pattern guides: .claude/skills/sqlspec-usage/patterns/")
+print("Examples: .claude/skills/sqlspec-usage/examples/")
+print(f"Adapter skills: {len(adapters_used)} adapters detected")
+print("\nAgents updated to reference skills automatically.")
+```
+
+---
+
 ## PHASE 5: PROJECT GUIDES CREATION
 
 ### Step 5.1: Create Architecture Guide

sqlspec-0.30.2/.claude/skills/README.md

@@ -0,0 +1,229 @@
+# Claude Skills for SQLSpec
+
+Comprehensive skills library for proper SQLSpec usage, ensuring consistent best practices across all database adapters, frameworks, and use cases.
+
+## Overview
+
+This skills library was created by analyzing:
+
+- **SQLSpec documentation** - Official usage guides
+- **SQLSpec source code** - Implementation patterns and standards
+- **AGENTS.md** - Project-specific conventions
+- **Example projects** - Real-world usage patterns
+
+## Skills Structure
+
+### 1. Main SQLSpec Usage Skill
+
+**Location:** [sqlspec-usage/skill.md](sqlspec-usage/skill.md)
+
+**Purpose:** Primary skill for all SQLSpec-related queries. Provides guidance on:
+
+- Configuration (all adapters)
+- Query execution patterns
+- Framework integration (Litestar, FastAPI, Starlette, Flask)
+- Migration management
+- Testing best practices
+- Performance optimization
+- Multi-database setups
+
+**Activation:** Automatically activates when questions involve SQLSpec configuration, database setup, query execution, or framework integration.
+
+### 2. Pattern Guides
+
+**Location:** `sqlspec-usage/patterns/`
+
+Detailed reference guides for specific SQLSpec usage patterns:
+
+| Guide | Purpose | Key Topics |
+|-------|---------|-----------|
+| [configuration.md](sqlspec-usage/patterns/configuration.md) | Configuration across all adapters | pool_config, driver_features, extension_config, multi-database |
+| [queries.md](sqlspec-usage/patterns/queries.md) | Query execution patterns | Parameter binding, result handling, transactions, type mapping |
+| [frameworks.md](sqlspec-usage/patterns/frameworks.md) | Framework integration | Litestar, FastAPI, Starlette, Flask patterns |
+| [migrations.md](sqlspec-usage/patterns/migrations.md) | Database migrations | CLI commands, hybrid versioning, programmatic control |
+| [testing.md](sqlspec-usage/patterns/testing.md) | Testing best practices | Test isolation, pytest-databases, parallel execution |
+| [performance.md](sqlspec-usage/patterns/performance.md) | Performance optimization | Pooling, caching, batch ops, Arrow integration |
+| [troubleshooting.md](sqlspec-usage/patterns/troubleshooting.md) | Common issues & solutions | Installation, config, query, transaction issues |
+
+### 3. Working Examples
+
+**Location:** `sqlspec-usage/examples/`
+
+Production-ready code examples:
+
+| Example | Description |
+|---------|-------------|
+| [litestar-integration.py](sqlspec-usage/examples/litestar-integration.py) | Complete Litestar + SQLSpec app with multi-database, DI, error handling |
+| [fastapi-integration.py](sqlspec-usage/examples/fastapi-integration.py) | FastAPI integration with dependency injection and type-safe responses |
+| [multi-database.py](sqlspec-usage/examples/multi-database.py) | Multi-database configuration and cross-database queries |
+| [migration-workflow.sh](sqlspec-usage/examples/migration-workflow.sh) | Complete migration workflow with hybrid versioning |
+| [testing-patterns.py](sqlspec-usage/examples/testing-patterns.py) | Pytest testing patterns with isolation and parallel execution |
+
+### 4. Adapter-Specific Skills
+
+**Location:** `sqlspec-adapters/`
+
+Detailed guidance for individual database adapters:
+
+| Adapter | File | Status |
+|---------|------|--------|
+| AsyncPG (PostgreSQL async) | [asyncpg.md](sqlspec-adapters/asyncpg.md) | ✅ Complete |
+| Psycopg (PostgreSQL sync/async) | psycopg.md | 📝 Template |
+| Psqlpy (PostgreSQL Rust-based) | psqlpy.md | 📝 Template |
+| SQLite (sync) | sqlite.md | 📝 Template |
+| AioSQLite (async) | aiosqlite.md | 📝 Template |
+| DuckDB (analytics) | duckdb.md | 📝 Template |
+| Oracle | oracledb.md | 📝 Template |
+| Asyncmy (MySQL async) | asyncmy.md | 📝 Template |
+| BigQuery | bigquery.md | 📝 Template |
+| ADBC (Arrow-native) | adbc.md | 📝 Template |
+
+**Note:** Template adapters follow the AsyncPG structure and can be quickly expanded when needed.
+
+## Usage in Agent Workflow
+
+### Expert Agent
+
+The Expert agent references these skills during implementation:
+
+```python
+# Main skill for overall guidance
+Read(".claude/skills/sqlspec-usage/skill.md")
+
+# Specific pattern guides as needed
+Read(".claude/skills/sqlspec-usage/patterns/configuration.md")
+Read(".claude/skills/sqlspec-usage/patterns/queries.md")
+
+# Adapter-specific guidance
+Read(f".claude/skills/sqlspec-adapters/{adapter}.md")
+
+# Working examples for reference
+Read(".claude/skills/sqlspec-usage/examples/litestar-integration.py")
+```
+
+### Testing Agent
+
+The Testing agent uses testing-specific skills:
+
+```python
+Read(".claude/skills/sqlspec-usage/patterns/testing.md")
+Read(".claude/skills/sqlspec-usage/examples/testing-patterns.py")
+```
+
+## Bootstrap Integration
+
+The `.claude/bootstrap.md` includes automatic skill creation for SQLSpec projects:
+
+**Phase 4.6:** Detects SQLSpec projects and auto-generates:
+
+1. Main SQLSpec skill
+2. All pattern guides
+3. Working examples
+4. Adapter-specific skills for detected adapters
+5. Updates agent files to reference skills
+
+## Anti-Pattern Detection
+
+All skills include sections on anti-patterns to avoid:
+
+- Configuration mistakes (missing pool_config, duplicate session keys)
+- Session management errors (no context managers, mixing sync/async)
+- Query execution issues (SQL injection, wrong parameter style)
+- Framework integration problems (duplicate keys, missing middleware)
+- Testing pitfalls (:memory: with pooling, class-based tests)
+
+## Best Practices Enforcement
+
+Skills enforce SQLSpec best practices:
+
+1. **Always use context managers** for session management
+2. **Store config keys** returned from `add_config()`
+3. **Use parameter binding** (never string concatenation)
+4. **Enable connection pooling** in production
+5. **Use unique session_key values** for multi-database setups
+6. **Close pools on shutdown** with `close_all_pools()`
+7. **Use typed schema mapping** for type safety
+8. **Prefer framework plugins** over manual setup
+9. **Use temp files for SQLite pooling tests**, not `:memory:`
+10. **Define TypedDict for driver_features** in all adapters
+
+## Maintenance
+
+### Adding New Patterns
+
+When new SQLSpec patterns are discovered:
+
+1. Add to relevant pattern guide in `patterns/`
+2. Update main skill.md if it's a major pattern
+3. Add working example if applicable
+4. Update AGENTS.md if it affects project standards
+
+### Expanding Adapter Skills
+
+To expand a template adapter skill:
+
+1. Copy `asyncpg.md` as template
+2. Fill in adapter-specific:
+   - Configuration parameters
+   - Parameter binding style
+   - Adapter-specific features
+   - Performance characteristics
+   - Common issues
+3. Update `sqlspec-adapters/README.md`
+4. Add to main skill.md adapter comparison table
+
+### Knowledge Capture Process
+
+After significant SQLSpec work:
+
+1. **Analyze** what was built for reusable patterns
+2. **Update** relevant pattern guides
+3. **Add examples** if they demonstrate new techniques
+4. **Update** adapter skills if adapter-specific features were used
+5. **Update** AGENTS.md if it affects project conventions
+
+## Real-World Pattern Sources
+
+Skills incorporate patterns from:
+
+- **oracle-vertexai-demo** - Oracle-specific usage, embeddings
+- **postgres-vertexai-demo** - PostgreSQL with vector search
+- **sqlstack** - Multi-framework integration
+- **accelerator** - Production deployment patterns
+
+(Note: Deep analysis of these projects is pending and will enhance skills further)
+
+## Skill Activation
+
+Skills activate automatically when:
+
+- User asks about SQLSpec configuration
+- Database connection issues arise
+- Query execution questions occur
+- Framework integration is discussed
+- Migration management is needed
+- Testing patterns are requested
+- Performance optimization is sought
+- Troubleshooting is required
+
+No manual invocation needed - skills provide context-aware guidance.
+
+## Contributing
+
+To contribute new patterns or improvements:
+
+1. Test pattern in real code
+2. Document in appropriate guide
+3. Add working example if useful
+4. Update this README if structure changes
+5. Submit PR with clear benefit explanation
+
+## Version
+
+**Version:** 1.0.0
+**Created:** November 15, 2025
+**Last Updated:** November 15, 2025
+
+## License
+
+Same as SQLSpec project license.

sqlspec-0.30.2/.claude/skills/sqlspec_adapters/README.md

@@ -0,0 +1,70 @@
+# SQLSpec Adapter Skills
+
+Individual skills for each database adapter with adapter-specific guidance.
+
+## Available Adapter Skills
+
+### PostgreSQL Adapters
+
+- **[asyncpg.md](asyncpg.md)** - AsyncPG (async, high performance)
+- **psycopg.md** - Psycopg (sync/async, feature-rich) - TODO
+- **psqlpy.md** - Psqlpy (Rust-based, extreme performance) - TODO
+
+### SQLite Adapters
+
+- **sqlite.md** - SQLite (sync, embedded) - TODO
+- **aiosqlite.md** - AioSQLite (async, embedded) - TODO
+
+### Analytics & OLAP
+
+- **duckdb.md** - DuckDB (columnar, analytics) - TODO
+
+### Oracle
+
+- **oracledb.md** - Oracle Database (sync/async, enterprise) - TODO
+
+### MySQL/MariaDB
+
+- **asyncmy.md** - Asyncmy (async MySQL) - TODO
+
+### Cloud & Multi-Database
+
+- **bigquery.md** - Google BigQuery (data warehouse) - TODO
+- **adbc.md** - ADBC (Arrow-native, multi-database) - TODO
+
+## Adapter Selection Guide
+
+| Use Case | Recommended Adapter | Skill File |
+|----------|-------------------|-----------|
+| PostgreSQL async | AsyncPG | [asyncpg.md](asyncpg.md) |
+| PostgreSQL sync | Psycopg | psycopg.md |
+| PostgreSQL extreme perf | Psqlpy | psqlpy.md |
+| Embedded database | SQLite or DuckDB | sqlite.md, duckdb.md |
+| Analytics queries | DuckDB | duckdb.md |
+| Oracle enterprise | OracleDB | oracledb.md |
+| MySQL/MariaDB | Asyncmy | asyncmy.md |
+| Cloud data warehouse | BigQuery | bigquery.md |
+| Multi-database | ADBC | adbc.md |
+| Arrow ecosystem | ADBC or DuckDB | adbc.md, duckdb.md |
+
+## Skill Template
+
+Each adapter skill covers:
+
+1. When to use this adapter
+2. Configuration examples
+3. Parameter binding style
+4. Adapter-specific features
+5. Performance optimization
+6. Best practices
+7. Common issues
+8. Real-world examples
+
+## Contributing
+
+To add a new adapter skill:
+
+1. Copy `asyncpg.md` as a template
+2. Fill in adapter-specific details
+3. Add to this README
+4. Link from main skill.md