sqlspec 0.47.0__cp314-cp314-win_amd64.whl

sqlspec/adapters/oracledb/events/__init__.py

@@ -0,0 +1,16 @@
+"""Events helpers for the Oracle adapter."""
+
+from sqlspec.adapters.oracledb.events.backend import (
+    OracleAsyncAQEventBackend,
+    OracleSyncAQEventBackend,
+    create_event_backend,
+)
+from sqlspec.adapters.oracledb.events.store import OracleAsyncEventQueueStore, OracleSyncEventQueueStore
+
+__all__ = (
+    "OracleAsyncAQEventBackend",
+    "OracleAsyncEventQueueStore",
+    "OracleSyncAQEventBackend",
+    "OracleSyncEventQueueStore",
+    "create_event_backend",
+)

sqlspec/adapters/oracledb/events/_hub.py

@@ -0,0 +1,345 @@
+"""Persistent Oracle AQ queue-handle caches used by Oracle AQ event backends.
+
+Eliminates per-iteration session + queue handle acquisition. The hub holds a
+single dedicated connection per backend instance and caches one queue handle
+per subscribed channel. Each dequeue uses the cached handle and honors the
+caller's poll_interval (capped at the configured aq_wait_seconds ceiling).
+"""
+
+# pyright: reportPrivateUsage=false
+
+import asyncio
+import contextlib
+import logging
+import threading
+from math import ceil
+from typing import TYPE_CHECKING, Any
+
+from sqlspec.exceptions import EventChannelError, MissingDependencyError
+from sqlspec.utils.logging import get_logger, log_with_context
+
+if TYPE_CHECKING:
+    from sqlspec.adapters.oracledb.config import OracleAsyncConfig, OracleSyncConfig
+
+logger = get_logger("sqlspec.adapters.oracledb.events.hub")
+
+__all__ = ("OracleAsyncAQHub", "OracleSyncAQHub")
+
+
+_AQ_AVAILABLE = False
+OracleDatabaseError: Any
+
+try:  # pragma: no cover - optional dependency path
+    from sqlspec.adapters.oracledb._typing import AQMSG_INVISIBLE as _AQMSG_INVISIBLE
+    from sqlspec.adapters.oracledb._typing import AQMSG_PAYLOAD_TYPE_JSON as _AQMSG_PAYLOAD_TYPE_JSON
+    from sqlspec.adapters.oracledb._typing import AQMSG_VISIBLE as _AQMSG_VISIBLE
+    from sqlspec.adapters.oracledb._typing import DB_TYPE_JSON as _DB_TYPE_JSON
+    from sqlspec.adapters.oracledb._typing import AQDequeueOptions as _AQDequeueOptions
+    from sqlspec.adapters.oracledb._typing import DatabaseError as _OracleDatabaseErrorImported
+except ImportError:  # pragma: no cover - optional dependency path
+    _AQDequeueOptions = None
+    _AQMSG_INVISIBLE = None
+    _AQMSG_PAYLOAD_TYPE_JSON = None
+    _AQMSG_VISIBLE = None
+    _DB_TYPE_JSON = None
+    OracleDatabaseError = None
+else:  # pragma: no cover - optional dependency path
+    _AQ_AVAILABLE = True
+    OracleDatabaseError = _OracleDatabaseErrorImported
+
+AQDequeueOptions: Any = _AQDequeueOptions
+AQMSG_INVISIBLE: "int | None" = _AQMSG_INVISIBLE
+AQMSG_PAYLOAD_TYPE_JSON: Any = _AQMSG_PAYLOAD_TYPE_JSON
+AQMSG_VISIBLE: "int | None" = _AQMSG_VISIBLE
+DB_TYPE_JSON: Any = _DB_TYPE_JSON
+
+
+def _resolve_payload_type() -> Any:
+    """Pick the right driver constant for JSON payloads."""
+    if DB_TYPE_JSON is not None:
+        return DB_TYPE_JSON
+    return AQMSG_PAYLOAD_TYPE_JSON
+
+
+def _resolve_options(visibility: "int | None", default_visibility: "int | None", wait_seconds: float) -> Any:
+    """Build an AQDequeueOptions instance for the requested wait + visibility."""
+    if AQDequeueOptions is None:  # pragma: no cover - optional dependency path
+        msg = "oracledb AQDequeueOptions"
+        raise MissingDependencyError(msg, install_package="oracledb")
+    options = AQDequeueOptions()
+    options.wait = 0 if wait_seconds <= 0 else ceil(wait_seconds)
+    if visibility is not None:
+        options.visibility = visibility
+    elif default_visibility is not None:
+        options.visibility = default_visibility
+    return options
+
+
+def _channel_queue_name(template: str, channel: str) -> str:
+    """Apply a queue-name template (supports ``{channel}`` substitution)."""
+    if isinstance(template, str) and "{" in template:
+        with contextlib.suppress(Exception):
+            return template.format(channel=channel.upper())
+    return template
+
+
+def _resolve_wait_seconds(poll_interval: float, ceiling: int) -> float:
+    """Cap the caller's poll_interval at the configured aq_wait_seconds ceiling."""
+    interval = max(float(poll_interval), 0.0)
+    if ceiling <= 0:
+        return interval
+    return min(interval, float(ceiling))
+
+
+class OracleSyncAQHub:
+    """Per-channel persistent queue-handle cache for sync Oracle AQ."""
+
+    __slots__ = (
+        "_config",
+        "_default_visibility",
+        "_lock",
+        "_pool_destroying_registered",
+        "_queue_name_template",
+        "_queues",
+        "_session_cm",
+        "_session_driver",
+        "_shutting_down",
+        "_visibility",
+        "_wait_ceiling",
+    )
+
+    def __init__(
+        self,
+        config: "OracleSyncConfig",
+        *,
+        queue_name_template: str,
+        visibility: "int | None",
+        default_visibility: "int | None",
+        wait_ceiling: int,
+    ) -> None:
+        self._config = config
+        self._queue_name_template = queue_name_template
+        self._visibility = visibility
+        self._default_visibility = default_visibility
+        self._wait_ceiling = wait_ceiling
+        self._lock = threading.Lock()
+        self._queues: dict[str, Any] = {}
+        self._session_cm: Any | None = None
+        self._session_driver: Any | None = None
+        self._shutting_down = False
+        self._pool_destroying_registered = False
+
+    def subscribe(self, channel: str) -> None:
+        with self._lock:
+            self._ensure_handle_locked(channel)
+
+    def dequeue(self, channel: str, poll_interval: float) -> "Any | None":
+        with self._lock:
+            if self._shutting_down:
+                return None
+            queue = self._ensure_handle_locked(channel)
+            driver = self._session_driver
+            if driver is None:
+                return None
+            wait_seconds = _resolve_wait_seconds(poll_interval, self._wait_ceiling)
+            options = _resolve_options(self._visibility, self._default_visibility, wait_seconds)
+            try:
+                message = queue.deqone(options=options)
+            except Exception as error:  # pragma: no cover - driver surfaced runtime
+                if OracleDatabaseError is None or not isinstance(error, OracleDatabaseError):
+                    raise
+                log_with_context(
+                    logger,
+                    logging.WARNING,
+                    "event.receive",
+                    adapter_name="oracledb",
+                    backend_name="advanced_queue",
+                    mode="sync",
+                    error_type=type(error).__name__,
+                    status="failed",
+                )
+                with contextlib.suppress(Exception):
+                    driver.rollback()
+                return None
+            if message is None:
+                with contextlib.suppress(Exception):
+                    driver.rollback()
+                return None
+            payload = message.payload
+            with contextlib.suppress(Exception):
+                driver.commit()
+        return payload
+
+    def shutdown(self) -> None:
+        with self._lock:
+            if self._shutting_down:
+                return
+            self._shutting_down = True
+            session_cm = self._session_cm
+            self._queues.clear()
+            self._session_cm = None
+            self._session_driver = None
+        if session_cm is not None:
+            with contextlib.suppress(Exception):
+                session_cm.__exit__(None, None, None)
+        self._shutting_down = False
+
+    def _ensure_handle_locked(self, channel: str) -> Any:
+        cached = self._queues.get(channel)
+        if cached is not None:
+            return cached
+        if not _AQ_AVAILABLE:  # pragma: no cover - optional dependency path
+            msg = "oracledb"
+            raise MissingDependencyError(msg, install_package="oracledb")
+        driver = self._session_driver
+        if driver is None:
+            session_cm = self._config.provide_session()
+            driver = session_cm.__enter__()
+            self._session_cm = session_cm
+            self._session_driver = driver
+            self._register_pool_destroying()
+        connection = getattr(driver, "connection", None)
+        if connection is None:
+            msg = "Oracle driver does not expose a raw connection"
+            raise EventChannelError(msg)
+        queue_name = _channel_queue_name(self._queue_name_template, channel)
+        queue = connection.queue(queue_name, payload_type=_resolve_payload_type())
+        self._queues[channel] = queue
+        return queue
+
+    def _register_pool_destroying(self) -> None:
+        if self._pool_destroying_registered:
+            return
+        runtime = self._config.get_observability_runtime()
+        runtime.register_lifecycle_hook("on_pool_destroying", self._pool_destroying_hook)
+        self._pool_destroying_registered = True
+
+    def _pool_destroying_hook(self, _context: "dict[str, Any]") -> None:
+        self.shutdown()
+
+
+class OracleAsyncAQHub:
+    """Per-channel persistent queue-handle cache for async Oracle AQ."""
+
+    __slots__ = (
+        "_config",
+        "_default_visibility",
+        "_lock",
+        "_pool_destroying_registered",
+        "_queue_name_template",
+        "_queues",
+        "_session_cm",
+        "_session_driver",
+        "_shutting_down",
+        "_visibility",
+        "_wait_ceiling",
+    )
+
+    def __init__(
+        self,
+        config: "OracleAsyncConfig",
+        *,
+        queue_name_template: str,
+        visibility: "int | None",
+        default_visibility: "int | None",
+        wait_ceiling: int,
+    ) -> None:
+        self._config = config
+        self._queue_name_template = queue_name_template
+        self._visibility = visibility
+        self._default_visibility = default_visibility
+        self._wait_ceiling = wait_ceiling
+        self._lock = asyncio.Lock()
+        self._queues: dict[str, Any] = {}
+        self._session_cm: Any | None = None
+        self._session_driver: Any | None = None
+        self._shutting_down = False
+        self._pool_destroying_registered = False
+
+    async def subscribe(self, channel: str) -> None:
+        async with self._lock:
+            await self._ensure_handle_locked(channel)
+
+    async def dequeue(self, channel: str, poll_interval: float) -> "Any | None":
+        async with self._lock:
+            if self._shutting_down:
+                return None
+            queue = await self._ensure_handle_locked(channel)
+            driver = self._session_driver
+            if driver is None:
+                return None
+            wait_seconds = _resolve_wait_seconds(poll_interval, self._wait_ceiling)
+            options = _resolve_options(self._visibility, self._default_visibility, wait_seconds)
+            try:
+                message = await queue.deqone(options=options)
+            except Exception as error:  # pragma: no cover - driver surfaced runtime
+                if OracleDatabaseError is None or not isinstance(error, OracleDatabaseError):
+                    raise
+                log_with_context(
+                    logger,
+                    logging.WARNING,
+                    "event.receive",
+                    adapter_name="oracledb",
+                    backend_name="advanced_queue",
+                    mode="async",
+                    error_type=type(error).__name__,
+                    status="failed",
+                )
+                with contextlib.suppress(Exception):
+                    await driver.rollback()
+                return None
+            if message is None:
+                with contextlib.suppress(Exception):
+                    await driver.rollback()
+                return None
+            payload = message.payload
+            with contextlib.suppress(Exception):
+                await driver.commit()
+        return payload
+
+    async def shutdown(self) -> None:
+        async with self._lock:
+            if self._shutting_down:
+                return
+            self._shutting_down = True
+            session_cm = self._session_cm
+            self._queues.clear()
+            self._session_cm = None
+            self._session_driver = None
+        if session_cm is not None:
+            with contextlib.suppress(Exception):
+                await session_cm.__aexit__(None, None, None)
+        self._shutting_down = False
+
+    async def _ensure_handle_locked(self, channel: str) -> Any:
+        cached = self._queues.get(channel)
+        if cached is not None:
+            return cached
+        if not _AQ_AVAILABLE:  # pragma: no cover - optional dependency path
+            msg = "oracledb"
+            raise MissingDependencyError(msg, install_package="oracledb")
+        driver = self._session_driver
+        if driver is None:
+            session_cm = self._config.provide_session()
+            driver = await session_cm.__aenter__()
+            self._session_cm = session_cm
+            self._session_driver = driver
+            self._register_pool_destroying()
+        connection = getattr(driver, "connection", None)
+        if connection is None:
+            msg = "Oracle driver does not expose a raw connection"
+            raise EventChannelError(msg)
+        queue_name = _channel_queue_name(self._queue_name_template, channel)
+        queue = connection.queue(queue_name, payload_type=_resolve_payload_type())
+        self._queues[channel] = queue
+        return queue
+
+    def _register_pool_destroying(self) -> None:
+        if self._pool_destroying_registered:
+            return
+        runtime = self._config.get_observability_runtime()
+        runtime.register_lifecycle_hook("on_pool_destroying", self._pool_destroying_hook)
+        self._pool_destroying_registered = True
+
+    def _pool_destroying_hook(self, _context: "dict[str, Any]") -> "Any":
+        return self.shutdown()

