Quick Start Guide

Get up and running with REDB in minutes

~10 min

How to start

A new project from a template: in the editor or with one command. The guide below starts from scratch, without templates.

1 In VS Code

The redb Route XML extension: the "redb: New Project" command shows every template as a card, builds a form from its parameters and creates the project.

The New redb Project page in VS Code
2 From the command line Fastest

SQLite with Pro: no database server, no license key. A console app with CRUD, queries and a tree; the database is a file next to the app.

$ dotnet new install redb.Templates
$ dotnet new redb -n MyApp
$ dotnet run --project MyApp

For integration: dotnet new redb-route-eip -n MyModule , it needs no broker and no database.

Applications

8 templates in the redb.Templates pack. Each runs as is; the ones marked Tsak run in their own host or as a Tsak module.

Console app redb

Create, load, update, query and a tree: the basics of RedBase in one Program.cs.

--db sqlite|postgres|mssql, --pro true|false

dotnet new redb -n MyApp
Details →
Razor Pages site redb-razor

A product list with search, sorting and paging in the database, and a create / edit form.

SQLite Pro; PostgreSQL or SQL Server through compose

dotnet new redb-razor -n MySite
Details →
Blazor site redb-blazor

The same list and form as an interactive Blazor Server site, plus a category tree.

SQLite Pro; PostgreSQL or SQL Server through compose

dotnet new redb-blazor -n MySite
Details →
Integration worker redb-worker
Tsak

Files from a folder, an XSD check, one transaction in RedBase, a receipt back. Duplicates are caught by a unique key.

SQLite Pro; SFTP, AS2 or SQL as the source in one line

dotnet new redb-worker -n MyWorker
Details →
LLM chat redb-chat
Tsak

A chat on redb.Route.Llm with the history in RedBase, in the console and over HTTP.

--tools none|shell|mcp, --audit true|false

dotnet new redb-chat -n MyChat
Details →
Blazor WebAssembly app redb-app
Tsak

A WebAssembly client and a REST DSL API with sign-in by JWT: products, a form, a category tree.

SQLite Pro; nginx serves the client and forwards /api/

dotnet new redb-app -n MyApp
Details →
Blazor BFF redb-bff
Tsak

A Blazor Server front with a cookie session and a backend of redb.Route controllers behind a service key.

SQLite Pro; the backend is reachable only from the web server

dotnet new redb-bff -n MyApp
Details →
Application on redb.Identity redb-identity-app
Tsak

A Tsak module next to Identity in one worker, checking bearer tokens by introspection over direct-vm, and a Blazor web server that signs users in with OpenID Connect.

--web true|false, --framework net10.0|net9.0|net8.0

dotnet new redb-identity-app -n MyApp
Details →

redb.Route modules

20 templates in the same pack. Each module shows its scenario as XML route files and as the same routes in C#, packs into a .tpkg and runs on a Tsak worker. Templates with a broker or a server ship a compose file for a local stand.

--context <name>, --framework net10.0|net9.0|net8.0

Basics 4

redb-route

A timer route in XML and the same route in C#, the context sample, a .tpkg on build.

dotnet new redb-route -n MyModule
redb-route-beans

XML routes that call a C# class of the project: a bean from configuration, method arguments, the exchange.

dotnet new redb-route-beans -n MyModule
redb-route-rest

An HTTP JSON API: GET and POST, a JSON schema check, 400 on a bad body, OpenAPI.

dotnet new redb-route-rest -n MyModule
redb-route-redb

Stores redb objects from routes: a props class as the scheme, save by a unique key, a typed LINQ report.

--db sqlite|postgres|mssql

dotnet new redb-route-redb -n MyModule

Integration patterns, no broker 4

redb-route-eip

Seda queue, idempotent consumer, throttle, wire tap, aggregator, router, splitter, dead letter channel.

dotnet new redb-route-eip -n MyModule
redb-route-scatter-gather

One request to three recipients in parallel, a timeout, the best answer picked.

dotnet new redb-route-scatter-gather -n MyModule
redb-route-validator-xslt

XML documents: an XSD check, an XSLT transformation, a rejected document routed with the reason.

dotnet new redb-route-validator-xslt -n MyModule
redb-route-cron

Quartz jobs: cron with a time zone, no overlapping runs, a misfire rule, an interval.

dotnet new redb-route-cron -n MyModule

Data and files 6

redb-route-sql

The SQL outbox pattern: a route writes rows, a poll consumer marks each done or failed.

--db sqlite|postgres|mssql

dotnet new redb-route-sql -n MyModule
redb-route-sql-batch

Messages aggregated into batches of 20, one transaction per batch, a refused row skipped and reported.

--db sqlite|postgres|mssql

dotnet new redb-route-sql-batch -n MyModule
redb-route-file

An inbox polled for new files, done and error folders, a receipt per file.

--transport file|ftp|sftp

dotnet new redb-route-file -n MyModule
redb-route-s3

Objects written to a bucket, new ones read and moved to an archive bucket.

dotnet new redb-route-s3 -n MyModule
redb-route-ldap

A directory watch with an initial load, a search on a timer, a password check by bind.

dotnet new redb-route-ldap -n MyModule
redb-route-email

An SMTP sender with retries, an IMAP reader that marks processed messages read.

dotnet new redb-route-email -n MyModule

Messaging 4

redb-route-rabbitmq

One shared connection, a producer, a consumer with retries, a queue for messages that still fail.

dotnet new redb-route-rabbitmq -n MyModule
redb-route-kafka

A keyed producer, a consumer group with retries, a topic for records that still fail.

