SQL File Loader

Load and cache SQL files with named statement support. SQL files can contain multiple named statements separated by -- name: comments.

SQLFileLoader

class sqlspec.loader.SQLFileLoader[source]

Bases: object

Loads and parses SQL files with named SQL queries.

Loads SQL files containing named queries (using -- name: syntax) and retrieves them by name.

__init__(*, encoding='utf-8', storage_registry=None, runtime=None, strict_parameter_annotations=False)[source]

Initialize the SQL file loader.

Parameters:

  • encoding (str) -- Text encoding for reading SQL files.

  • storage_registry (StorageRegistry | None) -- Storage registry for handling file URIs.

  • runtime (ObservabilityRuntime | None) -- Observability runtime for instrumentation.

  • strict_parameter_annotations (bool) -- When True, a malformed -- param: directive raises instead of emitting a warning and skipping the line.

set_observability_runtime(runtime)[source]

Attach an observability runtime used for instrumentation.

Return type:

None

load_sql(*paths)[source]

Load SQL files and parse named queries.

Parameters:

*paths (str | Path) -- One or more file paths or directory paths to load.

Return type:

None

add_named_sql(name, sql, dialect=None, parameters=None)[source]

Add a named SQL query directly without loading from a file.

Parameters:
Raises:

ValueError -- If query name already exists.

Return type:

None

get_query_parameters(name)[source]

Get declared parameter metadata for a query.

Parameters:

name (str) -- Query name (hyphens are converted to underscores).

Return type:

tuple[ParameterDeclaration, ...]

Returns:

Tuple of declared parameters; empty if the query declares none.

Raises:

SQLStatementNotFoundError -- If the query does not exist.

get_file(path)[source]

Get a loaded SQLFile object by path.

Parameters:

path (str | Path) -- Path of the file.

Return type:

SQLFile | None

Returns:

SQLFile object if loaded, None otherwise.

get_file_for_query(name)[source]

Get the SQLFile object containing a query.

Parameters:

name (str) -- Query name (hyphens are converted to underscores).

Return type:

SQLFile | None

Returns:

SQLFile object if query exists, None otherwise.

list_queries()[source]

List all available query names.

Return type:

list[str]

Returns:

Sorted list of query names.

list_files()[source]

List all loaded file paths.

Return type:

list[str]

Returns:

Sorted list of file paths.

has_query(name)[source]

Check if a query exists.

Parameters:

name (str) -- Query name to check.

Return type:

bool

Returns:

True if query exists.

clear_cache()[source]

Clear all cached files and queries.

Return type:

None

clear_file_cache()[source]

Clear the file cache only, keeping loaded queries.

Return type:

None

get_query_text(name)[source]

Get raw SQL text for a query.

Parameters:

name (str) -- Query name.

Return type:

str

Returns:

Raw SQL text.

get_sql(name)[source]

Get a SQL object by statement name.

Parameters:

name (str) -- Name of the statement (from -- name: in SQL file). Hyphens in names are converted to underscores.

Return type:

SQL

Returns:

SQL object ready for execution.

SQLFile

class sqlspec.loader.SQLFile[source]

Bases: object

Represents a loaded SQL file with metadata.

Contains SQL content and associated metadata including file location, timestamps, and content hash.

__init__(content, path, metadata=None, loaded_at=None)[source]

Initialize SQLFile.

Parameters:

  • content (str) -- Raw SQL content from the file.

  • path (str) -- Path where the SQL file was loaded from.

  • metadata (dict[str, typing.Any] | None) -- Optional metadata associated with the SQL file.

  • loaded_at (datetime | None) -- Timestamp when the file was loaded.

NamedStatement

class sqlspec.loader.NamedStatement[source]

Bases: object

Represents a parsed SQL statement with metadata.

Contains individual SQL statements extracted from files with their normalized names, SQL content, optional dialect specifications, and line position for error reporting.

__init__(name, sql, dialect=None, start_line=0, parameters=())[source]

Declared Parameters

Parameters declared in SQL files via -- param: directives are exposed as ParameterDeclaration objects. See Declared Parameters for the grammar and validation behavior.

class sqlspec.ParameterDeclaration[source]

Bases: object

A single parameter declared in a SQL file header.

__init__(name, type_str, description=None, *, required=True)[source]
sqlspec.register_param_type(name, py_type)[source]

Register or override a declared-type-string matcher.

Parameters:

  • name (str) -- The declared type string as written in -- param: (case-insensitive).

  • py_type (type | tuple[type, ...] | Callable[[object], bool]) -- The Python type, tuple of types, or predicate used for validation.

Return type:

None

sqlspec.resolve_param_type(type_str)[source]

Resolve a declared type string to a matcher, or None if unknown.

Unknown type strings are documentation-only and skipped during validation. The declared string is looked up, never evaluated. Parameterized containers (list[int]) resolve to their origin type (list).

Parameters:

type_str (str) -- The declared type string from a -- param: directive.

Return type:

type | tuple[type, ...] | Callable[[object], bool] | None

Returns:

The resolved matcher, or None when not in the registry.