Protocols¶

from sqlspec.protocols import (
    ArrowTableStatsProtocol,
    AsyncDataDictionaryProtocol,
    AsyncDeleteProtocol,
    AsyncReadableProtocol,
    AsyncReadBytesProtocol,
    AsyncWritableBytesSink,
    AsyncWriteBytesProtocol,
    CursorMetadataProtocol,
    DictProtocol,
    DirectStreamWriteProtocol,
    HasAddListenerProtocol,
    HasAsDictProtocol,
    HasConfigProtocol,
    HasConnectionConfigProtocol,
    HasDatabaseUrlAndBindKeyProtocol,
    HasErrnoProtocol,
    HasExpressionAndParametersProtocol,
    HasExpressionAndSQLProtocol,
    HasExpressionProtocol,
    HasExtensionConfigProtocol,
    HasLastRowIdProtocol,
    HasMigrationConfigProtocol,
    HasNotifiesProtocol,
    HasParameterBuilderProtocol,
    HasRowcountProtocol,
    HasSQLGlotExpressionProtocol,
    HasSqliteErrorProtocol,
    HasSqlStateProtocol,
    HasStatementConfigProtocol,
    HasWhereProtocol,
    MappingLikeProtocol,
    NotificationProtocol,
    ObjectStoreProtocol,
    PipelineCapableProtocol,
    QueryResultProtocol,
    ReadableProtocol,
    SQLBuilderProtocol,
    StatementProtocol,
    SupportsArrowResults,
    SupportsCloseProtocol,
    SyncDataDictionaryProtocol,
    WithMethodProtocol,
    WritableBytesSink,
)
from sqlspec.utils.type_guards import supports_direct_stream_write

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.

DirectStreamWriteProtocol ¶

Bases: Protocol

Optional capability protocol for backends supporting streaming Arrow writes.

WritableBytesSink ¶

Bases: Protocol

Synchronous writable byte sink returned by DirectStreamWriteProtocol.

AsyncWritableBytesSink ¶

Bases: Protocol

Asynchronous writable byte sink returned by DirectStreamWriteProtocol.

`supports_direct_stream_write(obj)` ¶

Return whether a storage backend instance implements DirectStreamWriteProtocol.

Returns:

Type	Description
`TypeGuard[DirectStreamWriteProtocol]`	True if obj is an instance exposing direct synchronous and asynchronous write streams.

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.

GeezerVison

Protocols¶

Statement & Builder Protocols¶

StatementProtocol ¶

SQLBuilderProtocol ¶

HasSQLGlotExpressionProtocol ¶

HasExpressionProtocol ¶

HasExpressionAndSQLProtocol ¶

HasExpressionAndParametersProtocol ¶

HasParameterBuilderProtocol ¶

HasWhereProtocol ¶

WithMethodProtocol ¶

Driver, Cursor & Result Protocols¶

QueryResultProtocol ¶

CursorMetadataProtocol ¶

SupportsArrowResults ¶

ArrowTableStatsProtocol ¶

PipelineCapableProtocol ¶

SupportsCloseProtocol ¶

HasRowcountProtocol ¶

HasLastRowIdProtocol ¶

HasSqlStateProtocol ¶

HasErrnoProtocol ¶

HasSqliteErrorProtocol ¶

Data Dictionary & Storage Protocols¶

SyncDataDictionaryProtocol ¶

AsyncDataDictionaryProtocol ¶

ObjectStoreProtocol ¶

ReadableProtocol ¶

AsyncReadableProtocol ¶

AsyncReadBytesProtocol ¶

AsyncWriteBytesProtocol ¶

AsyncDeleteProtocol ¶

DirectStreamWriteProtocol ¶

WritableBytesSink ¶

AsyncWritableBytesSink ¶

supports_direct_stream_write(obj) ¶

Configuration, Event & Model Structural Protocols¶

HasConfigProtocol ¶

HasConnectionConfigProtocol ¶

HasMigrationConfigProtocol ¶

HasExtensionConfigProtocol ¶

HasStatementConfigProtocol ¶

HasDatabaseUrlAndBindKeyProtocol ¶

NotificationProtocol ¶

HasNotifiesProtocol ¶

HasAddListenerProtocol ¶

DictProtocol ¶

MappingLikeProtocol ¶

HasAsDictProtocol ¶

`supports_direct_stream_write(obj)` ¶