SQLSpec Registry¶

from sqlspec import SQLSpec

Central registry for database configurations, connection pools, driver sessions, named SQL file loading, and global statement cache controls. See Quickstart and Configuration for usage guides.

Registry Class¶

SQLSpec ¶

Configuration manager and registry for database connections and pools.

init ¶

__init__(*, loader=None, observability_config=None)

add_config ¶

add_config(config)

Add a configuration instance to the registry.

Parameters:

Name	Type	Description	Default
`config`	`SyncConfigT \| AsyncConfigT`	The configuration instance to add.	required

Returns:

Type	Description
`SyncConfigT \| AsyncConfigT`	The same configuration instance (it IS the handle).

get_connection ¶

get_connection(config)

Get a database connection for the specified configuration.

Parameters:

Name	Type	Description	Default
`config`	`NoPoolSyncConfig[ConnectionT, DriverT] \| SyncDatabaseConfig[ConnectionT, PoolT, DriverT] \| NoPoolAsyncConfig[ConnectionT, DriverT] \| AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]`	The configuration instance.	required

Returns:

Type	Description
`ConnectionT \| Awaitable[ConnectionT]`	A database connection or an awaitable yielding a connection.

get_session ¶

get_session(config)

Get a database session (driver adapter) for the specified configuration.

Parameters:

Name	Type	Description	Default
`config`	`NoPoolSyncConfig[ConnectionT, DriverT] \| SyncDatabaseConfig[ConnectionT, PoolT, DriverT] \| NoPoolAsyncConfig[ConnectionT, DriverT] \| AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]`	The configuration instance.	required

Returns:

Type	Description
`DriverT \| Awaitable[DriverT]`	A driver adapter instance or an awaitable yielding one.

provide_connection ¶

provide_connection(config, *args, **kwargs)

Create and provide a database connection from the specified configuration.

Parameters:

Name	Type	Description	Default
`config`	`NoPoolSyncConfig[ConnectionT, DriverT] \| SyncDatabaseConfig[ConnectionT, PoolT, DriverT] \| NoPoolAsyncConfig[ConnectionT, DriverT] \| AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]`	The configuration instance.	required
`*args`	`Any`	Positional arguments to pass to the config's provide_connection.	`()`
`**kwargs`	`Any`	Keyword arguments to pass to the config's provide_connection.	`{}`

Returns:

Type	Description
`AbstractContextManager[ConnectionT] \| AbstractAsyncContextManager[ConnectionT]`	A sync or async context manager yielding a connection.

provide_session ¶

provide_session(config, *args, **kwargs)

Create and provide a database session from the specified configuration.

Parameters:

Name	Type	Description	Default
`config`	`NoPoolSyncConfig[ConnectionT, DriverT] \| SyncDatabaseConfig[ConnectionT, PoolT, DriverT] \| NoPoolAsyncConfig[ConnectionT, DriverT] \| AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]`	The configuration instance.	required
`*args`	`Any`	Positional arguments to pass to the config's provide_session.	`()`
`**kwargs`	`Any`	Keyword arguments to pass to the config's provide_session.	`{}`

Returns:

Type	Description
`AbstractContextManager[DriverT] \| AbstractAsyncContextManager[DriverT]`	A sync or async context manager yielding a driver adapter instance.

get_pool ¶

get_pool(config)

Get the connection pool for the specified configuration.

Parameters:

Name	Type	Description	Default
`config`	`NoPoolSyncConfig[ConnectionT, DriverT] \| NoPoolAsyncConfig[ConnectionT, DriverT] \| SyncDatabaseConfig[ConnectionT, PoolT, DriverT] \| AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]`	The configuration instance.	required

Returns:

Type	Description
`type[PoolT] \| Awaitable[type[PoolT]] \| None`	The connection pool, an awaitable yielding the pool, or None if not supported.

close_pool ¶

close_pool(config)

Close the connection pool for the specified configuration.

Parameters:

Name	Type	Description	Default
`config`	`NoPoolSyncConfig[ConnectionT, DriverT] \| SyncDatabaseConfig[ConnectionT, PoolT, DriverT] \| NoPoolAsyncConfig[ConnectionT, DriverT] \| AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]`	The configuration instance.	required

Returns:

Type	Description
`Awaitable[None] \| None`	None, or an awaitable if closing an async pool.

close_all_pools ¶

close_all_pools()

Explicitly close all connection pools (async and sync).

This method should be called before application shutdown for proper cleanup.

event_channel ¶

event_channel(config)

Create an event channel for the provided configuration.

Returns SyncEventChannel for sync configs, AsyncEventChannel for async configs.

Parameters:

