Docs / SDKs / Python

Python SDK

Zero-dependency walkindb client for Python 3.8+. Uses urllib from the standard library, so it installs inside any agent sandbox.

Install

pip install walkindb

The package has zero runtime dependencies. It uses urllib.request and json from the Python standard library, so it installs and imports inside locked-down environments (Lambda, Cloud Run, Modal, Docker slim, conda, the Claude Code sandbox, etc.) with no libssl / libcurl / cryptography wheel problems.

60-second example

from walkindb import Client

db = Client()

# First call provisions a new walk-in; walkindb returns a session token which
# the Client captures transparently and reuses on subsequent calls.
db.execute("CREATE TABLE notes(id INTEGER PRIMARY KEY, body TEXT)")
db.execute("INSERT INTO notes(body) VALUES('hello')")

result = db.execute("SELECT * FROM notes")
print(result.columns)       # ['id', 'body']
print(result.rows)          # [[1, 'hello']]
print(result.rows_affected) # 0 on SELECT, N on INSERT/UPDATE/DELETE

# Inspect the session
print(db.session[:24])      # wkn_AZ159u9PdmS97ks7FnSm...
print(db.expires_at)        # unix timestamp when the walk-in will be deleted

Client

The walkindb client. Stateful — it remembers the session token returned on the first call and reuses it transparently. Thread-safe for reads of session / expires_at, but not designed for concurrent execute() calls across threads; use one Client per thread or coroutine.

Client(base_url, *, session, timeout, user_agent)

from walkindb import Client

db = Client(
    base_url="https://api.walkindb.com",  # optional; default shown
    session=None,                            # optional pre-existing token
    timeout=10.0,                            # seconds per request
    user_agent="walkindb-python/0.1.0",     # override if you want your own UA
)

Client.execute(sql, args=None) -> Result

Execute one SQL statement against the current walk-in instance.

# Simple statement
result = db.execute("SELECT 1 AS hello")

# Multiple statements in one call (semicolon-separated)
db.execute("""
    CREATE TABLE kv(k TEXT PRIMARY KEY, v TEXT);
    INSERT INTO kv VALUES('greeting', 'hello');
    INSERT INTO kv VALUES('farewell', 'goodbye');
""")

# Bound parameters (reserved for future use; currently sent on the wire but ignored server-side)
db.execute("INSERT INTO notes(body) VALUES(?)", ["hello"])

Returns: Result dataclass (documented below).

Raises: WalkinDBError on any non-2xx response.

Client.healthz() -> bool

Lightweight probe. Returns True if GET /healthz responds 2xx, False on any other status or network error. Does not raise. Does not consume rate-limit budget.

if not db.healthz():
    raise RuntimeError("walkindb unreachable")

Client.reset_session()

Forget the current session token. The next execute() call will provision a fresh walk-in.

db.reset_session()
db.execute("SELECT 1")  # provisions a new instance

Client.session (read-only property)

str | None. The current wkn_-prefixed session token, or None if no instance has been provisioned yet.

Client.expires_at (read-only property)

int | None. Unix timestamp (seconds since epoch) at which the current instance will be deleted, or None if no instance has been provisioned.

Result

Dataclass returned by Client.execute(). Mirrors the JSON response shape from the API:

@dataclass
class Result:
    columns:       list[str]       # column names; empty for non-SELECT
    rows:          list[list[Any]] # row data in column order
    rows_affected: int             # 0 on SELECT, N on INSERT/UPDATE/DELETE
    truncated:     bool            # True if walkindb capped the result at 10k rows / ~1 MB

WalkinDBError

Exception raised when the server returns a non-2xx response, or when a network-level error occurs. Subclasses Exception.

class WalkinDBError(Exception):
    status:       int             # HTTP status code (0 for network errors)
    error:        str             # server-provided error message
    retry_after:  float | None    # seconds to wait before retrying (from Retry-After header)

Error-handling recipe:

from walkindb import Client, WalkinDBError
import time

db = Client()
try:
    result = db.execute("SELECT * FROM notes")
except WalkinDBError as e:
    if e.status == 400:
        print("bad sql:", e.error)
    elif e.status == 404:
        # session expired or tampered — start fresh
        db.reset_session()
    elif e.status == 408:
        print("query timed out")
    elif e.status == 429:
        time.sleep(e.retry_after or 10)
    elif e.status == 507:
        # instance quota full — provision a new walk-in
        db.reset_session()
    else:
        raise

See the full Error codes reference for every status the server returns.

CLI smoke test

The package ships a minimal __main__ so you can verify installation and connectivity in one command:

python -m walkindb

session: wkn_AZ159u9PdmS97ks7FnSm...
expires_at: 1775891006
result: columns=['hello'] rows=[[1]]

Self-hosted deployments

If you're running walkindb on your own host, pass base_url:

db = Client(base_url="https://my-walkindb.internal:8443")

Also see

• JavaScript / TypeScript SDK — the equivalent client for JS
• REST API reference — what the client is wrapping
• Error codes
• Agent patterns — recipes using the Python client
• walkindb on PyPI