redb.Export 3.0.0

RedBase — typed object storage for .NET. Schema = C# class. Zero migrations. Full LINQ. Postgres & MSSQL.

Trees, lists, aggregations, windows — one LINQ API.

RedBase is a data platform for .NET that stores typed objects in a relational backend (PostgreSQL, Microsoft SQL Server). You define schemas as plain C# classes — RedBase handles storage, indexing, querying, trees, lists, aggregation, and window functions through a single LINQ-style API.

No Entity Framework. No migrations. No 40-table Include chains. Just C# classes and one line to save, one line to load.

Why RedBase

Strong typing — real columns, not JSON blobs. Every property of your *Props class maps to a dedicated typed column with a FK constraint and an index. string → nvarchar, decimal → numeric(18,4), DateTime → timestamptz, arrays and dictionaries → normalised rows. Your data is queryable, filterable, and aggregatable at the SQL level — no JSON_VALUE hacks, no full-table JSON scans, no cast errors at runtime.

Quick Start

// 1. Define a schema — that's your "migration"
[RedbScheme("Employee")]
public class EmployeeProps
{
    public string FirstName { get; set; } = "";
    public string LastName { get; set; } = "";
    public int Age { get; set; }
    public decimal Salary { get; set; }
    public string Department { get; set; } = "";
    public string Position { get; set; } = "";
    public DateTime HireDate { get; set; }
    public string[]? Skills { get; set; }
    public Address? HomeAddress { get; set; }
    public Dictionary<int, decimal>? BonusByYear { get; set; }
}

// 2. Sync scheme (creates storage automatically)
await redb.SyncSchemeAsync<EmployeeProps>();

// 3. Save — from E001_SaveAsync.cs
var employee = new RedbObject<EmployeeProps>
{
    name = "New Developer",
    Props = new EmployeeProps
    {
        FirstName = "Alice",
        LastName = "Johnson",
        Age = 28,
        Position = "Developer",
        Department = "Engineering",
        Salary = 85000m,
        HireDate = DateTime.Today,
        Skills = ["C#", "React", "SQL"]
    }
};
await redb.SaveAsync(employee);

// 4. Load — from E002_LoadAsync.cs
var loaded = await redb.LoadAsync<EmployeeProps>(employee.Id);
// loaded.Props.FirstName → "Alice"

// 5. Query — from E010_WhereSimple.cs
var results = await redb.Query<EmployeeProps>()
    .Where(e => e.Salary > 75000m)
    .OrderByDescending(e => e.Salary)
    .Take(100)
    .ToListAsync();

// 6. Projection — from E075_Select.cs
var projected = await redb.Query<EmployeeProps>()
    .Select(x => new { x.Props.FirstName, x.Props.LastName, x.Props.Salary })
    .ToListAsync();

Create from Template

dotnet new install redb.Templates
dotnet new redb -n MyProject --provider postgres
cd MyProject
dotnet run

Packages

Package	NuGet	Description
redb.Core		Core abstractions, query builder, LINQ provider
redb.Postgres		PostgreSQL provider (free, Apache 2.0)
redb.MSSql		Microsoft SQL Server provider (free, Apache 2.0)
redb.Core.Pro		Pro extensions: parallel materialization, change tracking, migrations
redb.Postgres.Pro		PostgreSQL Pro provider with optimized query generation
redb.MSSql.Pro		MSSQL Pro provider with optimized query generation
redb.Export		Database export/import: .redb files (JSONL/ZIP) for backup, migration between PostgreSQL ↔ MSSQL

Installation

# PostgreSQL (Free)
dotnet add package redb.Postgres

# or MSSQL (Free)
dotnet add package redb.MSSql

# Pro — includes redb.Core.Pro automatically
dotnet add package redb.Postgres.Pro   # or redb.MSSql.Pro

Each provider package pulls in redb.Core (or redb.Core.Pro) as a transitive dependency.

Setup & InitializeAsync

using redb.Core;
using redb.Core.Extensions;
using redb.Postgres.Pro.Extensions;  // or redb.MSSql.Pro.Extensions

var builder = WebApplication.CreateBuilder(args);

// Register REDB Pro
builder.Services.AddRedbPro(options => options
    .UsePostgres("Host=localhost;Database=mydb;Username=postgres;Password=pass")
    // .UseMsSql("Server=localhost;Database=mydb;User Id=sa;Password=pass;TrustServerCertificate=true")
    .WithLicense("YOUR-LICENSE-KEY")     // optional — trial works without it
    .Configure(c =>
    {
        c.PropsSaveStrategy = PropsSaveStrategy.ChangeTracking;
        c.EnableLazyLoadingForProps = false;
        c.EnablePropsCache = true;
    }));

var app = builder.Build();

// Initialize and sync schemes
var redb = app.Services.GetRequiredService<IRedbService>();
await redb.InitializeAsync();
await redb.SyncSchemeAsync<EmployeeProps>();

Free version — same pattern, just AddRedb instead of AddRedbPro, no license:

