Data Connections

All connect_* functions resolve params in this order:

explicit function arguments
optional profile values, where supported (connect_databricks, connect_redshift)
environment variables

If a required value is still missing after resolution, the helper raises TemporaClientError.

BigQuery

from tempora.datasets import connect_bigquery, disconnect_bigquery

connect_bigquery(
    project_id: str | None = None,
    dataset_id: str | None = None,
    host: str | None = None,
    port: str | None = None,
    service_account_json: str | None = None
) -> None

Open a BigQuery connection. The connection project is used by default unless a dataset overrides it with project=.

Parameter Name	Description
`project_id`	Default GCP project for the connection. If omitted, uses `BIGQUERY_PROJECT_ID`.
`dataset_id`	Optional default BigQuery dataset. If omitted, uses `BIGQUERY_DATASET_ID`.
`host`	Optional BigQuery API endpoint host. If omitted, uses `BIGQUERY_HOST`.
`port`	Optional BigQuery API endpoint port. If omitted, uses `BIGQUERY_PORT` if set; otherwise defaults to `'443'`.
`service_account_json`	Optional service account JSON string. If omitted, uses `BIGQUERY_SERVICE_ACCOUNT_JSON` or falls back to the server's Application Default Credentials.

disconnect_bigquery() -> None

Close an existing connection to BigQuery.

ClickHouse

from tempora.datasets import connect_clickhouse, disconnect_clickhouse

connect_clickhouse(
    host: str | None = None,
    user: str | None = None,
    password: str | None = None,
    port: str | None = None
) -> None

Open a ClickHouse connection.

Parameter Name	Description
`host`	ClickHouse server host. If omitted, uses `CLICKHOUSE_HOST`.
`user`	Optional ClickHouse username. If omitted, uses `CLICKHOUSE_USER`.
`password`	Optional ClickHouse password. If omitted, uses `CLICKHOUSE_PASSWORD`.
`port`	Server port. If omitted, uses `CLICKHOUSE_PORT` if set; otherwise defaults to `'8123'`.

disconnect_clickhouse() -> None

Close an existing connection to ClickHouse.

Databricks

from tempora.datasets import connect_databricks, disconnect_databricks

connect_databricks(
    host: str | None = None,
    auth_token: str | None = None,
    http_path: str | None = None,
    port: str | None = None,
    profile: str | None = None
) -> None

Open a Databricks SQL connection. Datasets then select catalog / schema / table separately.

Parameter Name	Description
`host`	Databricks workspace host. If omitted, uses `DATABRICKS_HOST` or a profile value.
`auth_token`	Databricks auth token. If omitted, uses `DATABRICKS_AUTH_TOKEN` or a profile value.
`http_path`	SQL warehouse or endpoint HTTP path. If omitted, uses `DATABRICKS_HTTP_PATH` or a profile value.
`port`	Workspace port. If omitted, uses `DATABRICKS_PORT`, a profile value, or defaults to `'443'`.
`profile`	Profile name in `.databrickscfg` used to load defaults.

disconnect_databricks() -> None

Close an existing connection to Databricks.

InfluxDB

from tempora.datasets import connect_influxdb, disconnect_influxdb

connect_influxdb(
    host: str | None = None,
    token: str | None = None,
    database: str | None = None,
    timeout: int | None = None
) -> None

Open an InfluxDB connection.

Parameter Name	Description
`host`	InfluxDB server host. If omitted, uses `INFLUXDB_HOST`.
`token`	InfluxDB authentication token. If omitted, uses `INFLUXDB_TOKEN`.
`database`	InfluxDB database name. If omitted, uses `INFLUXDB_DATABASE`.
`timeout`	Optional request timeout. If omitted, uses `INFLUXDB_TIMEOUT` when set.

disconnect_influxdb() -> None

Close an existing connection to InfluxDB.

MotherDuck

from tempora.datasets import connect_motherduck, disconnect_motherduck

connect_motherduck(
    db_name: str,
    auth_token: str | None = None
) -> None

Open a MotherDuck connection. This helper uses token-based auth.

Parameter Name	Description
`db_name`	MotherDuck database name to open.
`auth_token`	MotherDuck auth token. If omitted, uses `MOTHERDUCK_AUTH_TOKEN`.

disconnect_motherduck() -> None

Close an existing connection to MotherDuck.

MotherDuck uses token-only auth in this client helper.

MSSQL

from tempora.datasets import connect_mssql, disconnect_mssql

connect_mssql(
    host: str | None = None,
    user: str | None = None,
    password: str | None = None,
    port: str | None = None,
    instance: str | None = None
) -> None

Open an MSSQL connection.

Parameter Name	Description
`host`	MSSQL server host. If omitted, uses `MSSQL_HOST`.
`user`	MSSQL username. If omitted, uses `MSSQL_USER`.
`password`	MSSQL password. If omitted, uses `MSSQL_PASSWORD`.
`port`	Server port. If omitted, uses `MSSQL_PORT` if set; otherwise defaults to `'1433'`.
`instance`	Optional SQL Server instance name. If omitted, uses `MSSQL_INSTANCE`.

