Core Concepts

The foundational types that power CSharpDB's type system and schema definitions.

DbType

CSharpDB uses six compact physical value carriers beneath its richer declared SQL types. Multiple logical declarations can share a carrier without sharing range, coercion, or materialization rules; see the SQL data type reference.

Type	C# Mapping	Description
`Null`	`null`	Absence of value
`Integer`	`long`	Shared 64-bit carrier for logical `BOOLEAN`, 32-bit `INTEGER`, and `BIGINT`
`Real`	`double`	64-bit IEEE floating point
`Text`	`string`	UTF-8 encoded text
`Blob`	`byte[]`	Raw binary data
`Decimal`	`decimal`	Exact base-10 decimal with up to 18 digits of precision

DbValue

DbValue is a lightweight struct that represents a dynamically-typed database value. It wraps the six physical carriers and provides type-safe access, comparison, and truthiness evaluation.

var id      = DbValue.FromInteger(42);
var name    = DbValue.FromText("Alice");
var score   = DbValue.FromReal(98.5);
var balance = DbValue.FromDecimal(100.50m);
var empty   = DbValue.Null;

// Type-safe access
long idVal     = id.AsInteger;    // 42
string nameVal = name.AsText;     // "Alice"
decimal amount = balance.AsDecimal; // 100.5m
bool isNull    = empty.IsNull;    // true

// Comparison
int cmp = DbValue.Compare(id, DbValue.FromInteger(43)); // -1

TableSchema

Defines the structure of a table: its name, columns, types, nullability, and primary key.

var schema = new TableSchema
{
    TableName = "Orders",
    Columns = [
        new ColumnDefinition { Name = "OrderId",    Type = DbType.Integer, IsPrimaryKey = true },
        new ColumnDefinition { Name = "CustomerId", Type = DbType.Integer },
        new ColumnDefinition { Name = "Total",      Type = DbType.Real },
        new ColumnDefinition { Name = "Notes",      Type = DbType.Text, Nullable = true },
    ]
};

// Access column info
int idx = schema.GetColumnIndex("Total");  // 2
int pk  = schema.PrimaryKeyColumnIndex;   // 0

IndexSchema

IndexSchema defines secondary indexes on table columns. Indexes support composite keys, unique constraints, and efficient range scans via BTreeIndexCursor.

var index = new IndexSchema
{
    IndexName = "idx_orders_customer",
    TableName = "Orders",
    Columns = ["CustomerId"],
    IsUnique = false,
};

TriggerSchema

TriggerSchema stores trigger metadata — timing (BEFORE/AFTER), event (INSERT/UPDATE/DELETE), and the SQL body for execution by the query engine.

ColumnDefinition

Each column in a TableSchema is described by a ColumnDefinition that captures:

Property	Type	Description
`Name`	`string`	Column name
`Type`	`DbType`	Data type
`IsPrimaryKey`	`bool`	Whether this is the primary key column
`Nullable`	`bool`	Whether NULL values are allowed

Core Concepts

DbType

DbValue

TableSchema

IndexSchema

TriggerSchema

ColumnDefinition

Next Steps

SQL Reference

Storage Engine

Architecture