Typing

Public type aliases, metadata types, and protocol definitions used throughout SQLSpec.

Optional dependency exports

The sqlspec.typing module and its private sqlspec._typing backing module resolve heavy optional-dependency symbols lazily. Importing sqlspec does not import Pydantic, Litestar, PyArrow, pandas, Polars, OpenTelemetry, or Prometheus. Accessing one of their exported symbols imports its dependency on first use and caches the resolved object:

import sqlspec.typing as sqlspec_typing

arrow_table_type = sqlspec_typing.ArrowTable  # Imports PyArrow here.

When an optional dependency is not installed, the same access returns a stable typed shim. Repeated access returns the identical real object or shim, preserving annotation and runtime identity behavior. Features that require the dependency still raise the normal missing-dependency error when enabled.

msgspec remains eager because its core types and conversion functions are used throughout result mapping and serialization. orjson also remains on the existing eager path; both have a small measured import cost compared with the deferred integrations.

Metadata Types

class sqlspec.data_dictionary.ForeignKeyMetadata

Bases: object

Metadata for a foreign key constraint.

__init__(table_name, column_name, referenced_table, referenced_column, constraint_name=None, schema=None, referenced_schema=None)

class sqlspec.data_dictionary.ColumnMetadata

Bases: TypedDict

Metadata for a database column.

class sqlspec.data_dictionary.TableMetadata

Bases: TypedDict

Metadata for a database table.

class sqlspec.data_dictionary.IndexMetadata

Bases: TypedDict

Metadata for a database index.

class sqlspec.data_dictionary.VersionInfo

Bases: object

Parsed database version info.

__init__(major, minor=0, patch=0)

Initialize version info.

Parameters:

• major (int) -- Major version number

• minor (int) -- Minor version number

• patch (int) -- Patch version number

property version_tuple: tuple[int, int, int]

Get version as tuple for comparison.

__str__()

String representation of version info.

Return type:

str

__repr__()

Detailed string representation.

Return type:

str

__eq__(other)

Check version equality.

Return type:

bool

__lt__(other)

Check if this version is less than another.

Return type:

bool

__le__(other)

Check if this version is less than or equal to another.

Return type:

bool

__gt__(other)

Check if this version is greater than another.

Return type:

bool

__ge__(other)

Check if this version is greater than or equal to another.

Return type:

bool

__hash__()

Make VersionInfo hashable based on version tuple.

Return type:

int

Protocols

class sqlspec.typing.DictLike

Bases: Protocol

A protocol for objects that behave like a dictionary for reading.

__init__(*args, **kwargs)

Feature Flags

class sqlspec.data_dictionary.FeatureFlags

Bases: TypedDict

Typed feature flags for data dictionary dialects.

class sqlspec.data_dictionary.FeatureVersions

Bases: TypedDict

Typed feature version requirements for data dictionary dialects.