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

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)

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.

set_observability_runtime(runtime)

Attach an observability runtime used for instrumentation.

Return type:

None

load_sql(*paths)

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)

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

Parameters:

• name (str) – Name for the SQL query.

• sql (str) – Raw SQL content.

• dialect (str | None) – Optional dialect for the SQL statement.

Raises:

ValueError – If query name already exists.

Return type:

None

get_file(path)

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)

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()

List all available query names.

Return type:

list[str]

Returns:

Sorted list of query names.

list_files()

List all loaded file paths.

Return type:

list[str]

Returns:

Sorted list of file paths.

has_query(name)

Check if a query exists.

Parameters:

name (str) – Query name to check.

Return type:

bool

Returns:

True if query exists.

clear_cache()

Clear all cached files and queries.

Return type:

None

clear_file_cache()

Clear the file cache only, keeping loaded queries.

Return type:

None

get_query_text(name)

Get raw SQL text for a query.

Parameters:

name (str) – Query name.

Return type:

str

Returns:

Raw SQL text.

Raises:

SQLFileNotFoundError – If query not found.

get_sql(name)

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.

Raises:

SQLFileNotFoundError – If statement name not found.

SQLFile

class sqlspec.loader.SQLFile

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)

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

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)