Documentation | TrashDB

Python SDK

Published as trashdb on PyPI. Source on GitHub. Built with zero runtime dependencies — uses only stdlib urllib.request.

Installation

pip install trashdb

Quick start

from trashdb import TrashDB

client = TrashDB(
  api_key=os.environ["TRASHDB_API_KEY"],
)

container = client.create_container(
  engine="chromadb",
  ttl_minutes=15,
  name="my-test-db",
)

print(container.connection_string)

Reference

TrashDB(api_key, base_url=None, retry_max=3, retry_base_ms=500)

Constructor accepting an API key and optional base URL.

Param	Type	Description
api_key	str	Your API key from the Dashboard
base_url	str \| None	Defaults to https://api.trashdb.dev/api/v1
retry_max	int	Max retries for 502/503/504 responses (default 3)
retry_base_ms	int	Base backoff in ms, doubled each attempt (default 500)

create_container(engine, ttl_minutes, name=None)

Create an ephemeral database container. Returns a ContainerResponse with connection_string, host, port, etc.

Param	Type	Description
engine	str	Engine identifier (chromadb, qdrant, redis, postgres, mongodb, supabase)
ttl_minutes	int	Time-to-live in minutes
name	str \| None	Optional human-readable name

get_running_containers()

List all active containers. Returns list[ContainerResponse].

destroy_container(container_id)

Destroy a running container. Returns True on success.

Param	Type	Description
container_id	str	The container ID to destroy

get_engines()

List supported engines. Public, no auth needed. Returns list[EngineInfo].

get_container_logs(container_id, tail=100)

Fetch logs for a running container. Returns list[str].

Param	Type	Description
container_id	str	The container ID
tail	int	Number of lines to return (default 100)

Error handling

from trashdb import TrashDBAPIError

try:
  client.destroy_container(container_id)
except TrashDBAPIError as err:
  print(err.status, err.message)