Configuration

SQLSpec configuration is centered around adapter-specific config objects. Each config captures connection parameters, optional pooling settings, and extension-specific options for framework integrations.

Core Configuration

basic configuration
from sqlspec import SQLSpec
from sqlspec.adapters.sqlite import SqliteConfig
from sqlspec.core import StatementConfig

db_path = tmp_path / "app.db"
statement_config = StatementConfig(enable_validation=False)

spec = SQLSpec()
primary = spec.add_config(
    SqliteConfig(connection_config={"database": str(db_path)}, statement_config=statement_config)
)

with spec.provide_session(primary) as session:
    session.execute("create table if not exists health (id integer primary key, ok bool)")
    result = session.execute("select * from health")
    print(result.all())

Pooling and Connections

  • Sync adapters expose provide_session() and provide_connection() context managers.

  • Async adapters expose async context managers with the same method names.

  • Drivers with pooling support provide create_pool() and get_pool() helpers.

Extension Settings

Use extension_config to pass framework- or extension-specific settings. Each extension documents its available keys. Example keys include session key names, commit mode, correlation middleware, and migrations toggles.

Multiple Databases

Use SQLSpec.add_config(..., name="analytics") to register multiple configs on a single registry. Each framework integration can target a specific bind key or session key.