dotnet new redb-route-kafka -n MyModule
redb-route-amqp

AMQP 1.0 (Artemis, Qpid, Azure Service Bus): a producer, a consumer with retries, a failure queue.

dotnet new redb-route-amqp -n MyModule
redb-route-mqtt

MQTT 3.1.1 and 5: sensors publishing with QoS 1, a retained status, a subscriber with wildcards.

dotnet new redb-route-mqtt -n MyModule

B2B exchange 2

redb-route-as2

AS2: a signed and encrypted document with a verified signed MDN, receiving with duplicate detection.

dotnet new redb-route-as2 -n MyModule
redb-route-as4

AS4 (eDelivery): a signed and encrypted message with a verified receipt, receiving with duplicate detection.

dotnet new redb-route-as4 -n MyModule
A host for the modules

A Tsak worker loads .tpkg modules from its folder, reloads them on the fly, and has a management API and a scheduler. The template comes in its own redb.Tsak.Templates pack.

$ dotnet new install redb.Tsak.Templates
$ dotnet new tsak-worker -n MyHost
PVT prefilter On: a selective filter does not read the whole scheme.
Change tracking On: a save writes only the fields that changed.
Docker and compose A Dockerfile and compose files for PostgreSQL and SQL Server.
Own host or Tsak A route-based module runs in either one.

Applications in detail: options, what is inside, run and deploy →

This guide covers the essential CRUD operations: Create, Read, Update, Delete, and Query. Follow along to build your first REDB-powered application.

1

Installation

Install REDB packages via NuGet. Choose your database provider:

bash
# For PostgreSQL
dotnet add package redb.Postgres

# For SQL Server
dotnet add package redb.MSSql

# For SQLite (embedded / offline / Blazor WASM / mobile)
dotnet add package redb.SQLite        # Free (native extension)
dotnet add package redb.SQLite.Pro    # Pro (pure C# — WASM / mobile)

# For Pro features (advanced queries, bulk operations)
dotnet add package redb.Postgres.Pro
dotnet add package redb.MSSql.Pro
2

Configuration

Register REDB services in your Program.cs:

csharp
// Free version
services.AddRedb(options => options
    .UsePostgres("Host=localhost;Database=mydb;Username=user;Password=pass"));

// Pro version (no license key required since 3.3.0)
services.AddRedbPro(options => options
    .Configure(c =>
    {
        c.PropsSaveStrategy = PropsSaveStrategy.ChangeTracking;
        //c.EnablePropsCache = false;
        //c.PropsCacheMaxSize = 10000;
        //c.PropsCacheTtl = TimeSpan.FromMinutes(60);
    })
    .UsePostgres("Host=localhost;Port=5432;Username=postgres;Password=***;Database=redb;Pooling=true;Include Error Detail=true;Options=-c jit=off")
    //.UseMsSql("Server=localhost;Database=redb;User Id=sa;Password=***;TrustServerCertificate=true;Command Timeout=600;")
    //.UseSqlite("Data Source=app.db")   // embedded; Pro tier runs in Blazor WASM / mobile
    );
3

Define Your Model

Create a Props class with the [RedbScheme] attribute. This is your business entity - no database tables to create, no migrations to write:

csharp
using redb.Core.Attributes;

[RedbScheme("Product catalog")]
public class ProductProps
{
    public string Name { get; set; } = "";
    public string? Description { get; set; }
    public decimal Price { get; set; }
    public string[] Tags { get; set; } = [];
    public bool IsActive { get; set; } = true;
}
4

Create - SaveAsync

Create and save a new object. The SaveAsync method returns the generated ID:

csharp
var product = new RedbObject<ProductProps>
{
    name = "Widget Pro base name",
    Props = new ProductProps
    {
        Name = "Widget Pro",
        Description = "A professional widget",
        Price = 99.99m,
        Tags = ["electronics", "tools"],
        IsActive = true
    }
};

var id = await redb.SaveAsync(product);
// id now contains the generated object ID
5

Read - LoadAsync

Load an object by its ID. Returns the complete object with all properties:

csharp
var loaded = await redb.LoadAsync<ProductProps>(id);

// Access properties
var name = loaded.Props.Name;
var price = loaded.Props.Price;

// or
if (loaded != null) {
    var product = (ProductProps)loaded;
    var name = product.Name;
    var price = product.Price;
}
6

Query - Where

Filter data using familiar LINQ syntax. All conditions compile to native SQL:

csharp
// Simple filter
var expensive = await redb.Query<ProductProps>()
    .Where(p => p.Price > 75000m)
    .Take(100)
    .ToListAsync();

// AND condition
var filtered = await redb.Query<ProductProps>()
    .Where(p => p.Price >= 30 && p.Price < 100)
    .ToListAsync();

// OR condition
var mixed = await redb.Query<ProductProps>()
    .Where(p => p.Price < 10 || p.Price > 90000m)
    .ToListAsync();

// NOT equal
var notWidgets = await redb.Query<ProductProps>()
    .Where(p => p.Name != "Widget")
    .ToListAsync();
7

Count - CountAsync

Get the count of objects matching your criteria:

csharp
// Total count
var totalCount = await redb.Query<ProductProps>().CountAsync();

// Filtered count
var activeCount = await redb.Query<ProductProps>()
    .Where(p => p.IsActive)
    .CountAsync();
8

Delete - DeleteAsync

Remove an object by ID. The object is permanently deleted:

csharp
// Delete by ID
await redb.DeleteAsync(id);

// Verify deletion
var deleted = await redb.LoadAsync<ProductProps>(id);
// deleted will be null

Next Steps