sqlspec
Use when working with sqlspec, SQLSpec, SQLFileLoader, drivers, query builders, named SQL, filters, pagination, Arrow, framework extensions, ADK stores, or observers. Not for ORM repositories — use advanced-alchemy.
Install
npx skills add https://github.com/litestar-org/litestar-skills/tree/main/skills/sqlspec
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install litestar-org-litestar-skills@llmmart
git clone https://github.com/litestar-org/litestar-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole litestar-org/litestar-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
SQLSpec Skill
SQLSpec is a type-safe SQL query mapper for Python -- NOT an ORM. It provides flexible connectivity with consistent interfaces across its database adapter packages. Write raw SQL, use the builder API, or load SQL from files. Statements pass through a sqlglot-powered AST pipeline for validation, parameter handling, and dialect conversion.
Match-Your-Framework — read first
sqlspec ships first-party extensions for five web frameworks. If your project uses one of these, jump directly to the matching integration guide and skip the others:
- Litestar — register configs on
SQLSpec, then pass that registry toSQLSpecPlugin. The plugin adds DI, thelitestar dbCLI, and request observability. Seereferences/extensions.md. - FastAPI →
references/fastapi-integration.md—Depends(plugin.provide_session())DI,Annotated[...]handlers, filter providers. - Flask →
references/flask-integration.md—plugin.init_app(app), pull-basedplugin.get_session(), async-via-portal. - Starlette →
references/starlette-integration.md—request.state-based session access, lifespan wrapping, middleware variants. - Sanic — first-party ASGI-style extension for Sanic applications; match Sanic's app/request lifecycle instead of copying Litestar DI examples.
Shared topics that apply to every framework live in references/commit-modes.md (autocommit / manual middleware) and references/multi-database.md (multi-config registry). Read the framework guide first, then those for depth.
The rest of this SKILL.md covers framework-agnostic topics: adapter setup, query builder, driver methods, filters, observability, migrations, the ADK extension, and data-dictionary introspection.
Code Style Rules
from __future__ import annotationsrule — SQLSpec adapter config modules and driver definitions avoidfrom __future__ import annotationsbecause configs are introspected at runtime. Consumer application modules (handlers, services, tests that use a configured driver) MAY and typically SHOULD use it — canonical Litestar apps use it in 100+ files.
Quick Reference
Adapter Pattern
from sqlspec import SQLSpec
from sqlspec.adapters.asyncpg import AsyncpgConfig
config = AsyncpgConfig(
connection_config={
"dsn": "postgresql://user:pass@localhost:5432/mydb",
"min_size": 2,
"max_size": 10,
},
)
db_manager = SQLSpec()
db_manager.add_config(config)
async with db_manager.provide_session(config) as db:
users = await db.select(
"SELECT * FROM users WHERE active = $1",
True,
schema_type=User,
)
Query Builder Essentials
from sqlspec import sql
stmt = (
sql.select("id", "name", "email")
.from_("users")
.where_eq("status", "active")
.where("created_at > :since", since=cutoff_date)
.order_by("created_at", desc=True)
.limit(50)
.to_statement()
)
insert_stmt = (
sql.insert("users").columns("name", "email").values(name="Alice", email="alice@example.com").to_statement()
)
merge_stmt = (
sql.merge("inventory", dialect="postgres")
.using("updates")
.on("inventory.product_id = updates.product_id")
.when_matched_then_update(qty="updates.qty")
.when_not_matched_then_insert(product_id="updates.product_id", qty="updates.qty")
.to_statement()
)
Driver Method Summary
| Method | Returns | Use Case |
|---|---|---|
select() / fetch() |
List of rows | Filtered queries, listing |
select_value() |
Single scalar | COUNT(*), MAX(), existence checks |
select_value_or_none() |
Scalar or None |
Optional scalar lookup |
select_one() |
One row (strict) | Get-by-ID, raises NotFoundError |
select_one_or_none() |
One row or None |
Optional lookup |
select_with_total() |
Rows plus total | Pagination |
select_stream() / fetch_stream() |
Context-managed row stream | Bounded row iteration where adapter supports native streaming |
select_to_arrow() / fetch_to_arrow() |
ArrowResult |
Bulk data export, analytics |
select_to_storage() |
StorageBridgeJob |
Export query results to local or cloud storage |
execute() |
SQLResult |
INSERT/UPDATE/DELETE metadata |
execute_many() |
SQLResult |
Batch operation metadata |
execute_script() |
SQLResult |
Multi-statement SQL script execution |
execute_stack() |
tuple[StackResult, ...] |
Ordered statement-stack execution |
load_from_arrow() |
StorageBridgeJob |
Adapter-supported Arrow ingest |
load_from_storage() |
StorageBridgeJob |
Adapter-supported staged-file ingest |
load_from_records() |
StorageBridgeJob |
Records normalized through the Arrow ingest path |
transaction() |
Context manager | Atomic transaction or savepoint scope on a driver |
Arrow Integration Basics
arrow_result = await db.select_to_arrow(
"SELECT * FROM large_dataset WHERE region = $1",
region,
return_format="reader",
batch_size=10_000,
)
await db.load_from_arrow("users", arrow_result)
await db.load_from_records("users", [{"id": 1, "name": "Ada"}])
References Index
Choosing between
sqlspecandadvanced-alchemy:advanced-alchemygives you an opinionated ORM service layer withUUIDAuditBase, lifecycle hooks, repository / service / Alembic integration, andOffsetPagination[T]out of the box — pick it when you want a complete CRUD surface with attribute-style row access and you're happy inside the SQLAlchemy ecosystem.sqlspecgives you direct SQL control, first-party database adapter packages (asyncpg, oracledb, Db2, Sybase ASE, SQL Anywhere, DuckDB, BigQuery, Spanner, SQLite, and more), Arrow result paths for analytics, and a builder API when you need it — pick it when you want explicit SQL, heterogeneous database backends, or Arrow integration. Both skills integrate with Litestar via first-party plugins; see../advanced-alchemy/SKILL.mdfor the ORM path.
For detailed instructions, patterns, and API guides, refer to the following documents:
Standards & Style
- Code Quality & Mypyc -- Type annotation rules, import standards, test structure.
Core Utilities
- SQLglot Best Practices -- v30+ guardrails, AST manipulation,
copy=Falsepattern.
Architecture & Performance
- Architecture & Caching -- Core data flow, global cache configuration, namespaces,
StatementCacheHolder, and zero-copy AST sharing. - Performance & Cloud Controls -- Bounded async bridge, cache/fetch tuning, BigQuery job controls, Spanner sync/async session controls.
- Data Dictionary -- Dialect feature flags, runtime introspection (
get_tables,get_columns,get_indexes), Spanner Property Graph/Change Stream metadata, ADBC native metadata/statistics.
Query Building & Execution
- Query Builder API --
sqlfactory: select, insert, update, delete, merge. - Driver Method Reference --
select(),select_one(),select_stream(),select_to_arrow(), load methods. - Filter & Pagination System --
LimitOffsetFilter,OrderByFilter,SearchFilter.
Data Integration
- Arrow & ADBC Integration --
select_to_arrow()formats, Arrow-native paths, conversion fallbacks. - Native Bulk Ingest --
load_from_arrow(),load_from_storage(),load_from_records(), adapter gates. - SQL File Loading --
SQLFileLoaderwith search paths, metadata directives.
Adapters & Drivers
- Adapter & Driver Registry -- Full adapter registry with dialects and parameter styles.
Framework & Storage Integrations
- Framework Extensions -- Litestar plugin, FastAPI/Starlette integration.
- Storage Integration -- ADK store, Litestar session stores, event channel backends.
- Event Channels (Pub/Sub) --
AsyncEventChannel, subscribe/publish patterns. - ADK Extension -- ADK 2 session/memory/artifact stores, scoped state, Spanner hybrid vector/FTS/RRF & Property Graph memory.
Migrations & Schema
- Native Migration Runner -- standalone
sqlspecCLI, timestamp versioning,ddl_migrationstracker, extension migrations, and Litestarlitestar dbintegration.
Observability
- Observability & Tracing -- Telemetry semantics, correlation extraction.
Advanced Patterns
- Design Patterns -- Service layer, batch operations, upsert, AST tenant filters.
- Service Patterns -- SQLSpecAsyncService base, named SQL templates via db_manager.get_sql, direct driver API (select_value / select_one / execute), variadic filter composition, create_filter_dependencies() wiring.
- Dishka Integration -- FromDishka as Inject alias, multi-provider pattern (REQUEST-scoped domain services, REQUEST-scoped driver, APP-scoped singletons), handler injection.
- Vector Search — Oracle VECTOR_DISTANCE cosine similarity, Vertex AI embedding generation, SHA256-keyed embedding cache, intent classification via exemplar similarity, pgvector cross-reference.
Key Resources
- SQLglot Docs: https://sqlglot.com/sqlglot.html
- SQLglot GitHub: https://github.com/tobymao/sqlglot
- Mypyc Docs: https://mypyc.readthedocs.io/
- PyArrow Docs: https://arrow.apache.org/docs/python/
Official References
Shared Styleguide Baseline
- Use shared styleguides for generic language/framework rules to reduce duplication in this skill.
- General Principles
- Python
- Litestar
- Keep this skill focused on tool-specific workflows, edge cases, and integration details.
Files (litestar-skills)
-
references
-
adapters.md 19 KB
Loading… -
adk.md 13.5 KB
Loading… -
architecture.md 4.2 KB
Loading… -
arrow.md 4.3 KB
Loading… -
bulk-ingest.md 5.1 KB
Loading… -
commit-modes.md 9 KB
Loading… -
data-dictionary.md 6.3 KB
Loading… -
dishka-integration.md 13 KB
Loading… -
driver_api.md 11 KB
Loading… -
events.md 6.8 KB
Loading… -
extensions.md 7.1 KB
Loading… -
fastapi-integration.md 24.7 KB
Loading… -
filters.md 8.7 KB
Loading… -
flask-integration.md 21.2 KB
Loading… -
loader.md 7.5 KB
Loading… -
migrations.md 12.7 KB
Loading… -
multi-database.md 15.6 KB
Loading… -
observability.md 16.1 KB
Loading… -
patterns.md 7.3 KB
Loading… -
performance.md 7.2 KB
Loading… -
query_builder.md 11 KB
Loading… -
service-patterns.md 15.8 KB
Loading… -
sqlglot.md 2.6 KB
Loading… -
standards.md 5.4 KB
Loading… -
starlette-integration.md 18 KB
Loading… -
storage.md 5.3 KB
Loading… -
vector-search.md 11.8 KB
Loading…
-
-
SKILL.md 17.8 KB
--- name: sqlspec description: "Use when working with sqlspec, SQLSpec, SQLFileLoader, drivers, query builders, named SQL, filters, pagination, Arrow, framework extensions, ADK stores, or observers. Not for ORM repositories — use advanced-alchemy." --- # SQLSpec Skill SQLSpec is a **type-safe SQL query mapper for Python** -- NOT an ORM. It provides flexible connectivity with consistent interfaces across its database adapter packages. Write raw SQL, use the builder API, or load SQL from files. Statements pass through a sqlglot-powered AST pipeline for validation, parameter handling, and dialect conversion. ## Match-Your-Framework — read first sqlspec ships first-party extensions for five web frameworks. If your project uses one of these, **jump directly to the matching integration guide and skip the others**: - **Litestar** — register configs on `SQLSpec`, then pass that registry to `SQLSpecPlugin`. The plugin adds DI, the `litestar db` CLI, and request observability. See [`references/extensions.md`](references/extensions.md). - **FastAPI** → [`references/fastapi-integration.md`](references/fastapi-integration.md) — `Depends(plugin.provide_session())` DI, `Annotated[...]` handlers, filter providers. - **Flask** → [`references/flask-integration.md`](references/flask-integration.md) — `plugin.init_app(app)`, pull-based `plugin.get_session()`, async-via-portal. - **Starlette** → [`references/starlette-integration.md`](references/starlette-integration.md) — `request.state`-based session access, lifespan wrapping, middleware variants. - **Sanic** — first-party ASGI-style extension for Sanic applications; match Sanic's app/request lifecycle instead of copying Litestar DI examples. Shared topics that apply to every framework live in [`references/commit-modes.md`](references/commit-modes.md) (autocommit / manual middleware) and [`references/multi-database.md`](references/multi-database.md) (multi-config registry). Read the framework guide first, then those for depth. The rest of this SKILL.md covers framework-agnostic topics: adapter setup, query builder, driver methods, filters, observability, migrations, the ADK extension, and data-dictionary introspection. ## Code Style Rules - **`from __future__ import annotations` rule** — SQLSpec adapter config modules and driver definitions avoid `from __future__ import annotations` because configs are introspected at runtime. Consumer application modules (handlers, services, tests that *use* a configured driver) MAY and typically SHOULD use it — canonical Litestar apps use it in 100+ files. ## Quick Reference ### Adapter Pattern ```python from sqlspec import SQLSpec from sqlspec.adapters.asyncpg import AsyncpgConfig config = AsyncpgConfig( connection_config={ "dsn": "postgresql://user:pass@localhost:5432/mydb", "min_size": 2, "max_size": 10, }, ) db_manager = SQLSpec() db_manager.add_config(config) async with db_manager.provide_session(config) as db: users = await db.select( "SELECT * FROM users WHERE active = $1", True, schema_type=User, ) ``` ### Query Builder Essentials ```python from sqlspec import sql stmt = ( sql.select("id", "name", "email") .from_("users") .where_eq("status", "active") .where("created_at > :since", since=cutoff_date) .order_by("created_at", desc=True) .limit(50) .to_statement() ) insert_stmt = ( sql.insert("users").columns("name", "email").values(name="Alice", email="alice@example.com").to_statement() ) merge_stmt = ( sql.merge("inventory", dialect="postgres") .using("updates") .on("inventory.product_id = updates.product_id") .when_matched_then_update(qty="updates.qty") .when_not_matched_then_insert(product_id="updates.product_id", qty="updates.qty") .to_statement() ) ``` ### Driver Method Summary | Method | Returns | Use Case | | --- | --- | --- | | `select()` / `fetch()` | List of rows | Filtered queries, listing | | `select_value()` | Single scalar | `COUNT(*)`, `MAX()`, existence checks | | `select_value_or_none()` | Scalar or `None` | Optional scalar lookup | | `select_one()` | One row (strict) | Get-by-ID, raises `NotFoundError` | | `select_one_or_none()` | One row or `None` | Optional lookup | | `select_with_total()` | Rows plus total | Pagination | | `select_stream()` / `fetch_stream()` | Context-managed row stream | Bounded row iteration where adapter supports native streaming | | `select_to_arrow()` / `fetch_to_arrow()` | `ArrowResult` | Bulk data export, analytics | | `select_to_storage()` | `StorageBridgeJob` | Export query results to local or cloud storage | | `execute()` | `SQLResult` | INSERT/UPDATE/DELETE metadata | | `execute_many()` | `SQLResult` | Batch operation metadata | | `execute_script()` | `SQLResult` | Multi-statement SQL script execution | | `execute_stack()` | `tuple[StackResult, ...]` | Ordered statement-stack execution | | `load_from_arrow()` | `StorageBridgeJob` | Adapter-supported Arrow ingest | | `load_from_storage()` | `StorageBridgeJob` | Adapter-supported staged-file ingest | | `load_from_records()` | `StorageBridgeJob` | Records normalized through the Arrow ingest path | | `transaction()` | Context manager | Atomic transaction or savepoint scope on a driver | ### Arrow Integration Basics ```python arrow_result = await db.select_to_arrow( "SELECT * FROM large_dataset WHERE region = $1", region, return_format="reader", batch_size=10_000, ) await db.load_from_arrow("users", arrow_result) await db.load_from_records("users", [{"id": 1, "name": "Ada"}]) ``` <workflow> ## Workflow ### Step 1: Choose Adapter and Pattern | Need | Adapter | Key Feature | | --- | --- | --- | | PostgreSQL async | `asyncpg`, `psycopg` | Async, NUMERIC/PYFORMAT params, auto-probed `pgvector` / `pg_textsearch` / `paradedb` | | PostgreSQL sync | `psycopg` | Sync+async, PYFORMAT params | | SQLite | `sqlite`, `aiosqlite` | QMARK params, local dev | | DuckDB analytics | `duckdb` | Arrow-native OLAP, extension load/install lifecycle, direct object-store transfer | | Arrow / multi-engine ETL | `adbc` | Arrow-native ingest/export across DuckDB, PostgreSQL, BigQuery, Flight SQL, GizmoSQL, Quack, Oracle, and Db2 | | MySQL async | `asyncmy` | PYFORMAT params | | Oracle | `oracledb` | NAMED_COLON params, sync+async | | IBM Db2 | `db2` | QMARK params, sync+async via `ibm_db`, `SYSCAT` catalog reflection | | SQL Server / Sybase / SQL Anywhere | `mssql_python`, `pymssql`, `sybase`, `sqlanywhere` | T-SQL (`tsql`), Sybase ASE (`sybase`), and SAP SQL Anywhere (`sqlanywhere`) dialects | | BigQuery / Spanner | `bigquery`, `spanner` | NAMED_AT params, cloud job/session controls, Spanner sync+async drivers, Property Graph & Vector/Search index AST | | Raw SQL strings | Driver methods | `select()`, `execute()` | | Dynamic queries | Query builder | `sql.select()...to_statement()`, `sql.update()...from_()`, `sql.upsert()` | | SQL from files | `SQLFileLoader` | Metadata directives, `-- param:`, `-- fragment:`, `/* include: */`, `/* slot: */`, caching | | High-volume ingest/export | Storage bridge | Check the adapter matrix before selecting `load_from_arrow()`, `load_from_storage()`, `load_from_records()`, or `select_to_storage()` | ### Step 2: Implement 1. Configure the adapter with connection details (standardized aliases like `dsn`/`url`/`conninfo`, `database`/`dbname`, `user`/`username` normalize automatically) and pool settings 2. Register the config with `SQLSpec.add_config()` and use `SQLSpec.provide_session(config)` or config-backed `SQLSpecAsyncService(config=..., loader=...)` for connection lifecycle 3. Choose the appropriate driver method for your query shape 4. Use `schema_type` parameter for typed results (msgspec Structs, dataclasses, or Pydantic models) 5. Apply filters with `LimitOffsetFilter`, `CursorFilter`, `OrderByFilter`, `SearchFilter`, `BeforeAfterFilter`, or `InCollectionFilter` 6. Use `select_stream(..., native_only=True)` when bounded-memory streaming is mandatory 7. Check adapter ingest capabilities, then use `load_from_records()`, `load_from_arrow()`, `load_from_storage()`, or `select_to_storage()` for high-volume data movement ### Step 3: Validate Run through the validation checkpoint below before considering the work complete. </workflow> <guardrails> ## Guardrails - **Always use typed adapters**: import the specific adapter config, not generic base classes - **Always use `schema_type`** for query results -- get typed objects, not raw dicts - **Always use context managers** for driver lifecycle -- `async with db_manager.provide_session(config) as db:` or `async with service.provide_session() as db:` - **Prefer the query builder** for complex dynamic queries -- avoids string concatenation, handles dialect conversion - **Prefer `SQLFileLoader`** for static queries -- keeps SQL out of Python, supports reusable `-- fragment:` / `/* include: */` blocks and validated `/* slot: */` splicing, and reuses the global file-cache namespace - **Use `-- param:` declarations for named SQL files that cross service boundaries** -- load-time and execute-time validation catches name drift and required parameter omissions - **Use `native_only=True` for streaming or Arrow paths only when fallback is unacceptable** -- unsupported adapters otherwise use eager row conversion - **Pass regular query bind values as positional arguments** -- `await db.select("... WHERE id = $1", user_id, schema_type=User)`, not `await db.select(..., [user_id], ...)` - **Never concatenate SQL strings** -- use parameterized queries, query builder expressions, or declared `/* slot: <name> */` fragments - **Never hold connections outside context managers** -- connection leaks exhaust the pool; prefer config-backed services (`SQLSpecAsyncService(config=...)`) when operations should hold a connection only for the duration of a single query or `begin_transaction()` block - **Match parameter style to adapter**: `$1` for asyncpg, `%s` for psycopg, `?` for sqlite/duckdb/db2, `:name` for oracledb - **Cloud adapter controls** -- BigQuery job controls live in `driver_features`; Spanner request controls live in `driver_features` or `provide_session()` kwargs - **Adapter config / driver modules avoid `from __future__ import annotations`**. Consumer app modules MAY use it. </guardrails> <validation> ### Validation Checkpoint Before delivering SQLSpec code, verify: - [ ] Adapter config uses the correct import path (`sqlspec.adapters.<name>`) - [ ] Connection lifecycle uses `SQLSpec.provide_session(config)` or `service.provide_session()` context manager - [ ] Parameter style matches the adapter (see adapter registry table) - [ ] Query results use `schema_type` for type-safe mapping - [ ] Complex dynamic queries use the builder API or declared SQL slots, not string concatenation - [ ] Filters use SQLSpec filter objects (`LimitOffsetFilter`, `CursorFilter`, `OrderByFilter`, etc.) not manual LIMIT/OFFSET - [ ] Dishka-first Litestar apps that disable SQLSpec DI set `extension_config={"litestar": {"disable_di": True, "manage_lifespan": True}}` when `SQLSpecPlugin` should still manage pool lifespan - [ ] Streaming code uses context managers and sets `native_only=True` when eager fallback would be a bug - [ ] Bulk ingest/export code checks the adapter matrix before using `load_from_arrow()`, `load_from_storage()`, `load_from_records()`, or `select_to_storage()` - [ ] ADK stores are selected from supported adapter `adk` packages; BigQuery is not an OLTP live-agent ADK backend </validation> <example> ## Example **Task:** "Set up an asyncpg adapter, define a typed model, and execute a parameterized query with pagination." ```python from dataclasses import dataclass from sqlspec import SQLSpec from sqlspec.adapters.asyncpg import AsyncpgConfig from sqlspec.core.filters import LimitOffsetFilter, OrderByFilter @dataclass class User: id: int name: str email: str active: bool config = AsyncpgConfig( connection_config={ "dsn": "postgresql://user:pass@localhost:5432/mydb", "min_size": 2, "max_size": 10, }, ) db_manager = SQLSpec() db_manager.add_config(config) async def list_active_users(page: int = 1, page_size: int = 25) -> list[User]: filters = [ OrderByFilter(field_name="name", sort_order="asc"), LimitOffsetFilter(limit=page_size, offset=(page - 1) * page_size), ] async with db_manager.provide_session(config) as db: users = await db.select( "SELECT id, name, email, active FROM users WHERE active = $1", True, *filters, schema_type=User, ) return users async def get_user_count() -> int: async with db_manager.provide_session(config) as db: count = await db.select_value("SELECT COUNT(*) FROM users WHERE active = $1", True) return count ``` </example> ## References Index > **Choosing between `sqlspec` and `advanced-alchemy`:** `advanced-alchemy` gives you an opinionated ORM service layer with `UUIDAuditBase`, lifecycle hooks, repository / service / Alembic integration, and `OffsetPagination[T]` out of the box — pick it when you want a complete CRUD surface with attribute-style row access and you're happy inside the SQLAlchemy ecosystem. `sqlspec` gives you direct SQL control, first-party database adapter packages (asyncpg, oracledb, Db2, Sybase ASE, SQL Anywhere, DuckDB, BigQuery, Spanner, SQLite, and more), Arrow result paths for analytics, and a builder API when you need it — pick it when you want explicit SQL, heterogeneous database backends, or Arrow integration. Both skills integrate with Litestar via first-party plugins; see [`../advanced-alchemy/SKILL.md`](../advanced-alchemy/SKILL.md) for the ORM path. For detailed instructions, patterns, and API guides, refer to the following documents: ### Standards & Style - **[Code Quality & Mypyc](references/standards.md)** -- Type annotation rules, import standards, test structure. ### Core Utilities - **[SQLglot Best Practices](references/sqlglot.md)** -- v30+ guardrails, AST manipulation, `copy=False` pattern. ### Architecture & Performance - **[Architecture & Caching](references/architecture.md)** -- Core data flow, global cache configuration, namespaces, `StatementCacheHolder`, and zero-copy AST sharing. - **[Performance & Cloud Controls](references/performance.md)** -- Bounded async bridge, cache/fetch tuning, BigQuery job controls, Spanner sync/async session controls. - **[Data Dictionary](references/data-dictionary.md)** -- Dialect feature flags, runtime introspection (`get_tables`, `get_columns`, `get_indexes`), Spanner Property Graph/Change Stream metadata, ADBC native metadata/statistics. ### Query Building & Execution - **[Query Builder API](references/query_builder.md)** -- `sql` factory: select, insert, update, delete, merge. - **[Driver Method Reference](references/driver_api.md)** -- `select()`, `select_one()`, `select_stream()`, `select_to_arrow()`, load methods. - **[Filter & Pagination System](references/filters.md)** -- `LimitOffsetFilter`, `OrderByFilter`, `SearchFilter`. ### Data Integration - **[Arrow & ADBC Integration](references/arrow.md)** -- `select_to_arrow()` formats, Arrow-native paths, conversion fallbacks. - **[Native Bulk Ingest](references/bulk-ingest.md)** -- `load_from_arrow()`, `load_from_storage()`, `load_from_records()`, adapter gates. - **[SQL File Loading](references/loader.md)** -- `SQLFileLoader` with search paths, metadata directives. ### Adapters & Drivers - **[Adapter & Driver Registry](references/adapters.md)** -- Full adapter registry with dialects and parameter styles. ### Framework & Storage Integrations - **[Framework Extensions](references/extensions.md)** -- Litestar plugin, FastAPI/Starlette integration. - **[Storage Integration](references/storage.md)** -- ADK store, Litestar session stores, event channel backends. - **[Event Channels (Pub/Sub)](references/events.md)** -- `AsyncEventChannel`, subscribe/publish patterns. - **[ADK Extension](references/adk.md)** -- ADK 2 session/memory/artifact stores, scoped state, Spanner hybrid vector/FTS/RRF & Property Graph memory. ### Migrations & Schema - **[Native Migration Runner](references/migrations.md)** -- standalone `sqlspec` CLI, timestamp versioning, `ddl_migrations` tracker, extension migrations, and Litestar `litestar db` integration. ### Observability - **[Observability & Tracing](references/observability.md)** -- Telemetry semantics, correlation extraction. ### Advanced Patterns - **[Design Patterns](references/patterns.md)** -- Service layer, batch operations, upsert, AST tenant filters. - **[Service Patterns](references/service-patterns.md)** -- SQLSpecAsyncService base, named SQL templates via db_manager.get_sql, direct driver API (select_value / select_one / execute), variadic filter composition, create_filter_dependencies() wiring. - **[Dishka Integration](references/dishka-integration.md)** -- FromDishka as Inject alias, multi-provider pattern (REQUEST-scoped domain services, REQUEST-scoped driver, APP-scoped singletons), handler injection. - **[Vector Search](references/vector-search.md)** — Oracle VECTOR_DISTANCE cosine similarity, Vertex AI embedding generation, SHA256-keyed embedding cache, intent classification via exemplar similarity, pgvector cross-reference. ## Key Resources - **SQLglot Docs**: <https://sqlglot.com/sqlglot.html> - **SQLglot GitHub**: <https://github.com/tobymao/sqlglot> - **Mypyc Docs**: <https://mypyc.readthedocs.io/> - **PyArrow Docs**: <https://arrow.apache.org/docs/python/> ## Official References - <https://sqlspec.dev/> - <https://sqlspec.dev/changelog/> - <https://github.com/litestar-org/sqlspec> ## Shared Styleguide Baseline - Use shared styleguides for generic language/framework rules to reduce duplication in this skill. - [General Principles](../litestar-styleguide/references/general.md) - [Python](../litestar-styleguide/references/python.md) - [Litestar](../litestar-styleguide/references/litestar.md) - Keep this skill focused on tool-specific workflows, edge cases, and integration details.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.