sqlspec 0.1.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

sqlspec/adapters/duckdb/config.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, cast
+
+from sqlspec.config import GenericDatabaseConfig
+from sqlspec.exceptions import ImproperConfigurationError
+from sqlspec.typing import Empty, EmptyType, dataclass_to_dict
+
+if TYPE_CHECKING:
+    from collections.abc import Generator, Sequence
+
+    from duckdb import DuckDBPyConnection
+
+__all__ = ("DuckDBConfig", "ExtensionConfig")
+
+
+@dataclass
+class ExtensionConfig:
+    """Configuration for a DuckDB extension.
+
+    This class provides configuration options for DuckDB extensions, including installation
+    and post-install configuration settings.
+
+    Args:
+        name: The name of the extension to install
+        config: Optional configuration settings to apply after installation
+        force_install: Whether to force reinstall if already present
+        repository: Optional repository name to install from
+        repository_url: Optional repository URL to install from
+        version: Optional version of the extension to install
+    """
+
+    name: str
+    config: dict[str, Any] | None = None
+    force_install: bool = False
+    repository: str | None = None
+    repository_url: str | None = None
+    version: str | None = None
+
+    @classmethod
+    def from_dict(cls, name: str, config: dict[str, Any] | bool | None = None) -> ExtensionConfig:
+        """Create an ExtensionConfig from a configuration dictionary.
+
+        Args:
+            name: The name of the extension
+            config: Configuration dictionary that may contain settings
+
+        Returns:
+            A new ExtensionConfig instance
+        """
+        if config is None:
+            return cls(name=name)
+
+        if not isinstance(config, dict):
+            config = {"force_install": bool(config)}
+
+        install_args = {
+            key: config.pop(key)
+            for key in ["force_install", "repository", "repository_url", "version", "config", "name"]
+            if key in config
+        }
+        return cls(name=name, **install_args)
+
+
+@dataclass
+class DuckDBConfig(GenericDatabaseConfig):
+    """Configuration for DuckDB database connections.
+
+    This class provides configuration options for DuckDB database connections, wrapping all parameters
+    available to duckdb.connect().
+
+    For details see: https://duckdb.org/docs/api/python/overview#connection-options
+    """
+
+    database: str | EmptyType = Empty
+    """The path to the database file to be opened. Pass ":memory:" to open a connection to a database that resides in RAM instead of on disk. If not specified, an in-memory database will be created."""
+
+    read_only: bool | EmptyType = Empty
+    """If True, the database will be opened in read-only mode. This is required if multiple processes want to access the same database file at the same time."""
+
+    config: dict[str, Any] | EmptyType = Empty
+    """A dictionary of configuration options to be passed to DuckDB. These can include settings like 'access_mode', 'max_memory', 'threads', etc.
+
+    For details see: https://duckdb.org/docs/api/python/overview#connection-options
+    """
+
+    extensions: Sequence[ExtensionConfig] | EmptyType = Empty
+    """A sequence of extension configurations to install and configure upon connection creation."""
+
+    def __post_init__(self) -> None:
+        """Post-initialization validation and processing.
+
+        This method handles merging extension configurations from both the extensions field
+        and the config dictionary, if present. The config['extensions'] field can be either:
+        - A dictionary mapping extension names to their configurations
+        - A list of extension names (which will be installed with force_install=True)
+
+        Raises:
+            ImproperConfigurationError: If there are duplicate extension configurations.
+        """
+        if self.config is Empty:
+            self.config = {}
+
+        if self.extensions is Empty:
+            self.extensions = []
+        # this is purely for mypy
+        assert isinstance(self.config, dict)  # noqa: S101
+        assert isinstance(self.extensions, list)  # noqa: S101
+
+        _e = self.config.pop("extensions", {})
+        if not isinstance(_e, (dict, list, tuple)):
+            msg = "When configuring extensions in the 'config' dictionary, the value must be a dictionary or sequence of extension names"
+            raise ImproperConfigurationError(msg)
+        if not isinstance(_e, dict):
+            _e = {str(ext): {"force_install": False} for ext in _e}
+
+        if len(set(_e.keys()).intersection({ext.name for ext in self.extensions})) > 0:
+            msg = "Configuring the same extension in both 'extensions' and as a key in 'config['extensions']' is not allowed"
+            raise ImproperConfigurationError(msg)
+
+        self.extensions.extend([ExtensionConfig.from_dict(name, ext_config) for name, ext_config in _e.items()])
+
+    def _configure_extensions(self, connection: DuckDBPyConnection) -> None:
+        """Configure extensions for the connection.
+
+        Args:
+            connection: The DuckDB connection to configure extensions for.
+
+        Raises:
+            ImproperConfigurationError: If extension installation or configuration fails.
+        """
+        if self.extensions is Empty:
+            return
+
+        for extension in cast("list[ExtensionConfig]", self.extensions):
+            try:
+                if extension.force_install:
+                    connection.install_extension(
+                        extension=extension.name,
+                        force_install=extension.force_install,
+                        repository=extension.repository,
+                        repository_url=extension.repository_url,
+                        version=extension.version,
+                    )
+                connection.load_extension(extension.name)
+
+                if extension.config:
+                    for key, value in extension.config.items():
+                        connection.execute(f"SET {key}={value}")
+            except Exception as e:
+                msg = f"Failed to configure extension {extension.name}. Error: {e!s}"
+                raise ImproperConfigurationError(msg) from e
+
+    @property
+    def connection_config_dict(self) -> dict[str, Any]:
+        """Return the connection configuration as a dict.
+
+        Returns:
+            A string keyed dict of config kwargs for the duckdb.connect() function.
+        """
+        config = dataclass_to_dict(self, exclude_empty=True, exclude={"extensions"}, convert_nested=False)
+        if not config.get("database"):
+            config["database"] = ":memory:"
+        return config
+
+    def create_connection(self) -> DuckDBPyConnection:
+        """Create and return a new database connection with configured extensions.
+
+        Returns:
+            A new DuckDB connection instance with extensions installed and configured.
+
+        Raises:
+            ImproperConfigurationError: If the connection could not be established or extensions could not be configured.
+        """
+        import duckdb
+
+        try:
+            connection = duckdb.connect(**self.connection_config_dict)
+            self._configure_extensions(connection)
+            return connection
+        except Exception as e:
+            msg = f"Could not configure the DuckDB connection. Error: {e!s}"
+            raise ImproperConfigurationError(msg) from e
+
+    @contextmanager
+    def provide_connection(self, *args: Any, **kwargs: Any) -> Generator[DuckDBPyConnection, None, None]:
+        """Create and provide a database connection.
+
+        Yields:
+            A DuckDB connection instance.
+
+        Raises:
+            ImproperConfigurationError: If the connection could not be established.
+        """
+        connection = self.create_connection()
+        try:
+            yield connection
+        finally:
+            connection.close()