disconnect_mssql() -> None

Close an existing connection to MSSQL.

MySQL

from tempora.datasets import connect_mysql, disconnect_mysql

connect_mysql(
    host: str | None = None,
    user: str | None = None,
    password: str | None = None,
    port: str | None = None
) -> None

Open a MySQL connection.

Parameter Name	Description
`host`	MySQL server host. If omitted, uses `MYSQL_HOST`.
`user`	MySQL username. If omitted, uses `MYSQL_USER`.
`password`	MySQL password. If omitted, uses `MYSQL_PASSWORD`.
`port`	Server port. If omitted, uses `MYSQL_PORT` if set; otherwise defaults to `'3306'`.

disconnect_mysql() -> None

Close an existing connection to MySQL.

Oracle

from tempora.datasets import connect_oracle, disconnect_oracle

connect_oracle(
    host: str | None = None,
    user: str | None = None,
    password: str | None = None,
    service_name: str | None = None,
    port: str | None = None
) -> None

Open an Oracle connection.

Parameter Name	Description
`host`	Oracle server host. If omitted, uses `ORACLE_HOST`.
`user`	Oracle username. If omitted, uses `ORACLE_USER`.
`password`	Oracle password. If omitted, uses `ORACLE_PASSWORD`.
`service_name`	Oracle service name. If omitted, uses `ORACLE_SERVICE_NAME`.
`port`	Server port. If omitted, uses `ORACLE_PORT` if set; otherwise defaults to `'1521'`.

disconnect_oracle() -> None

Close an existing connection to Oracle.

PostgreSQL

from tempora.datasets import connect_postgresql, disconnect_postgresql

connect_postgresql(
    host: str | None = None,
    user: str | None = None,
    password: str | None = None,
    database: str | None = None,
    port: str | None = None,
    role: str | None = None
) -> None

Open a PostgreSQL connection.

Parameter Name	Description
`host`	PostgreSQL server host. If omitted, uses `POSTGRESQL_HOST`.
`user`	PostgreSQL username. If omitted, uses `POSTGRESQL_USER`.
`password`	PostgreSQL password. If omitted, uses `POSTGRESQL_PASSWORD`.
`database`	PostgreSQL database name. If omitted, uses `POSTGRESQL_DATABASE`.
`port`	Server port. If omitted, uses `POSTGRESQL_PORT` if set; otherwise defaults to `'5432'`.
`role`	Optional session role. If omitted, uses `POSTGRESQL_ROLE`.

disconnect_postgresql() -> None

Close an existing connection to PostgreSQL.

Redshift

from tempora.datasets import connect_redshift, disconnect_redshift

connect_redshift(
    cluster_type: RedshiftClusterType = 'redshift',
    host: str | None = None,
    user: str | None = None,
    password: str | None = None,
    database: str | None = None,
    port: str | None = None,
    cluster_identifier: str | None = None,
    workgroup_name: str | None = None,
    profile: str | None = None,
    aws_region: str | None = None,
    aws_access_key_id: str | None = None,
    aws_secret_access_key: str | None = None,
    aws_session_token: str | None = None,
    sslmode: str | None = None,
    config_props: dict[str, bool | int | str] | None = None
) -> None

Open a Redshift connection.

Parameter Name	Description
`cluster_type`	Redshift connection mode. See RedshiftClusterType.
`host`	Redshift cluster host. If omitted, uses `REDSHIFT_HOST`.
`user`	Redshift username. Required for provisioned direct auth and IAM auth. If omitted, uses `REDSHIFT_USER` when applicable.
`password`	Redshift password. Required for `cluster_type='redshift'`. If omitted, uses `REDSHIFT_PASSWORD` when applicable.
`database`	Redshift database name. If omitted, uses `REDSHIFT_DATABASE`.
`port`	Cluster port. If omitted, uses `REDSHIFT_PORT` if set; otherwise defaults to `'5439'`.
`cluster_identifier`	Redshift provisioned cluster identifier. Required for `cluster_type='redshift-iam'`.
`workgroup_name`	Redshift Serverless workgroup name. Required for `cluster_type='redshift-serverless'`.
`profile`	AWS shared config / credentials profile name. If provided, the client resolves AWS credentials locally and forwards the concrete values to the server.
`aws_region`	Optional AWS region. If omitted, uses `AWS_REGION` or `AWS_DEFAULT_REGION`.
`aws_access_key_id`	Optional AWS access key ID. If omitted, uses `AWS_ACCESS_KEY_ID`.
`aws_secret_access_key`	Optional AWS secret access key. If omitted, uses `AWS_SECRET_ACCESS_KEY`.
`aws_session_token`	Optional AWS session token. If omitted, uses `AWS_SESSION_TOKEN`.
`sslmode`	Optional SSL mode. If omitted, uses `REDSHIFT_SSLMODE`.
`config_props`	Optional additional Redshift JDBC-style configuration properties. Keys must be strings and values must be `bool`, `int`, or `str`.

