opteryx-sqlalchemy 0.0.0__py3-none-any.whl

opteryx_sqlalchemy-0.0.0.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: opteryx-sqlalchemy
+Version: 0.0.0
+Summary: Opteryx SQLAlchemy Dialect
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: brotli-asgi
+Requires-Dist: python-jose[cryptography]==3.3.0
+Requires-Dist: cryptography>=40.0.0
+Requires-Dist: requests>=2.30.0
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: sqlalchemy>=2.0.0
+Dynamic: license-file

opteryx_sqlalchemy-0.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+opteryx_sqlalchemy-0.0.0.dist-info/licenses/LICENSE,sha256=m8Z1IUiQRdgLd9_9LtMRjZSStEy0pZXJqy_2KTv14r4,11341
+sqlalchemy_dialect/__init__.py,sha256=5OAksQuB-yEkNv9DQO3Qet149Spdj5Fb5rAkJereeXw,491
+sqlalchemy_dialect/dbapi.py,sha256=LXBSHG1h0nBZEdqZm593hc7fbfzu0_OIUdFkCn85h4M,22683
+sqlalchemy_dialect/dialect.py,sha256=pFE_6OrwurpQLR-BtF40bYqoc1dzQEEho_oSyodLApc,10573
+opteryx_sqlalchemy-0.0.0.dist-info/METADATA,sha256=QHwEv2t3xLv3lPmYE5hutvlxbznUyD71_isLaknvNGk,381
+opteryx_sqlalchemy-0.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+opteryx_sqlalchemy-0.0.0.dist-info/entry_points.txt,sha256=bli1cTeTUJrjjOE1a5Frpz2WHJsn8k4sOOC7yjvIPPo,74
+opteryx_sqlalchemy-0.0.0.dist-info/top_level.txt,sha256=MXcCVk91HI49RJztG1b06V8eU0kEFraCdIxvtJb1cTQ,19
+opteryx_sqlalchemy-0.0.0.dist-info/RECORD,,

opteryx_sqlalchemy-0.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

opteryx_sqlalchemy-0.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[sqlalchemy.dialects]
+opteryx = sqlalchemy_dialect.dialect:OptetyxDialect

opteryx_sqlalchemy-0.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Justin Joyce
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

opteryx_sqlalchemy-0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sqlalchemy_dialect

sqlalchemy_dialect/__init__.py

@@ -0,0 +1,18 @@
+"""SQLAlchemy dialect for Opteryx data service.
+
+This module provides a SQLAlchemy dialect that connects to the Opteryx
+data service via its HTTP API, enabling use of SQLAlchemy's ORM and
+SQL expression language with Opteryx.
+
+Usage:
+    from sqlalchemy import create_engine
+
+    # Connect to Opteryx data service
+    engine = create_engine(
+        "opteryx://user:password@data.opteryx.app:443/default?ssl=true"
+    )
+"""
+
+from .dialect import OptetyxDialect
+
+__all__ = ["OptetyxDialect"]

sqlalchemy_dialect/dbapi.py