sqlspec/adapters/oracledb/__init__.py

@@ -0,0 +1,13 @@
+from .config import (
+    OracleAsyncDatabaseConfig,
+    OracleAsyncPoolConfig,
+    OracleSyncDatabaseConfig,
+    OracleSyncPoolConfig,
+)
+
+__all__ = (
+    "OracleAsyncDatabaseConfig",
+    "OracleAsyncPoolConfig",
+    "OracleSyncDatabaseConfig",
+    "OracleSyncPoolConfig",
+)

sqlspec/adapters/oracledb/config/__init__.py

@@ -0,0 +1,9 @@
+from sqlspec.adapters.oracledb.config._asyncio import OracleAsyncDatabaseConfig, OracleAsyncPoolConfig
+from sqlspec.adapters.oracledb.config._sync import OracleSyncDatabaseConfig, OracleSyncPoolConfig
+
+__all__ = (
+    "OracleAsyncDatabaseConfig",
+    "OracleAsyncPoolConfig",
+    "OracleSyncDatabaseConfig",
+    "OracleSyncPoolConfig",
+)

sqlspec/adapters/oracledb/config/_asyncio.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from oracledb import create_pool_async as oracledb_create_pool
+from oracledb.connection import AsyncConnection
+from oracledb.pool import AsyncConnectionPool
+
+from sqlspec.adapters.oracledb.config._common import (
+    OracleGenericDatabaseConfig,
+    OracleGenericPoolConfig,
+)
+from sqlspec.exceptions import ImproperConfigurationError
+from sqlspec.typing import dataclass_to_dict
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator, Awaitable
+    from typing import Any
+
+__all__ = (
+    "OracleAsyncDatabaseConfig",
+    "OracleAsyncPoolConfig",
+)
+
+
+@dataclass
+class OracleAsyncPoolConfig(OracleGenericPoolConfig[AsyncConnectionPool, AsyncConnection]):
+    """Async Oracle Pool Config"""
+
+
+@dataclass
+class OracleAsyncDatabaseConfig(OracleGenericDatabaseConfig[AsyncConnectionPool, AsyncConnection]):
+    """Async Oracle database Configuration."""
+
+    pool_config: OracleAsyncPoolConfig | None = None
+    """Oracle Pool configuration"""
+    pool_instance: AsyncConnectionPool | None = None
+    """Optional pool to use.
+
+    If set, the plugin will use the provided pool rather than instantiate one.
+    """
+
+    @property
+    def pool_config_dict(self) -> dict[str, Any]:
+        """Return the pool configuration as a dict.
+
+        Returns:
+            A string keyed dict of config kwargs for the Asyncpg :func:`create_pool <oracledb.pool.create_pool>`
+            function.
+        """
+        if self.pool_config is not None:
+            return dataclass_to_dict(self.pool_config, exclude_empty=True, convert_nested=False)
+        msg = "'pool_config' methods can not be used when a 'pool_instance' is provided."
+        raise ImproperConfigurationError(msg)
+
+    async def create_pool(self) -> AsyncConnectionPool:
+        """Return a pool. If none exists yet, create one.
+
+        Returns:
+            Getter that returns the pool instance used by the plugin.
+        """
+        if self.pool_instance is not None:
+            return self.pool_instance
+
+        if self.pool_config is None:
+            msg = "One of 'pool_config' or 'pool_instance' must be provided."
+            raise ImproperConfigurationError(msg)
+
+        pool_config = self.pool_config_dict
+        self.pool_instance = oracledb_create_pool(**pool_config)
+        if self.pool_instance is None:
+            msg = "Could not configure the 'pool_instance'. Please check your configuration."
+            raise ImproperConfigurationError(msg)
+        return self.pool_instance
+
+    def provide_pool(self, *args: Any, **kwargs: Any) -> Awaitable[AsyncConnectionPool]:
+        """Create a pool instance.
+
+        Returns:
+            A Pool instance.
+        """
+        return self.create_pool()
+
+    @asynccontextmanager
+    async def provide_connection(self, *args: Any, **kwargs: Any) -> AsyncGenerator[AsyncConnection, None]:
+        """Create a connection instance.
+
+        Returns:
+            A connection instance.
+        """
+        db_pool = await self.provide_pool(*args, **kwargs)
+        async with db_pool.acquire() as connection:
+            yield connection

