adbc_driver_flightsql

Low-Level API

Low-level ADBC bindings for the Flight SQL driver.

class adbc_driver_flightsql.ConnectionOptions(*values)

Bases: Enum

Connection options specific to the Flight SQL driver.

OPTION_BOOL_SESSION_OPTION_PREFIX = 'adbc.flight.sql.session.optionbool.'

Get or set a boolean valued session option.

OPTION_ERASE_SESSION_OPTION_PREFIX = 'adbc.flight.sql.session.optionerase.'

Erase a session option (use “” as the value).

OPTION_SESSION_OPTIONS = 'adbc.flight.sql.session.options'

Get all session options as a JSON key-value blob.

OPTION_SESSION_OPTION_PREFIX = 'adbc.flight.sql.session.option.'

Get or set a session option.

OPTION_STRING_LIST_SESSION_OPTION_PREFIX = 'adbc.flight.sql.session.optionstringlist.'

Get or set a string-list-valued session option as a JSON array.

RPC_CALL_HEADER_PREFIX = 'adbc.flight.sql.rpc.call_header.'

Add an arbitrary header to all outgoing requests.

This option should prefix the name of the header to add (i.e. it should be used like f"{ConnectionOptions.RPC_CALL_HEADER_PREFIX}x-my-header").

Overrides any headers set via the equivalent database option.

TIMEOUT_FETCH = 'adbc.flight.sql.rpc.timeout_seconds.fetch'

Set a timeout on calls that fetch data (in floating-point seconds).

This corresponds to Flight RPC DoGet calls.

TIMEOUT_QUERY = 'adbc.flight.sql.rpc.timeout_seconds.query'

Set a timeout on calls that execute queries (in floating-point seconds).

This corresponds to Flight RPC GetFlightInfo calls.

TIMEOUT_UPDATE = 'adbc.flight.sql.rpc.timeout_seconds.update'

Set a timeout on calls that upload or update data (in floating-point seconds).

class adbc_driver_flightsql.DatabaseOptions(*values)

Bases: Enum

Database options specific to the Flight SQL driver.

AUTHORITY = 'adbc.flight.sql.client_option.authority'

Server name in authentication handshake

AUTHORIZATION_HEADER = 'adbc.flight.sql.authorization_header'

The authorization header to use for requests.

MTLS_CERT_CHAIN = 'adbc.flight.sql.client_option.mtls_cert_chain'

Enable mTLS and use these PEM-encoded certificates.

MTLS_PRIVATE_KEY = 'adbc.flight.sql.client_option.mtls_private_key'

Enable mTLS and use this PEM-encoded private key.

OAUTH_AUTH_URI = 'adbc.flight.sql.oauth.auth_uri'

The authorization endpoint URL for OAuth 2.0.

OAUTH_CLIENT_ID = 'adbc.flight.sql.oauth.client_id'

Unique identifier issued to the client application by the authorization server.

OAUTH_CLIENT_SECRET = 'adbc.flight.sql.oauth.client_secret'

Secret associated with the client_id. Used to authenticate the client application to the authorization server.

OAUTH_EXCHANGE_ACTOR_TOKEN = 'adbc.flight.sql.oauth.exchange.actor_token'

A security token that represents the identity of the acting party.

OAUTH_EXCHANGE_ACTOR_TOKEN_TYPE = 'adbc.flight.sql.oauth.exchange.actor_token_type'

Identifier for the type of the actor token.

See OAuthTokenType for supported token types.

OAUTH_EXCHANGE_AUD = 'adbc.flight.sql.oauth.exchange.aud'

The intended audience for the requested security token in token exchange.

OAUTH_EXCHANGE_REQUESTED_TOKEN_TYPE = 'adbc.flight.sql.oauth.exchange.requested_token_type'

The type of token the client wants to receive in exchange.

See OAuthTokenType for supported token types.

OAUTH_EXCHANGE_RESOURCE = 'adbc.flight.sql.oauth.exchange.resource'

The resource server where the client intends to use the requested security token in token exchange.

OAUTH_EXCHANGE_SCOPE = 'adbc.flight.sql.oauth.exchange.scope'

Specific permissions requested for the new token in token exchange.

OAUTH_EXCHANGE_SUBJECT_TOKEN = 'adbc.flight.sql.oauth.exchange.subject_token'

The security token that the client application wants to exchange.

OAUTH_EXCHANGE_SUBJECT_TOKEN_TYPE = 'adbc.flight.sql.oauth.exchange.subject_token_type'

Identifier for the type of the subject token.

See OAuthTokenType for supported token types.

OAUTH_FLOW = 'adbc.flight.sql.oauth.flow'

Specifies the OAuth 2.0 flow type to use.

See OAuthFlowType for possible values.

OAUTH_REDIRECT_URI = 'adbc.flight.sql.oauth.redirect_uri'

The redirect URI for OAuth 2.0 flows.

OAUTH_SCOPE = 'adbc.flight.sql.oauth.scope'

Space-separated list of permissions that the client is requesting access to (e.g., "read.all offline_access").

OAUTH_TOKEN_URI = 'adbc.flight.sql.oauth.token_uri'

The endpoint URL where the client application requests tokens from the authorization server.

RPC_CALL_HEADER_PREFIX = 'adbc.flight.sql.rpc.call_header.'

Add an arbitrary header to all outgoing requests.

This option should prefix the name of the header to add (i.e. it should be used like f"{DatabaseOptions.RpcCallHeaderPrefix}.x-my-header").

TIMEOUT_FETCH = 'adbc.flight.sql.rpc.timeout_seconds.fetch'

Set a timeout on calls that fetch data (in floating-point seconds).

This corresponds to Flight RPC DoGet calls.

