TrashDB.Client 0.1.0

TrashDB .NET SDK

Official C# / .NET client for TrashDB — spin up an ephemeral database in seconds, destroy it when you're done.

using var client = new TrashDBClient(new TrashDBOptions { ApiKey = "your-api-key" });

var container = await client.CreateContainerAsync(new CreateContainerParams
{
    Engine     = "postgres",
    TtlMinutes = 10,
    Name       = "my-integration-test-db",
});

Console.WriteLine(container.ConnectionString);
// Host=localhost;Port=54321;Database=trashdb;Username=trashdb;Password=...

await client.DestroyContainerAsync(container.Id);

Why TrashDB?

• Zero infra overhead — no Docker Compose files, no local DBs to manage, no cleanup scripts.
• Every test gets a fresh database — no shared state, no flaky tests from leftover data.
• 6 engines, one API — PostgreSQL, Redis, MongoDB, Qdrant, ChromaDB, Supabase.
• Auto-expiry — containers self-destruct after your TTL. Forget about it.
• CI-native — one API call to get a real database in your pipeline.

Installation

dotnet add package TrashDB.Client

Targets: netstandard2.1, net6.0, net8.0. Zero runtime dependencies.

Quick Start

1. Get an API key

Sign up at trashdb.dev and grab your API key from the dashboard.

2. Configure

Set the TRASHDB_API_KEY environment variable, or pass it directly:

export TRASHDB_API_KEY="trashdb-your-key-here"

3. Use the client

using TrashDB.Client;
using TrashDB.Client.Models;

// Option A: reads TRASHDB_API_KEY from environment
using var client = new TrashDBClient();

// Option B: explicit
using var client = new TrashDBClient(new TrashDBOptions
{
    ApiKey  = "trashdb-your-key-here",
    BaseUrl = "https://api.trashdb.dev/api/v1", // optional, this is the default
});

API Reference

CreateContainerAsync

Provisions a new ephemeral database container.

var container = await client.CreateContainerAsync(new CreateContainerParams
{
    Engine     = "postgres",   // required — see supported engines below
    TtlMinutes = 15,           // 1–1440 (24h). Defaults to 5.
    Name       = "my-db",      // optional friendly name
});

// container.Id              — unique container ID
// container.Engine          — "postgres"
// container.Port            — host port (e.g. 54321)
// container.ConnectionString — ready-to-use connection string
// container.ExpiresAt       — when the container will be destroyed

GetRunningContainersAsync

Lists all containers currently running for your account.

var containers = await client.GetRunningContainersAsync();
foreach (var c in containers)
    Console.WriteLine($"{c.Engine} on port {c.Port} — expires {c.ExpiresAt:u}");

DestroyContainerAsync

Destroys a container immediately, regardless of its TTL.

bool ok = await client.DestroyContainerAsync(container.Id);

GetEnginesAsync

Returns the list of supported database engines.

var engines = await client.GetEnginesAsync();
// [{ Id="postgres", Name="PostgreSQL", MaxTtlMinutes=1440 }, ...]

GetContainerLogsAsync

Retrieves recent log output from a running container (useful for debugging).

string logs = await client.GetContainerLogsAsync(
    containerId:   container.Id,
    tail:          100,          // last N lines, default 200
    sinceSeconds:  300           // last 5 minutes, optional
);

Supported Engines

Connection Strings

Each engine returns a ready-to-use connection string in container.ConnectionString:

Error Handling

All API errors throw TrashDBApiException:

using TrashDB.Client.Exceptions;
using TrashDB.Client.Models;

try
{
    var container = await client.CreateContainerAsync(new CreateContainerParams
    {
        Engine = "postgres",
        TtlMinutes = 9999, // exceeds limit
    });
}
catch (TrashDBApiException ex)
{
    Console.WriteLine($"HTTP {ex.HttpStatus}, code {ex.Code}: {ex.Message}");
    // HTTP 400, code 1003: TTL exceeds the maximum allowed value.

    if (ex.Code == TrashDBErrorCode.QuotaExceeded)
        Console.WriteLine("You've hit your monthly quota.");
}

Error codes

Full list in TrashDBErrorCode.

Advanced Usage

Dependency Injection (ASP.NET Core)

// Program.cs
builder.Services.AddSingleton(_ => new TrashDBClient(new TrashDBOptions
{
    ApiKey = builder.Configuration["TrashDB:ApiKey"],
}));

Testing with a mock HttpClient

var handler = new MockHttpMessageHandler();
var http    = new HttpClient(handler) { BaseAddress = new Uri("http://localhost") };

using var client = new TrashDBClient(new TrashDBOptions
{
    ApiKey     = "test-key",
    BaseUrl    = "http://localhost/api/v1",
    HttpClient = http,
});

Custom base URL (self-hosted)

using var client = new TrashDBClient(new TrashDBOptions
{
    ApiKey  = "your-key",
    BaseUrl = "https://your-trashdb-instance.example.com/api/v1",
});

Retry configuration

By default, the client retries 3 times on 502 / 503 / 504 with exponential backoff starting at 500 ms.

using var client = new TrashDBClient(new TrashDBOptions
{
    ApiKey         = "your-key",
    MaxRetries     = 5,
    InitialBackoff = TimeSpan.FromSeconds(1),
});

Use in CI / Integration Tests

A common pattern — create a container at test setup, destroy it at teardown:

// xUnit example
public class MyDbTests : IAsyncLifetime
{
    private TrashDBClient _trashDb = null!;
    private ContainerResponse _container = null!;

    public async Task InitializeAsync()
    {
        _trashDb   = new TrashDBClient();
        _container = await _trashDb.CreateContainerAsync(new CreateContainerParams
        {
            Engine     = "postgres",
            TtlMinutes = 10,
        });
        // Use _container.ConnectionString to configure your DbContext / Npgsql connection
    }

    public async Task DisposeAsync()
    {
        await _trashDb.DestroyContainerAsync(_container.Id);
        _trashDb.Dispose();
    }

    [Fact]
    public async Task MyTest()
    {
        // _container.ConnectionString is ready to use
    }
}

Other SDKs & Integrations

Contributing

Pull requests are welcome! Please open an issue first for major changes.

git clone https://github.com/trashdb/sdk-dotnet
cd sdk-dotnet
dotnet build
dotnet test

License

MIT © TrashDB