disconnect_redshift() -> None

Close an existing connection to Redshift.

RedshiftClusterType

from tempora.datasets.redshift import RedshiftClusterType

RedshiftClusterType = Literal['redshift', 'redshift-iam', 'redshift-serverless']

Values

Name	Description
`'redshift'`	Provisioned Redshift with direct user/password authentication.
`'redshift-iam'`	Provisioned Redshift with IAM-based authentication.
`'redshift-serverless'`	Redshift Serverless.

Snowflake

from tempora.datasets import connect_snowflake, disconnect_snowflake

connect_snowflake(
    user: str | None = None,
    password: str | None = None,
    account: str | None = None,
    auth_type: Literal['password', 'mfa', 'pat'] = 'password',
    auth_token: str | None = None,
    role: str | None = None,
    warehouse: str | None = None,
    profile: str | None = None
) -> None

Open a connection to Snowflake.

Use this helper to establish the authenticated Snowflake session that database-backed datasets will use.

Parameter Name	Description
`user`	Login name. If omitted, uses `SNOWFLAKE_USER`.
`password`	Password. If omitted and `auth_type` is `'password'` or `'mfa'`, uses `SNOWFLAKE_PASSWORD`.
`account`	Snowflake account identifier. If omitted, uses `SNOWFLAKE_ACCOUNT`.
`auth_type`	Authentication mode: `'password'`, `'mfa'`, or `'pat'`.
`auth_token`	Authentication token for `'mfa'` or `'pat'` auth. If omitted, uses `SNOWFLAKE_AUTH_TOKEN`.
`role`	Snowflake role to use for authentication.
`warehouse`	Default warehouse name.
`profile`	Name of a connection profile in `connections.toml` to load defaults from.

disconnect_snowflake() -> None

Close an existing connection to Snowflake.

Teradata

from tempora.datasets import connect_teradata, disconnect_teradata

connect_teradata(
    host: str | None = None,
    user: str | None = None,
    password: str | None = None,
    port: str | None = None
) -> None

Open a Teradata connection.

Parameter Name	Description
`host`	Teradata server host. If omitted, uses `TERADATA_HOST`.
`user`	Teradata username. If omitted, uses `TERADATA_USER`.
`password`	Teradata password. If omitted, uses `TERADATA_PASSWORD`.
`port`	Server port. If omitted, uses `TERADATA_PORT` if set; otherwise defaults to `'1025'`.

disconnect_teradata() -> None

Close an existing connection to Teradata.

Environment Variables

Driver	Variables
BigQuery	`BIGQUERY_PROJECT_ID`, `BIGQUERY_DATASET_ID`, `BIGQUERY_HOST`, `BIGQUERY_PORT`, `BIGQUERY_SERVICE_ACCOUNT_JSON`
ClickHouse	`CLICKHOUSE_HOST`, `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`, `CLICKHOUSE_PORT`
Databricks	`DATABRICKS_HOST`, `DATABRICKS_AUTH_TOKEN`, `DATABRICKS_HTTP_PATH`, `DATABRICKS_PORT`
InfluxDB	`INFLUXDB_HOST`, `INFLUXDB_TOKEN`, `INFLUXDB_DATABASE`, `INFLUXDB_TIMEOUT`
MotherDuck	`MOTHERDUCK_AUTH_TOKEN`
MSSQL	`MSSQL_HOST`, `MSSQL_USER`, `MSSQL_PASSWORD`, `MSSQL_PORT`, `MSSQL_INSTANCE`
MySQL	`MYSQL_HOST`, `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_PORT`
Oracle	`ORACLE_HOST`, `ORACLE_USER`, `ORACLE_PASSWORD`, `ORACLE_SERVICE_NAME`, `ORACLE_PORT`
PostgreSQL	`POSTGRESQL_DATABASE`, `POSTGRESQL_HOST`, `POSTGRESQL_USER`, `POSTGRESQL_PASSWORD`, `POSTGRESQL_PORT`, `POSTGRESQL_ROLE`
Redshift	`REDSHIFT_CLUSTER_TYPE`, `REDSHIFT_DATABASE`, `REDSHIFT_HOST`, `REDSHIFT_USER`, `REDSHIFT_PASSWORD`, `REDSHIFT_PORT`, `REDSHIFT_CLUSTER_IDENTIFIER`, `REDSHIFT_WORKGROUP_NAME`, `REDSHIFT_SSLMODE`, `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`
Snowflake	`SNOWFLAKE_USER`, `SNOWFLAKE_PASSWORD`, `SNOWFLAKE_ACCOUNT`, `SNOWFLAKE_AUTH_TOKEN`, `SNOWFLAKE_ROLE`, `SNOWFLAKE_WAREHOUSE`
Teradata	`TERADATA_HOST`, `TERADATA_USER`, `TERADATA_PASSWORD`, `TERADATA_PORT`