python-quickstart

Python Quickstart

What This Demonstrates

The full TraceDB Python sync SDK surface: client construction (with retry configuration), health check, catalog inspection, metrics, schema apply, GraphQL schema export, single-record put with idempotency replay and conflict detection, batch insert, patch, get, scan, hybrid query, TraceQL string execution, GraphQL query execution, explain plans, delete with tombstone, admin operations (compact, snapshot, restore, job listing), and typed error envelope parsing.

The smoke can either target an already-running TraceDB server or start one itself via cargo run from a sibling tracedb checkout.

Prerequisites

• Python 3.12+
• TraceDB server v0.1.0
• tracedb Python package v0.1.0
• Protocol lock revision a50c7ada6fdd56a25128d186fd611472b78133f7
• A TraceDB server, either:
  • Already running (set TRACEDB_URL and TRACEDB_TOKEN), or
  • A sibling ../tracedb checkout with a Rust toolchain so the smoke can start its own server

Run

# Option A: target an already-running server
export TRACEDB_URL="http://127.0.0.1:8080"
export TRACEDB_TOKEN="dev-token"
python3 http_smoke.py

# Option B: let the smoke start its own server (requires ../tracedb checkout)
python3 http_smoke.py

# Optional: write JSON summary to a file
python3 http_smoke.py --summary-json /tmp/smoke-summary.json

Verify

The script exits non-zero on any failure. A successful run prints a JSON summary ending with "ok": true and the message:

python sdk http smoke ok

Expected Output

A JSON summary object with fields:

• ok: true when all checks pass
• mode: "python-sdk-http-smoke"
• steps: per-operation booleans covering the full SDK surface
• records_put: 1, records_inserted: 3, records_scanned: 3
• traceql_result_count, graphql_result_count: non-zero
• idempotency_replay_epoch: matches put_epoch
• idempotency_conflict_status: 409
• error_envelope: parsed error from a deliberate malformed request
• snapshot_target, restore_target: admin paths

Notes

• Creates a table docs scoped to tenant tenant-a.
• When TRACEDB_URL is set, the smoke targets the externally provided server. The table and records are not automatically cleaned up. To remove the table, drop it via the TraceDB CLI or API after the run, or manually delete the server data directory if using a throwaway instance.
• When no TRACEDB_URL is set, the smoke starts a tracedb-server process via cargo run with a temporary data directory; the server is automatically terminated on completion, and the table and records are removed when the temporary data directory is removed.
• No network calls outside localhost.