sqlspec/adapters/oracledb/events/backend.py

@@ -0,0 +1,300 @@
+"""Oracle Advanced Queuing backend for EventChannel."""
+
+import contextlib
+import logging
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+from sqlspec.adapters.oracledb.events._hub import OracleAsyncAQHub, OracleSyncAQHub
+from sqlspec.exceptions import ImproperConfigurationError, MissingDependencyError
+from sqlspec.extensions.events import EventMessage, parse_event_timestamp
+from sqlspec.utils.logging import get_logger, log_with_context
+from sqlspec.utils.uuids import uuid4
+
+if TYPE_CHECKING:
+    from sqlspec.adapters.oracledb.config import OracleAsyncConfig, OracleSyncConfig
+
+_ORACLEDB_AVAILABLE = False
+
+try:  # pragma: no cover - optional dependency path
+    from sqlspec.adapters.oracledb._typing import AQMSG_INVISIBLE as _AQMSG_INVISIBLE
+    from sqlspec.adapters.oracledb._typing import AQMSG_PAYLOAD_TYPE_JSON as _AQMSG_PAYLOAD_TYPE_JSON
+    from sqlspec.adapters.oracledb._typing import AQMSG_VISIBLE as _AQMSG_VISIBLE
+    from sqlspec.adapters.oracledb._typing import DB_TYPE_JSON as _DB_TYPE_JSON
+    from sqlspec.adapters.oracledb._typing import AQDequeueOptions as _AQDequeueOptions
+except ImportError:  # pragma: no cover - optional dependency path
+    _AQDequeueOptions = None
+    _AQMSG_INVISIBLE = None
+    _AQMSG_PAYLOAD_TYPE_JSON = None
+    _AQMSG_VISIBLE = None
+    _DB_TYPE_JSON = None
+else:  # pragma: no cover - optional dependency path
+    _ORACLEDB_AVAILABLE = True
+
+AQDequeueOptions: Any = _AQDequeueOptions
+AQMSG_INVISIBLE: "int | None" = _AQMSG_INVISIBLE
+AQMSG_PAYLOAD_TYPE_JSON: Any = _AQMSG_PAYLOAD_TYPE_JSON
+AQMSG_VISIBLE: "int | None" = _AQMSG_VISIBLE
+DB_TYPE_JSON: Any = _DB_TYPE_JSON
+
+logger = get_logger("sqlspec.events.oracle")
+
+__all__ = ("OracleAsyncAQEventBackend", "OracleSyncAQEventBackend", "create_event_backend")
+
+_DEFAULT_QUEUE_NAME = "SQLSPEC_EVENTS_QUEUE"
+_DEFAULT_VISIBILITY: "int | None"
+_VISIBILITY_LOOKUP: "dict[str, int]"
+
+if AQDequeueOptions is None:
+    _DEFAULT_VISIBILITY = None
+    _VISIBILITY_LOOKUP = {}
+else:
+    _DEFAULT_VISIBILITY = AQMSG_VISIBLE
+    _VISIBILITY_LOOKUP = {}
+    if _DEFAULT_VISIBILITY is not None:
+        _VISIBILITY_LOOKUP["AQMSG_VISIBLE"] = _DEFAULT_VISIBILITY
+    if AQMSG_INVISIBLE is not None:
+        _VISIBILITY_LOOKUP["AQMSG_INVISIBLE"] = AQMSG_INVISIBLE
+
+
+def _resolve_visibility_setting(value: Any) -> "int | None":
+    if value is None:
+        return None
+    if isinstance(value, int):
+        return value
+    if not isinstance(value, str):
+        msg = f"Invalid aq_visibility value: {value!r}. Expected int or AQMSG_* string."
+        raise ImproperConfigurationError(msg)
+    visibility = _VISIBILITY_LOOKUP.get(value)
+    if visibility is None:
+        msg = f"Invalid aq_visibility value: {value!r}. Expected one of: {sorted(_VISIBILITY_LOOKUP)}"
+        raise ImproperConfigurationError(msg)
+    return visibility
+
+
+class OracleSyncAQEventBackend:
+    """Oracle AQ backend for sync Oracle adapters."""
+
+    __slots__ = ("_config", "_hub", "_queue_name", "_runtime", "_visibility", "_wait_seconds")
+
+    supports_sync = True
+    supports_async = False
+    backend_name = "advanced_queue"
+
+    def __init__(self, config: "OracleSyncConfig", settings: "dict[str, Any] | None" = None) -> None:
+        if "oracledb" not in type(config).__module__:
+            msg = "Oracle AQ backend requires an Oracle adapter"
+            raise ImproperConfigurationError(msg)
+        if config.is_async:
+            msg = "OracleSyncAQEventBackend requires a sync adapter"
+            raise ImproperConfigurationError(msg)
+        if not _ORACLEDB_AVAILABLE:
+            msg = "oracledb"
+            raise MissingDependencyError(msg, install_package="oracledb")
+        self._config = config
+        self._runtime = config.get_observability_runtime()
+        settings = settings or {}
+        self._queue_name = settings.get("aq_queue", _DEFAULT_QUEUE_NAME)
+        self._visibility: int | None = _resolve_visibility_setting(settings.get("aq_visibility"))
+        self._wait_seconds: int = int(settings.get("aq_wait_seconds", 5))
+        self._hub: OracleSyncAQHub | None = None
+        log_with_context(
+            logger,
+            logging.DEBUG,
+            "event.listen",
+            adapter_name="oracledb",
+            backend_name=self.backend_name,
+            mode="sync",
+            status="backend_ready",
+        )
+
+    def publish(self, channel: str, payload: "dict[str, Any]", metadata: "dict[str, Any] | None" = None) -> str:
+        event_id = uuid4().hex
+        envelope = _build_envelope(channel, event_id, payload, metadata)
+        session_cm = self._config.provide_session()
+        with session_cm as driver:
+            connection = driver.connection
+            if connection is None:
+                msg = "Oracle driver does not expose a raw connection"
+                raise ImproperConfigurationError(msg)
+            queue = _get_publish_queue(connection, channel, self._queue_name)
+            queue.enqone(payload=envelope)
+            driver.commit()
+        self._runtime.increment_metric("events.publish.native")
+        return event_id
+
+    def dequeue(self, channel: str, poll_interval: float) -> "EventMessage | None":
+        hub = self._ensure_hub()
+        payload = hub.dequeue(channel, poll_interval)
+        if payload is None:
+            return None
+        return _parse_message(channel, payload)
+
+    def ack(self, _event_id: str) -> None:
+        """Acknowledge an event (no-op for Oracle AQ - committed at dequeue time)."""
+        self._runtime.increment_metric("events.ack")
+
+    def nack(self, _event_id: str) -> None:
+        """Return an event to the queue (no-op for Oracle AQ)."""
+
+    def shutdown(self) -> None:
+        hub = self._hub
+        if hub is not None:
+            self._hub = None
+            hub.shutdown()
+
+    def _ensure_hub(self) -> OracleSyncAQHub:
+        if self._hub is None:
+            self._hub = OracleSyncAQHub(
+                self._config,
+                queue_name_template=self._queue_name,
+                visibility=self._visibility,
+                default_visibility=_DEFAULT_VISIBILITY,
+                wait_ceiling=self._wait_seconds,
+            )
+        return self._hub
+
+
+class OracleAsyncAQEventBackend:
+    """Oracle AQ backend for async Oracle adapters."""
+
+    __slots__ = ("_config", "_hub", "_queue_name", "_runtime", "_visibility", "_wait_seconds")
+
+    supports_sync = False
+    supports_async = True
+    backend_name = "advanced_queue"
+
+    def __init__(self, config: "OracleAsyncConfig", settings: "dict[str, Any] | None" = None) -> None:
+        if "oracledb" not in type(config).__module__:
+            msg = "Oracle AQ backend requires an Oracle adapter"
+            raise ImproperConfigurationError(msg)
+        if not config.is_async:
+            msg = "OracleAsyncAQEventBackend requires an async adapter"
+            raise ImproperConfigurationError(msg)
+        if not _ORACLEDB_AVAILABLE:
+            msg = "oracledb"
+            raise MissingDependencyError(msg, install_package="oracledb")
+        self._config = config
+        self._runtime = config.get_observability_runtime()
+        settings = settings or {}
+        self._queue_name = settings.get("aq_queue", _DEFAULT_QUEUE_NAME)
+        self._visibility: int | None = _resolve_visibility_setting(settings.get("aq_visibility"))
+        self._wait_seconds: int = int(settings.get("aq_wait_seconds", 5))
+        self._hub: OracleAsyncAQHub | None = None
+
+    async def publish(self, channel: str, payload: "dict[str, Any]", metadata: "dict[str, Any] | None" = None) -> str:
+        event_id = uuid4().hex
+        envelope = _build_envelope(channel, event_id, payload, metadata)
+        session_cm = self._config.provide_session()
+        async with session_cm as driver:
+            connection = driver.connection
+            if connection is None:
+                msg = "Oracle driver does not expose a raw connection"
+                raise ImproperConfigurationError(msg)
+            queue = _get_publish_queue(connection, channel, self._queue_name)
+            await queue.enqone(payload=envelope)
+            await driver.commit()
+        self._runtime.increment_metric("events.publish.native")
+        return event_id
+
+    async def dequeue(self, channel: str, poll_interval: float) -> "EventMessage | None":
+        hub = self._ensure_hub()
+        payload = await hub.dequeue(channel, poll_interval)
+        if payload is None:
+            return None
+        return _parse_message(channel, payload)
+
+    async def ack(self, _event_id: str) -> None:
+        """Acknowledge an event (no-op for Oracle AQ - committed at dequeue time)."""
+        self._runtime.increment_metric("events.ack")
+
+    async def nack(self, _event_id: str) -> None:
+        """Return an event to the queue (no-op for Oracle AQ)."""
+
+    async def shutdown(self) -> None:
+        hub = self._hub
+        if hub is not None:
+            self._hub = None
+            await hub.shutdown()
+
+    def _ensure_hub(self) -> OracleAsyncAQHub:
+        if self._hub is None:
+            self._hub = OracleAsyncAQHub(
+                self._config,
+                queue_name_template=self._queue_name,
+                visibility=self._visibility,
+                default_visibility=_DEFAULT_VISIBILITY,
+                wait_ceiling=self._wait_seconds,
+            )
+        return self._hub
+
+
+def _get_publish_queue(connection: Any, channel: str, queue_name: str) -> Any:
+    """Acquire a queue handle for a one-shot publish."""
+    if not _ORACLEDB_AVAILABLE:
+        msg = "oracledb"
+        raise MissingDependencyError(msg, install_package="oracledb")
+    if isinstance(queue_name, str) and "{" in queue_name:
+        with contextlib.suppress(Exception):
+            queue_name = queue_name.format(channel=channel.upper())
+    payload_type = DB_TYPE_JSON if DB_TYPE_JSON is not None else AQMSG_PAYLOAD_TYPE_JSON
+    return connection.queue(queue_name, payload_type=payload_type)
+
+
+def _build_envelope(
+    channel: str, event_id: str, payload: "dict[str, Any]", metadata: "dict[str, Any] | None"
+) -> "dict[str, Any]":
+    """Build event envelope for Oracle AQ."""
+    return {
+        "channel": channel,
+        "event_id": event_id,
+        "payload": payload,
+        "metadata": metadata,
+        "published_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def _parse_message(channel: str, payload: Any) -> EventMessage:
+    """Parse Oracle AQ message payload into EventMessage."""
+    if not isinstance(payload, dict):
+        payload = {"payload": payload}
+    payload_channel = payload.get("channel")
+    message_channel = payload_channel if isinstance(payload_channel, str) else channel
+    event_id = payload.get("event_id", uuid4().hex)
+    body = payload.get("payload")
+    if not isinstance(body, dict):
+        body = {"value": body}
+    metadata = payload.get("metadata")
+    if not (metadata is None or isinstance(metadata, dict)):
+        metadata = {"value": metadata}
+    timestamp = parse_event_timestamp(payload.get("published_at"))
+    return EventMessage(
+        event_id=event_id,
+        channel=message_channel,
+        payload=body,
+        metadata=metadata,
+        attempts=0,
+        available_at=timestamp,
+        lease_expires_at=None,
+        created_at=timestamp,
+    )
+
+
+def create_event_backend(
+    config: "OracleAsyncConfig | OracleSyncConfig", backend_name: str, extension_settings: "dict[str, Any]"
+) -> "OracleSyncAQEventBackend | OracleAsyncAQEventBackend | None":
+    """Factory used by EventChannel to create the Oracle AQ backend."""
+    is_async = config.is_async
+    match (backend_name, is_async):
+        case ("advanced_queue", False):
+            try:
+                return OracleSyncAQEventBackend(config, extension_settings)  # type: ignore[arg-type]
+            except (ImproperConfigurationError, MissingDependencyError):
+                return None
+        case ("advanced_queue", True):
+            try:
+                return OracleAsyncAQEventBackend(config, extension_settings)  # type: ignore[arg-type]
+            except (ImproperConfigurationError, MissingDependencyError):
+                return None
+        case _:
+            return None