sqlspec 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

sqlspec/adapters/duckdb/config.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from sqlspec.config import GenericDatabaseConfig
+from sqlspec.exceptions import ImproperConfigurationError
+from sqlspec.utils.dataclass import simple_asdict
+from sqlspec.utils.empty import Empty, EmptyType
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from duckdb import DuckDBPyConnection
+
+__all__ = ("DuckDBConfig",)
+
+
+@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
+    """
+
+    @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 = simple_asdict(self, exclude_empty=True, 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.
+
+        Returns:
+            A new DuckDB connection instance.
+
+        Raises:
+            ImproperConfigurationError: If the connection could not be established.
+        """
+        import duckdb
+
+        try:
+            return duckdb.connect(**self.connection_config_dict)
+        except Exception as e:
+            msg = f"Could not configure the DuckDB connection. Error: {e!s}"
+            raise ImproperConfigurationError(msg) from e
+
+    @contextmanager
+    def lifespan(self, *args: Any, **kwargs: Any) -> Generator[None, None, None]:
+        """Manage the lifecycle of a database connection.
+
+        Yields:
+            None
+
+        Raises:
+            ImproperConfigurationError: If the connection could not be established.
+        """
+        connection = self.create_connection()
+        try:
+            yield
+        finally:
+            connection.close()
+
+    @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,98 @@
+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.utils.dataclass import simple_asdict
+
+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"""
+
+    @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 simple_asdict(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
+
+    @asynccontextmanager
+    async def lifespan(self, *args: Any, **kwargs) -> AsyncGenerator[None, None]:
+        db_pool = await self.create_pool()
+        try:
+            yield
+        finally:
+            await db_pool.close(force=True)
+
+    def provide_pool(self, *args: Any, **kwargs) -> 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.utils.empty 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.utils.empty 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,102 @@
+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.utils.dataclass import simple_asdict
+
+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 simple_asdict(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 lifespan(self, *args: Any, **kwargs: Any) -> Generator[None, None, None]:
+        db_pool = self.create_pool()
+        try:
+            yield
+        finally:
+            db_pool.close()
+
+    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,84 @@
+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.utils.dataclass import simple_asdict
+
+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 simple_asdict(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
+
+    @asynccontextmanager
+    async def lifespan(self, *args: Any, **kwargs: Any) -> AsyncGenerator[None, None]:
+        """Manage the lifecycle of the connection pool."""
+        pool = await self.create_pool()
+        try:
+            yield
+        finally:
+            await pool.close()
+
+    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

sqlspec/adapters/psycopg/config/_common.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+from sqlspec.config import GenericDatabaseConfig, GenericPoolConfig
+from sqlspec.utils.empty import Empty
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from typing import Any
+
+    from psycopg import AsyncConnection, Connection
+    from psycopg_pool import AsyncConnectionPool, ConnectionPool
+
+    from sqlspec.utils.empty import EmptyType
+
+__all__ = (
+    "PsycoPgGenericDatabaseConfig",
+    "PsycoPgGenericPoolConfig",
+)
+
+
+ConnectionT = TypeVar("ConnectionT", bound="Connection | AsyncConnection")
+PoolT = TypeVar("PoolT", bound="ConnectionPool | AsyncConnectionPool")
+
+
+@dataclass
+class PsycoPgGenericPoolConfig(Generic[PoolT, ConnectionT], GenericPoolConfig):
+    """Configuration for Psycopg connection pools.
+
+    This class provides configuration options for both synchronous and asynchronous Psycopg
+    database connection pools. It supports all standard Psycopg connection parameters and pool-specific
+    settings.([1](https://www.psycopg.org/psycopg3/docs/api/pool.html))
+    """
+
+    conninfo: str | EmptyType = Empty
+    """Connection string in libpq format"""
+    kwargs: dict[str, Any] | EmptyType = Empty
+    """Additional connection parameters"""
+    min_size: int | EmptyType = Empty
+    """Minimum number of connections in the pool"""
+    max_size: int | EmptyType = Empty
+    """Maximum number of connections in the pool"""
+    name: str | EmptyType = Empty
+    """Name of the connection pool"""
+    timeout: float | EmptyType = Empty
+    """Timeout for acquiring connections"""
+    max_waiting: int | EmptyType = Empty
+    """Maximum number of waiting clients"""
+    max_lifetime: float | EmptyType = Empty
+    """Maximum connection lifetime"""
+    max_idle: float | EmptyType = Empty
+    """Maximum idle time for connections"""
+    reconnect_timeout: float | EmptyType = Empty
+    """Time between reconnection attempts"""
+    num_workers: int | EmptyType = Empty
+    """Number of background workers"""
+    configure: Callable[[ConnectionT], None] | EmptyType = Empty
+    """Callback to configure new connections"""
+
+
+@dataclass
+class PsycoPgGenericDatabaseConfig(Generic[PoolT, ConnectionT], GenericDatabaseConfig):
+    """Psycopg database Configuration.
+
+    This class provides the base configuration for Psycopg database connections, extending
+    the generic database configuration with Psycopg-specific settings.([1](https://www.psycopg.org/psycopg3/docs/api/connections.html))
+
+    The configuration supports all standard Psycopg connection parameters and can be used
+    with both synchronous and asynchronous connections.([2](https://www.psycopg.org/psycopg3/docs/api/connections.html))
+    """