using redb.Core.Extensions;
using redb.Postgres.Extensions;  // or redb.MSSql.Extensions

builder.Services.AddRedb(options => options
    .UsePostgres("Host=localhost;Database=mydb;Username=postgres;Password=pass"));

Database Setup Options

REDB provides several ways to create the database schema:

Option A — Automatic on startup (recommended):

// Creates schema if missing, then initializes
await redb.InitializeAsync(ensureCreated: true);

Option B — Explicit call:

await redb.EnsureDatabaseAsync(); // idempotent — safe to call every time
await redb.InitializeAsync();

Option C — Export SQL script for DBA / CI:

var sql = redb.GetSchemaScript();
File.WriteAllText("redb_schema.sql", sql);

Option D — CLI tool:

dotnet tool install --global redb.CLI

# Create schema in an existing database
redb init --connection "Host=localhost;Database=mydb;..." --provider postgres

# Export SQL to file
redb schema --provider postgres --output redb_schema.sql

Capabilities

CRUD

Object Graph (RedbObject References in Props)

Props can contain RedbObject<T> properties — single, array, or dictionary. The entire graph is saved and loaded in one call. No JOINs, no Include chains, no manual assembly.

// Real model from redb.Examples/Models/ExampleModels.cs
[RedbScheme("Employee")]
public class EmployeeProps
{
    public string FirstName { get; set; } = "";
    public int Age { get; set; }
    public decimal Salary { get; set; }

    // Nested business class (Address with nested BuildingInfo)
    public Address? HomeAddress { get; set; }

    // Array of business classes
    public Contact[]? Contacts { get; set; }

    // RedbObject reference — single
    public RedbObject<ProjectMetricsProps>? CurrentProject { get; set; }

    // RedbObject references — array
    public RedbObject<ProjectMetricsProps>[]? PastProjects { get; set; }

    // Dictionary with RedbObject values
    public Dictionary<string, RedbObject<ProjectMetricsProps>>? ProjectMetrics { get; set; }

    // Dictionary with nested classes
    public Dictionary<string, Department>? DepartmentHistory { get; set; }

    // Tuple key dictionary
    public Dictionary<(int Year, string Quarter), string>? PerformanceReviews { get; set; }
}

// Save — entire graph persisted, ParentId set automatically
await redb.SaveAsync(employee);

// Load — full graph reconstructed, all nested objects hydrated
var loaded = await redb.LoadAsync<OrderProps>(id);
// loaded.Props.Payment.Props          — ready
// loaded.Props.RelatedMetrics[0].Props — ready
// loaded.Props.Coupons["SUMMER"].Props — ready

Nested objects are real RedbObject instances with their own id, name, DateCreate, DateModify, and Props. They can be queried independently, updated in place, and participate in tree structures.

Rich Props Structure

Props fields can be any combination of scalars, nested classes, collections, and dictionaries — arbitrarily deep. Everything is serialized, stored, and fully restored on load. No extra tables, no FKs, no mapping.

[RedbScheme("Analytics Record")]
public class AnalyticsRecordProps
{
    // Scalars
    public string Title { get; set; } = "";
    public int Views { get; set; }
    public decimal Revenue { get; set; }

    // Primitive arrays
    public string[]? Tags { get; set; }
    public int[]? Scores { get; set; }

    // Nested business class
    public Address? HomeAddress { get; set; }

    // Array of business classes
    public Contact[]? Contacts { get; set; }

    // Dictionary<string, primitive>
    public Dictionary<string, string>? PhoneBook { get; set; }

    // Dictionary<int, decimal>
    public Dictionary<int, decimal>? PriceList { get; set; }

    // Dictionary<string, nested class>
    public Dictionary<string, Address>? AddressBook { get; set; }

    // Dictionary<string, complex class with its own arrays and dicts>
    public Dictionary<string, ProjectInfo>? ComplexBook { get; set; }

    // Tuple key dictionary
    public Dictionary<(int, string), string>? TupleKeyDict { get; set; }
}

public class Address
{
    public string City { get; set; } = "";
    public string Street { get; set; } = "";
    public BuildingDetails? Details { get; set; }   // nesting goes deeper
}

public class ProjectInfo
{
    public string Title { get; set; } = "";
    public int Priority { get; set; }
    public string[]? Tags { get; set; }             // arrays inside dict values
    public MetricTag[]? MetricTags { get; set; }    // class arrays inside dict values
    public Dictionary<string, int>? Scores { get; set; } // dict inside dict value
}

All saved and loaded with a single SaveAsync / LoadAsync. Fields can be added or removed at any time — SyncSchemeAsync handles it.

Where Filters

DateTime

String Operations

Nested Properties

Array Operations

Dictionary Operations

Projection & Pagination

Existence & Count

Arithmetic & Math

Aggregation

GroupBy

Window Functions

Tree Structures

Built-in hierarchical data with closure-table storage and recursive CTEs.

Lists (Reference Dictionaries)

