sqlodin 0.6.0__py3-none-any.whl

sqlodin/__init__.py

@@ -0,0 +1,15 @@
+"""SQLodin: durable SQL with a small, explicit Python API."""
+from .client import Connection, PendingWrite, connect
+from .errors import (ConnectionError, ConstraintError, Error, PendingWriteError,
+                     QueryError, SerializationError, SessionError, UnknownOutcome)
+from .results import Row, Rows, WriteResult
+from .transport import Endpoint, TLS
+from .vector import Vector
+from .search import SearchIndex
+
+__all__ = [
+    'Vector', 'SearchIndex', 'connect', 'Connection', 'Endpoint', 'TLS', 'PendingWrite', 'Row', 'Rows', 'WriteResult',
+    'Error', 'ConnectionError', 'ConstraintError', 'PendingWriteError', 'QueryError',
+    'SessionError', 'SerializationError', 'UnknownOutcome',
+]
+__version__ = '0.6.0'

sqlodin/client.py

@@ -0,0 +1,333 @@
+"""Synchronous connections with explicit recovery of uncertain durable writes."""
+import base64
+import json
+import re
+import secrets
+import threading
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from .errors import (ConnectionError, ConstraintError, PendingWriteError, QueryError,
+                     SessionError, SerializationError, UnknownOutcome)
+from .parameters import Value, encode, prepare
+from .vector import Vector
+from .results import Row, Rows, WriteResult
+from .transport import Endpoint, TLS, Transport
+
+
+@dataclass(frozen=True)
+class PendingWrite:
+    session: str
+    sequence: int
+    sql: str
+    parameters: tuple[Value, ...] = ()
+    read_version: int = 0
+    epoch: int = 0
+
+    def __post_init__(self):
+        if not re.fullmatch(r'[0-9a-f]{32}', self.session) or int(self.session, 16) == 0:
+            raise ValueError("Session must be 32 lowercase hexadecimal digits, not all zero")
+        if type(self.sequence) is not int or not 1 <= self.sequence < 2**63:
+            raise ValueError("Sequence must be a positive signed 64-bit integer")
+        if not self.sql or '\x00' in self.sql or len(self.sql.encode('utf-8')) > 4096:
+            raise ValueError("Invalid pending SQL body")
+        if type(self.read_version) is not int or not 0 <= self.read_version < 2**63:
+            raise ValueError("Invalid transaction read version")
+        if type(self.epoch) is not int or not 0 <= self.epoch < 2**63:
+            raise ValueError("Invalid session epoch")
+        object.__setattr__(self, 'parameters', tuple(self.parameters))
+        if len(self.parameters) > 16:
+            raise ValueError("Too many parameters")
+        if sum(len(v) for v in self.parameters if isinstance(v, Vector)) > 384:
+            raise ValueError("A request supports at most 384 vector components in total")
+        for value in self.parameters:
+            encode(value)
+
+    def to_json(self) -> str:
+        """Save securely before recovery; contains SQL and parameter values."""
+        parameters = [{"vector": list(v)} if isinstance(v, Vector) else v for v in self.parameters]
+        return json.dumps(dict(session=self.session, sequence=self.sequence, sql=self.sql,
+                               parameters=parameters, read_version=self.read_version, epoch=self.epoch), allow_nan=False)
+
+    @classmethod
+    def from_json(cls, text: str) -> 'PendingWrite':
+        value = json.loads(text)
+        value["parameters"] = tuple(Vector(p["vector"]) if isinstance(p, dict) and set(p) == {"vector"}
+                                    else p for p in value.get("parameters", ()))
+        return cls(**value)
+
+
+class Connection:
+    def __init__(self, endpoints: Sequence[Endpoint], *, cluster: str, tls: TLS,
+                 timeout: float = 10, pending: PendingWrite | None = None):
+        self.endpoints = tuple(endpoints)
+        if not self.endpoints or any(not isinstance(e, Endpoint) for e in self.endpoints):
+            raise ValueError("Provide at least one Endpoint(address, server_name)")
+        if not cluster or not 0 < timeout <= 60:
+            raise ValueError("Cluster is required; timeout must be in (0, 60] seconds")
+        self.cluster, self.timeout = cluster, timeout
+        self._session = pending.session if pending else secrets.token_hex(16)
+        self._sequence = pending.sequence if pending else 1
+        self._pending = pending
+        self._epoch = pending.epoch if pending else None
+        self._transport = Transport(tls)
+        self._index = 0
+        self._lock = threading.RLock()
+        self._closed = False
+        self._transaction = False
+
+    @property
+    def pending(self) -> PendingWrite | None:
+        return self._pending
+
+    def close(self) -> None:
+        with self._lock:
+            self._transport.close()
+            self._closed = True
+
+    def __enter__(self):
+        self._ready()
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    def _ready(self):
+        if self._closed:
+            raise ConnectionError("Connection is closed")
+        if self._transaction:
+            raise PendingWriteError("Use the transaction's execute() while building an atomic batch")
+
+    def execute(self, sql: str, parameters: Sequence[Value] = ()) -> WriteResult:
+        """Execute a durable transaction body; ? values are bound, never formatted."""
+        text, values = prepare(sql, parameters)
+        with self._lock:
+            self._ready()
+            return self._execute_prepared(text, values)
+
+    def _execute_prepared(self, text, values, read_version=0):
+        if self._pending is not None:
+            raise PendingWriteError("Resolve the outstanding write before submitting another")
+        if self._epoch is None:
+            self._epoch = self.session_epoch()
+        self._pending = PendingWrite(self._session, self._sequence, text, values, read_version, self._epoch)
+        return self._resolve()
+
+    def resolve_pending(self) -> WriteResult:
+        """Retry the exact saved identity and content, including after failover."""
+        with self._lock:
+            self._ready()
+            if self._pending is None:
+                raise PendingWriteError("There is no pending write")
+            return self._resolve()
+
+    def _resolve(self):
+        pending = self._pending
+        request = dict(op='execute', sql=pending.sql, session=pending.session,
+                       sequence=pending.sequence, session_epoch=pending.epoch, read_version=pending.read_version, parameters=[encode(v) for v in pending.parameters])
+        try:
+            response = self._call(request)
+        except ConnectionError as exc:
+            raise UnknownOutcome(pending) from exc
+        code = response.get('error', '')
+        if code in ('Expired', 'Identity_Conflict', 'Session_Limit'):
+            raise SessionError(code)
+        if code not in ('', 'Constraint', 'Policy', 'Sequence_Gap', 'Invalid_SQL',
+                        'Invalid_Request', 'Unsupported', 'Conflict'):
+            raise UnknownOutcome(pending)
+        self._pending = None
+        if code not in ('Invalid_Request', 'Unsupported'):
+            self._sequence += 1
+        if code == "Conflict":
+            raise SerializationError(code)
+        if code:
+            raise ConstraintError(code) if code == 'Constraint' else QueryError(code)
+        return WriteResult(response['changes'], response['applied'], response['node'], response['sequence'])
+
+    def query(self, sql: str, parameters: Sequence[Value] = (), *, consistency: str = 'linearizable') -> Rows:
+        """Read after a fresh quorum barrier; local reads explicitly allow stale data."""
+        if consistency not in ('linearizable', 'local'):
+            raise ValueError("Consistency must be 'linearizable' or 'local'")
+        text, values = prepare(sql, parameters)
+        with self._lock:
+            self._ready()
+            response = self._call(dict(op='query', sql=text, consistency=consistency,
+                                       parameters=[encode(v) for v in values]))
+            self._raise_query(response)
+            try:
+                columns = tuple(response['columns'])
+                if not all(isinstance(c, str) for c in columns):
+                    raise ValueError('Invalid column names')
+                rows = tuple(Row(columns, tuple(_decode(v) for v in row)) for row in response['rows'])
+                if any(len(row.as_tuple()) != len(columns) for row in rows):
+                    raise ValueError('Invalid row width')
+                return Rows(columns, rows, response['applied'], response['node'])
+            except (KeyError, TypeError, ValueError) as exc:
+                raise ConnectionError("Malformed query result") from exc
+
+    def status(self) -> dict:
+        """Local node information, not a quorum health check."""
+        with self._lock:
+            self._ready()
+            result = self._call(dict(op='status'))
+            self._raise_query(result)
+            return {k: result[k] for k in ('cluster', 'node', 'protocol', 'policy', 'applied',
+                    'snapshot_prefix', 'snapshot_sealed', 'snapshot_error', 'generation_prefix') if k in result}
+
+    def session_epoch(self) -> int:
+        """Read the current retry-session epoch through a fresh quorum barrier."""
+        with self._lock:
+            self._ready()
+            response = self._call(dict(op='session_epoch'))
+            # Pre-epoch services never retire session rows and have only epoch zero.
+            if response.get('error') == 'Unsupported':
+                return 0
+            self._raise_query(response)
+            epoch = response.get('session_epoch')
+            if type(epoch) is not int or not 0 <= epoch < 2**63:
+                raise ConnectionError('Malformed session epoch')
+            return epoch
+
+    def retire_sessions(self, *, expected_epoch: int) -> int:
+        """Fence the old epoch and reclaim its session rows.
+
+        Quiesce clients and resolve their pending writes first. Old pending writes
+        then fail with Expired; never relabel them into a new epoch. After a lost
+        response, retry this same expected_epoch. Open new connections afterwards.
+        """
+        if type(expected_epoch) is not int or not 0 <= expected_epoch < 2**63-1:
+            raise ValueError('Invalid expected session epoch')
+        with self._lock:
+            self._ready()
+            if self._pending is not None or self._transaction:
+                raise PendingWriteError('Resolve pending work before retiring sessions')
+            response = self._call(dict(op='retire_sessions', session_epoch=expected_epoch))
+            self._raise_query(response)
+            epoch = response.get('session_epoch')
+            if type(epoch) is not int or epoch < expected_epoch+1:
+                raise ConnectionError('Malformed retirement response; retry the same expected_epoch')
+            return epoch
+
+    def request_snapshot(self) -> int:
+        """Request a distributed snapshot; return its proposed checkpoint slot.
+
+        This is admission, not certification or a backup completion guarantee.
+        Inspect status()['snapshot_sealed'] for the locally learned certificate.
+        A displaced checkpoint may require a new request.
+        """
+        with self._lock:
+            self._ready()
+            response = self._call(dict(op='snapshot'))
+            self._raise_query(response)
+            slot = response.get('snapshot_requested')
+            if type(slot) is not int or slot <= 0:
+                raise ConnectionError('Malformed snapshot admission result')
+            return slot
+
+    @staticmethod
+    def _raise_query(response):
+        if response['status'] != 'ok':
+            if response.get('error') == 'Conflict': raise SerializationError('Conflict')
+            if response.get('error') == 'Constraint': raise ConstraintError('Constraint')
+            raise QueryError(response.get('error', 'Unknown'))
+
+    def _call(self, request):
+        deadline = time.monotonic() + self.timeout
+        request = dict(request, protocol=1, cluster=self.cluster)
+        last_error = None
+        while time.monotonic() < deadline:
+            endpoint = self.endpoints[self._index]
+            # Divide the remaining budget so an unavailable seed cannot consume
+            # the entire failover deadline. Every retry retains the write identity.
+            attempt = min(deadline, time.monotonic() + max(0.1, (deadline - time.monotonic()) / len(self.endpoints)))
+            request['timeout_ms'] = max(1, min(60000, int((attempt - time.monotonic()) * 900)))
+            try:
+                response = self._transport.exchange(endpoint, request, attempt)
+                self._validate(response, request)
+                if response.get('error') not in ('Busy', 'Unknown_Outcome', 'Read_Timeout'):
+                    return response
+                last_error = response['error']
+            except (ConnectionError, TimeoutError) as exc:
+                last_error = str(exc)
+            self._transport.close()
+            self._index = (self._index + 1) % len(self.endpoints)
+            time.sleep(min(0.01, max(0, deadline - time.monotonic())))
+        raise ConnectionError(f"Operation deadline exceeded: {last_error}")
+
+    def _validate(self, response, request):
+        if response.get('cluster') != self.cluster or response.get('protocol') != 1:
+            raise ConnectionError("Response cluster or protocol mismatch")
+        if response.get('status') not in ('ok', 'error'):
+            raise ConnectionError("Invalid response status")
+        for name in ('node', 'applied', 'changes', 'sequence'):
+            if type(response.get(name)) is not int or response[name] < 0:
+                raise ConnectionError(f"Invalid response {name}")
+        if request['op'] == 'execute' and response['sequence'] != request['sequence']:
+            raise ConnectionError("Write response identity mismatch")
+        code = response.get('error')
+        if not isinstance(code, str) or (response['status'] == 'ok') != (code == ''):
+            raise ConnectionError("Invalid error/status combination")
+
+    def _begin_optimistic(self):
+        with self._lock:
+            self._ready()
+            response = self._call(dict(op='begin'))
+            self._raise_query(response)
+            epoch = response.get('session_epoch', 0)
+            if type(epoch) is not int or not 0 <= epoch < 2**63:
+                raise ConnectionError('Malformed transaction session epoch')
+            if self._epoch is None:
+                self._epoch = epoch
+            version = response.get('read_version')
+            if type(version) is not int or not 1 <= version < 2**63:
+                raise ConnectionError('Invalid transaction read version')
+            return version
+
+    def _preview(self, body, values, version, query='', query_values=()):
+        with self._lock:
+            self._ready()
+            response = self._call(dict(op='preview', sql=body, read_version=version,
+                parameters=[encode(v) for v in values], read_sql=query,
+                read_parameters=[encode(v) for v in query_values]))
+            self._raise_query(response)
+            return response
+
+    def search_index(self, name: str, *, dimensions: int):
+        """Open a named ordinary-BLOB/FTS5 index handle without creating schema."""
+        from .search import SearchIndex
+        return SearchIndex(self, name, dimensions=dimensions)
+
+    def create_search_index(self, name: str, *, dimensions: int):
+        """Atomically create an FTS5 index and its typed-vector content table."""
+        index = self.search_index(name, dimensions=dimensions)
+        index.create()
+        return index
+
+    def transaction(self):
+        """Buffer a write-only batch; commit the complete body on successful exit."""
+        from .transaction import Transaction
+        return Transaction(self)
+
+
+def _decode(value):
+    kind = value['kind']
+    if kind == 'Null':
+        return None
+    if kind == 'Integer':
+        return value['integer']
+    if kind == 'Real':
+        return value['real']
+    if kind == 'Text':
+        return value['text']
+    if kind == 'Blob':
+        return base64.b64decode(value['text'], validate=True)
+    raise ValueError(f"Unknown result kind: {kind}")
+
+
+def connect(endpoints: Endpoint | Sequence[Endpoint], *, cluster: str, tls: TLS,
+            timeout: float = 10, pending: PendingWrite | None = None) -> Connection:
+    """Create a reusable connection; the first operation establishes mTLS."""
+    if isinstance(endpoints, Endpoint):
+        endpoints = [endpoints]
+    return Connection(endpoints, cluster=cluster, tls=tls, timeout=timeout, pending=pending)