Name	Type	Description	Default
`config`	`type[SyncConfigT \| AsyncConfigT] \| SyncDatabaseConfig[Any, Any, Any] \| NoPoolSyncConfig[Any, Any] \| AsyncDatabaseConfig[Any, Any, Any] \| NoPoolAsyncConfig[Any, Any]`	A registered database configuration instance or type.	required

Returns:

Type	Description
`SyncEventChannel \| AsyncEventChannel`	The appropriate event channel type for the configuration.

telemetry_snapshot ¶

telemetry_snapshot()

Return aggregated diagnostics across all registered configurations.

load_sql_files ¶

load_sql_files(*paths)

Load SQL files from paths or directories.

Parameters:

Name	Type	Description	Default
`*paths`	`str \| Path`	One or more file paths or directory paths to load.	`()`

add_named_sql ¶

add_named_sql(name, sql, dialect=None, parameters=None)

Add a named SQL query directly.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name for the SQL query.	required
`sql`	`str`	Raw SQL content.	required
`dialect`	`str \| None`	Optional dialect for the SQL statement.	`None`
`parameters`	`Sequence[ParameterDeclaration] \| None`	Optional declared parameter metadata for the query.	`None`

get_sql ¶

get_sql(name, **slots)

Get a SQL object by name, filling its slots.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the statement from SQL file comments. Hyphens in names are converted to underscores.	required
`**slots`	`Any`	Values for the statement's `/* slot: name */` markers: a `str`, a sqlglot expression, or a `SQL` object whose named parameters are bound.	`{}`

Returns:

Type	Description
`SQL`	SQL object ready for execution.

list_sql_queries ¶

list_sql_queries()

List all available query names.

Returns:

Type	Description
`list[str]`	Sorted list of query names.

has_sql_query ¶

has_sql_query(name)

Check if a SQL query exists.

Parameters:

Name	Type	Description	Default
`name`	`str`	Query name to check.	required

Returns:

Type	Description
`bool`	True if the query exists in the loader.

clear_sql_cache ¶

clear_sql_cache()

Clear the SQL file cache.

reload_sql_files ¶

reload_sql_files(*, reload=False)

Reload all SQL files.

Parameters:

Name	Type	Description	Default
`reload`	`bool`	Reload currently tracked files after clearing the cache.	`False`

configure_cache ¶

configure_cache(
    *,
    sql_cache_size=None,
    fragment_cache_size=None,
    optimized_cache_size=None,
    compiled_cache_enabled=None,
    sql_cache_enabled=None,
    fragment_cache_enabled=None,
    optimized_cache_enabled=None,
)

Update cache configuration with partial values.

Parameters:

Name	Type	Description	Default
`sql_cache_size`	`int \| None`	Size of the statement/builder cache.	`None`
`fragment_cache_size`	`int \| None`	Size of the expression/parameter/file cache.	`None`
`optimized_cache_size`	`int \| None`	Size of the optimized expression cache.	`None`
`compiled_cache_enabled`	`bool \| None`	Master switch for namespaced and compiled SQL caches.	`None`
`sql_cache_enabled`	`bool \| None`	Enable/disable statement and builder cache.	`None`
`fragment_cache_enabled`	`bool \| None`	Enable/disable expression/parameter/file cache.	`None`
`optimized_cache_enabled`	`bool \| None`	Enable/disable optimized expression cache.	`None`

get_cache_config ¶

get_cache_config()

Get the current global cache configuration.

Returns:

Type	Description
`CacheConfig`	The current cache configuration.

update_cache_config ¶

update_cache_config(config)

Update the global cache configuration.

Parameters:

Name	Type	Description	Default
`config`	`CacheConfig`	The new cache configuration to apply.	required

get_cache_stats ¶

get_cache_stats()

Get current cache statistics.

Returns:

Type	Description
`dict[str, Any]`	Cache statistics object with detailed metrics.

reset_stats_only ¶

reset_stats_only()

Reset cache statistics without clearing cached data.

log_cache_stats ¶

log_cache_stats()

Log current cache statistics using the configured logger.

SQLSpec Registry¶

Registry Class¶

SQLSpec ¶

__init__ ¶

add_config ¶

get_connection ¶

get_session ¶

provide_connection ¶

provide_session ¶

get_pool ¶

close_pool ¶

close_all_pools ¶

event_channel ¶

telemetry_snapshot ¶

load_sql_files ¶

add_named_sql ¶

get_sql ¶

list_sql_queries ¶

has_sql_query ¶

clear_sql_cache ¶

reload_sql_files ¶

configure_cache ¶

get_cache_config ¶

update_cache_config ¶

get_cache_stats ¶

reset_stats_only ¶

log_cache_stats ¶

init ¶