fuju-trace-sql 0.1.10__tar.gz

fuju_trace_sql-0.1.10/.gitignore

@@ -0,0 +1,41 @@
+# Rust 构建产物（巨大，绝不入库）
+target/
+**/target/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+
+# Node / TypeScript
+node_modules/
+dist/
+*.tsbuildinfo
+fuju-trace-console/.test-dist/
+fuju-trace-node/artifacts/
+
+# C / 扩展构建产物（tracevault-extension）
+*.o
+*.so
+*.a
+*.node
+
+# 运行时/测试落盘产物（WAL / 段 / manifest / 向量文件，正常写在 temp_dir，这里兜底）
+*.wal
+*.vortex
+manifest.dat
+vectors.dat
+
+# 编辑器 / 操作系统
+.DS_Store
+*.swp
+*~
+.idea/
+.vscode/
+.gstack/
+
+# 控制台前端构建产物（vite build 后拷入，编译期内嵌）
+fuju-trace-engine/crates/fuju-trace-engine/console_dist/

fuju_trace_sql-0.1.10/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: fuju-trace-sql
+Version: 0.1.10
+Summary: SQLite, DuckDB and PostgreSQL storage adapters for Fuju Trace
+Project-URL: Homepage, https://github.com/vibeinging/fuju-trace
+Project-URL: Repository, https://github.com/vibeinging/fuju-trace
+Project-URL: Issues, https://github.com/vibeinging/fuju-trace/issues
+Author: Fuju Trace
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: fuju-trace==0.1.10
+Provides-Extra: duckdb
+Requires-Dist: duckdb<3,>=1.0; extra == 'duckdb'
+Provides-Extra: postgresql
+Requires-Dist: psycopg2-binary<3,>=2.9.5; extra == 'postgresql'
+Description-Content-Type: text/markdown
+
+# Fuju Trace SQL adapters
+
+This package adds three direct database adapters to the Fuju Trace Python
+SDK: SQLite, DuckDB, and PostgreSQL. They have the same event ingestion
+and basic read API as the VexDB adapter, but their current text search is a
+portable **substring scan**. They do not provide BM25, ANN, vector writes, or
+hybrid search. Use VexDB or the local TraceDB when those search features matter.
+
+Install an adapter through a Fuju Trace extra:
+
+```bash
+python -m pip install 'fuju-trace[sqlite]==0.1.10'
+python -m pip install 'fuju-trace[duckdb]==0.1.10'
+python -m pip install 'fuju-trace[postgresql]==0.1.10'
+```
+
+## Install from this checkout
+
+```bash
+python -m pip install -e ./fuju-trace-sdk/python -e ./fuju-trace-sql
+# Add one or more optional drivers when needed:
+python -m pip install 'duckdb>=1.0,<3' 'psycopg2-binary>=2.9.5,<3'
+```
+
+SQLite uses Python's standard library. The `[duckdb]` and `[postgresql]`
+extras install their respective database drivers.
+
+## Connect
+
+```python
+from fuju_trace import DbExporter, Tracer, connect
+
+with connect(sqlite_path="./trace.sqlite", tenant_id=1, initialize=True) as db:
+    tracer = Tracer(exporter=DbExporter(db, tenant_id=1), node_id=1)
+    with tracer.trace("request", session_id=42, tenant_id=1) as trace:
+        with trace.span("tool call") as span:
+            span.log("query failed")
+    tracer.close()
+    print(db.search(text="failed", k=10))
+    print(db.list_spans(filters={"externalSessionId": 42}))
+```
+
+Other connection forms:
+
+```python
+connect(duckdb_path="./trace.duckdb", tenant_id=1, initialize=True)
+connect(postgresql_dsn="dbname=app user=trace", tenant_id=1, initialize=True)
+connect(postgresql_params={"host": "localhost", "dbname": "app",
+                           "user": "trace"}, tenant_id=1, initialize=True)
+```
+
+Supply credentials from your secret manager or environment, never from source
+control. Set `initialize=True` only for first setup; it creates private
+`fuju_trace_*` tables and indexes. Use `table_prefix` to isolate installations.
+Opening a database without the schema requires initialization first.
+
+## API and limits
+
+- `ingest(events)` is transactional and deduplicates
+  `(ext_span_id, seq, event_type)` within the bound tenant. The source event
+  and folded span are committed together.
+- `trace(id)`, `span(trace_id, span_id)`, `list_spans(filters=...)`, and
+  `list_trace_ids(filters=...)` read the folded model.
+- `search(text=..., k=..., filter=...)` searches log and input/output text.
+  Supported filters include trace ID, session ID, time, agent, status, and
+  exact attributes. `%` and `_` in a query are treated literally.
+- `capabilities()` reports `text="substring_scan"` and `vector=None`.
+  Passing a vector raises `NotImplementedError`.
+- Each store binds one tenant and serializes one connection across threads.
+  Give each process its own connection and each writer process a distinct
+  `node_id` (0–1023).
+- SQLite enables WAL for file databases; concurrent writes still serialize.
+  DuckDB is best used by one writer process for a database file. PostgreSQL
+  uses row locks when folding spans.
+- The substring search has no text index and can scan many spans. It is a
+  correctness-first baseline, not a large-scale search benchmark result.
+
+For DuckDB's file concurrency behavior and FTS index refresh requirement, see
+its [concurrency](https://duckdb.org/docs/stable/connect/concurrency.html) and
+[full-text search](https://duckdb.org/docs/current/core_extensions/full_text_search)
+documentation.
+
+## Verification
+
+```bash
+python -m unittest discover -s fuju-trace-sql/tests -p 'test_*.py'
+```
+
+SQLite and DuckDB tests use real database files. They cover writes, retries,
+filters, tenant isolation, and reopen. The PostgreSQL test below uses a real
+server and covers the same path plus two connections writing one span at the
+same time. No MySQL server is needed or supported.
+
+To start a temporary local PostgreSQL instance, run the following from the
+repository root. It listens only on a private Unix socket and deletes its data
+directory after the test. `initdb`, `pg_ctl`, `createdb`, and a Python with
+`psycopg2` must be installed:
+
+```bash
+FUJU_SQL_PYTHON=python3 ./fuju-trace-sql/tests/run_local_postgresql.sh
+```
+
+For an existing **disposable test database** with table create/drop permission,
+set `POSTGRESQL_DSN` and run `python fuju-trace-sql/tests/live_smoke.py`.
+The test creates and removes only four tables under its own random
+`fuju_smoke_*` prefix. CI runs it against a PostgreSQL 16 service container.
+These checks verify storage behavior; they do not benchmark search performance
+or exercise VexDB-Lite vector extensions.
+The [real database test report](../docs/reports/2026-09-25_sql-adapter-real-tests.md)
+records the versions and results from the local run.

fuju_trace_sql-0.1.10/README.md

@@ -0,0 +1,110 @@
+# Fuju Trace SQL adapters
+
+This package adds three direct database adapters to the Fuju Trace Python
+SDK: SQLite, DuckDB, and PostgreSQL. They have the same event ingestion
+and basic read API as the VexDB adapter, but their current text search is a
+portable **substring scan**. They do not provide BM25, ANN, vector writes, or
+hybrid search. Use VexDB or the local TraceDB when those search features matter.
+
+Install an adapter through a Fuju Trace extra:
+
+```bash
+python -m pip install 'fuju-trace[sqlite]==0.1.10'
+python -m pip install 'fuju-trace[duckdb]==0.1.10'
+python -m pip install 'fuju-trace[postgresql]==0.1.10'
+```
+
+## Install from this checkout
+
+```bash
+python -m pip install -e ./fuju-trace-sdk/python -e ./fuju-trace-sql
+# Add one or more optional drivers when needed:
+python -m pip install 'duckdb>=1.0,<3' 'psycopg2-binary>=2.9.5,<3'
+```
+
+SQLite uses Python's standard library. The `[duckdb]` and `[postgresql]`
+extras install their respective database drivers.
+
+## Connect
+
+```python
+from fuju_trace import DbExporter, Tracer, connect
+
+with connect(sqlite_path="./trace.sqlite", tenant_id=1, initialize=True) as db:
+    tracer = Tracer(exporter=DbExporter(db, tenant_id=1), node_id=1)
+    with tracer.trace("request", session_id=42, tenant_id=1) as trace:
+        with trace.span("tool call") as span:
+            span.log("query failed")
+    tracer.close()
+    print(db.search(text="failed", k=10))
+    print(db.list_spans(filters={"externalSessionId": 42}))
+```
+
+Other connection forms:
+
+```python
+connect(duckdb_path="./trace.duckdb", tenant_id=1, initialize=True)
+connect(postgresql_dsn="dbname=app user=trace", tenant_id=1, initialize=True)
+connect(postgresql_params={"host": "localhost", "dbname": "app",
+                           "user": "trace"}, tenant_id=1, initialize=True)
+```
+
+Supply credentials from your secret manager or environment, never from source
+control. Set `initialize=True` only for first setup; it creates private
+`fuju_trace_*` tables and indexes. Use `table_prefix` to isolate installations.
+Opening a database without the schema requires initialization first.
+
+## API and limits
+
+- `ingest(events)` is transactional and deduplicates
+  `(ext_span_id, seq, event_type)` within the bound tenant. The source event
+  and folded span are committed together.
+- `trace(id)`, `span(trace_id, span_id)`, `list_spans(filters=...)`, and
+  `list_trace_ids(filters=...)` read the folded model.
+- `search(text=..., k=..., filter=...)` searches log and input/output text.
+  Supported filters include trace ID, session ID, time, agent, status, and
+  exact attributes. `%` and `_` in a query are treated literally.
+- `capabilities()` reports `text="substring_scan"` and `vector=None`.
+  Passing a vector raises `NotImplementedError`.
+- Each store binds one tenant and serializes one connection across threads.
+  Give each process its own connection and each writer process a distinct
+  `node_id` (0–1023).
+- SQLite enables WAL for file databases; concurrent writes still serialize.
+  DuckDB is best used by one writer process for a database file. PostgreSQL
+  uses row locks when folding spans.
+- The substring search has no text index and can scan many spans. It is a
+  correctness-first baseline, not a large-scale search benchmark result.
+
+For DuckDB's file concurrency behavior and FTS index refresh requirement, see
+its [concurrency](https://duckdb.org/docs/stable/connect/concurrency.html) and
+[full-text search](https://duckdb.org/docs/current/core_extensions/full_text_search)
+documentation.
+
+## Verification
+
+```bash
+python -m unittest discover -s fuju-trace-sql/tests -p 'test_*.py'
+```
+
+SQLite and DuckDB tests use real database files. They cover writes, retries,
+filters, tenant isolation, and reopen. The PostgreSQL test below uses a real
+server and covers the same path plus two connections writing one span at the
+same time. No MySQL server is needed or supported.
+
+To start a temporary local PostgreSQL instance, run the following from the
+repository root. It listens only on a private Unix socket and deletes its data
+directory after the test. `initdb`, `pg_ctl`, `createdb`, and a Python with
+`psycopg2` must be installed:
+
+```bash
+FUJU_SQL_PYTHON=python3 ./fuju-trace-sql/tests/run_local_postgresql.sh
+```
+
+For an existing **disposable test database** with table create/drop permission,
+set `POSTGRESQL_DSN` and run `python fuju-trace-sql/tests/live_smoke.py`.
+The test creates and removes only four tables under its own random
+`fuju_smoke_*` prefix. CI runs it against a PostgreSQL 16 service container.
+These checks verify storage behavior; they do not benchmark search performance
+or exercise VexDB-Lite vector extensions.
+The [real database test report](../docs/reports/2026-09-25_sql-adapter-real-tests.md)
+records the versions and results from the local run.

fuju_trace_sql-0.1.10/fuju_trace_sql/__init__.py

@@ -0,0 +1,475 @@
+"""Direct SQL stores for Fuju Trace.
+
+Each store owns private tables under a validated prefix. Source events and the
+folded span projection change in one transaction. Text search is a portable
+substring query; native FTS and vector indexes are separate future capabilities.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sqlite3
+import threading
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Callable, Iterator, Mapping, Sequence
+
+from fuju_trace.event import EventType, event_id
+
+__all__ = [
+    "SQLiteTraceStore", "DuckDBTraceStore", "PostgreSQLTraceStore",
+]
+
+_PREFIX = re.compile(r"^[a-z][a-z0-9_]{0,35}$")
+_FIELDS = (
+    "parent_span_id", "status", "duration_ns", "input_tokens", "output_tokens",
+    "cache_read_tokens", "cache_write_tokens", "session_id", "tenant_id",
+    "external_trace_id", "external_span_id", "external_parent_span_id",
+    "external_session_id", "span_name", "display_name", "agent_name",
+    "tool_name", "model", "input_text", "output_text", "eval_score", "eval_label",
+)
+_ALIASES = {"projectId": "project_id", "callSite": "call_site"}
+
+
+def _json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True,
+                      separators=(",", ":"), allow_nan=False)
+
+
+def _key(value: Any) -> str:
+    return hashlib.sha256(str(value).encode("utf-8")).hexdigest()
+
+
+def _fold(events: Sequence[Mapping[str, Any]]) -> dict[str, Any]:
+    ordered = sorted(events, key=lambda e: (int(e["seq"]), int(e["event_type"])))
+    first = ordered[0]
+    span: dict[str, Any] = {
+        "trace_id": first["trace_id"], "span_id": first["span_id"],
+        "has_start": False, "has_end": False, "event_count": len(ordered),
+        "ts": min(int(e["ts"]) for e in ordered), "logs": [], "attrs": {},
+    }
+    seen_logs: set[str] = set()
+    for event in ordered:
+        kind = int(event["event_type"])
+        span["has_start"] |= kind == 1
+        span["has_end"] |= kind == 2
+        for field in _FIELDS:
+            value = event.get(field)
+            if value is not None and (field not in {"span_name", "display_name"} or kind == 1):
+                span[field] = value
+        for log in event.get("logs") or []:
+            if log not in seen_logs:
+                seen_logs.add(log)
+                span["logs"].append(log)
+        span["attrs"].update(event.get("attrs") or {})
+    return span
+
+
+def _search_text(span: Mapping[str, Any]) -> str:
+    # Display fields must not silently become search terms.
+    return "\n".join(str(value) for value in (
+        span.get("input_text"), span.get("output_text"), *(span.get("logs") or []),
+    ) if value) or " "
+
+
+def _like(value: str) -> str:
+    return "%" + value.replace("!", "!!").replace("%", "!%").replace("_", "!_") + "%"
+
+
+class SQLTraceStore:
+    """One tenant, one DB-API connection, guarded by a thread lock."""
+
+    dialect = ""
+
+    def __init__(self, connection: Any, *, tenant_id: str | int,
+                 table_prefix: str = "fuju_trace") -> None:
+        if not _PREFIX.fullmatch(table_prefix):
+            raise ValueError("table_prefix must be a short lowercase SQL identifier")
+        if tenant_id is None or str(tenant_id) == "":
+            raise ValueError("tenant_id is required")
+        self._conn = connection
+        self._lock = threading.RLock()
+        self._closed = False
+        self._tenant = str(tenant_id)
+        self._tenant_key = _key(self._tenant)
+        self.prefix = table_prefix
+        self._config = f"{table_prefix}_config"
+        self._events = f"{table_prefix}_events"
+        self._spans = f"{table_prefix}_spans"
+        self._attrs = f"{table_prefix}_attrs"
+
+    @property
+    def _bind(self) -> str:
+        return "?" if self.dialect in ("sqlite", "duckdb") else "%s"
+
+    def _execute(self, cur: Any, sql: str, params: Sequence[Any] = ()) -> Any:
+        return cur.execute(sql.replace("?", self._bind), tuple(params))
+
+    @contextmanager
+    def _tx(self, *, write: bool = False) -> Iterator[Any]:
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("trace store is closed")
+            # DuckDB cursor() creates another connection. An unnamed in-memory
+            # database would then appear empty to that connection.
+            cur = self._conn if self.dialect == "duckdb" else self._conn.cursor()
+            try:
+                if write and self.dialect == "sqlite":
+                    cur.execute("BEGIN IMMEDIATE")
+                elif write and self.dialect == "duckdb":
+                    cur.execute("BEGIN TRANSACTION")
+                yield cur
+                if self.dialect != "duckdb" or write:
+                    self._conn.commit()
+            except Exception:
+                if self.dialect != "duckdb" or write:
+                    self._conn.rollback()
+                raise
+            finally:
+                if cur is not self._conn:
+                    cur.close()
+
+    def _tenant_for(self, requested: str | int | None) -> str:
+        if requested is not None and str(requested) != self._tenant:
+            raise ValueError("tenant_id does not match this store")
+        return self._tenant_key
+
+    def initialize(self) -> None:
+        """Create a private, versioned schema; never mutate another prefix."""
+        with self._tx(write=True) as cur:
+            self._execute(cur, f"CREATE TABLE IF NOT EXISTS {self._config} (name TEXT PRIMARY KEY, value VARCHAR(255) NOT NULL)")
+            self._execute(cur, f"SELECT value FROM {self._config} WHERE name='schema_version'")
+            row = cur.fetchone()
+            if row is None:
+                self._execute(cur, f"INSERT INTO {self._config} (name,value) VALUES ('schema_version','1')")
+            elif row[0] != "1":
+                raise ValueError(f"unsupported {self.prefix} schema version")
+            self._execute(cur, f"""CREATE TABLE IF NOT EXISTS {self._events} (
+                tenant_key CHAR(64) NOT NULL, event_key CHAR(64) NOT NULL,
+                trace_key CHAR(64) NOT NULL, span_key CHAR(64) NOT NULL,
+                seq BIGINT NOT NULL, ts BIGINT NOT NULL, event_json TEXT NOT NULL,
+                PRIMARY KEY (tenant_key,event_key))""")
+            self._execute(cur, f"""CREATE TABLE IF NOT EXISTS {self._spans} (
+                tenant_key CHAR(64) NOT NULL, trace_key CHAR(64) NOT NULL,
+                span_key CHAR(64) NOT NULL, trace_id TEXT NOT NULL,
+                span_id TEXT NOT NULL, ts BIGINT NOT NULL,
+                agent_name TEXT, status INTEGER, session_key CHAR(64),
+                search_text TEXT NOT NULL, data TEXT NOT NULL,
+                PRIMARY KEY (tenant_key,trace_key,span_key))""")
+            self._execute(cur, f"""CREATE TABLE IF NOT EXISTS {self._attrs} (
+                tenant_key CHAR(64) NOT NULL, trace_key CHAR(64) NOT NULL,
+                span_key CHAR(64) NOT NULL, attr_key_hash CHAR(64) NOT NULL,
+                value_hash CHAR(64) NOT NULL, attr_key TEXT NOT NULL,
+                value_json TEXT NOT NULL,
+                PRIMARY KEY (tenant_key,trace_key,span_key,attr_key_hash))""")
+            self._index(cur, f"{self.prefix}_event_span_idx", self._events,
+                        "(tenant_key,trace_key,span_key,seq)")
+            self._index(cur, f"{self.prefix}_span_time_idx", self._spans,
+                        "(tenant_key,ts)")
+            self._index(cur, f"{self.prefix}_span_session_idx", self._spans,
+                        "(tenant_key,session_key,ts)")
+            self._index(cur, f"{self.prefix}_attrs_lookup_idx", self._attrs,
+                        "(tenant_key,attr_key_hash,value_hash)")
+
+    def _index(self, cur: Any, name: str, table: str, columns: str) -> None:
+        self._execute(cur, f"CREATE INDEX IF NOT EXISTS {name} ON {table} {columns}")
+
+    def ingest(self, events: Sequence[Mapping[str, Any]], *,
+               tenant_id: str | int | None = None) -> dict[str, int]:
+        tenant = self._tenant_for(tenant_id)
+        prepared: list[tuple[str, str, str, str, str, int, int, str]] = []
+        for raw in events:
+            event = dict(raw)
+            if event.get("tenant_id") is not None and str(event["tenant_id"]) != self._tenant:
+                raise ValueError("event tenant_id does not match this store")
+            kind, seq = int(event["event_type"]), int(event["seq"])
+            if kind not in (1, 2, 3, 4, 5) or not 0 <= seq < 2**63:
+                raise ValueError("invalid event_type or seq")
+            ext_id = str(event["ext_span_id"]) if event.get("ext_span_id") is not None else ""
+            if not ext_id:
+                raise ValueError("ext_span_id is required")
+            expected_id = event_id(ext_id, seq, EventType(kind))
+            if event.get("event_id") is not None and int(event["event_id"]) != expected_id:
+                raise ValueError("event_id does not match ext_span_id, seq and event_type")
+            trace_id = str(event["trace_id"]) if event.get("trace_id") is not None else ""
+            span_id = str(event["span_id"]) if event.get("span_id") is not None else ""
+            if not trace_id or not span_id:
+                raise ValueError("trace_id and span_id are required")
+            event["tenant_id"] = self._tenant
+            identity = _key(_json([ext_id, seq, kind]))
+            prepared.append((identity, _key(trace_id), _key(span_id),
+                             trace_id, span_id, seq, int(event["ts"]), _json(event)))
+        if not prepared:
+            return {"ingested": 0}
+        group_ids = {(trace_key, span_key): (trace_id, span_id)
+                     for _, trace_key, span_key, trace_id, span_id, _, _, _ in prepared}
+        groups = sorted(group_ids)
+        inserted = 0
+        with self._tx(write=True) as cur:
+            for trace_key, span_key in groups:
+                trace_id, span_id = group_ids[(trace_key, span_key)]
+                self._execute(cur, f"""INSERT INTO {self._spans}
+                    (tenant_key,trace_key,span_key,trace_id,span_id,ts,search_text,data)
+                    VALUES (?,?,?,?,?,0,' ','{{}}') ON CONFLICT DO NOTHING""",
+                    (tenant, trace_key, span_key, trace_id, span_id))
+                lock = " FOR UPDATE" if self.dialect == "postgresql" else ""
+                self._execute(cur, f"""SELECT 1 FROM {self._spans}
+                    WHERE tenant_key=? AND trace_key=? AND span_key=?{lock}""",
+                    (tenant, trace_key, span_key))
+                cur.fetchone()
+            for identity, trace_key, span_key, _trace_id, _span_id, seq, ts, body in prepared:
+                self._execute(cur, f"""SELECT trace_key,span_key FROM {self._events}
+                    WHERE tenant_key=? AND event_key=?""", (tenant, identity))
+                existing = cur.fetchone()
+                if existing is not None:
+                    if (str(existing[0]), str(existing[1])) != (trace_key, span_key):
+                        raise ValueError("duplicate event identity belongs to another span")
+                    continue
+                self._execute(cur, f"""INSERT INTO {self._events}
+                    (tenant_key,event_key,trace_key,span_key,seq,ts,event_json)
+                    VALUES (?,?,?,?,?,?,?)""",
+                    (tenant, identity, trace_key, span_key, seq, ts, body))
+                inserted += 1
+            for trace_key, span_key in groups:
+                self._execute(cur, f"""SELECT event_json FROM {self._events}
+                    WHERE tenant_key=? AND trace_key=? AND span_key=?
+                    ORDER BY seq,event_key""", (tenant, trace_key, span_key))
+                sources = [json.loads(row[0]) for row in cur.fetchall()]
+                if not sources:
+                    self._execute(cur, f"""DELETE FROM {self._spans}
+                        WHERE tenant_key=? AND trace_key=? AND span_key=? AND data='{{}}'""",
+                        (tenant, trace_key, span_key))
+                    continue
+                span = _fold(sources)
+                session = span.get("external_session_id") or span.get("session_id")
+                self._execute(cur, f"""UPDATE {self._spans} SET
+                    ts=?,agent_name=?,status=?,session_key=?,search_text=?,data=?
+                    WHERE tenant_key=? AND trace_key=? AND span_key=?""",
+                    (span["ts"], span.get("agent_name"), span.get("status"),
+                     _key(session) if session is not None else None,
+                     _search_text(span), _json(span), tenant, trace_key, span_key))
+                self._execute(cur, f"""DELETE FROM {self._attrs}
+                    WHERE tenant_key=? AND trace_key=? AND span_key=?""",
+                    (tenant, trace_key, span_key))
+                for attr_key, value in sorted((span.get("attrs") or {}).items()):
+                    encoded = _json(value)
+                    self._execute(cur, f"""INSERT INTO {self._attrs}
+                        (tenant_key,trace_key,span_key,attr_key_hash,value_hash,attr_key,value_json)
+                        VALUES (?,?,?,?,?,?,?)""",
+                        (tenant, trace_key, span_key, _key(attr_key), _key(encoded),
+                         str(attr_key), encoded))
+        return {"ingested": inserted}
+
+    def _where(self, filters: Mapping[str, Any]) -> tuple[str, list[Any]]:
+        clauses = ["s.tenant_key=?", "s.data<>'{}'"]
+        params: list[Any] = [self._tenant_key]
+        attrs: dict[str, Any] = {}
+        for key, value in filters.items():
+            if key in {"tenant_id", "tenantId"}:
+                raise ValueError("tenant cannot be set in a filter")
+            if value is None and key != "attrs":
+                continue
+            if key in {"trace_id", "externalTraceId", "external_trace_id"}:
+                clauses.append("s.trace_key=?")
+                params.append(_key(value))
+            elif key in {"externalSessionId", "external_session_id"}:
+                clauses.append("s.session_key=?")
+                params.append(_key(value))
+            elif key == "agent_name":
+                clauses.append("s.agent_name=?")
+                params.append(value)
+            elif key == "status":
+                clauses.append("s.status=?")
+                params.append(value)
+            elif key in {"time_from", "time_to"}:
+                clauses.append(f"s.ts {'>=' if key == 'time_from' else '<='}?")
+                params.append(int(value))
+            elif key == "attrs":
+                if not isinstance(value, Mapping):
+                    raise ValueError("filter.attrs must be an object")
+                attrs.update(value)
+            elif key in {"project_id", "projectId", "skill", "mode", "call_site", "callSite"}:
+                attrs[_ALIASES.get(key, key)] = value
+            else:
+                raise ValueError(f"unsupported search filter: {key}")
+        for key, value in sorted(attrs.items()):
+            encoded = _json(value)
+            clauses.append(f"""EXISTS (SELECT 1 FROM {self._attrs} a
+                WHERE a.tenant_key=s.tenant_key AND a.trace_key=s.trace_key
+                AND a.span_key=s.span_key AND a.attr_key_hash=?
+                AND a.value_hash=? AND a.attr_key=? AND a.value_json=?)""")
+            params.extend((_key(key), _key(encoded), str(key), encoded))
+        return " AND ".join(clauses), params
+
+    def search(self, query: Mapping[str, Any] | None = None, *,
+               tenant_id: str | int | None = None, **kwargs: Any) -> list[dict[str, Any]]:
+        self._tenant_for(tenant_id)
+        body = {**dict(query or {}), **kwargs}
+        if set(body) - {"text", "vector", "k", "filter"}:
+            raise ValueError("unsupported search field")
+        if body.get("vector") is not None:
+            raise NotImplementedError(f"{self.dialect} vector search is not configured")
+        text = body.get("text")
+        if not isinstance(text, str) or not text:
+            raise ValueError("search requires non-empty text")
+        k = int(body.get("k", 10))
+        if not 1 <= k <= 1000:
+            raise ValueError("k must be between 1 and 1000")
+        filters = body.get("filter") or {}
+        if not isinstance(filters, Mapping):
+            raise ValueError("filter must be an object")
+        where, params = self._where(filters)
+        with self._tx() as cur:
+            self._execute(cur, f"""SELECT s.data FROM {self._spans} s
+                WHERE {where} AND s.search_text LIKE ? ESCAPE '!'
+                ORDER BY s.ts DESC,s.trace_key,s.span_key LIMIT ?""",
+                (*params, _like(text), k))
+            return [dict(json.loads(row[0]), score=1.0) for row in cur.fetchall()]
+
+    def trace(self, trace_id: str | int, *, tenant_id: str | int | None = None) -> list[dict[str, Any]]:
+        tenant = self._tenant_for(tenant_id)
+        with self._tx() as cur:
+            self._execute(cur, f"""SELECT data FROM {self._spans}
+                WHERE tenant_key=? AND trace_key=? AND data<>'{{}}'
+                ORDER BY ts,span_key""", (tenant, _key(trace_id)))
+            return [json.loads(row[0]) for row in cur.fetchall()]
+
+    def span(self, trace_id: str | int, span_id: str | int, *,
+             tenant_id: str | int | None = None) -> dict[str, Any] | None:
+        tenant = self._tenant_for(tenant_id)
+        with self._tx() as cur:
+            self._execute(cur, f"""SELECT data FROM {self._spans}
+                WHERE tenant_key=? AND trace_key=? AND span_key=? AND data<>'{{}}'""",
+                (tenant, _key(trace_id), _key(span_id)))
+            row = cur.fetchone()
+            return json.loads(row[0]) if row else None
+
+    def list_spans(self, *, filters: Mapping[str, Any] | None = None,
+                   limit: int = 100, cursor: int = 0,
+                   tenant_id: str | int | None = None) -> dict[str, Any]:
+        self._tenant_for(tenant_id)
+        if not 1 <= limit <= 1000 or cursor < 0:
+            raise ValueError("limit must be 1..1000 and cursor nonnegative")
+        where, params = self._where(filters or {})
+        with self._tx() as cur:
+            self._execute(cur, f"SELECT COUNT(*) FROM {self._spans} s WHERE {where}", params)
+            total = int(cur.fetchone()[0])
+            self._execute(cur, f"""SELECT s.data FROM {self._spans} s WHERE {where}
+                ORDER BY s.ts,s.trace_key,s.span_key LIMIT ? OFFSET ?""",
+                (*params, limit, cursor))
+            return {"items": [json.loads(row[0]) for row in cur.fetchall()], "total": total}
+
+    def list_trace_ids(self, *, filters: Mapping[str, Any] | None = None,
+                       limit: int = 20, cursor: int = 0,
+                       tenant_id: str | int | None = None) -> dict[str, Any]:
+        self._tenant_for(tenant_id)
+        if not 1 <= limit <= 1000 or cursor < 0:
+            raise ValueError("limit must be 1..1000 and cursor nonnegative")
+        where, params = self._where(filters or {})
+        with self._tx() as cur:
+            self._execute(cur, f"SELECT COUNT(DISTINCT s.trace_key) FROM {self._spans} s WHERE {where}", params)
+            total = int(cur.fetchone()[0])
+            self._execute(cur, f"""SELECT MIN(s.trace_id) FROM {self._spans} s WHERE {where}
+                GROUP BY s.trace_key ORDER BY MIN(s.ts),s.trace_key LIMIT ? OFFSET ?""",
+                (*params, limit, cursor))
+            return {"items": [str(row[0]) for row in cur.fetchall()], "total": total}
+
+    def capabilities(self) -> dict[str, Any]:
+        return {"backend": self.dialect, "text": "substring_scan",
+                "vector": None, "hybrid": None, "attrs_filter": "exact_sql",
+                "transactional_projection": True, "session_filter": True}
+
+    def ping(self) -> bool:
+        with self._tx() as cur:
+            self._execute(cur, f"SELECT value FROM {self._config} WHERE name='schema_version'")
+            row = cur.fetchone()
+            if row is None or row[0] != "1":
+                return False
+            for table in (self._events, self._spans, self._attrs):
+                self._execute(cur, f"SELECT 1 FROM {table} LIMIT 0")
+            return True
+
+    def close(self) -> None:
+        with self._lock:
+            if not self._closed:
+                self._closed = True
+                self._conn.close()
+
+    def __enter__(self) -> SQLTraceStore:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+
+class SQLiteTraceStore(SQLTraceStore):
+    dialect = "sqlite"
+
+    @classmethod
+    def open(cls, path: str | Path, *, tenant_id: str | int,
+             initialize: bool = False, table_prefix: str = "fuju_trace") -> SQLiteTraceStore:
+        conn = sqlite3.connect(str(path), timeout=30, check_same_thread=False)
+        conn.execute("PRAGMA busy_timeout=30000")
+        if str(path) != ":memory:":
+            conn.execute("PRAGMA journal_mode=WAL")
+        store = cls(conn, tenant_id=tenant_id, table_prefix=table_prefix)
+        try:
+            if initialize:
+                store.initialize()
+            return store
+        except Exception:
+            store.close()
+            raise
+
+
+class DuckDBTraceStore(SQLTraceStore):
+    dialect = "duckdb"
+
+    @classmethod
+    def open(cls, path: str | Path, *, tenant_id: str | int,
+             initialize: bool = False, table_prefix: str = "fuju_trace") -> DuckDBTraceStore:
+        try:
+            import duckdb
+        except ImportError as exc:
+            raise RuntimeError("install fuju-trace-sql[duckdb]") from exc
+        store = cls(duckdb.connect(str(path)), tenant_id=tenant_id, table_prefix=table_prefix)
+        try:
+            if initialize:
+                store.initialize()
+            return store
+        except Exception:
+            store.close()
+            raise
+
+
+class PostgreSQLTraceStore(SQLTraceStore):
+    dialect = "postgresql"
+
+    @classmethod
+    def open(cls, dsn: str | None = None, *, tenant_id: str | int,
+             connection_params: Mapping[str, Any] | None = None,
+             initialize: bool = False, table_prefix: str = "fuju_trace",
+             connection_factory: Callable[..., Any] | None = None) -> PostgreSQLTraceStore:
+        if (dsn is None) == (connection_params is None):
+            raise ValueError("provide PostgreSQL dsn or connection_params")
+        if dsn == "" or connection_params == {}:
+            raise ValueError("PostgreSQL connection target must not be empty")
+        if connection_factory is None:
+            try:
+                import psycopg2
+            except ImportError as exc:
+                raise RuntimeError("install fuju-trace-sql[postgresql]") from exc
+            connection_factory = psycopg2.connect
+        conn = (connection_factory(dsn) if dsn is not None
+                else connection_factory(**dict(connection_params)))
+        if hasattr(conn, "autocommit"):
+            conn.autocommit = False
+        store = cls(conn, tenant_id=tenant_id, table_prefix=table_prefix)
+        try:
+            if initialize:
+                store.initialize()
+            return store
+        except Exception:
+            store.close()
+            raise

fuju_trace_sql-0.1.10/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling==1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fuju-trace-sql"
+version = "0.1.10"
+description = "SQLite, DuckDB and PostgreSQL storage adapters for Fuju Trace"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Fuju Trace" }]
+dependencies = ["fuju-trace==0.1.10"]
+
+[project.optional-dependencies]
+duckdb = ["duckdb>=1.0,<3"]
+postgresql = ["psycopg2-binary>=2.9.5,<3"]
+
+[project.urls]
+Homepage = "https://github.com/vibeinging/fuju-trace"
+Repository = "https://github.com/vibeinging/fuju-trace"
+Issues = "https://github.com/vibeinging/fuju-trace/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["fuju_trace_sql"]

fuju_trace_sql-0.1.10/tests/live_smoke.py

@@ -0,0 +1,133 @@
+"""Integration checks against a disposable PostgreSQL database.
+
+Creates and removes four tables under a random fuju_smoke_* prefix.
+"""
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import uuid
+from contextlib import closing
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+sys.path.insert(0, str(ROOT.parent / "fuju-trace-sdk" / "python"))
+
+from fuju_trace import DbExporter, Tracer, connect
+
+
+def _event(trace_id: str, span_id: str, ext_span_id: str, seq: int,
+           event_type: int, **fields: object) -> dict[str, object]:
+    return {
+        "trace_id": trace_id, "span_id": span_id, "ext_span_id": ext_span_id,
+        "seq": seq, "event_type": event_type, "ts": 100 + seq,
+        "tenant_id": 1, **fields,
+    }
+
+
+def main() -> int:
+    prefix = "fuju_smoke_" + uuid.uuid4().hex[:12]
+    dsn = os.environ.get("POSTGRESQL_DSN")
+    if not dsn:
+        raise SystemExit("POSTGRESQL_DSN is required")
+    db = None
+    try:
+        db = connect(postgresql_dsn=dsn, tenant_id=1, initialize=True,
+                     table_prefix=prefix)
+        assert db.ping()
+
+        trace_id = "live-" + uuid.uuid4().hex
+        span_id = "span-1"
+        source_id = "source-" + uuid.uuid4().hex
+        events = [
+            _event(trace_id, span_id, source_id, 0, 1, span_name="review",
+                   session_id=42, attrs={"project_id": "sql-live"}),
+            _event(trace_id, span_id, source_id, 1, 4, logs=["疑似盗刷"]),
+            _event(trace_id, span_id, source_id, 2, 2, status=1),
+        ]
+        assert db.ingest(events[1:]) == {"ingested": 2}
+        assert db.ingest(events) == {"ingested": 1}
+        assert db.ingest(events) == {"ingested": 0}
+        span = db.span(trace_id, span_id)
+        assert span is not None and span["event_count"] == 3
+        assert span["span_name"] == "review" and span["logs"] == ["疑似盗刷"]
+        assert db.trace(trace_id) == [span]
+        assert len(db.search(text="盗刷", filter={"project_id": "sql-live", "status": 1})) == 1
+        assert db.list_trace_ids(filters={"externalSessionId": 42})["items"] == [trace_id]
+
+        try:
+            db.ingest([{**events[0], "span_id": "wrong-span"}])
+        except ValueError:
+            pass
+        else:
+            raise AssertionError("conflicting event identity was accepted")
+        assert db.span(trace_id, "wrong-span") is None
+        assert db.span(trace_id, span_id)["event_count"] == 3
+
+        with connect(postgresql_dsn=dsn, tenant_id=2, table_prefix=prefix) as other_tenant:
+            assert other_tenant.trace(trace_id) == []
+            assert other_tenant.search(text="盗刷") == []
+
+        concurrent_span = "span-2"
+        concurrent_source = "source-" + uuid.uuid4().hex
+        db.ingest([_event(trace_id, concurrent_span, concurrent_source, 0, 1,
+                          span_name="parallel")])
+        barrier = threading.Barrier(2)
+        failures: list[Exception] = []
+
+        def write_one(event: dict[str, object]) -> None:
+            try:
+                with connect(postgresql_dsn=dsn, tenant_id=1, table_prefix=prefix) as writer:
+                    barrier.wait(timeout=10)
+                    writer.ingest([event])
+            except Exception as exc:
+                failures.append(exc)
+
+        writers = [
+            threading.Thread(target=write_one, args=(
+                _event(trace_id, concurrent_span, concurrent_source, 1, 4,
+                       logs=["parallel log"]),)),
+            threading.Thread(target=write_one, args=(
+                _event(trace_id, concurrent_span, concurrent_source, 2, 2,
+                       status=0),)),
+        ]
+        for writer in writers:
+            writer.start()
+        for writer in writers:
+            writer.join(timeout=15)
+        assert not any(writer.is_alive() for writer in writers), "parallel writers timed out"
+        assert not failures, failures
+        folded = db.span(trace_id, concurrent_span)
+        assert folded is not None and folded["event_count"] == 3
+        assert folded["logs"] == ["parallel log"] and folded["has_end"]
+
+        tracer = Tracer(exporter=DbExporter(db, tenant_id=1), node_id=1)
+        with tracer.trace("smoke", session_id=42, tenant_id=1) as trace:
+            with trace.span("write") as span:
+                span.log("fuju sql live smoke")
+        tracer.close()
+        assert len(db.search(text="fuju sql live smoke")) == 1
+        db.close()
+        db = None
+        with connect(postgresql_dsn=dsn, tenant_id=1, table_prefix=prefix) as reopened:
+            assert reopened.ping()
+            assert reopened.span(trace_id, span_id)["event_count"] == 3
+            assert reopened.span(trace_id, concurrent_span)["event_count"] == 3
+        print("postgresql: real write, retry, rollback, tenant, concurrent writers, search, reopen OK")
+    finally:
+        if db is not None:
+            db.close()
+        # These names were generated here and validated by the store.
+        import psycopg2
+        with closing(psycopg2.connect(dsn)) as cleanup:
+            with cleanup:
+                with cleanup.cursor() as cur:
+                    for suffix in ("attrs", "spans", "events", "config"):
+                        cur.execute(f"DROP TABLE IF EXISTS {prefix}_{suffix}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fuju_trace_sql-0.1.10/tests/run_local_postgresql.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
+test_python=${FUJU_SQL_PYTHON:-python3}
+
+for program in initdb pg_ctl createdb; do
+  if ! command -v "$program" >/dev/null 2>&1; then
+    printf 'missing PostgreSQL command: %s\n' "$program" >&2
+    exit 1
+  fi
+done
+"$test_python" -c 'import psycopg2' || {
+  printf 'install fuju-trace-sql[postgresql] for %s\n' "$test_python" >&2
+  exit 1
+}
+
+pg_test_dir=$(mktemp -d /tmp/fuju-trace-pg.XXXXXX)
+cleanup() {
+  pg_ctl -D "$pg_test_dir/data" -m immediate stop >/dev/null 2>&1 || true
+  rm -r -- "$pg_test_dir"
+}
+trap cleanup EXIT
+
+initdb -D "$pg_test_dir/data" -A trust -U fuju_test --no-instructions > "$pg_test_dir/init.log"
+pg_ctl -D "$pg_test_dir/data" -l "$pg_test_dir/server.log" \
+  -o "-c listen_addresses='' -c unix_socket_directories=$pg_test_dir -p 55432" start
+createdb -h "$pg_test_dir" -p 55432 -U fuju_test fuju_test
+
+POSTGRESQL_DSN="host=$pg_test_dir port=55432 dbname=fuju_test user=fuju_test" \
+  "$test_python" "$repo_dir/fuju-trace-sql/tests/live_smoke.py"

fuju_trace_sql-0.1.10/tests/test_sql.py

@@ -0,0 +1,190 @@
+import sys
+import sqlite3
+import tempfile
+import threading
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+sys.path.insert(0, str(ROOT.parent / "fuju-trace-sdk" / "python"))
+
+from fuju_trace import DbExporter, Tracer, connect
+from fuju_trace_sql import (
+    DuckDBTraceStore, PostgreSQLTraceStore, SQLiteTraceStore,
+)
+
+
+def _events():
+    return [
+        {"trace_id": "trace-1", "span_id": "span-1", "ext_span_id": "source-1",
+         "event_type": 1, "seq": 0, "ts": 10, "tenant_id": 1,
+         "span_name": "plan", "session_id": 42, "agent_name": "planner",
+         "attrs": {"project_id": "demo", "retry": True}},
+        {"trace_id": "trace-1", "span_id": "span-1", "ext_span_id": "source-1",
+         "event_type": 4, "seq": 1, "ts": 11, "tenant_id": 1,
+         "logs": ["疑似盗刷"], "attrs": {"step": 2}},
+        {"trace_id": "trace-1", "span_id": "span-1", "ext_span_id": "source-1",
+         "event_type": 2, "seq": 2, "ts": 12, "tenant_id": 1, "status": 1},
+    ]
+
+
+class SQLiteTests(unittest.TestCase):
+    def test_sdk_round_trip_retry_filters_and_reopen(self):
+        with tempfile.TemporaryDirectory() as temp:
+            db_path = Path(temp) / "trace.sqlite"
+            with connect(sqlite_path=db_path, tenant_id=1, initialize=True) as db:
+                self.assertTrue(db.ping())
+                self.assertEqual(db.ingest(_events()[1:]), {"ingested": 2})
+                self.assertEqual(db.ingest(_events()), {"ingested": 1})
+                self.assertEqual(db.ingest(_events()), {"ingested": 0})
+                span = db.span("trace-1", "span-1")
+                self.assertEqual(span["span_name"], "plan")
+                self.assertEqual(span["logs"], ["疑似盗刷"])
+                self.assertEqual(span["event_count"], 3)
+                self.assertEqual(db.trace("trace-1"), [span])
+                query = {"text": "盗刷", "filter": {
+                    "externalSessionId": 42, "agent_name": "planner",
+                    "status": 1, "attrs": {"project_id": "demo", "retry": True},
+                }}
+                self.assertEqual(len(db.search(query)), 1)
+                self.assertEqual(db.search(text="盗%", k=10), [])
+                self.assertEqual(db.list_spans(filters={"externalSessionId": 42})["total"], 1)
+                self.assertEqual(db.list_trace_ids(filters={"externalSessionId": 42})["items"], ["trace-1"])
+                with self.assertRaises(ValueError):
+                    db.search(text="盗刷", filter={"tenant_id": 2})
+                with self.assertRaises(ValueError):
+                    db.span("trace-1", "span-1", tenant_id=2)
+                with self.assertRaises(NotImplementedError):
+                    db.search(vector=[1.0, 0.0])
+                self.assertEqual(db.capabilities()["vector"], None)
+            with SQLiteTraceStore.open(db_path, tenant_id=1, initialize=True) as reopened:
+                self.assertEqual(reopened.span("trace-1", "span-1")["event_count"], 3)
+            with SQLiteTraceStore.open(db_path, tenant_id=2) as other:
+                self.assertEqual(other.trace("trace-1"), [])
+
+    def test_transaction_rollback_and_conflicting_retry(self):
+        with SQLiteTraceStore.open(":memory:", tenant_id=1, initialize=True) as db:
+            with self.assertRaises(ValueError):
+                db.ingest([_events()[0], {**_events()[1], "tenant_id": 2}])
+            self.assertEqual(db.list_spans()["total"], 0)
+            with self.assertRaises(TypeError):
+                db.ingest([{**_events()[0], "logs": [["invalid log"]]}])
+            self.assertEqual(db.list_spans()["total"], 0)
+            db.ingest([_events()[0]])
+            with self.assertRaises(ValueError):
+                db.ingest([{**_events()[0], "span_id": "another"}])
+            self.assertEqual(db.list_spans()["total"], 1)
+            self.assertIsNone(db.span("trace-1", "another"))
+
+    def test_sdk_exporter_and_concurrent_sessions(self):
+        with SQLiteTraceStore.open(":memory:", tenant_id=1, initialize=True) as db:
+            failures = []
+            def write(node):
+                try:
+                    tracer = Tracer(exporter=DbExporter(db, tenant_id=1), node_id=node)
+                    with tracer.trace(f"request-{node}", session_id=node, tenant_id=1) as trace:
+                        with trace.span("work") as span:
+                            span.log(f"log-{node}")
+                    tracer.close()
+                except Exception as exc:
+                    failures.append(exc)
+            threads = [threading.Thread(target=write, args=(i,)) for i in range(4)]
+            for thread in threads:
+                thread.start()
+            for thread in threads:
+                thread.join()
+            self.assertFalse(failures)
+            self.assertEqual(db.list_spans()["total"], 4)
+
+    def test_validation_and_no_silent_vector_claim(self):
+        with SQLiteTraceStore.open(":memory:", tenant_id=1, initialize=True) as db:
+            event = _events()[0]
+            with self.assertRaises(ValueError):
+                db.ingest([{**event, "event_id": 42}])
+            with self.assertRaises(ValueError):
+                db.ingest([{**event, "ext_span_id": None}])
+            self.assertEqual(db.list_spans()["total"], 0)
+        with self.assertRaises(ValueError):
+            connect(sqlite_path=":memory:", duckdb_path=":memory:", tenant_id=1)
+        with self.assertRaises(ValueError):
+            connect(sqlite_path=":memory:", tenant_id=None)
+
+
+class DriverRoutingTests(unittest.TestCase):
+    def test_postgresql_dml_through_dbapi_compatibility_layer(self):
+        # SQLite executes equivalent SQL here; real server smoke is separate.
+        class Cursor:
+            def __init__(self, inner):
+                self.inner = inner
+            def execute(self, sql, params=()):
+                sql = sql.replace("%s", "?").replace(" FOR UPDATE", "")
+                return self.inner.execute(sql, params)
+            def fetchone(self):
+                return self.inner.fetchone()
+            def fetchall(self):
+                return self.inner.fetchall()
+            def close(self):
+                self.inner.close()
+        class Connection:
+            def __init__(self, inner):
+                self.inner = inner
+            def cursor(self):
+                return Cursor(self.inner.cursor())
+            def commit(self):
+                self.inner.commit()
+            def rollback(self):
+                self.inner.rollback()
+            def close(self):
+                self.inner.close()
+        raw = sqlite3.connect(":memory:")
+        SQLiteTraceStore(raw, tenant_id=1).initialize()
+        wrapped = Connection(raw)
+        with PostgreSQLTraceStore.open(
+            "dbname=unused", tenant_id=1,
+            connection_factory=lambda _: wrapped,
+        ) as db:
+            self.assertEqual(db.ingest(_events()), {"ingested": 3})
+            self.assertEqual(db.ingest(_events()), {"ingested": 0})
+            self.assertEqual(db.list_trace_ids()["items"], ["trace-1"])
+            self.assertEqual(len(db.search(text="盗刷", filter={"project_id": "demo"})), 1)
+
+    def test_postgresql_driver_routing_without_connecting(self):
+        class Connection:
+            def __init__(self):
+                self.closed = False
+            def close(self):
+                self.closed = True
+        pg = Connection()
+        captured = []
+        with PostgreSQLTraceStore.open("dbname=trace", tenant_id=1,
+                                       connection_factory=lambda dsn: (captured.append(dsn), pg)[1]) as db:
+            self.assertEqual(db.capabilities()["backend"], "postgresql")
+        self.assertTrue(pg.closed)
+        self.assertEqual(captured[0], "dbname=trace")
+
+    def test_duckdb_round_trip_if_installed(self):
+        try:
+            import duckdb  # noqa: F401
+        except ImportError:
+            self.skipTest("duckdb optional driver is not installed")
+        with tempfile.TemporaryDirectory() as temp:
+            path = Path(temp) / "trace.duckdb"
+            with connect(duckdb_path=path, tenant_id=1, initialize=True) as db:
+                self.assertEqual(db.ingest(_events()[1:]), {"ingested": 2})
+                self.assertEqual(db.ingest(_events()), {"ingested": 1})
+                self.assertEqual(db.ingest(_events()), {"ingested": 0})
+                self.assertEqual(len(db.search(text="盗刷", filter={"externalSessionId": 42})), 1)
+                self.assertEqual(db.span("trace-1", "span-1")["event_count"], 3)
+                with self.assertRaises(ValueError):
+                    db.ingest([{**_events()[0], "span_id": "wrong-span"}])
+                self.assertIsNone(db.span("trace-1", "wrong-span"))
+            with DuckDBTraceStore.open(path, tenant_id=1) as db:
+                self.assertEqual(db.list_trace_ids()["items"], ["trace-1"])
+                self.assertEqual(db.span("trace-1", "span-1")["logs"], ["疑似盗刷"])
+            with DuckDBTraceStore.open(path, tenant_id=2) as other:
+                self.assertEqual(other.trace("trace-1"), [])
+
+
+if __name__ == "__main__":
+    unittest.main()