Compiler & Splitter¶

from sqlspec.core import (
    CompiledSQL,
    CorrelationExtractor,
    OperationProfile,
    OperationType,
    SQLProcessor,
    is_copy_from_operation,
    is_copy_operation,
    is_copy_to_operation,
    split_sql_script,
)

SQLGlot AST compilation, dialect translation, operation classification (SELECT, INSERT, UPDATE, DELETE, DDL, COPY, COMMAND), comment correlation extraction, and dialect-aware multi-statement script splitting.

SQL Processor & Compiled Output¶

SQLProcessor ¶

SQL processor with compilation and caching.

Processes SQL statements by compiling them into executable format with parameter substitution. Includes LRU-style caching for compilation results to avoid re-processing identical statements.

cache_stats ¶

cache_stats

Get cache statistics.

Returns:

Type	Description
`dict[str, int]`	Dictionary with cache statistics

compile ¶

compile(
    sql, parameters=None, is_many=False, expression=None, param_fingerprint=None
)

Compile SQL statement.

Parameters:

Name	Type	Description	Default
`sql`	`str`	SQL string for compilation	required
`parameters`	`Any`	Parameter values for substitution	`None`
`is_many`	`bool`	Whether this is for execute_many operation	`False`
`expression`	`Expr \| None`	Pre-parsed SQLGlot expression to reuse	`None`
`param_fingerprint`	`Any \| None`	Pre-computed parameter fingerprint.	`None`

Returns:

Type	Description
`CompiledSQL`	CompiledSQL with execution information

clear_cache ¶

clear_cache()

Clear compilation cache and reset statistics.

CompiledSQL ¶

Compiled SQL result.

Contains the result of SQL compilation with information needed for execution. Immutable container holding compiled SQL text, processed parameters, operation type, and execution metadata.

compiled_sql ¶

compiled_sql = compiled_sql

execution_parameters ¶

execution_parameters = execution_parameters

operation_type ¶

operation_type = operation_type

expression ¶

expression = expression

parameter_style ¶

parameter_style = parameter_style

supports_many ¶

supports_many = supports_many

parameter_casts ¶

parameter_casts = parameter_casts or {}

parameter_profile ¶

parameter_profile = parameter_profile or ParameterProfile.empty()

operation_profile ¶

operation_profile = operation_profile or OperationProfile.empty()

input_named_parameters ¶

input_named_parameters = input_named_parameters

applied_wrap_types ¶

applied_wrap_types = applied_wrap_types

OperationProfile ¶

Semantic characteristics derived from the parsed SQL expression.

returns_rows ¶

returns_rows = returns_rows

modifies_rows ¶

modifies_rows = modifies_rows

empty ¶

empty()

OperationType ¶

OperationType = Literal[
    "SELECT",
    "INSERT",
    "UPDATE",
    "DELETE",
    "COPY",
    "COPY_FROM",
    "COPY_TO",
    "EXECUTE",
    "SCRIPT",
    "DDL",
    "PRAGMA",
    "MERGE",
    "COMMAND",
]

Script Splitting & Operation Helpers¶

split_sql_script ¶

split_sql_script(script, dialect=None, strip_trailing_terminator=False)

Split SQL script into individual statements.

Parameters:

Name	Type	Description	Default
`script`	`str`	The SQL script to split	required
`dialect`	`str \| None`	The SQL dialect name	`None`
`strip_trailing_terminator`	`bool`	If True, remove trailing terminators from statements	`False`

Returns:

Type	Description
`list[str]`	List of individual SQL statements

CorrelationExtractor ¶

Extracts correlation IDs from HTTP request headers.

This class provides configurable header extraction with

Configurable primary header (highest priority)
Additional custom headers (middle priority)
Standard trace context headers as fallbacks
Automatic UUID generation when no header found
Input sanitization (max length, whitespace trimming)

The extractor follows a priority order: primary header first, then configured headers, then trace context fallbacks (if enabled).

DEFAULT_HEADERS ¶

DEFAULT_HEADERS = (
    "x-request-id",
    "x-correlation-id",
    "traceparent",
    "x-cloud-trace-context",
    "x-amzn-trace-id",
    "x-b3-traceid",
    "x-client-trace-id",
    "grpc-trace-bin",
)

Default trace context headers to check as fallbacks.

These headers cover

x-request-id: Common request ID header
x-correlation-id: Common correlation ID header
traceparent: W3C Trace Context standard
x-cloud-trace-context: Google Cloud trace header
x-amzn-trace-id: AWS X-Ray trace header
x-b3-traceid: Zipkin B3 propagation
x-client-trace-id: Envoy proxy trace header
grpc-trace-bin: gRPC binary trace header

DEFAULT_MAX_LENGTH ¶

DEFAULT_MAX_LENGTH = 128

Maximum length for correlation IDs to prevent log injection.

headers ¶

headers

Get the ordered list of headers to check.

max_length ¶

max_length

Get the maximum correlation ID length.

extract ¶

extract(get_header)

Extract correlation ID from headers or generate a new one.

Iterates through configured headers in priority order and returns the first non-empty value found. If no header contains a value, generates a new UUID.

Parameters:

Name	Type	Description	Default
`get_header`	`Callable[[str], str \| None]`	A callable that takes a header name (lowercase) and returns the header value or None.	required

Returns:

Type	Description
`str`	The extracted or generated correlation ID.

is_copy_operation ¶

is_copy_operation(operation_type)

Determine if the operation corresponds to any PostgreSQL COPY variant.

Parameters:

Name	Type	Description	Default
`operation_type`	`OperationType`	Operation type detected by the compiler.	required

Returns:

Type	Description
`bool`	True when the operation type represents COPY, COPY FROM, or COPY TO.

is_copy_from_operation ¶

is_copy_from_operation(operation_type)

Check if the operation streams data into the database using COPY.

Parameters:

Name	Type	Description	Default
`operation_type`	`OperationType`	Operation type detected by the compiler.	required

Returns:

Type	Description
`bool`	True for COPY operations that read from client input (COPY FROM).

is_copy_to_operation ¶

is_copy_to_operation(operation_type)

Check if the operation streams data out from the database using COPY.

Parameters:

Name	Type	Description	Default
`operation_type`	`OperationType`	Operation type detected by the compiler.	required

Returns:

Type	Description
`bool`	True for COPY operations that write to client output (COPY TO).