@@ -0,0 +1,651 @@
+"""DBAPI 2.0 (PEP 249) compliant interface for Opteryx data service.
+
+This module implements a minimal DBAPI 2.0 interface that communicates
+with the Opteryx data service via HTTP. It provides Connection and Cursor
+classes that translate SQL queries into HTTP requests.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Optional
+from typing import Sequence
+from typing import Tuple
+from typing import Union
+from urllib.parse import urljoin
+
+import requests
+
+# Module globals required by PEP 249
+apilevel = "2.0"
+threadsafety = 1  # Threads may share the module, but not connections
+paramstyle = "named"  # Named style: WHERE name=:name
+
+
+class Error(Exception):
+    """Base exception for DBAPI errors."""
+
+
+class Warning(Exception):  # noqa: A001
+    """Warning exception."""
+
+
+class InterfaceError(Error):
+    """Exception for interface errors."""
+
+
+class DatabaseError(Error):
+    """Exception for database errors."""
+
+
+class DataError(DatabaseError):
+    """Exception for data errors."""
+
+
+class OperationalError(DatabaseError):
+    """Exception for operational errors."""
+
+
+class IntegrityError(DatabaseError):
+    """Exception for integrity constraint errors."""
+
+
+class InternalError(DatabaseError):
+    """Exception for internal errors."""
+
+
+class ProgrammingError(DatabaseError):
+    """Exception for programming errors."""
+
+
+class NotSupportedError(DatabaseError):
+    """Exception for not supported operations."""
+
+
+# Type constructors (required by PEP 249)
+def Date(year: int, month: int, day: int) -> str:
+    """Construct a date value."""
+    return f"{year:04d}-{month:02d}-{day:02d}"
+
+
+def Time(hour: int, minute: int, second: int) -> str:
+    """Construct a time value."""
+    return f"{hour:02d}:{minute:02d}:{second:02d}"
+
+
+def Timestamp(year: int, month: int, day: int, hour: int, minute: int, second: int) -> str:
+    """Construct a timestamp value."""
+    return f"{year:04d}-{month:02d}-{day:02d} {hour:02d}:{minute:02d}:{second:02d}"
+
+
+def Binary(string: bytes) -> bytes:
+    """Construct a binary value."""
+    return string
+
+
+STRING = str
+BINARY = bytes
+NUMBER = float
+DATETIME = str
+ROWID = str
+
+
+class Cursor:
+    """DBAPI 2.0 Cursor implementation for Opteryx."""
+
+    def __init__(self, connection: "Connection") -> None:
+        self._connection = connection
+        self._jwt_token: Optional[str] = None
+        self._description: Optional[
+            List[Tuple[str, Any, None, None, None, None, Optional[bool]]]
+        ] = None
+        self._rowcount = -1
+        self._rows: List[Tuple[Any, ...]] = []
+        self._row_index = 0
+        self._arraysize = 1
+        self._closed = False
+        self._statement_handle: Optional[str] = None
+
+        # Try to authenticate using client credentials (client credentials flow)
+        # client_id is connection._username and client_secret is connection._token
+        try:
+            username = getattr(self._connection, "_username", None)
+            secret = getattr(self._connection, "_token", None)
+            if username and secret:
+                host = getattr(self._connection, "_host", "localhost")
+                # Normalize domain and build auth host (auth.domain)
+                try:
+                    domain = self._connection._normalize_domain(host)
+                except Exception:
+                    domain = host
+                # Only add auth. prefix when domain looks like a DNS name (not 'localhost')
+                if "." in domain and not domain.startswith("localhost"):
+                    auth_host = f"auth.{domain}"
+                else:
+                    auth_host = domain
+                scheme = "https" if getattr(self._connection, "_ssl", False) else "http"
+                auth_url = f"{scheme}://{auth_host}/token"
+
+                # Build form-encoded payload
+                payload = {
+                    "grant_type": "client_credentials",
+                    "client_id": username,
+                    "client_secret": secret,
+                }
+                # Use the connection session for auth so auth header set for all subsequent calls
+                sess = getattr(self._connection, "_session", requests.Session())
+                headers = {
+                    "accept": "application/json",
+                    "Content-Type": "application/x-www-form-urlencoded",
+                }
+                resp = sess.post(
+                    auth_url,
+                    data=payload,
+                    headers=headers,
+                    timeout=getattr(self._connection, "_timeout", 30),
+                )
+                resp.raise_for_status()
+                body = resp.json() if resp.text else {}
+                token = body.get("access_token") or body.get("token") or body.get("jwt")
+                if token:
+                    self._jwt_token = token
+                    # Set Authorization header for subsequent requests via the connection session
+                    try:
+                        self._connection._session.headers["Authorization"] = f"Bearer {token}"
+                    except Exception:
+                        # If connection session is not available or some other issue, ignore gracefully
+                        pass
+        except requests.exceptions.RequestException:
+            # Authentication failed — don't raise here; we will attempt queries without the JWT
+            self._jwt_token = None
+        except Exception:
+            # Any unexpected failure in auth should not crash cursor creation
+            self._jwt_token = None
+
+    @property
+    def description(
+        self,
+    ) -> Optional[List[Tuple[str, Any, None, None, None, None, Optional[bool]]]]:
+        """Column description as required by PEP 249."""
+        return self._description
+
+    @property
+    def rowcount(self) -> int:
+        """Number of rows affected by the last operation."""
+        return self._rowcount
+
+    @property
+    def arraysize(self) -> int:
+        """Number of rows to fetch at a time."""
+        return self._arraysize
+
+    @arraysize.setter
+    def arraysize(self, value: int) -> None:
+        self._arraysize = value
+
+    def close(self) -> None:
+        """Close the cursor."""
+        self._closed = True
+        self._rows = []
+        self._description = None
+
+    def _check_closed(self) -> None:
+        """Raise exception if cursor is closed."""
+        if self._closed:
+            raise ProgrammingError("Cursor is closed")
+
+    def execute(
+        self,
+        operation: str,
+        parameters: Optional[Union[Dict[str, Any], Sequence[Any]]] = None,
+    ) -> "Cursor":
+        """Execute a SQL statement.
+
+        Args:
+            operation: SQL statement to execute
+            parameters: Optional parameters for the statement
+
+        Returns:
+            Self for method chaining
+        """
+        self._check_closed()
+        self._rows = []
+        self._row_index = 0
+        self._description = None
+        self._rowcount = -1
+
+        # Convert sequence parameters to dict if needed
+        params_dict: Optional[Dict[str, Any]] = None
+        if parameters is not None:
+            if isinstance(parameters, dict):
+                params_dict = parameters
+            else:
+                # Convert positional to named parameters
+                params_dict = {f"p{i}": v for i, v in enumerate(parameters)}
+                # Replace ? placeholders with :p0, :p1, etc.
+                for i in range(len(parameters)):
+                    operation = operation.replace("?", f":p{i}", 1)
+
+        # Submit the statement
+        response = self._connection._submit_statement(operation, params_dict)
+        self._statement_handle = response.get("execution_id")
+
+        if not self._statement_handle:
+            raise DatabaseError("No statement handle returned from server")
+
+        # Poll for completion
+        self._poll_for_results()
+
+        return self
+
+    def _poll_for_results(self) -> None:
+        """Poll the server until statement execution completes."""
+        if not self._statement_handle:
+            return
+
+        max_wait = 300  # Maximum wait time in seconds
+        poll_interval = 0.5
+        elapsed = 0.0
+
+        while elapsed < max_wait:
+            status = self._connection._get_statement_status(self._statement_handle)
+            raw_state = status.get("status")
+
+            if isinstance(raw_state, dict):
+                state_value = raw_state.get("state")
+                status_details = raw_state
+            else:
+                state_value = raw_state
+                status_details = {}
+
+            if not state_value:
+                state_value = status.get("state")
+
+            normalized_state = (state_value or "UNKNOWN").upper()
+
+            if normalized_state in ("COMPLETED", "SUCCEEDED", "INCHOATE"):
+                self._fetch_results()
+                return
+            if normalized_state in ("FAILED", "CANCELLED"):
+                description = (
+                    status_details.get("description")
+                    or status.get("description")
+                    or status.get("detail")
+                    or "Unknown error"
+                )
+                raise DatabaseError(f"Statement execution failed: {description}")
+            if normalized_state in ("UNKNOWN", "SUBMITTED", "EXECUTING", "RUNNING"):
+                time.sleep(poll_interval)
+                elapsed += poll_interval
+                poll_interval = min(poll_interval * 1.5, 2.5)
+                continue
+
+            raise DatabaseError(f"Unknown statement state: {state_value}")
+
+        raise OperationalError("Statement execution timed out")
+
+    @staticmethod
+    def _rows_from_columnar_data(column_data: Sequence[Dict[str, Any]]) -> List[Tuple[Any, ...]]:
+        """Convert column-oriented payloads into row tuples."""
+        column_values: List[List[Any]] = []
+        for column in column_data:
+            if not isinstance(column, dict):
+                continue
+            values = column.get("values") or []
+            column_values.append(list(values))
+        if not column_values:
+            return []
+        max_rows = max((len(values) for values in column_values), default=0)
+        return [
+            tuple(
+                column_values[col_index][row_index]
+                if row_index < len(column_values[col_index])
+                else None
+                for col_index in range(len(column_values))
+            )
+            for row_index in range(max_rows)
+        ]
+
+    def _fetch_results(self) -> None:
+        """Fetch results from a completed statement."""
+        if not self._statement_handle:
+            return
+
+        page_size = max(self._opteryx_max_row_buffer or 10, self._arraysize)
+        offset = 0
+        has_description = False
+        rows: List[Tuple[Any, ...]] = []
+        total_rows: Optional[int] = None
+
+        def process_result_page(result: Dict[str, Any]) -> int:
+            nonlocal has_description, total_rows
+            new_rows = 0
+            if total_rows is None and "total_rows" in result:
+                try:
+                    total_rows = int(result.get("total_rows", 0))
+                except (TypeError, ValueError):
+                    total_rows = None
+
+            columns_meta = result.get("columns", [])
+            if columns_meta and not has_description:
+                self._description = [
+                    (col.get("name", f"col{i}"), None, None, None, None, None, None)
+                    for i, col in enumerate(columns_meta)
+                ]
+                has_description = True
+
+            data = result.get("data", [])
+            if data:
+                if isinstance(data[0], dict) and "values" in data[0]:
+                    if not has_description:
+                        self._description = [
+                            (col.get("name", f"col{i}"), None, None, None, None, None, None)
+                            for i, col in enumerate(data)
+                        ]
+                        has_description = True
+                    column_rows = self._rows_from_columnar_data(data)
+                    rows.extend(column_rows)
+                    new_rows = len(column_rows)
+                else:
+                    for row in data:
+                        rows.append(tuple(row))
+                    new_rows = len(data)
+
+            return new_rows
+
+        status_result = self._connection._get_statement_status(self._statement_handle)  # pylint: disable=protected-access
+        process_result_page(status_result)
+        offset = len(rows)
+
+        while True:
+            if total_rows is not None and offset >= total_rows:
+                break
+
+            result = self._connection._get_statement_results(  # pylint: disable=protected-access
+                self._statement_handle, num_rows=page_size, offset=offset
+            )
+
+            fetched_this_page = process_result_page(result)
+            if fetched_this_page <= 0:
+                break
+
+            offset += fetched_this_page
+            if fetched_this_page < page_size:
+                break
+
+        # Finalize rows and counts
+        self._rows = rows
+        self._rowcount = len(self._rows)
+
+    def executemany(
+        self,
+        operation: str,
+        seq_of_parameters: Sequence[Union[Dict[str, Any], Sequence[Any]]],
+    ) -> "Cursor":
+        """Execute a SQL statement multiple times with different parameters."""
+        self._check_closed()
+        for parameters in seq_of_parameters:
+            self.execute(operation, parameters)
+        return self
+
+    def fetchone(self) -> Optional[Tuple[Any, ...]]:
+        """Fetch the next row of a query result set."""
+        self._check_closed()
+        if self._row_index >= len(self._rows):
+            return None
+        row = self._rows[self._row_index]
+        self._row_index += 1
+        return row
+
+    def fetchmany(self, size: Optional[int] = None) -> List[Tuple[Any, ...]]:
+        """Fetch the next set of rows."""
+        self._check_closed()
+        if size is None:
+            size = self._arraysize
+        rows = self._rows[self._row_index : self._row_index + size]
+        self._row_index += len(rows)
+        return rows
+
+    def fetchall(self) -> List[Tuple[Any, ...]]:
+        """Fetch all remaining rows."""
+        self._check_closed()
+        rows = self._rows[self._row_index :]
+        self._row_index = len(self._rows)
+        return rows
+
+    def setinputsizes(self, sizes: Sequence[Any]) -> None:
+        """Set input sizes (no-op, but required by PEP 249)."""
+        _ = sizes
+        return None
+
+    def setoutputsize(self, size: int, column: Optional[int] = None) -> None:
+        """Set output size (no-op, but required by PEP 249)."""
+        _ = size
+        _ = column
+        return None
+
+    def __iter__(self) -> "Cursor":
+        """Make cursor iterable."""
+        return self
+
+    def __next__(self) -> Tuple[Any, ...]:
+        """Get next row."""
+        row = self.fetchone()
+        if row is None:
+            raise StopIteration
+        return row
+
+
+class Connection:
+    """DBAPI 2.0 Connection implementation for Opteryx.
+
+    Manages HTTP connections to the Opteryx data service.
+    """
+
+    def __init__(
+        self,
+        host: str = "localhost",
+        port: int = 8000,
+        username: Optional[str] = None,
+        token: Optional[str] = None,
+        database: Optional[str] = None,
+        ssl: bool = False,
+        timeout: float = 30.0,
+    ) -> None:
+        """Initialize connection to Opteryx data service.
+
+        Args:
+            host: Hostname of the Opteryx data service
+            port: Port number
+            username: Username for authentication (optional)
+            token: Bearer token for authentication
+            database: Database/schema name (optional)
+            ssl: Whether to use HTTPS
+            timeout: Request timeout in seconds
+        """
+        self._host = host
+        self._port = port
+        self._username = username
+        self._token = token
+        self._database = database
+        self._ssl = ssl
+        self._timeout = timeout
+        self._closed = False
+
+        # Build base URL
+        scheme = "https" if ssl else "http"
+        if (ssl and port == 443) or (not ssl and port == 80):
+            self._base_url = f"{scheme}://{host}"
+        else:
+            self._base_url = f"{scheme}://{host}:{port}"
+
+        # Create session for connection pooling
+        self._session = requests.Session()
+        if token:
+            self._session.headers["Authorization"] = f"Bearer {token}"
+        self._session.headers["Content-Type"] = "application/json"
+
+    def _normalize_domain(self, host: str) -> str:
+        """Return the base domain for the given host by stripping known subdomain prefixes.
+
+        Examples:
+            'data.opteryx.app' -> 'opteryx.app'
+            'auth.opteryx.app' -> 'opteryx.app'
+            'opteryx.app' -> 'opteryx.app'
+            'localhost' -> 'localhost'
+        """
+        domain = host
+        for p in ("data.", "auth."):
+            if domain.startswith(p):
+                domain = domain[len(p) :]
+        return domain
+
+    def _data_base_url(self) -> str:
+        """Construct a base URL that targets the 'data' subdomain for API requests."""
+        scheme = "https" if self._ssl else "http"
+        domain = self._normalize_domain(self._host)
+        # Only add subdomain prefix for DNS-style hosts (e.g. example.com), not for localhost or IPs
+        if "." in domain and not domain.startswith("localhost"):
+            data_host = f"data.{domain}"
+        else:
+            data_host = domain
+        if (self._ssl and self._port == 443) or (not self._ssl and self._port == 80):
+            return f"{scheme}://{data_host}"
+        return f"{scheme}://{data_host}:{self._port}"
+
+    def _check_closed(self) -> None:
+        """Raise exception if connection is closed."""
+        if self._closed:
+            raise ProgrammingError("Connection is closed")
+
+    def _submit_statement(
+        self, sql: str, parameters: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Submit a SQL statement to the data service."""
+        self._check_closed()
+
+        url = urljoin(self._data_base_url() + "/", "api/v1/statements")
+        payload: Dict[str, Any] = {"sqlText": sql}
+        if parameters:
+            payload["parameters"] = parameters
+
+        try:
+            response = self._session.post(url, json=payload, timeout=self._timeout)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.HTTPError as e:
+            if e.response is not None:
+                try:
+                    detail = e.response.json().get("detail", str(e))
+                except (ValueError, json.JSONDecodeError):
+                    detail = e.response.text or str(e)
+                raise DatabaseError(f"HTTP error: {detail}") from e
+            raise DatabaseError(f"HTTP error: {e}") from e
+        except requests.exceptions.RequestException as e:
+            raise OperationalError(f"Connection error: {e}") from e
+
+    def _get_statement_status(self, statement_handle: str) -> Dict[str, Any]:
+        """Get the status of a submitted statement."""
+        self._check_closed()
+
+        url = urljoin(self._data_base_url() + "/", f"api/v1/statements/{statement_handle}/status")
+
+        try:
+            response = self._session.get(url, timeout=self._timeout)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.HTTPError as e:
+            if e.response is not None and e.response.status_code == 404:
+                raise ProgrammingError("Statement not found") from e
+            raise DatabaseError(f"HTTP error: {e}") from e
+        except requests.exceptions.RequestException as e:
+            raise OperationalError(f"Connection error: {e}") from e
+
+    def _get_statement_results(
+        self, statement_handle: str, num_rows: Optional[int] = None, offset: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """Get results for a completed statement.
+
+        Note: The current API may return results as part of status response
+        or via a separate results endpoint. This method handles both cases.
+        """
+        url = urljoin(self._data_base_url() + "/", f"api/v1/statements/{statement_handle}/results")
+        params: Dict[str, Any] = {}
+        if num_rows is not None:
+            params["num_rows"] = int(num_rows)
+        if offset is not None:
+            params["offset"] = int(offset)
+        try:
+            response = self._session.get(url, params=params or None, timeout=self._timeout)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException:
+            pass
+
+        # Fallback to status endpoint if dedicated results are unavailable
+        return self._get_statement_status(statement_handle)
+
+    def close(self) -> None:
+        """Close the connection."""
+        if not self._closed:
+            self._session.close()
+            self._closed = True
+
+    def commit(self) -> None:
+        """Commit transaction (no-op for Opteryx as it's read-only)."""
+        self._check_closed()
+
+    def rollback(self) -> None:
+        """Rollback transaction (no-op for Opteryx as it's read-only)."""
+        self._check_closed()
+
+    def cursor(self) -> Cursor:
+        """Create a new cursor object."""
+        self._check_closed()
+        return Cursor(self)
+
+    def __enter__(self) -> "Connection":
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit."""
+        self.close()
+
+
+def connect(
+    host: str = "localhost",
+    port: int = 8000,
+    username: Optional[str] = None,
+    token: Optional[str] = None,
+    database: Optional[str] = None,
+    ssl: bool = False,
+    timeout: float = 30.0,
+) -> Connection:
+    """Create a new connection to the Opteryx data service.
+
+    Args:
+        host: Hostname of the Opteryx data service
+        port: Port number
+        username: Username for authentication (optional)
+        token: Bearer token for authentication
+        database: Database/schema name (optional)
+        ssl: Whether to use HTTPS
+        timeout: Request timeout in seconds
+
+    Returns:
+        A new Connection object
+    """
+    return Connection(
+        host=host,
+        port=port,
+        username=username,
+        token=token,
+        database=database,
+        ssl=ssl,
+        timeout=timeout,
+    )

sqlalchemy_dialect/dialect.py

@@ -0,0 +1,346 @@
+"""SQLAlchemy dialect for Opteryx data service.
+
+This module provides a SQLAlchemy dialect implementation that enables
+connecting to the Opteryx data service using SQLAlchemy's engine and
+ORM capabilities.
+
+Connection URL format:
+    opteryx://[username:token@]host[:port]/[database][?ssl=true]
+
+Examples:
+    opteryx://data.opteryx.app/default
+    opteryx://user:mytoken@data.opteryx.app:443/default?ssl=true
+    opteryx://localhost:8000/default
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from typing import Optional
+from typing import Tuple
+
+from sqlalchemy import types as sqltypes
+from sqlalchemy.engine import default
+from sqlalchemy.engine.interfaces import ExecutionContext
+from sqlalchemy.engine.url import URL
+
+from . import dbapi
+
+
+def _quote_identifier(identifier: str) -> str:
+    """Safely quote a SQL identifier to prevent SQL injection.
+
+    Args:
+        identifier: The identifier (table name, column name, etc.) to quote
+
+    Returns:
+        A safely quoted identifier string
+
+    Raises:
+        ValueError: If the identifier contains invalid characters
+    """
+    # Validate identifier format - alphanumeric, underscores, and dots only
+    if not re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", identifier):
+        raise ValueError(f"Invalid identifier: {identifier}")
+    # Return double-quoted identifier (standard SQL quoting)
+    return f'"{identifier}"'
+
+
+class OptetyxDialect(default.DefaultDialect):
+    """SQLAlchemy dialect for Opteryx data service.
+
+    This dialect communicates with the Opteryx data service via HTTP,
+    translating SQLAlchemy operations into API calls.
+    """
+
+    name = "opteryx"
+    driver = "http"
+
+    # Capabilities
+    supports_alter = False
+    supports_pk_autoincrement = False
+    supports_default_values = False
+    supports_empty_insert = False
+    supports_sequences = False
+    sequences_optional = True
+    supports_native_boolean = True
+    supports_native_decimal = True
+    supports_statement_cache = False
+    postfetch_lastrowid = False
+
+    # Opteryx is read-only (analytics engine)
+    supports_sane_rowcount = False
+    supports_sane_multi_rowcount = False
+
+    # Default SQL features
+    default_paramstyle = "named"
+    supports_native_enum = False
+    supports_simple_order_by_label = True
+    supports_comments = False
+    inline_comments = False
+
+    # Required for SQLAlchemy
+    preexecute_autoincrement_sequences = False
+    implicit_returning = False
+    full_returning = False
+
+    # Type mapping
+    colspecs = {}
+    ischema_names = {
+        "VARCHAR": sqltypes.String,
+        "STRING": sqltypes.String,
+        "TEXT": sqltypes.Text,
+        "INTEGER": sqltypes.Integer,
+        "INT": sqltypes.Integer,
+        "BIGINT": sqltypes.BigInteger,
+        "SMALLINT": sqltypes.SmallInteger,
+        "FLOAT": sqltypes.Float,
+        "DOUBLE": sqltypes.Float,
+        "REAL": sqltypes.Float,
+        "DECIMAL": sqltypes.Numeric,
+        "NUMERIC": sqltypes.Numeric,
+        "BOOLEAN": sqltypes.Boolean,
+        "BOOL": sqltypes.Boolean,
+        "DATE": sqltypes.Date,
+        "TIME": sqltypes.Time,
+        "TIMESTAMP": sqltypes.DateTime,
+        "DATETIME": sqltypes.DateTime,
+        "BLOB": sqltypes.LargeBinary,
+        "BINARY": sqltypes.LargeBinary,
+    }
+
+    @classmethod
+    def dbapi(cls) -> Any:
+        """Return the DBAPI module."""
+        return dbapi
+
+    @classmethod
+    def import_dbapi(cls) -> Any:
+        """Import and return the DBAPI module."""
+        return dbapi
+
+    def create_connect_args(self, url: URL) -> Tuple[list, dict]:
+        """Create connection arguments from SQLAlchemy URL.
+
+        Args:
+            url: SQLAlchemy URL object
+
+        Returns:
+            Tuple of (positional args, keyword args) for dbapi.connect()
+        """
+        opts = {}
+
+        # Host
+        if url.host:
+            opts["host"] = url.host
+
+        # Port
+        if url.port:
+            opts["port"] = url.port
+        else:
+            # Default ports based on SSL setting
+            query = dict(url.query) if url.query else {}
+            ssl = query.get("ssl", "").lower() in ("true", "1", "yes")
+            opts["port"] = 443 if ssl else 8000
+
+        # Username and token (password field used for token)
+        if url.username:
+            opts["username"] = url.username
+        if url.password:
+            opts["token"] = url.password
+
+        # Database
+        if url.database:
+            opts["database"] = url.database
+
+        # Query parameters
+        if url.query:
+            query = dict(url.query)
+            if "ssl" in query:
+                opts["ssl"] = query["ssl"].lower() in ("true", "1", "yes")
+            if "timeout" in query:
+                try:
+                    opts["timeout"] = float(query["timeout"])
+                except ValueError:
+                    pass
+
+        return ([], opts)
+
+    def do_execute(
+        self,
+        cursor: Any,
+        statement: str,
+        parameters: Optional[Any],
+        context: Optional[ExecutionContext] = None,
+    ) -> Any:
+        """Propagate execution options so downstream code can react to them."""
+        execution_options = getattr(context, "execution_options", {}) if context is not None else {}
+        streaming_requested = bool(execution_options.get("stream_results"))
+        max_row_buffer = execution_options.get("max_row_buffer")
+
+        # Attach the parsed streaming hints to the DBAPI cursor for later use.
+        cursor._opteryx_execution_options = dict(execution_options)
+        cursor._opteryx_stream_results_requested = streaming_requested
+        cursor._opteryx_max_row_buffer = max_row_buffer
+
+        return super().do_execute(cursor, statement, parameters, context=context)
+
+    def do_ping(self, dbapi_connection: Any) -> bool:
+        """Check if the connection is still alive.
+
+        Args:
+            dbapi_connection: The DBAPI connection object
+
+        Returns:
+            True if the connection is alive, False otherwise
+        """
+        try:
+            cursor = dbapi_connection.cursor()
+            cursor.execute("SELECT 1")
+            cursor.fetchone()
+            cursor.close()
+            return True
+        except Exception:
+            return False
+
+    def get_isolation_level(self, dbapi_connection: Any) -> str:
+        """Return the isolation level.
+
+        Opteryx doesn't support transactions, so we return a nominal value.
+        """
+        return "AUTOCOMMIT"
+
+    def has_table(
+        self, connection: Any, table_name: str, schema: Optional[str] = None, **kw: Any
+    ) -> bool:
+        """Check if a table exists.
+
+        Args:
+            connection: SQLAlchemy connection
+            table_name: Name of the table
+            schema: Optional schema name
+
+        Returns:
+            True if the table exists
+        """
+        # Try to query the table with a limit of 0 to check existence
+        try:
+            # Safely quote identifiers to prevent SQL injection
+            quoted_table = _quote_identifier(table_name)
+            if schema:
+                quoted_schema = _quote_identifier(schema)
+                full_name = f"{quoted_schema}.{quoted_table}"
+            else:
+                full_name = quoted_table
+            result = connection.execute(f"SELECT * FROM {full_name} LIMIT 0")
+            result.close()
+            return True
+        except (ValueError, Exception):
+            # ValueError from invalid identifier, or database error
+            return False
+
+    def get_columns(
+        self,
+        connection: Any,
+        table_name: str,
+        schema: Optional[str] = None,
+        **kw: Any,
+    ) -> list:
+        """Get column information for a table.
+
+        Returns an empty list as Opteryx may not support full introspection.
+        """
+        return []
+
+    def get_pk_constraint(
+        self,
+        connection: Any,
+        table_name: str,
+        schema: Optional[str] = None,
+        **kw: Any,
+    ) -> dict:
+        """Get primary key constraint.
+
+        Opteryx doesn't have primary keys in the traditional sense.
+        """
+        return {"constrained_columns": [], "name": None}
+
+    def get_foreign_keys(
+        self,
+        connection: Any,
+        table_name: str,
+        schema: Optional[str] = None,
+        **kw: Any,
+    ) -> list:
+        """Get foreign key information.
+
+        Opteryx doesn't support foreign keys.
+        """
+        return []
+
+    def get_indexes(
+        self,
+        connection: Any,
+        table_name: str,
+        schema: Optional[str] = None,
+        **kw: Any,
+    ) -> list:
+        """Get index information.
+
+        Opteryx doesn't expose index information.
+        """
+        return []
+
+    def get_table_names(self, connection: Any, schema: Optional[str] = None, **kw: Any) -> list:
+        """Get list of table names.
+
+        Attempts to query Opteryx for available tables.
+        """
+        try:
+            result = connection.execute("SHOW TABLES")
+            tables = [row[0] for row in result.fetchall()]
+            result.close()
+            return tables
+        except Exception:
+            return []
+
+    def get_view_names(self, connection: Any, schema: Optional[str] = None, **kw: Any) -> list:
+        """Get list of view names.
+
+        Opteryx may not distinguish between tables and views.
+        """
+        return []
+
+    def get_schema_names(self, connection: Any, **kw: Any) -> list:
+        """Get list of schema names."""
+        try:
+            result = connection.execute("SHOW SCHEMAS")
+            schemas = [row[0] for row in result.fetchall()]
+            result.close()
+            return schemas
+        except Exception:
+            return ["default"]
+
+    def _get_server_version_info(self, connection: Any) -> Tuple[int, ...]:
+        """Get server version information."""
+        return (0, 26, 1)  # Match Opteryx version in pyproject.toml
+
+    def _check_unicode_returns(
+        self, connection: Any, additional_tests: Optional[list] = None
+    ) -> bool:
+        """Check if the connection returns unicode strings."""
+        return True
+
+    def _check_unicode_description(self, connection: Any) -> bool:
+        """Check if column descriptions are unicode."""
+        return True
+
+
+# Register the dialect
+def register_dialect() -> None:
+    """Register the Opteryx dialect with SQLAlchemy."""
+    from sqlalchemy.dialects import registry
+
+    registry.register("opteryx", "app.sqlalchemy_dialect.dialect", "OptetyxDialect")
+    registry.register("opteryx.http", "app.sqlalchemy_dialect.dialect", "OptetyxDialect")