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¶

Register multiple configs on a single SQLSpec instance and use each config handle independently. This pattern works for any combination of sync and async adapters.

multi-database with observability¶

from sqlspec import SQLSpec
from sqlspec.adapters.sqlite import SqliteConfig
from sqlspec.observability import ObservabilityConfig, SamplingConfig

spec = SQLSpec(observability_config=ObservabilityConfig(sampling=SamplingConfig(sample_rate=0.1), print_sql=True))

# Primary database
primary = spec.add_config(SqliteConfig(connection_config={"database": str(tmp_path / "primary.db")}))

# Analytics database
analytics = spec.add_config(SqliteConfig(connection_config={"database": str(tmp_path / "analytics.db")}))

# Load SQL files from multiple directories
sql_dir = tmp_path / "sql"
sql_dir.mkdir()
(sql_dir / "queries.sql").write_text("-- name: list_users\nselect id, name from users order by id;\n")
spec.load_sql_files(sql_dir)

# Use each config independently
with spec.provide_session(primary) as session:
    session.execute("create table users (id integer primary key, name text)")
    session.execute("insert into users (name) values ('Alice')")
    result = session.execute(spec.get_sql("list_users"))
    print(result.all())

with spec.provide_session(analytics) as session:
    session.execute("create table events (id integer primary key, event text)")
    session.execute("insert into events (event) values ('page_view')")
    result = session.execute("select * from events")
    print(result.all())

Key points:

Each add_config() call returns the config handle you pass to provide_session().
ObservabilityConfig on the SQLSpec instance applies to all registered configs.
load_sql_files() accepts multiple paths and loads queries into a shared namespace.