Guide

Getting Started

TrashDB is a RESTful API for provisioning ephemeral database containers. Every container has a TTL, so it is automatically destroyed when the timer reaches zero. No cleanup, no lingering infra.

Authentication

All API requests require an API key passed via the X-Api-Key header. Generate a key from your Dashboard.

# All requests must include:
X-Api-Key: tr_live_xxxxxxxxxxxx

# Example with curl
curl https://api.trashdb.dev/api/v1/containers \
  -H "X-Api-Key: tr_live_xxxxxxxxxxxx"

CI / GitHub Actions

The fastest way to run integration tests with disposable databases. Use the official trashdb/run-tests action — it creates a container, injects the connection string into your environment, runs your tests, and destroys the container when done.

Setup

Save your API key as a repository secret in GitHub: Settings → Secrets and variables → Actions.

# .github/workflows/test.yml
name: CI

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: trashdb/run-tests@v1
        with:
          api-key: ${{ secrets.TRASHDB_API_KEY }}
          engine: postgres
          run: npm test

Environment variables

The action automatically exports the right variable for each engine:

Engine	Env var	Also sets
postgres	DATABASE_URL	PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE
supabase	DATABASE_URL	PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE
redis	REDIS_URL	—
mongodb	MONGODB_URI	—
chromadb	CHROMA_URL	—
qdrant	QDRANT_URL	—

How it works

The action calls POST /containers to spin up an ephemeral database.
It exports the connection string as DATABASE_URL (and engine-specific vars).
Your test command runs — npm test, pytest, etc.
On exit, the container is destroyed. If something crashes, the TTL auto-cleans it.

Your tests read process.env.DATABASE_URL as usual. No SDK imports, no connection string management, no cleanup code.

Supported Engines

TrashDB currently supports the following database engines:

chromadb

ChromaDB

qdrant

Qdrant

redis

Redis

postgres

PostgreSQL

mongodb

MongoDB

supabase

Supabase

Error Handling

The API returns standard HTTP status codes. Error responses include a JSON body with an internal code and a human-readable message.

Status	Meaning
200	Success
201	Container created
204	Container destroyed
400	Bad request — invalid engine or missing field
401	Unauthorized — missing or invalid API key
404	Container not found
429	Rate limited
500	Internal server error

// Error response body
{
  "code": ERR_ENGINE_NOT_FOUND,
  "message": "Engine 'mysql' is not supported"
}

// SDK usage
import { TrashDBAPIError } from "@trashdb/ts"

try {
  await client.destroyContainer(id);
} catch (error) {
  if (error instanceof TrashDBAPIError)
    console.error(error.status, error.message);
}