sqlodin/dbapi.py

@@ -0,0 +1,324 @@
+"""DB-API transactions using bounded optimistic execution and durable commit."""
+from collections.abc import Mapping
+from itertools import islice
+from .parameters import prepare
+from .vector import Vector
+from . import client as native
+from . import errors
+
+apilevel = '2.0'
+threadsafety = 1
+paramstyle = 'qmark'
+
+
+class Warning(Exception): pass
+class Error(Exception): pass
+class InterfaceError(Error): pass
+class DatabaseError(Error): pass
+class DataError(DatabaseError): pass
+class OperationalError(DatabaseError):
+    def __init__(self, message, *, pending=None):
+        self.pending = pending
+        super().__init__(message)
+class SerializationError(OperationalError):
+    sqlstate = "40001"
+
+class IntegrityError(DatabaseError): pass
+class InternalError(DatabaseError): pass
+class ProgrammingError(DatabaseError): pass
+class NotSupportedError(DatabaseError): pass
+
+
+def _translate(exc, pending=None):
+    if isinstance(exc, errors.SerializationError):
+        return SerializationError(str(exc))
+    if isinstance(exc, errors.ConstraintError):
+        return IntegrityError(str(exc))
+    if isinstance(exc, (errors.UnknownOutcome, errors.PendingWriteError, errors.ConnectionError)):
+        return OperationalError(str(exc), pending=getattr(exc, 'pending', pending))
+    if isinstance(exc, errors.QueryError):
+        return ProgrammingError(str(exc))
+    if isinstance(exc, (ValueError, TypeError)):
+        return DataError(str(exc))
+    return OperationalError(str(exc), pending=pending)
+
+
+def _kind(sql):
+    """Classify one statement using top-level tokens, preserving quoted SQL/data."""
+    words, depth, i = [], 0, 0
+    while i < len(sql):
+        c = sql[i]
+        if sql.startswith('--', i):
+            end = sql.find('\n', i)
+            i = len(sql) if end < 0 else end
+        elif sql.startswith('/*', i):
+            end = sql.find('*/', i + 2)
+            if end < 0: raise ProgrammingError('Unterminated comment')
+            i = end + 2
+        elif c in "'\"`[":
+            closing = ']' if c == '[' else c
+            i += 1
+            while i < len(sql):
+                if sql[i] == closing:
+                    i += 1
+                    if closing != ']' and i < len(sql) and sql[i] == closing:
+                        i += 1
+                        continue
+                    break
+                i += 1
+            else: raise ProgrammingError('Unterminated quote')
+        elif c == '(':
+            depth += 1
+            i += 1
+        elif c == ')':
+            depth -= 1
+            i += 1
+        elif c == ';' and depth == 0:
+            words.append(';')
+            i += 1
+        elif (c.isalpha() or c == '_') and depth == 0:
+            end = i + 1
+            while end < len(sql) and (sql[end].isalnum() or sql[end] == '_'): end += 1
+            words.append(sql[i:end].upper())
+            i = end
+        else:
+            i += 1
+    while words and words[-1] == ';': words.pop()
+    if not words or ';' in words or depth != 0:
+        raise ProgrammingError('Execute exactly one balanced SQL statement')
+    if 'RETURNING' in words:
+        raise NotSupportedError('DML RETURNING is not supported by the SQLodin service')
+    kind = words[0]
+    if kind == 'WITH':
+        kind = next((w for w in words[1:] if w in ('SELECT', 'INSERT', 'UPDATE', 'DELETE', 'REPLACE')), '')
+    if kind in ('SELECT', 'VALUES'):
+        return 'query'
+    if kind in ('INSERT', 'UPDATE', 'DELETE', 'REPLACE', 'CREATE', 'DROP', 'ALTER'):
+        return 'execute'
+    raise NotSupportedError('Only queries and DML/DDL statements are supported; transaction control uses Connection methods')
+
+
+def connect(endpoints, *, cluster, tls, timeout=10, autocommit=False):
+    if type(autocommit) is not bool: raise ValueError('autocommit must be bool')
+    return Connection(native.connect(endpoints, cluster=cluster, tls=tls, timeout=timeout), autocommit=autocommit)
+
+
+class Connection:
+    def __init__(self, connection, *, autocommit=False):
+        self.native = connection
+        self.closed = False
+        self._autocommit = autocommit
+        self._version = None
+        self._statements = []
+        self._savepoints = []
+        self._failed = False
+
+    @property
+    def autocommit(self): return self._autocommit
+    @autocommit.setter
+    def autocommit(self, value):
+        if type(value) is not bool: raise NotSupportedError('autocommit must be bool')
+        self._ready()
+        if value != self._autocommit and self._version is not None:
+            raise ProgrammingError('Commit or roll back before changing autocommit')
+        self._autocommit = value
+
+    def _ready(self, *, allow_failed=False):
+        if self.closed: raise InterfaceError('Connection is closed')
+        if self.native.pending is not None:
+            raise OperationalError('Unresolved commit; recover its identity before reuse', pending=self.native.pending)
+        if self._failed and not allow_failed:
+            raise OperationalError('Transaction aborted; roll back before reuse')
+
+    def _begin(self):
+        self._ready()
+        if self._version is None:
+            try:
+                self._version = self.native._begin_optimistic()
+            except errors.Error as exc:
+                self._failed = True
+                raise _translate(exc, self.native.pending) from exc
+
+    @staticmethod
+    def _body(statements):
+        texts, values = [], []
+        for sql, params in statements:
+            text, bound = prepare(sql, params, offset=len(values))
+            texts.append(text + '\n')
+            values.extend(bound)
+        body = '\n;\n'.join(texts)
+        if len(statements) > 8 or len(body.encode('utf-8')) > 4096:
+            raise DataError('Transaction exceeds eight statements or 4096 SQL bytes')
+        if sum(len(v) for v in values if isinstance(v, Vector)) > 384:
+            raise DataError('Transaction exceeds 384 vector components')
+        return body, tuple(values)
+
+    def _preview(self, statements, query='', values=()):
+        body, parameters = self._body(statements)
+        text, bound = prepare(query, values) if query else ('', ())
+        self._begin()
+        return self.native._preview(body, parameters, self._version, text, bound)
+
+    def _clear(self):
+        self._version = None
+        self._statements.clear()
+        self._savepoints.clear()
+        self._failed = False
+
+    def cursor(self):
+        self._ready()
+        return Cursor(self)
+
+    def commit(self):
+        self._ready()
+        try:
+            if self._statements:
+                body, values = self._body(self._statements)
+                with self.native._lock:
+                    self.native._execute_prepared(body, values, self._version)
+        except (errors.Error, ValueError, TypeError) as exc:
+            self._failed = True
+            raise _translate(exc, self.native.pending) from exc
+        self._clear()
+
+    def rollback(self):
+        self._ready(allow_failed=True)
+        self._clear()  # Previews always roll back on the server; nothing was committed.
+
+    def savepoint(self, name):
+        if self.autocommit: raise NotSupportedError('Savepoints require transactional mode')
+        self._begin()
+        self._savepoints.append((name, len(self._statements)))
+
+    def _savepoint_index(self, name):
+        self._ready()
+        for index in range(len(self._savepoints) - 1, -1, -1):
+            if self._savepoints[index][0] == name: return index
+        raise ProgrammingError('Unknown savepoint')
+
+    def rollback_savepoint(self, name):
+        index = self._savepoint_index(name)
+        del self._statements[self._savepoints[index][1]:]
+        del self._savepoints[index + 1:]
+
+    def release_savepoint(self, name):
+        index = self._savepoint_index(name)
+        del self._savepoints[index:]
+
+    def close(self):
+        self._clear()
+        self.native.close()
+        self.closed = True
+
+
+class Cursor:
+    arraysize = 1
+
+    def __init__(self, connection):
+        self.connection = connection
+        self.description, self.lastrowid = None, None
+        self.rowcount = -1
+        self._rows, self._position = (), 0
+        self.closed = False
+
+    def _ready(self):
+        if self.closed: raise InterfaceError('Cursor is closed')
+        self.connection._ready()
+
+    def execute(self, operation, parameters=()):
+        self._ready()
+        self.description, self.lastrowid, self.rowcount = None, None, -1
+        self._rows, self._position = (), 0
+        if isinstance(parameters, Mapping): raise ProgrammingError('Use qmark positional parameters')
+        kind = _kind(operation)
+        try:
+            connection = self.connection
+            if kind == 'query':
+                if connection.autocommit:
+                    result = connection.native.query(operation, parameters)
+                    columns, rows = result.columns, tuple(row.as_tuple() for row in result)
+                else:
+                    result = connection._preview(connection._statements, operation, parameters)
+                    columns = result['columns']
+                    rows = tuple(tuple(native._decode(v) for v in row) for row in result['rows'])
+                self.description = tuple((name, None, None, None, None, None, None) for name in columns)
+                self._rows = rows
+            else:
+                candidate = [*connection._statements, (operation, tuple(parameters))]
+                result = connection._preview(candidate)
+                connection._statements = candidate
+                self.rowcount, self.lastrowid = result['changes'], result['lastrowid']
+                if connection.autocommit: connection.commit()
+        except (errors.Error, ValueError, TypeError) as exc:
+            if self.connection.autocommit and self.connection.native.pending is None:
+                self.connection._clear()
+            elif isinstance(exc, (errors.SerializationError, errors.ConnectionError)):
+                self.connection._failed = True
+            raise _translate(exc, self.connection.native.pending) from exc
+        except Error:
+            if self.connection.autocommit and self.connection.native.pending is None:
+                self.connection._clear()
+            raise
+        return self
+
+    def executemany(self, operation, seq_of_parameters):
+        self._ready()
+        if _kind(operation) != 'execute': raise NotSupportedError('executemany only supports writes')
+        parameters = list(islice(iter(seq_of_parameters), 9))
+        if len(parameters) > 8: raise NotSupportedError('An executemany is limited to eight statements')
+        self.description, self.lastrowid, self.rowcount = None, None, 0
+        self._rows, self._position = (), 0
+        if not parameters: return self
+        connection = self.connection
+        before = list(connection._statements)
+        auto = connection._autocommit
+        connection._autocommit = False
+        try:
+            count = 0
+            for values in parameters:
+                self.execute(operation, values)
+                count += self.rowcount
+            self.rowcount, self.lastrowid = count, None
+            if auto: connection.commit()
+        except BaseException:
+            connection._statements = before
+            if auto and connection.native.pending is None: connection._clear()
+            raise
+        finally:
+            connection._autocommit = auto
+        return self
+
+    def fetchone(self):
+        self._ready()
+        if self.description is None: raise ProgrammingError('No query result is available')
+        if self._position == len(self._rows): return None
+        row = self._rows[self._position]
+        self._position += 1
+        return row
+
+    def fetchmany(self, size=None):
+        self._ready()
+        if self.description is None: raise ProgrammingError('No query result is available')
+        size = self.arraysize if size is None else size
+        if type(size) is not int or size < 0: raise ProgrammingError('Invalid fetch size')
+        rows = []
+        for _ in range(size):
+            row = self.fetchone()
+            if row is None: break
+            rows.append(row)
+        return rows
+
+    def fetchall(self):
+        return self.fetchmany(len(self._rows) - self._position)
+
+    def close(self):
+        self._rows = ()
+        self.closed = True
+
+    def setinputsizes(self, *args): pass
+    def setoutputsize(self, *args): pass
+    def __iter__(self): return self
+    def __next__(self):
+        row = self.fetchone()
+        if row is None: raise StopIteration
+        return row