deltex 1.3.1__tar.gz

deltex-1.3.1/.gitignore

@@ -0,0 +1,35 @@
+/target
+**/*.rs.bk
+/bin
+/pkg
+*.wasm
+*.tar.gzclaudecode-linux-x64
+edgedb-docs.zip
+fastly-api.toml
+claudecode-linux-x64
+
+# Web build artifacts
+web/node_modules/
+web/dist/
+redis.env
+*.pem
+dashboard/node_modules/
+dashboard/dist/
+dashboard/.env.local
+dashboard/test-results/
+benchmarks/__pycache__/
+
+# SDK build artifacts
+sdk/rust/target/
+sdk/typescript/node_modules/
+sdk/typescript/dist/
+sdk/typescript/build/
+sdk/python/__pycache__/
+sdk/python/*.egg-info/
+sdk/python/build/
+sdk/python/dist/
+sdk/python/.eggs/
+sdk/python/**/__pycache__/
+sdk/go/bin/
+sdk/go/vendor/
+sdk/rust/Cargo.lock

deltex-1.3.1/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: deltex
+Version: 1.3.1
+Summary: Official Python client for Deltex — edge-native SQL database
+Project-URL: Homepage, https://deltex.dev
+Project-URL: Repository, https://github.com/deltex/deltex-python
+License: MIT
+Keywords: database,deltex,edge,sql
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# deltex — Python client
+
+Official Python client for [Deltex](https://deltex.dev) — edge-native SQL database.
+
+## Install
+
+```bash
+pip install deltex
+```
+
+## Quick start
+
+```python
+import deltex
+
+# Auto-reads DELTEX_API_KEY from environment
+db = deltex.connect()
+
+# Query
+users = db.query("SELECT * FROM users WHERE active = $1", [True])
+user  = db.query_one("SELECT * FROM users WHERE id = $1", [42])
+
+# Mutation
+n = db.execute("INSERT INTO events (type, ts) VALUES ($1, NOW())", ["pageview"])
+
+# Full result with commit status
+result = db.execute_raw("INSERT INTO orders (amount) VALUES ($1)", [99.99])
+print(result.commit_status)  # "edge-accepted" | "committed"
+print(result.execution_ms)   # server-side execution time
+```
+
+## API
+
+### `deltex.connect(api_key=None, endpoint=None, write_mode="sync", ...)`
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `api_key` | `DELTEX_API_KEY` env | Bearer token |
+| `endpoint` | `DELTEX_ENDPOINT` or `https://db.deltex.dev` | Engine URL |
+| `write_mode` | `"sync"` | `"sync"` / `"edge"` / `"async"` |
+| `timeout` | `30.0` | Request timeout (seconds) |
+| `max_retries` | `3` | Auto-retry on 429 |
+| `tag` | `None` | X-Query-Tag for analytics |
+
+### Methods
+
+```python
+db.query(sql, params=[])       → list[dict]
+db.query_one(sql, params=[])   → dict | None
+db.execute(sql, params=[])     → int  (rows affected)
+db.execute_raw(sql, params=[]) → QueryResult
+
+db.transaction(fn)             # BEGIN → fn(tx) → COMMIT
+db.batch(statements)           # atomic multi-statement, one round-trip → int
+
+db.with_write_mode("sync")     → Client  (per-client write mode)
+db.strong                      → Client  (X-Consistency: strong)
+db.with_idempotency_key(key)   → Client  (safe retry deduplication)
+db.with_tag(tag)               → Client  (X-Query-Tag)
+```
+
+## Async
+
+```python
+import asyncio
+import deltex
+
+async def main():
+    async with deltex.async_connect() as db:
+        users = await db.query("SELECT * FROM users LIMIT 10")
+        print(users)
+
+asyncio.run(main())
+```
+
+## Transaction
+
+```python
+def transfer(tx):
+    tx.execute("UPDATE accounts SET balance = balance - $1 WHERE id = $2", [100, 1])
+    tx.execute("UPDATE accounts SET balance = balance + $1 WHERE id = $2", [100, 2])
+
+db.transaction(transfer)
+```
+
+## Batch — fastest bulk write
+
+`batch()` applies a list of SQL statements in **one round-trip**, committed
+atomically, and returns total rows affected:
+
+```python
+n = db.batch([
+    "INSERT INTO products (name, price) VALUES ('Apple', 0.99)",
+    "INSERT INTO products (name, price) VALUES ('Banana', 0.59)",
+])  # n == 2
+```
+
+Each durable write has a ~300ms Fastly-KV commit floor, so looping `execute`
+costs ~N × 300ms. `batch()` (and a single multi-row `INSERT`) coalesce into one
+durable commit — O(1) instead of O(N): 78 separate writes ≈ 54s, the same 78 in
+a `batch()` ≈ 2s. `batch()` takes raw SQL (no binding) — for untrusted values,
+build statements safely or use `transaction`.
+
+## CLI
+
+```bash
+export DELTEX_API_KEY="dtx_k_..."
+
+deltex query "SELECT * FROM users LIMIT 5"
+deltex tables
+deltex schema orders
+deltex exec "DELETE FROM sessions WHERE expires_at < NOW()"
+deltex health
+deltex bench --samples 30
+```
+
+## Write Modes
+
+| Mode | Latency | Use when |
+|------|---------|----------|
+| `sync` (default) | ~340ms | Everything by default; durable, never loses an acked write (batch to amortize) |
+| `edge` | ~10ms | Caches, sessions, idempotent upserts — eventual durability |
+| `async` | ~5ms | High-volume telemetry, fire-and-forget |
+
+## Error handling
+
+```python
+from deltex import DeltexError, RateLimitError
+
+try:
+    db.query("SELECT * FROM nonexistent")
+except RateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after}s")
+except DeltexError as e:
+    print(f"Error {e.status}: {e.engine_message}")
+    print(f"SQL: {e.sql}")
+```
+
+## License
+
+MIT
+
+---
+
+## Common Patterns
+
+### Error handling
+
+```python
+import time
+from deltex import connect, RateLimitError, DeltexError
+
+db = connect()
+try:
+    result = db.query("SELECT * FROM users WHERE id = $1", [42])
+except RateLimitError as e:
+    time.sleep(e.retry_after)
+    result = db.query("SELECT * FROM users WHERE id = $1", [42])
+except DeltexError as e:
+    print(f"Query failed: {e}")
+    raise
+```
+
+### Async client (non-blocking)
+
+```python
+import deltex
+
+async def main():
+    db = deltex.async_connect()
+    rows = await db.query("SELECT * FROM products WHERE price < $1", [50.0])
+    for row in rows:
+        print(row["name"], row["price"])
+```
+
+### CLI usage
+
+```bash
+# Run a query
+deltex query "SELECT COUNT(*) FROM users"
+
+# Migrate
+deltex migrate --file migrations/001_create_users.sql
+
+# Backup
+deltex backup --output backup.json
+
+# Manage API keys
+deltex keys list
+deltex keys create --name "production"
+deltex keys revoke --id key_id_here
+```
+
+## SDK Version
+
+`v1.3.1` — see [CHANGELOG.md](../../CHANGELOG.md) for history.

deltex-1.3.1/README.md

@@ -0,0 +1,196 @@
+# deltex — Python client
+
+Official Python client for [Deltex](https://deltex.dev) — edge-native SQL database.
+
+## Install
+
+```bash
+pip install deltex
+```
+
+## Quick start
+
+```python
+import deltex
+
+# Auto-reads DELTEX_API_KEY from environment
+db = deltex.connect()
+
+# Query
+users = db.query("SELECT * FROM users WHERE active = $1", [True])
+user  = db.query_one("SELECT * FROM users WHERE id = $1", [42])
+
+# Mutation
+n = db.execute("INSERT INTO events (type, ts) VALUES ($1, NOW())", ["pageview"])
+
+# Full result with commit status
+result = db.execute_raw("INSERT INTO orders (amount) VALUES ($1)", [99.99])
+print(result.commit_status)  # "edge-accepted" | "committed"
+print(result.execution_ms)   # server-side execution time
+```
+
+## API
+
+### `deltex.connect(api_key=None, endpoint=None, write_mode="sync", ...)`
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `api_key` | `DELTEX_API_KEY` env | Bearer token |
+| `endpoint` | `DELTEX_ENDPOINT` or `https://db.deltex.dev` | Engine URL |
+| `write_mode` | `"sync"` | `"sync"` / `"edge"` / `"async"` |
+| `timeout` | `30.0` | Request timeout (seconds) |
+| `max_retries` | `3` | Auto-retry on 429 |
+| `tag` | `None` | X-Query-Tag for analytics |
+
+### Methods
+
+```python
+db.query(sql, params=[])       → list[dict]
+db.query_one(sql, params=[])   → dict | None
+db.execute(sql, params=[])     → int  (rows affected)
+db.execute_raw(sql, params=[]) → QueryResult
+
+db.transaction(fn)             # BEGIN → fn(tx) → COMMIT
+db.batch(statements)           # atomic multi-statement, one round-trip → int
+
+db.with_write_mode("sync")     → Client  (per-client write mode)
+db.strong                      → Client  (X-Consistency: strong)
+db.with_idempotency_key(key)   → Client  (safe retry deduplication)
+db.with_tag(tag)               → Client  (X-Query-Tag)
+```
+
+## Async
+
+```python
+import asyncio
+import deltex
+
+async def main():
+    async with deltex.async_connect() as db:
+        users = await db.query("SELECT * FROM users LIMIT 10")
+        print(users)
+
+asyncio.run(main())
+```
+
+## Transaction
+
+```python
+def transfer(tx):
+    tx.execute("UPDATE accounts SET balance = balance - $1 WHERE id = $2", [100, 1])
+    tx.execute("UPDATE accounts SET balance = balance + $1 WHERE id = $2", [100, 2])
+
+db.transaction(transfer)
+```
+
+## Batch — fastest bulk write
+
+`batch()` applies a list of SQL statements in **one round-trip**, committed
+atomically, and returns total rows affected:
+
+```python
+n = db.batch([
+    "INSERT INTO products (name, price) VALUES ('Apple', 0.99)",
+    "INSERT INTO products (name, price) VALUES ('Banana', 0.59)",
+])  # n == 2
+```
+
+Each durable write has a ~300ms Fastly-KV commit floor, so looping `execute`
+costs ~N × 300ms. `batch()` (and a single multi-row `INSERT`) coalesce into one
+durable commit — O(1) instead of O(N): 78 separate writes ≈ 54s, the same 78 in
+a `batch()` ≈ 2s. `batch()` takes raw SQL (no binding) — for untrusted values,
+build statements safely or use `transaction`.
+
+## CLI
+
+```bash
+export DELTEX_API_KEY="dtx_k_..."
+
+deltex query "SELECT * FROM users LIMIT 5"
+deltex tables
+deltex schema orders
+deltex exec "DELETE FROM sessions WHERE expires_at < NOW()"
+deltex health
+deltex bench --samples 30
+```
+
+## Write Modes
+
+| Mode | Latency | Use when |
+|------|---------|----------|
+| `sync` (default) | ~340ms | Everything by default; durable, never loses an acked write (batch to amortize) |
+| `edge` | ~10ms | Caches, sessions, idempotent upserts — eventual durability |
+| `async` | ~5ms | High-volume telemetry, fire-and-forget |
+
+## Error handling
+
+```python
+from deltex import DeltexError, RateLimitError
+
+try:
+    db.query("SELECT * FROM nonexistent")
+except RateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after}s")
+except DeltexError as e:
+    print(f"Error {e.status}: {e.engine_message}")
+    print(f"SQL: {e.sql}")
+```
+
+## License
+
+MIT
+
+---
+
+## Common Patterns
+
+### Error handling
+
+```python
+import time
+from deltex import connect, RateLimitError, DeltexError
+
+db = connect()
+try:
+    result = db.query("SELECT * FROM users WHERE id = $1", [42])
+except RateLimitError as e:
+    time.sleep(e.retry_after)
+    result = db.query("SELECT * FROM users WHERE id = $1", [42])
+except DeltexError as e:
+    print(f"Query failed: {e}")
+    raise
+```
+
+### Async client (non-blocking)
+
+```python
+import deltex
+
+async def main():
+    db = deltex.async_connect()
+    rows = await db.query("SELECT * FROM products WHERE price < $1", [50.0])
+    for row in rows:
+        print(row["name"], row["price"])
+```
+
+### CLI usage
+
+```bash
+# Run a query
+deltex query "SELECT COUNT(*) FROM users"
+
+# Migrate
+deltex migrate --file migrations/001_create_users.sql
+
+# Backup
+deltex backup --output backup.json
+
+# Manage API keys
+deltex keys list
+deltex keys create --name "production"
+deltex keys revoke --id key_id_here
+```
+
+## SDK Version
+
+`v1.3.1` — see [CHANGELOG.md](../../CHANGELOG.md) for history.

deltex-1.3.1/deltex/__init__.py

@@ -0,0 +1,35 @@
+"""
+deltex — Official Python client for Deltex edge-native SQL database.
+
+Usage:
+    import deltex
+
+    db = deltex.connect()  # reads DELTEX_API_KEY from env
+
+    # Query
+    users = db.query("SELECT * FROM users WHERE active = $1", [True])
+    user  = db.query_one("SELECT * FROM users WHERE id = $1", [42])
+
+    # Execute (INSERT/UPDATE/DELETE)
+    n = db.execute("INSERT INTO events (type, ts) VALUES ($1, NOW())", ["click"])
+
+    # Async
+    import asyncio
+    async def main():
+        async with deltex.async_connect() as db:
+            users = await db.query("SELECT * FROM users")
+"""
+
+from .client import connect, Client, DeltexError, RateLimitError, QueryResult
+from .async_client import async_connect, AsyncClient
+
+__version__ = "1.3.1"
+__all__ = [
+    "connect",
+    "async_connect",
+    "Client",
+    "AsyncClient",
+    "DeltexError",
+    "RateLimitError",
+    "QueryResult",
+]

deltex-1.3.1/deltex/async_client.py

@@ -0,0 +1,215 @@
+"""
+Deltex asyncio client.
+"""
+
+from __future__ import annotations
+
+import os
+import json
+import asyncio
+import urllib.request
+import urllib.error
+from typing import Any, Dict, List, Optional, Sequence
+
+from .client import (
+    _bind, _format_param, _TIMING_RE, _COMMIT_STATUS_VALUES,
+    DeltexError, RateLimitError, QueryResult, Row, Param,
+)
+
+
+async def _run_query_async(
+    sql: str,
+    url: str,
+    headers: Dict[str, str],
+    timeout: float,
+    max_retries: int,
+) -> QueryResult:
+    """Async HTTP execution using urllib in a thread (no external deps)."""
+    from .client import _run_query
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(
+        None,
+        lambda: _run_query(sql, url, headers, timeout, max_retries),
+    )
+
+
+class AsyncClient:
+    """
+    Deltex asyncio SQL client.
+
+    Example:
+        async with deltex.async_connect() as db:
+            users = await db.query("SELECT * FROM users WHERE active = $1", [True])
+            user  = await db.query_one("SELECT * FROM users WHERE id = $1", [42])
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        endpoint: Optional[str] = None,
+        write_mode: str = "sync",
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        tag: Optional[str] = None,
+    ):
+        self._api_key = api_key or os.environ.get("DELTEX_API_KEY", "")
+        if not self._api_key:
+            raise DeltexError("No API key. Set DELTEX_API_KEY env var or pass api_key=")
+
+        ep = (endpoint or os.environ.get("DELTEX_ENDPOINT") or "https://db.deltex.dev").rstrip("/")
+        self._url = f"{ep}/v1/query"
+        self._write_mode = write_mode
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+        self._headers: Dict[str, str] = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self._api_key}",
+            "X-Write-Mode": write_mode,
+        }
+        if tag:
+            self._headers["X-Query-Tag"] = tag
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        pass
+
+    async def query(self, sql: str, params: Sequence[Param] = ()) -> List[Row]:
+        """Execute SQL, return all rows."""
+        result = await _run_query_async(_bind(sql, params), self._url, self._headers, self._timeout, self._max_retries)
+        return result.rows
+
+    async def query_one(self, sql: str, params: Sequence[Param] = ()) -> Optional[Row]:
+        """Execute SQL, return first row or None."""
+        rows = (await _run_query_async(_bind(sql, params), self._url, self._headers, self._timeout, self._max_retries)).rows
+        return rows[0] if rows else None
+
+    async def execute(self, sql: str, params: Sequence[Param] = ()) -> int:
+        """Execute a mutation, return rows affected."""
+        return (await _run_query_async(_bind(sql, params), self._url, self._headers, self._timeout, self._max_retries)).rows_affected
+
+    async def execute_raw(self, sql: str, params: Sequence[Param] = ()) -> QueryResult:
+        """Execute SQL, return full QueryResult."""
+        return await _run_query_async(_bind(sql, params), self._url, self._headers, self._timeout, self._max_retries)
+
+    async def transaction(self, fn):
+        """
+        Execute an atomic transaction via Deltex's /transaction endpoint.
+
+        Mutating statements (``execute``/``execute_raw``) are collected and sent
+        atomically in a single round-trip; reads (``query``/``query_one``) execute
+        live. If ``fn`` raises before returning, no statements are sent — the
+        transaction is effectively rolled back.
+
+        Example:
+            async def do_transfer(tx):
+                await tx.execute("UPDATE accounts SET balance = balance - $1 WHERE id = $2", [100, 1])
+                await tx.execute("UPDATE accounts SET balance = balance + $1 WHERE id = $2", [100, 2])
+
+            await db.transaction(do_transfer)
+        """
+        statements: list = []
+        outer = self
+
+        class CollectingClient:
+            async def query(self_inner, sql: str, params: Sequence[Param] = ()) -> List[Row]:
+                return await outer.query(sql, params)
+
+            async def query_one(self_inner, sql: str, params: Sequence[Param] = ()) -> Optional[Row]:
+                return await outer.query_one(sql, params)
+
+            async def execute(self_inner, sql: str, params: Sequence[Param] = ()) -> int:
+                statements.append(_bind(sql, params))
+                return 0
+
+            async def execute_raw(self_inner, sql: str, params: Sequence[Param] = ()) -> QueryResult:
+                statements.append(_bind(sql, params))
+                return QueryResult(rows=[], columns=[], rows_affected=0)
+
+        tx = CollectingClient()
+        user_result = await fn(tx)
+
+        if not statements:
+            return user_result
+
+        tx_url = self._url.replace("/v1/query", "/v1/transaction")
+        body = json.dumps({"statements": statements, "isolation": "SERIALIZABLE"}).encode()
+
+        def _send() -> None:
+            req = urllib.request.Request(tx_url, data=body, method="POST", headers=self._headers)
+            try:
+                with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                    data = json.loads(resp.read())
+            except urllib.error.HTTPError as e:
+                data = json.loads(e.read())
+                raise DeltexError(data.get("message", str(e)), e.code, "; ".join(statements))
+            if data.get("success") is False:
+                raise DeltexError(data.get("message", "Transaction failed"), 500, "; ".join(statements))
+
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, _send)
+        return user_result
+
+    def with_write_mode(self, mode: str) -> "AsyncClient":
+        c = AsyncClient.__new__(AsyncClient)
+        c._api_key = self._api_key
+        c._url = self._url
+        c._write_mode = mode
+        c._timeout = self._timeout
+        c._max_retries = self._max_retries
+        c._headers = {**self._headers, "X-Write-Mode": mode}
+        return c
+
+    @property
+    def strong(self) -> "AsyncClient":
+        c = AsyncClient.__new__(AsyncClient)
+        c._api_key = self._api_key
+        c._url = self._url
+        c._write_mode = self._write_mode
+        c._timeout = self._timeout
+        c._max_retries = self._max_retries
+        c._headers = {**self._headers, "X-Consistency": "strong"}
+        return c
+
+    def with_tag(self, tag: str) -> "AsyncClient":
+        c = AsyncClient.__new__(AsyncClient)
+        c._api_key = self._api_key
+        c._url = self._url
+        c._write_mode = self._write_mode
+        c._timeout = self._timeout
+        c._max_retries = self._max_retries
+        c._headers = {**self._headers, "X-Query-Tag": tag}
+        return c
+
+    def with_idempotency_key(self, key: str) -> "AsyncClient":
+        c = AsyncClient.__new__(AsyncClient)
+        c._api_key = self._api_key
+        c._url = self._url
+        c._write_mode = self._write_mode
+        c._timeout = self._timeout
+        c._max_retries = self._max_retries
+        c._headers = {**self._headers, "X-Idempotency-Key": key}
+        return c
+
+
+def async_connect(
+    api_key: Optional[str] = None,
+    endpoint: Optional[str] = None,
+    write_mode: str = "sync",
+    timeout: float = 30.0,
+    max_retries: int = 3,
+    tag: Optional[str] = None,
+) -> AsyncClient:
+    """
+    Create an async Deltex client.
+
+    Example:
+        async with deltex.async_connect() as db:
+            users = await db.query("SELECT * FROM users")
+    """
+    return AsyncClient(
+        api_key=api_key, endpoint=endpoint, write_mode=write_mode,
+        timeout=timeout, max_retries=max_retries, tag=tag,
+    )