sqlspec/adapters/oracledb/config/_common.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+from oracledb import ConnectionPool
+
+from sqlspec.config import GenericDatabaseConfig, GenericPoolConfig
+from sqlspec.typing import Empty
+
+if TYPE_CHECKING:
+    import ssl
+    from collections.abc import Callable
+    from typing import Any
+
+    from oracledb import AuthMode, ConnectParams, Purity
+    from oracledb.connection import AsyncConnection, Connection
+    from oracledb.pool import AsyncConnectionPool, ConnectionPool
+
+    from sqlspec.typing import EmptyType
+
+__all__ = (
+    "OracleGenericDatabaseConfig",
+    "OracleGenericPoolConfig",
+)
+
+
+T = TypeVar("T")
+
+ConnectionT = TypeVar("ConnectionT", bound="Connection | AsyncConnection")
+PoolT = TypeVar("PoolT", bound="ConnectionPool | AsyncConnectionPool")
+
+
+@dataclass
+class OracleGenericPoolConfig(Generic[PoolT, ConnectionT], GenericPoolConfig):
+    """Configuration for Oracle database connection pools.
+
+    This class provides configuration options for both synchronous and asynchronous Oracle
+    database connection pools. It supports all standard Oracle connection parameters and pool-specific
+    settings.([1](https://python-oracledb.readthedocs.io/en/latest/api_manual/module.html))
+    """
+
+    conn_class: type[ConnectionT] | EmptyType = Empty
+    """The connection class to use (Connection or AsyncConnection)"""
+    dsn: str | EmptyType = Empty
+    """Connection string for the database   """
+    pool: PoolT | EmptyType = Empty
+    """Existing pool instance to use"""
+    params: ConnectParams | EmptyType = Empty
+    """Connection parameters object"""
+    user: str | EmptyType = Empty
+    """Username for database authentication"""
+    proxy_user: str | EmptyType = Empty
+    """Name of the proxy user to connect through"""
+    password: str | EmptyType = Empty
+    """Password for database authentication"""
+    newpassword: str | EmptyType = Empty
+    """New password for password change operations"""
+    wallet_password: str | EmptyType = Empty
+    """Password for accessing Oracle Wallet"""
+    access_token: str | tuple | Callable | EmptyType = Empty
+    """Token for token-based authentication"""
+    host: str | EmptyType = Empty
+    """Database server hostname"""
+    port: int | EmptyType = Empty
+    """Database server port number"""
+    protocol: str | EmptyType = Empty
+    """Network protocol (TCP or TCPS)"""
+    https_proxy: str | EmptyType = Empty
+    """HTTPS proxy server address"""
+    https_proxy_port: int | EmptyType = Empty
+    """HTTPS proxy server port"""
+    service_name: str | EmptyType = Empty
+    """Oracle service name"""
+    sid: str | EmptyType = Empty
+    """Oracle System ID (SID)"""
+    server_type: str | EmptyType = Empty
+    """Server type (dedicated, shared, pooled, or drcp)"""
+    cclass: str | EmptyType = Empty
+    """Connection class for database resident connection pooling"""
+    purity: Purity | EmptyType = Empty
+    """Session purity (NEW, SELF, or DEFAULT)"""
+    expire_time: int | EmptyType = Empty
+    """Time in minutes after which idle connections are closed"""
+    retry_count: int | EmptyType = Empty
+    """Number of attempts to connect"""
+    retry_delay: int | EmptyType = Empty
+    """Time in seconds between connection attempts"""
+    tcp_connect_timeout: float | EmptyType = Empty
+    """Timeout for establishing TCP connections"""
+    ssl_server_dn_match: bool | EmptyType = Empty
+    """If True, verify server certificate DN"""
+    ssl_server_cert_dn: str | EmptyType = Empty
+    """Expected server certificate DN"""
+    wallet_location: str | EmptyType = Empty
+    """Location of Oracle Wallet"""
+    events: bool | EmptyType = Empty
+    """If True, enables Oracle events for FAN and RLB"""
+    externalauth: bool | EmptyType = Empty
+    """If True, uses external authentication"""
+    mode: AuthMode | EmptyType = Empty
+    """Session mode (SYSDBA, SYSOPER, etc.)"""
+    disable_oob: bool | EmptyType = Empty
+    """If True, disables Oracle out-of-band breaks"""
+    stmtcachesize: int | EmptyType = Empty
+    """Size of the statement cache"""
+    edition: str | EmptyType = Empty
+    """Edition name for edition-based redefinition"""
+    tag: str | EmptyType = Empty
+    """Connection pool tag"""
+    matchanytag: bool | EmptyType = Empty
+    """If True, allows connections with different tags"""
+    config_dir: str | EmptyType = Empty
+    """Directory containing Oracle configuration files"""
+    appcontext: list | EmptyType = Empty
+    """Application context list"""
+    shardingkey: list | EmptyType = Empty
+    """Sharding key list"""
+    supershardingkey: list | EmptyType = Empty
+    """Super sharding key list"""
+    debug_jdwp: str | EmptyType = Empty
+    """JDWP debugging string"""
+    connection_id_prefix: str | EmptyType = Empty
+    """Prefix for connection identifiers"""
+    ssl_context: Any | EmptyType = Empty
+    """SSL context for TCPS connections"""
+    sdu: int | EmptyType = Empty
+    """Session data unit size"""
+    pool_boundary: str | EmptyType = Empty
+    """Connection pool boundary (statement or transaction)"""
+    use_tcp_fast_open: bool | EmptyType = Empty
+    """If True, enables TCP Fast Open"""
+    ssl_version: ssl.TLSVersion | EmptyType = Empty
+    """SSL/TLS protocol version"""
+    handle: int | EmptyType = Empty
+    """Oracle service context handle"""
+
+
+@dataclass
+class OracleGenericDatabaseConfig(Generic[PoolT, ConnectionT], GenericDatabaseConfig):
+    """Oracle database Configuration.
+
+    This class provides the base configuration for Oracle database connections, extending
+    the generic database configuration with Oracle-specific settings. It supports both
+    thin and thick modes of the python-oracledb driver.([1](https://python-oracledb.readthedocs.io/en/latest/index.html))
+
+    The configuration supports all standard Oracle connection parameters and can be used
+    with both synchronous and asynchronous connections. It includes support for features
+    like Oracle Wallet, external authentication, connection pooling, and advanced security
+    options.([2](https://python-oracledb.readthedocs.io/en/latest/user_guide/tuning.html))
+    """