Named lookup lists with items, useful for statuses, categories, roles.

Export / Import (Database Portability)

Full database export/import via .redb files (JSONL, optionally ZIP-compressed). Migrate between PostgreSQL and MSSQL, create backups, replicate data.

Users, Roles & Permissions

Built-in user management with password hashing, roles, and object-level permissions. No external identity provider required.

// Authenticate
var user = await redb.UserProvider.ValidateUserAsync("admin", "password123");
if (user != null)
{
    redb.SetCurrentUser(user);
    // All subsequent operations run as this user
}

// Temporary system elevation (skip permissions)
using (redb.CreateSystemContext())
{
    await redb.SaveAsync(sensitiveObject);
}

Architecture

graph TD
    A["IRedbService"] --> B["Query<T>()"]
    A --> C["TreeQuery<T>()"]
    A --> D["SaveAsync / LoadAsync"]
    A --> E["SyncSchemeAsync"]
    A --> F["ListProvider"]
    A --> G["UserProvider / RoleProvider"]
    
    B --> H["ExpressionToSqlCompiler"]
    C --> I["CTE recursive queries"]
    D --> J["IRedbContext (SQL)"]
    E --> K["Auto-migration"]
    
    H --> L["PostgreSQL / MSSQL"]
    I --> L
    J --> L
    K --> L

IRedbService          ← single entry point
├── Query<T>()        ← flat LINQ queries  
├── TreeQuery<T>()    ← hierarchical queries (CTE)
├── SaveAsync()       ← create / update (full object graph)
├── LoadAsync<T>()    ← load by ID (with all nested objects)
├── ListProvider      ← reference dictionaries
├── UserProvider      ← users, authentication, passwords
├── RoleProvider      ← roles and user-role assignments
├── SecurityContext   ← current user, permission checks
└── SyncSchemeAsync() ← auto-migration from C# class

Storage is provider-based. Each [RedbScheme] class maps to an internal structure in the target database. Schema changes (new fields, removed fields, type changes) are handled automatically by SyncSchemeAsync — no migration files needed.

Supported backends: PostgreSQL 14+, Microsoft SQL Server 2019+.

Schema lifecycle and multi-version deployments

Read path is graceful. When deployed code has a Props class without a field that exists in the database, the materializer silently skips it. Old binaries safely read newer data — no exception is thrown.

Write path is destructive by default. InitializeAsync() runs AutoSyncSchemesAsync() which calls SyncSchemeAsync<T>() per scheme. By default this deletes any _structures row not present in the C# Props class, and every _values row referencing those structures is silently removed as well:

• PostgreSQL — the FK _values._id_structure -> _structures._id is declared ON DELETE CASCADE.
• MSSQL — the FK is NO ACTION (MSSQL forbids multiple cascade paths into _values), but the trigger TR__structures__cascade_values (INSTEAD OF DELETE on _structures) deletes the dependent _values rows first, producing the same runtime effect as PostgreSQL.

For rolling / blue-green deployments where old and new app versions may share the database, disable destructive sync:

services.AddRedb(options => options
    .UsePostgres(connectionString)
    .Configure(c => c.DefaultStrictDeleteExtra = false));

When destructive sync is enabled and structures are actually removed, an ILogger.LogWarning is emitted listing the scheme name and the structure ids / names being deleted.

The per-save value-set ownership contract (one object's SaveAsync rewrites its full value set) is still destructive in this release — old and new versions should not write to the same object during the multi-version window. An opt-in PropsSaveMode.PreserveUnknownStructures flag is planned; see ROADMAP.

How It Compares

vs Entity Framework Core

// EF Core — 28 related entities
var order = await context.Orders
    .Include(o => o.Customer)
    .Include(o => o.Items).ThenInclude(i => i.Product).ThenInclude(p => p.Category)
    .Include(o => o.Items).ThenInclude(i => i.Discounts)
    .Include(o => o.Shipping).ThenInclude(s => s.Address)
    .Include(o => o.Payment).ThenInclude(p => p.Transactions)
    // ... 35 more Include lines ...
    .FirstOrDefaultAsync(o => o.Id == orderId);

// RedBase — same data
var order = await redb.LoadAsync<OrderProps>(orderId);
// All nested objects, arrays, dictionaries — loaded automatically.

vs MongoDB / JSONB

Pro

REDB Pro unlocks compiled query execution, parallel materialization, deep nested property queries, arithmetic and math expressions in WHERE, Sql.Function<T>() for calling arbitrary SQL functions, change tracking, schema migrations, and advanced analytics (window functions over grouped data). If performance matters — use Pro.

redbase.app/pricing

Documentation

License

Core packages (redb.Core, redb.Postgres, redb.MSSql, redb.Export, redb.CLI, redb.Templates, redb.PropsEditor) are licensed under Apache License 2.0 starting from version 2.0.0. Versions ≤ 1.3.0 published on nuget.org remain under MIT.

Pro packages require a commercial license — see LICENSE-PRO.txt.