Backends API¶
smallex.backends
¶
Backend registry and factory helpers.
get_backend(engine: str) -> BaseDatabaseBackend
¶
Create a backend instance from an engine identifier.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
engine
|
str
|
Backend identifier from config. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
BaseDatabaseBackend |
BaseDatabaseBackend
|
A concrete backend instance. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the engine is unknown. |
smallex.backends.base
¶
Base interfaces and shared utilities for database backends.
BaseDatabaseBackend
¶
Bases: ABC
Abstract base class for all supported database backends.
Concrete backends define connector import details and required options.
They then reuse :meth:connect to validate config and open a connection.
Attributes:
| Name | Type | Description |
|---|---|---|
engine_name |
str
|
Public engine identifier used in config files. |
module_path |
str
|
Import path for the connector module. |
connect_attr |
str
|
Connector function name in the imported module. |
required_connection_fields |
tuple[str, ...]
|
Required config keys for the backend. |
connect(options: Mapping[str, object]) -> ConnectionProtocol
¶
Open a database connection using the backend connector.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
options
|
Mapping[str, object]
|
Connection keyword arguments passed to the connector. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
ConnectionProtocol |
ConnectionProtocol
|
A DB-API-like connection object. |
prepare_connection_options(options: Mapping[str, object]) -> dict[str, object]
¶
Transform user config into connector-ready options.
Subclasses can override this to map normalized values to connector-specific keys and to remove framework-level keys that should not be passed to the underlying connector.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
options
|
Mapping[str, object]
|
Raw connection mapping from config. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, object]
|
dict[str, object]: Connector-ready connection options. |
test_connection(connection: ConnectionProtocol, options: Mapping[str, object]) -> None
¶
Verify a backend connection is usable.
validate_connection_options(options: Mapping[str, object]) -> None
¶
Validate connection options before opening a connection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
options
|
Mapping[str, object]
|
Connection keyword arguments from user config. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If one or more required fields are missing. |
DatabaseConfig
dataclass
¶
Configuration payload used to build a backend connection.
Attributes:
| Name | Type | Description |
|---|---|---|
engine |
str
|
Logical backend name (for example: |
connection |
dict[str, object]
|
Keyword arguments passed to the backend connector. |
smallex.backends.snowflake
¶
Snowflake backend implementation.
SnowflakeBackend
¶
Bases: BaseDatabaseBackend
Backend for Snowflake using snowflake-connector-python.
Expected connection options for password auth (default):
- account
- user
- password
- warehouse
- database
- schema
prepare_connection_options(options: Mapping[str, object]) -> dict[str, object]
¶
Map normalized auth mode values to Snowflake connector options.
test_connection(connection: ConnectionProtocol, options: Mapping[str, object]) -> None
¶
Verify Snowflake-specific connection details after connecting.
validate_connection_options(options: Mapping[str, object]) -> None
¶
Validate Snowflake fields according to selected auth mode.
smallex.backends.databricks
¶
Databricks SQL backend implementation.
DatabricksBackend
¶
Bases: BaseDatabaseBackend
Backend for Databricks SQL using databricks-sql-connector.
Expected connection options for token auth (default):
- server_hostname
- http_path
- access_token