sqlspec/adapters/oracledb/config/_sync.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from oracledb import create_pool as oracledb_create_pool
+from oracledb.connection import Connection
+from oracledb.pool import ConnectionPool
+
+from sqlspec.adapters.oracledb.config._common import (
+    OracleGenericDatabaseConfig,
+    OracleGenericPoolConfig,
+)
+from sqlspec.exceptions import ImproperConfigurationError
+from sqlspec.typing import dataclass_to_dict
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+    from typing import Any
+
+__all__ = (
+    "OracleSyncDatabaseConfig",
+    "OracleSyncPoolConfig",
+)
+
+
+@dataclass
+class OracleSyncPoolConfig(OracleGenericPoolConfig[ConnectionPool, Connection]):
+    """Sync Oracle Pool Config"""
+
+
+@dataclass
+class OracleSyncDatabaseConfig(OracleGenericDatabaseConfig[ConnectionPool, Connection]):
+    """Oracle database Configuration."""
+
+    pool_config: OracleSyncPoolConfig | None = None
+    """Oracle Pool configuration"""
+    pool_instance: ConnectionPool | None = None
+    """Optional pool to use.
+
+    If set, the plugin will use the provided pool rather than instantiate one.
+    """
+
+    @property
+    def pool_config_dict(self) -> dict[str, Any]:
+        """Return the pool configuration as a dict.
+
+        Returns:
+            A string keyed dict of config kwargs for the Asyncpg :func:`create_pool <oracledb.pool.create_pool>`
+            function.
+        """
+        if self.pool_config:
+            return dataclass_to_dict(self.pool_config, exclude_empty=True, convert_nested=False)
+        msg = "'pool_config' methods can not be used when a 'pool_instance' is provided."
+        raise ImproperConfigurationError(msg)
+
+    def create_pool(self) -> ConnectionPool:
+        """Return a pool. If none exists yet, create one.
+
+        Returns:
+            Getter that returns the pool instance used by the plugin.
+        """
+        if self.pool_instance is not None:
+            return self.pool_instance
+
+        if self.pool_config is None:
+            msg = "One of 'pool_config' or 'pool_instance' must be provided."
+            raise ImproperConfigurationError(msg)
+
+        pool_config = self.pool_config_dict
+        self.pool_instance = oracledb_create_pool(**pool_config)
+        if self.pool_instance is None:
+            msg = "Could not configure the 'pool_instance'. Please check your configuration."
+            raise ImproperConfigurationError(msg)
+        return self.pool_instance
+
+    def provide_pool(self, *args: Any, **kwargs: Any) -> ConnectionPool:
+        """Create a pool instance.
+
+        Returns:
+            A Pool instance.
+        """
+        return self.create_pool()
+
+    @contextmanager
+    def provide_connection(self, *args: Any, **kwargs: Any) -> Generator[Connection, None, None]:
+        """Create a connection instance.
+
+        Returns:
+            A connection instance.
+        """
+        db_pool = self.provide_pool(*args, **kwargs)
+        with db_pool.acquire() as connection:
+            yield connection