TIMEOUT_QUERY = 'adbc.flight.sql.rpc.timeout_seconds.query'

Set a timeout on calls that execute queries (in floating-point seconds).

This corresponds to Flight RPC GetFlightInfo calls.

TIMEOUT_UPDATE = 'adbc.flight.sql.rpc.timeout_seconds.update'

Set a timeout on calls that upload or update data (in floating-point seconds).

TLS_OVERRIDE_HOSTNAME = 'adbc.flight.sql.client_option.tls_override_hostname'

Override the hostname used for TLS.

TLS_ROOT_CERTS = 'adbc.flight.sql.client_option.tls_root_certs'

Use these PEM-encoded root certificates for TLS.

TLS_SKIP_VERIFY = 'adbc.flight.sql.client_option.tls_skip_verify'

Do not verify the server’s TLS certificate.

WITH_BLOCK = 'adbc.flight.sql.client_option.with_block'

Block and wait for the connection to be established.

Enable cookie middleware. Default is disabled (“false”)

WITH_MAX_MSG_SIZE = 'adbc.flight.sql.client_option.with_max_msg_size'

Set the maximum gRPC message size (in bytes). The default is 16 MiB.

class adbc_driver_flightsql.OAuthFlowType(*values)

Bases: Enum

OAuth 2.0 flow types supported by the Flight SQL driver.

Use these values with DatabaseOptions.OAUTH_FLOW.

CLIENT_CREDENTIALS = 'client_credentials'

OAuth 2.0 Client Credentials flow (RFC 6749 Section 4.4).

Use when the client application needs to authenticate itself to the authorization server using its own credentials.

TOKEN_EXCHANGE = 'token_exchange'

OAuth 2.0 Token Exchange flow (RFC 8693).

Use when the client application wants to exchange one security token for another.

class adbc_driver_flightsql.OAuthTokenType(*values)

Bases: Enum

OAuth 2.0 token types supported for token exchange (RFC 8693).

Use these values with token type options like DatabaseOptions.OAUTH_EXCHANGE_SUBJECT_TOKEN_TYPE, DatabaseOptions.OAUTH_EXCHANGE_ACTOR_TOKEN_TYPE, and DatabaseOptions.OAUTH_EXCHANGE_REQUESTED_TOKEN_TYPE.

ACCESS_TOKEN = 'urn:ietf:params:oauth:token-type:access_token'

An OAuth 2.0 access token.

ID_TOKEN = 'urn:ietf:params:oauth:token-type:id_token'

An OpenID Connect ID token.

JWT = 'urn:ietf:params:oauth:token-type:jwt'

A JSON Web Token (JWT).

REFRESH_TOKEN = 'urn:ietf:params:oauth:token-type:refresh_token'

An OAuth 2.0 refresh token.

SAML1 = 'urn:ietf:params:oauth:token-type:saml1'

A SAML 1.1 assertion.

SAML2 = 'urn:ietf:params:oauth:token-type:saml2'

A SAML 2.0 assertion.

class adbc_driver_flightsql.StatementOptions(*values)

Bases: Enum

Statement options specific to the Flight SQL driver.

LAST_FLIGHT_INFO = 'adbc.flight.sql.statement.exec.last_flight_info'

The latest FlightInfo value.

Thread-safe. Mostly useful when using incremental execution, where an advanced client may want to inspect the latest FlightInfo from the service, but without waiting for execute_partitions to return. (The service may send an updated FlightInfo with progress/app_metadata values, but execute_partitions will only return if there are new endpoints.)

QUEUE_SIZE = 'adbc.rpc.result_queue_size'

The number of batches to queue per partition. Defaults to 5.

This controls how much we read ahead on result sets.

RPC_CALL_HEADER_PREFIX = 'adbc.flight.sql.rpc.call_header.'

Add an arbitrary header to all outgoing requests.

This option should prefix the name of the header to add (i.e. it should be used like f"{ConnectionOptions.RPC_CALL_HEADER_PREFIX}x-my-header").

Overrides any headers set via the equivalent database or connection options.

SUBSTRAIT_VERSION = 'adbc.flight.sql.substrait.version'

Set the Substrait version passed in the Flight SQL request.

Most servers will not make use of this since the Substrait specification was updated to embed the version in the plan itself after this was originally added to Flight SQL.

TIMEOUT_FETCH = 'adbc.flight.sql.rpc.timeout_seconds.fetch'

Set a timeout on calls that fetch data (in floating-point seconds).

This corresponds to Flight RPC DoGet calls.

TIMEOUT_QUERY = 'adbc.flight.sql.rpc.timeout_seconds.query'

Set a timeout on calls that execute queries (in floating-point seconds).

This corresponds to Flight RPC GetFlightInfo calls.

TIMEOUT_UPDATE = 'adbc.flight.sql.rpc.timeout_seconds.update'

Set a timeout on calls that upload or update data (in floating-point seconds).

adbc_driver_flightsql.connect(uri: str, db_kwargs: Dict[str, str] | None = None) → AdbcDatabase

Create a low level ADBC connection to a Flight SQL backend.

Parameters:
uristr

The URI to connect to.

db_kwargsdict, optional

Initial database connection parameters.

DBAPI 2.0 API

DBAPI 2.0-compatible facade for the ADBC Arrow Flight SQL driver.

adbc_driver_flightsql.dbapi.connect(uri: str, db_kwargs: Dict[str, str] | None = None, conn_kwargs: Dict[str, str] | None = None, **kwargs) → Connection

Connect to a Flight SQL backend via ADBC.

Parameters:
uristr

The URI to connect to.

db_kwargsdict, optional

Initial database connection parameters.

conn_kwargsdict, optional

Connection-specific parameters. (ADBC differentiates between a ‘database’ object shared between multiple ‘connection’ objects.)