Protocols¶

from sqlspec.protocols import (
    AsyncDataDictionaryProtocol,
    CursorMetadataProtocol,
    ObjectStoreProtocol,
    PipelineCapableProtocol,
    QueryResultProtocol,
    SQLBuilderProtocol,
    StatementProtocol,
    SupportsArrowResults,
    SyncDataDictionaryProtocol,
)

Runtime-checkable structural Protocol definitions used across SQLSpec for static type checking and isinstance() narrowing.

Statement & Builder Protocols¶

StatementProtocol ¶

Bases: Protocol

Protocol for statement attribute access.

SQLBuilderProtocol ¶

Bases: Protocol

Protocol for SQL query builders.

HasSQLGlotExpressionProtocol ¶

Bases: Protocol

Protocol for objects with a sqlglot_expression property.

HasExpressionProtocol ¶

Bases: Protocol

Protocol for objects with an _expression attribute.

HasExpressionAndSQLProtocol ¶

Bases: Protocol

Protocol for objects with both expression and sql attributes (like SQL class).

HasExpressionAndParametersProtocol ¶

Bases: Protocol

Protocol for objects with both expression and parameters attributes.

HasParameterBuilderProtocol ¶

Bases: Protocol

Protocol for objects that can add parameters and build queries.

HasWhereProtocol ¶

Bases: Protocol

Protocol for SQL expressions that support WHERE clauses.

WithMethodProtocol ¶

Bases: Protocol

Protocol for objects with a with_ method (SQLGlot expressions).

Driver, Cursor & Result Protocols¶

QueryResultProtocol ¶

Bases: Protocol

Protocol for query execution results.

CursorMetadataProtocol ¶

Bases: Protocol

Protocol for cursor metadata access.

SupportsArrowResults ¶

Bases: Protocol

Protocol for adapters that support Arrow result format.

Adapters implementing this protocol can return query results in Apache Arrow format via the select_to_arrow() method, enabling zero-copy data transfer and efficient integration with data science tools.

ArrowTableStatsProtocol ¶

Bases: Protocol

Protocol for Arrow objects exposing row and byte counts.

PipelineCapableProtocol ¶

Bases: Protocol

Protocol for connections supporting pipeline execution.

SupportsCloseProtocol ¶

Bases: Protocol

Protocol for objects exposing close().

HasRowcountProtocol ¶

Bases: Protocol

Protocol for cursors exposing rowcount metadata.

HasLastRowIdProtocol ¶

Bases: Protocol

Protocol for cursors exposing lastrowid metadata.

HasSqlStateProtocol ¶

Bases: Protocol

Protocol for exceptions exposing sqlstate.

HasErrnoProtocol ¶

Bases: Protocol

Protocol for objects exposing errno details.

HasSqliteErrorProtocol ¶

Bases: Protocol

Protocol for sqlite errors exposing sqlite error details.

Data Dictionary & Storage Protocols¶

SyncDataDictionaryProtocol ¶

Bases: Protocol

Protocol for sync data dictionary implementations.

AsyncDataDictionaryProtocol ¶

Bases: Protocol

Protocol for async data dictionary implementations.

ObjectStoreProtocol ¶

Bases: Protocol

Protocol for object storage operations.

All synchronous methods use the *_sync suffix for consistency with async methods.

ReadableProtocol ¶

Bases: Protocol

Protocol for objects that have a read method.

AsyncReadableProtocol ¶

Bases: Protocol

Protocol for objects that have an async read method.

AsyncReadBytesProtocol ¶

Bases: Protocol

Protocol for async read_bytes support.

AsyncWriteBytesProtocol ¶

Bases: Protocol

Protocol for async write_bytes support.

AsyncDeleteProtocol ¶

Bases: Protocol

Protocol for async delete support.

Configuration, Event & Model Structural Protocols¶

HasConfigProtocol ¶

Bases: Protocol

Protocol for wrapper objects exposing a config attribute.

HasConnectionConfigProtocol ¶

Bases: Protocol

Protocol for configs exposing connection_config mapping.

HasMigrationConfigProtocol ¶

Bases: Protocol

Protocol for database configurations that support migrations.

Used to check if a config object has migration_config attribute.

HasExtensionConfigProtocol ¶

Bases: Protocol

Protocol for configs exposing extension_config mapping.

HasStatementConfigProtocol ¶

Bases: Protocol

Protocol for objects holding statement configuration.

HasDatabaseUrlAndBindKeyProtocol ¶

Bases: Protocol

Protocol for configs exposing database_url and bind_key.

NotificationProtocol ¶

Bases: Protocol

Protocol for database event notifications.

HasNotifiesProtocol ¶

Bases: Protocol

Protocol for asyncpg-like connections exposing notifications.

HasAddListenerProtocol ¶

Bases: Protocol

Protocol for asyncpg-like connections exposing add_listener.

DictProtocol ¶

Bases: Protocol

Protocol for objects with a dict attribute.

MappingLikeProtocol ¶

Bases: Protocol

Protocol for objects that can be converted to dict via dict() constructor.

This matches database row types like sqlite3.Row, asyncpg.Record, psycopg.Row that support dictionary-like access with keys() method.

HasAsDictProtocol ¶

Bases: Protocol

Protocol for objects with _asdict() method.

Used for row types that don't support dict() constructor directly but can be converted via _asdict() method.