sqlspec/adapters/psycopg/config/__init__.py

@@ -0,0 +1,9 @@
+from ._async import PsycoPgAsyncDatabaseConfig, PsycoPgAsyncPoolConfig
+from ._sync import PsycoPgSyncDatabaseConfig, PsycoPgSyncPoolConfig
+
+__all__ = (
+    "PsycoPgAsyncDatabaseConfig",
+    "PsycoPgAsyncPoolConfig",
+    "PsycoPgSyncDatabaseConfig",
+    "PsycoPgSyncPoolConfig",
+)

sqlspec/adapters/psycopg/config/_async.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from psycopg import AsyncConnection
+from psycopg_pool import AsyncConnectionPool
+
+from sqlspec.adapters.psycopg.config._common import (
+    PsycoPgGenericDatabaseConfig,
+    PsycoPgGenericPoolConfig,
+)
+from sqlspec.exceptions import ImproperConfigurationError
+from sqlspec.typing import dataclass_to_dict
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator, Awaitable
+    from typing import Any
+
+
+__all__ = (
+    "PsycoPgAsyncDatabaseConfig",
+    "PsycoPgAsyncPoolConfig",
+)
+
+
+@dataclass
+class PsycoPgAsyncPoolConfig(PsycoPgGenericPoolConfig[AsyncConnectionPool, AsyncConnection]):
+    """Async Psycopg Pool Config"""
+
+
+@dataclass
+class PsycoPgAsyncDatabaseConfig(PsycoPgGenericDatabaseConfig[AsyncConnectionPool, AsyncConnection]):
+    """Async Psycopg database Configuration."""
+
+    pool_config: PsycoPgAsyncPoolConfig | None = None
+    """Psycopg Pool configuration"""
+    pool_instance: AsyncConnectionPool | None = None
+    """Optional pool to use"""
+
+    @property
+    def pool_config_dict(self) -> dict[str, Any]:
+        """Return the pool configuration as a dict."""
+        if self.pool_config:
+            return dataclass_to_dict(self.pool_config, exclude_empty=True, convert_nested=False)
+        msg = "'pool_config' methods can not be used when a 'pool_instance' is provided."
+        raise ImproperConfigurationError(msg)
+
+    async def create_pool(self) -> AsyncConnectionPool:
+        """Create and return a connection pool."""
+        if self.pool_instance is not None:
+            return self.pool_instance
+
+        if self.pool_config is None:
+            msg = "One of 'pool_config' or 'pool_instance' must be provided."
+            raise ImproperConfigurationError(msg)
+
+        pool_config = self.pool_config_dict
+        self.pool_instance = AsyncConnectionPool(**pool_config)
+        if self.pool_instance is None:
+            msg = "Could not configure the 'pool_instance'. Please check your configuration."  # type: ignore[unreachable]
+            raise ImproperConfigurationError(msg)
+        return self.pool_instance
+
+    def provide_pool(self, *args: Any, **kwargs: Any) -> Awaitable[AsyncConnectionPool]:
+        """Create and return a connection pool."""
+        return self.create_pool()
+
+    @asynccontextmanager
+    async def provide_connection(self, *args: Any, **kwargs: Any) -> AsyncGenerator[AsyncConnection, None]:
+        """Create and provide a database connection."""
+        pool = await self.provide_pool(*args, **kwargs)
+        async with pool.connection() as connection:
+            yield connection