ElephantSqlDb.Data.Provider 1.0.193

.NET 8.0

dotnet add package ElephantSqlDb.Data.Provider --version 1.0.193

NuGet\Install-Package ElephantSqlDb.Data.Provider -Version 1.0.193

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="ElephantSqlDb.Data.Provider" Version="1.0.193" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="ElephantSqlDb.Data.Provider" Version="1.0.193" />
                    

                            Directory.Packages.props

<PackageReference Include="ElephantSqlDb.Data.Provider" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add ElephantSqlDb.Data.Provider --version 1.0.193

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: ElephantSqlDb.Data.Provider, 1.0.193"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package ElephantSqlDb.Data.Provider@1.0.193

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=ElephantSqlDb.Data.Provider&version=1.0.193
                    

                            Install as a Cake Addin

#tool nuget:?package=ElephantSqlDb.Data.Provider&version=1.0.193
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

ElephantSqlDb.Data — Developer Guide

ADO.NET provider, ServiceStack.OrmLite dialect and Entity Framework Core 8 provider for ElephantSqlDB, with read queries in the Dynatrace Query Language (DQL).

The package provides four kinds of support:

Data providers. Four ways to read and write ElephantSqlDB tables, all on one connection type, ElephantConnection: raw ADO.NET, Entity Framework Core 8 (LINQ, change tracking and dotnet ef scaffolding), a ServiceStack.OrmLite dialect (a one-line switch from a PostgreSQL-backed application) and Dapper. Read queries can also be written in the Dynatrace Query Language. All four share one parameter binder, one set of value formats and the same engine rules: no transactions, no DDL and no enforced constraints. See sections 6 to 11 and 22.

Logging support. A Serilog sink, a log4net appender and a Microsoft.Extensions.Logging provider that write application logs to an ElephantSqlDB table through the same ADO.NET provider. Logging never blocks the application thread; rows are written in parallel, and retries never duplicate a row. The log table uses Dynatrace field names, so logs can be queried with SQL or DQL. See section 23.

Telemetry support. OpenTelemetry exporters that write traces and metrics to ElephantSqlDB tables with one line, AddElephantSqlDbExporter(...), next to the instrumentation an application already uses. Requests, HttpClient calls and .NET runtime metrics are captured automatically, exported on the SDK's background threads, and joined to the log rows by trace_id, ready for ElephantSqlDB dashboards, SQL or DQL. Collection is agentless: there is no sidecar, node agent or extra container to deploy, size or patch. See section 24.

ODBC support. A native ODBC driver, built from the same core, that opens ElephantSqlDB to applications outside .NET: Python, R, PHP, Node.js, Go, Rust and C/C++, and tools such as Excel, Power BI and Tableau through a DSN. See section 25.

One platform for data, logs and telemetry. Application data, logs and telemetry are written with the same client, the same connection model and the same query languages, to the same platform. That gives you:

Correlation. Look up every error logged for an order ID or a trace_id with the same connection, client and SQL or DQL you use for the order itself. There is no export between an observability tool and a database.
One operational footprint. One client, one token and security model, one backup and compliance scope, and fewer vendors to integrate and secure.
One platform, one language. Developers query logs and telemetry with the SQL or DQL they already write for application data. There is no SPL or KQL to learn.
Dashboards and alerting built in. ElephantSqlDB dashboards chart data, logs and telemetry side by side, and raise alerts on user-defined events. There is no separate dashboard tool or alerting service to deploy and integrate.
Less technical debt. One platform replaces a separate application database (SQL Server, PostgreSQL, Oracle), log store (Elasticsearch, Splunk), tracing and metrics backends (Jaeger, Prometheus), dashboard and alerting tools (Kibana, Grafana, Alertmanager) and the storage and query side of an APM platform (Dynatrace, Datadog), each with its own language, client and integration.
Audit trails beside the records. For regulated workloads, the audit log lives on the same platform as the records it describes, under the same security model.
Constant-time lookups at any log volume. Key lookups on ElephantSqlDB are O(1), so finding an event by log_id, trace_id or an order ID costs the same at a thousand rows or ten billion. Logs are the fastest-growing data most companies have, and this is where other stores slow down.
Correlation that scales. "Show me the logs for this order" is a constant-time key lookup on both sides, the business record and its log entries, rather than a search that degrades as both grow.
Longer retention. Teams usually cut log retention because large stores get slow. When key-based retrieval does not degrade, keeping a year of logs instead of 30 days becomes a storage decision, not a performance one.

Find any event, or every event tied to a transaction, in constant time, no matter how many years of logs you keep. Constant time applies to key lookups; time-window, text and aggregate queries (from: -2h, contains(...), summarize) range over the data as usual. To get the most from it, log a trace or correlation ID with every event; the writer stores the current trace_id automatically.

Keep logs in their own database on the platform, through a separate Logs connection string or DatabaseName, so log volume, retention and access rules stay separate from application data.

What one platform replaces. A typical application stack spreads data, logs and telemetry across six or more tools, each deployed, secured, retained and queried separately:

Typical tool	Role	Query language	On ElephantSqlDB
SQL Server, PostgreSQL, Oracle	Application database	SQL	Application data, via ADO.NET, EF Core, OrmLite or Dapper
Logstash, Fluentd, Elasticsearch	Log pipeline and store	Lucene, KQL	`logs` table, via Serilog, log4net or ILogger
Splunk	Log store and search	SPL	`logs` table, queried with SQL or DQL
Jaeger, Zipkin	Trace store	Own UI and API	`spans` table, via the OpenTelemetry exporter
Prometheus	Metrics store	PromQL	`metrics` table, via the OpenTelemetry exporter
Kibana, Grafana	Dashboards	Per tool	ElephantSqlDB dashboards
Alertmanager, per-tool alert rules	Alerting	Per tool	Alerts on user-defined dashboard events
Dynatrace Grail, Datadog	Observability storage and query	DQL, own language	`logs`, `spans`, `metrics`, queried with SQL or DQL

What ElephantSqlDB does not replace: agent-based automatic instrumentation of other languages (such as Dynatrace OneAgent), AI-driven root-cause analysis such as Dynatrace Davis, real-user monitoring and synthetic checks. Teams that rely on those keep them; ElephantSqlDB works alongside as the platform where data, logs and telemetry are kept and queried together.

Version 0.1.0-alpha. Written against ElephantSqlDBClient 1.0.188 and the product documentation. Not yet exercised against a live table — work through Verification before depending on it.

What this is
Architecture
Installation
Connection strings
Dependency injection
Choosing an API: the same tasks four ways
Raw ADO.NET
Pagination and result metadata
OrmLite
Dapper
Entity Framework Core
Type mapping
No transactions
No DDL, no constraints
Parameters and injection
Performance
Error handling
Testing
Verification
Migrating from PostgreSQL
Troubleshooting
Dynatrace Query Language (DQL)
Logging with Serilog and log4net
Telemetry with OpenTelemetry
ODBC driver

1. What this is

ElephantSqlDBClient.Core is an HTTP/WebSocket API client with its own shape: operations are extension methods split by statement type, results come back generic over a CLR type, and the table is an argument on every call.

This package wraps that client in the ADO.NET abstractions — DbConnection, DbCommand, DbDataReader, DbParameter — so anything that speaks ADO.NET can reach an ElephantSqlDB table without knowing the client exists. That means OrmLite, Dapper, EF Core, reporting tools, and any code already written against IDbConnection.

It also ships an OrmLite dialect, so IDbConnectionFactory registration is a one-line change from a PostgreSQL-backed application.

The same package also includes an EF Core 8 provider built on these types: LINQ queries, change tracking and dotnet ef scaffolding. See section 11.

Commands can also be written in the Dynatrace Query Language (DQL). The provider translates them to SQL for read queries, so DQL works anywhere a DbCommand does. See section 22.

Application logs can be written to an ElephantSqlDB table through the same ADO.NET types, from Serilog, log4net or Microsoft.Extensions.Logging. See section 23. Traces and metrics can be exported to it from OpenTelemetry. See section 24.

Section 6 shows the same tasks — query, insert, update, delete, paging — in ADO.NET, Entity Framework Core, OrmLite and Dapper side by side.

Where the client returns more than rows — the PaginationDTO and AuthStatus that come back from every SELECT — the provider keeps them reachable rather than discarding them at the ADO.NET boundary. See section 8.

What it does not do is paper over gaps in the underlying engine. There are no transactions, no DDL, and no enforced constraints. The provider surfaces those as exceptions rather than silently pretending — see sections 13 and 14, which are the two you should read before writing any code.

2. Architecture

  Your code ──┬──▶ Entity Framework Core   (UseElephantSqlDb: LINQ → SQL)
              ├──▶ OrmLite                 (ElephantOrmLiteDialectProvider)
              ├──▶ Dapper
              ├──▶ raw ADO.NET
              └──▶ DQL                     (QueryLanguage = Dql: DQL → SQL)
                              │
                              ▼
        ElephantConnection · ElephantCommand · ElephantDataReader
                              │
                    ElephantParameterBinder      (renders values into SQL text)
                              │
                    IElephantExecutor            (test seam)
                              │
                    ElephantSqlDbExecutor        (routes by statement type)
                              │
                    ElephantSqlDBClient.Core     (HTTP / WebSocket)
                              │
                              ▼
                       ElephantSqlDB table

Files

File	Role
`ElephantConnection.cs`	`DbConnection`, `DbTransaction`, `DbProviderFactory`
`ElephantCommand.cs`	`DbCommand`
`ElephantDataReader.cs`	`DbDataReader` over paged, untyped rows
`ElephantParameter.cs`	`DbParameter`, collection, and the literal binder
`ElephantConnectionStringBuilder.cs`	Connection string keywords
`IElephantExecutor.cs`	Seam between ADO.NET and the client
`ElephantSqlDbExecutor.cs`	Adapter over `ElephantSqlDBClient.Core`
`ElephantConnectionExtensions.cs`	Paged query helpers
`ElephantOrmLiteDialectProvider.cs`	OrmLite dialect and type converters
`EntityFrameworkCore/`	EF Core 8 provider (section 11)
`Dql/`	DQL-to-SQL translation (section 22)
`Logging/`	Serilog sink, log4net appender, MEL provider (section 23)
`Telemetry/`	OpenTelemetry trace and metric exporters (section 24)
`ElephantQueryLanguage.cs`	`Sql` / `Dql` command language

How a query flows

ElephantCommand.ExecuteReaderAsync validates state. A DQL command is first translated to a SELECT by ElephantDql (section 22).
ElephantParameterBinder renders parameter values into the SQL text — the backend binds nothing, so substitution is the only route.
ElephantSqlDbExecutor.QueryAsync calls SelectSQLRecordsAsync<string>. T is string deliberately: the client special-cases it and returns raw JSON rather than mapping onto a CLR type the provider does not have.
JSON rows are projected into IDictionary<string, object?>.
The client's PaginationDTO and AuthStatus are captured as an ElephantPagination, so the caller can reach TotalItems and the outcome status rather than only the rows.
ElephantDataReader fixes column names and ordinals from the first page and converts values on demand.

How a write flows

ElephantSqlDbExecutor.ExecuteAsync classifies the leading keyword and routes:

Statement	Route
`INSERT`	Parsed, then `SaveToDatabaseWithNoResponse` once per VALUES row; the target database travels in the record envelope's `DatabaseName`
`UPDATE`	`UpdateSQLRecordsAsync` with `DatabaseName`
`DELETE`	`DeleteSQLRecordsAsync` with `DatabaseName`
`SAVEFILEASRECORD`	`SaveSQLRecordsFromFileAsync` with `DatabaseName`
`CREATE TABLE`	Accepted and dropped — tables appear on first write
`CREATE DATABASE [IF NOT EXISTS] name`	`CreateDatabaseAsync` — see Creating a database
`ALTER`, `DROP`, `TRUNCATE`, `CREATE INDEX`	`NotSupportedException`
Anything else	`ExecuteRootKeyCommandAsync`

Inserts bypass the client's InsertSQLRecordsAsync on purpose. See section 21 for why.

3. Installation

dotnet add package ElephantSqlDb.Data

Or reference the project directly:

<ProjectReference Include="..\ElephantSqlDb.Data\ElephantSqlDb.Data.csproj" />

Dependencies: ElephantSqlDBClient 1.0.188+, ServiceStack.OrmLite 8.x, Newtonsoft.Json 13.x, Microsoft.EntityFrameworkCore.Relational 8.0.x, Serilog 4.2.0, log4net 3.5.0 and Microsoft.Extensions.Logging 10.0.0 (logging, section 23), and OpenTelemetry 1.17.0 (telemetry, section 24). Targets net8.0.

Pin the OrmLite version rather than floating it. The dialect base class changed substantially in v8 — converters replaced the *ColumnDefinition fields, and TableRef replaced the (tableName, schema) pairs — so a floating major would break the overrides without warning.

The package also contains the EF Core 8 provider (section 11), so it brings Microsoft.EntityFrameworkCore.Relational 8.0.x as a dependency. No second package is needed.

4. Connection strings

BaseUri=https://api.elephantsqldb.example/;Token=…;Roles=Admin;UserEmail=svc@example.com;TenantId=0;Database=portal_table

Keyword	Required	Default	Notes
`BaseUri`	yes	—	Root of the HTTP API
`Token`	yes	—	Bearer token
`UserEmail`	yes	—
`Database`	yes	—	The table the connection authenticates against, and the default database for every statement. Override per connection or per command — see Choosing the database
`Roles`	no	—
`TenantId`	no	`0`
`LedgerPreface`	no	`Crypto-`
`MaxRecords`	no	`100`	Server-side page size
`UseWebSockets`	no	`false`
`MaxConnections`	no	`10`
`AsyncScale`	no	`1`
`CommandTimeout`	no	`30`	Seconds
`AllowNonTransactional`	no	`false`	See section 13
`AutoRegisterUser`	no	`false`	Create the account on open — see below
`AutoCreateLedger`	no	`false`	Create the table on open — see below
`Password`	no	—	Only used by `AutoRegisterUser`
`FirstName`	no	`Service`	Registration detail
`MiddleName`	no	—	Registration detail
`LastName`	no	`Account`	Registration detail
`Phone`	no	—	Registration detail
`EncryptionAlgorithm`	no	`SHA256`	Ledger created by `AutoCreateLedger`, and by `CreateDatabaseAsync` when it is not given one
`QueryLanguage`	no	`Sql`	`Sql` or `Dql`; default language of `CommandText` — see section 22
`DqlTimestampField`	no	`timestamp`	Column DQL's `from:`, `to:` and `timeframe:` filter on

Missing required keywords throw InvalidOperationException on Open, not on construction — a builder can be assembled incrementally.

Keeping the token out of source

Leave it blank in appsettings.json and supply it from the environment. Anything that reads IConfiguration picks it up through the normal precedence chain.

{
  "ConnectionStrings": {
    "Portal": "BaseUri=https://api.elephantsqldb.example/;Token=;Roles=;UserEmail=;Database=portal_table;MaxRecords=250"
  }
}

ConnectionStrings__Portal=BaseUri=…;Token=real-token;…

In Kubernetes, source that variable from a secret rather than baking it into the image.

What happens on Open

OpenAsync does more than dial the API. It parses and validates the connection string, constructs the client, then calls IsCredentialsValid — and two of the three states that call can return are recoverable.

The two side branches are each gated by a connection string flag. With the flag off the branch throws instead of remediating, and the message names the flag to set. Both loops return to IsCredentialsValid rather than proceeding directly, and the whole sequence is bounded to two passes — at most one registration and one table creation, so a server that keeps reporting the same recoverable state fails with that state rather than spinning.

The three states:

Status	Meaning	Provider behaviour
`Success`	Account and table both exist	Connection opens
`CredentialsNotFound`	No account for this email	Registers it if `AutoRegisterUser=true`, otherwise throws
`NoTenantDatabaseFound`	Account exists, table does not	Creates it if `AutoCreateLedger=true`, otherwise throws

Concurrency is not a concern. The engine is actor-based and message driven, so simultaneous requests for the same table resolve to the same entity— the first message creates it, later ones address the one that exists. There is no duplicate-create race, which is why a reported error is treated as a real failure rather than something to re-validate past: a message from CreateDatabaseAsync means a rejected name, a quota, or a permission, and the provider throws with it.

Each remediation is still followed by a fresh IsCredentialsValid, confirming the state it was meant to reach was actually reached.

Both flags are off by default, and the exception when they are off tells you which one to set:

ElephantException: Ledger 'portal_table' does not exist for 'svc@example.com'.
Create it in the management portal, or set AutoCreateLedger=true to have the
provider create it on open.

When to turn them on

AutoCreateLedger is reasonable for local development, integration tests and throwaway environments. Repeated creation is harmless — the entitymodel makes it idempotent — but a typo in Database produces an empty table instead of an error, and the application then runs against nothing.

AutoRegisterUser should stay off anywhere that is not a developer machine. Opening a connection is not the place to create an identity: it needs the password in the connection string, it races across replicas, and a stale UserEmail variable becomes a new account rather than a failure. Provision service accounts deliberately.

// Local development - stand everything up on first run.
var dev = new ElephantConnectionStringBuilder
{
    BaseUri = "https://api.elephantsqldb.example/",
    Token = token,
    UserEmail = "dev@example.com",
    Database = "dev_table",
    AutoRegisterUser = true,
    Password = "…",
    AutoCreateLedger = true
};

// Production - fail loudly if either is missing.
var prod = new ElephantConnectionStringBuilder
{
    BaseUri = "https://api.elephantsqldb.example/",
    Token = token,
    UserEmail = "svc@example.com",
    Database = "portal_table"
};

Doing it yourself

Where the bootstrap needs to be explicit — a provisioning job rather than a connection open — drive the client directly and leave both flags off:

var client = factory.GetApiClient();
var status = await client.IsCredentialsValid();

if (status == AuthStatus.CredentialsNotFound)
{
    await client.RegisterNewUserAsync(
        email, password, firstName, middleName, lastName, phone, false);

    status = await client.IsCredentialsValid();
}

if (status == AuthStatus.NoTenantDatabaseFound)
{
    var (errorMessage, _) = await client.CreateDatabaseAsync(client.GetLedgerName());

    if (!string.IsNullOrEmpty(errorMessage))
        logger.LogWarning("Ledger creation reported: {Message}", errorMessage);

    status = await client.IsCredentialsValid();
}

if (status != AuthStatus.Success)
    throw new InvalidOperationException($"Provisioning did not complete: {status}.");

Building one in code

var builder = new ElephantConnectionStringBuilder
{
    BaseUri = "https://api.elephantsqldb.example/",
    Token = token,
    UserEmail = "svc@example.com",
    Database = "portal_table",
    MaxRecords = 250,
    CommandTimeout = 60
};

builder.Validate();

var connectionString = builder.ConnectionString;

5. Dependency injection

Program.cs — minimal hosting

using ElephantSqlDb.Data;
using ServiceStack.Data;
using ServiceStack.OrmLite;

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("Portal")
    ?? throw new InvalidOperationException(
        "ConnectionStrings:Portal is not set. In the cluster this comes from the " +
        "ConnectionStrings__Portal environment variable.");

// Singleton. The factory holds no connection - it hands one out per
// OpenDbConnectionAsync call.
builder.Services.AddSingleton<IDbConnectionFactory>(_ => new OrmLiteConnectionFactory(
    connectionString,
    ElephantOrmLiteDialectProvider.Instance));

var app = builder.Build();
app.Run();

Startup.cs — classic hosting

public class Startup(IConfiguration configuration)
{
    public void ConfigureServices(IServiceCollection services)
    {
        var connectionString = configuration.GetConnectionString("Portal")
            ?? throw new InvalidOperationException("ConnectionStrings:Portal is not set.");

        services.AddSingleton<IDbConnectionFactory>(_ => new OrmLiteConnectionFactory(
            connectionString,
            ElephantOrmLiteDialectProvider.Instance));
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { }
}

Raw ADO.NET without OrmLite

builder.Services.AddSingleton(new ElephantConnectionStringBuilder
{
    ConnectionString = connectionString
});

builder.Services.AddScoped<DbConnection>(sp =>
    new ElephantConnection(
        sp.GetRequiredService<ElephantConnectionStringBuilder>().ConnectionString));

Scoped, not singleton — DbConnection is not thread-safe, and a singleton would be shared across concurrent requests.

Registering by invariant name

ElephantProviderFactory.Register();

var factory = DbProviderFactories.GetFactory("ElephantSqlDb.Data");
using var connection = factory.CreateConnection();

Useful for tools that resolve providers by name.

Do you need a repository per table?

No. IDbConnectionFactory is the only registration the provider requires. Everything above it is your choice of structure. Three reasonable shapes:

Inject the factory directly. OrmLite is already a data-access abstraction; wrapping it per table mostly adds indirection.

public sealed class OfferingService(IDbConnectionFactory dbFactory)
{
    public async Task<List<Offering>> GetOpenAsync(CancellationToken ct = default)
    {
        using var db = await dbFactory.OpenDbConnectionAsync(token: ct);
        return await db.SelectAsync<Offering>(o => o.Status == OfferingStatus.Open, token: ct);
    }
}

One open generic, registered once.

services.AddScoped(typeof(IRepository<>), typeof(Repository<>));

Repositories only where they earn it. Under this provider there is a specific argument for this: the engine enforces no unique constraints, so checks like "is this slug taken" have to live somewhere consistent. A repository is a reasonable home. That is a handful of aggregates, not one per table.

6. Choosing an API: the same tasks four ways

The package supports four ways to reach the same tables. They share one connection type (ElephantConnection), one parameter binder and one set of value formats, so you can mix them in one application and even on one table.

API	Use it when	Section
ADO.NET	You want full control of the SQL and the reader, or a tool needs a plain `DbConnection`.	7
Entity Framework Core	You want LINQ, change tracking, `DbContext` injection, or scaffolding (Radzen, Blazor apps).	11
OrmLite	You want typed CRUD with little ceremony, or are porting a PostgreSQL OrmLite app.	9
Dapper	You want hand-written SQL mapped straight onto objects, with minimal overhead.	10

Any of the ADO.NET paths can also take read queries written in DQL (Dynatrace Query Language), translated to SQL by the provider. The read examples below include the DQL form; DQL has no writes. See section 22.

Every example below works against the same table:

offerings (id, slug, name, status, target_amount, close_at)

Registration

ADO.NET — one connection per scope:

builder.Services.AddScoped<DbConnection>(_ => new ElephantConnection(connectionString));

Entity Framework Core — a context factory (the right choice for Blazor Server):

builder.Services.AddDbContextFactory<PortalDbContext>(options =>
    options.UseElephantSqlDb(connectionString));

OrmLite — a singleton connection factory:

builder.Services.AddSingleton<IDbConnectionFactory>(_ => new OrmLiteConnectionFactory(
    connectionString, ElephantOrmLiteDialectProvider.Instance));

Dapper — no registration of its own; it runs on the ADO.NET connection. Map snake_case columns to PascalCase properties once at startup:

Dapper.DefaultTypeMap.MatchNamesWithUnderscores = true;
SqlMapper.AddTypeHandler(new GuidTypeHandler());   // see section 10

Entity definitions

ADO.NET — no entity; read columns by ordinal or name.

Entity Framework Core:

[Table("offerings")]
public class Offering
{
    [Column("id")] public Guid Id { get; set; }
    [Column("slug")] public string Slug { get; set; } = "";
    [Column("name")] public string Name { get; set; } = "";
    [Column("status")] public string Status { get; set; } = "Draft";
    [Column("target_amount")] public decimal TargetAmount { get; set; }
    [Column("close_at")] public DateTimeOffset? CloseAt { get; set; }
}

public class PortalDbContext(DbContextOptions<PortalDbContext> options) : DbContext(options)
{
    public DbSet<Offering> Offerings => Set<Offering>();
}

OrmLite:

[Alias("offerings")]
public class Offering
{
    [PrimaryKey, Alias("id")] public Guid Id { get; set; } = Guid.NewGuid();
    [Alias("slug")] public string Slug { get; set; } = "";
    [Alias("name")] public string Name { get; set; } = "";
    [Alias("status")] public string Status { get; set; } = "Draft";
    [Alias("target_amount")] public decimal TargetAmount { get; set; }
    [Alias("close_at")] public DateTimeOffset? CloseAt { get; set; }
}

Dapper — a plain class; MatchNamesWithUnderscores maps target_amount to TargetAmount:

public class Offering
{
    public Guid Id { get; set; }
    public string Slug { get; set; } = "";
    public string Name { get; set; } = "";
    public string Status { get; set; } = "Draft";
    public decimal TargetAmount { get; set; }
    public DateTimeOffset? CloseAt { get; set; }
}

In a real application keep one Offering class and put both the EF Core and OrmLite attributes on it; they do not conflict.

Query a list

ADO.NET:

await using var connection = new ElephantConnection(connectionString);
await connection.OpenAsync();

await using var command = connection.CreateCommand();
command.CommandText = "SELECT id, name, target_amount FROM offerings WHERE status = @status";
command.Parameters.Add(new ElephantParameter("status", "Open"));

await using var reader = await command.ExecuteReaderAsync();
while (await reader.ReadAsync())
{
    var id = reader.GetGuid(0);
    var name = reader.GetString(1);
    var target = reader.GetDecimal(2);
}

Entity Framework Core:

await using var db = await dbFactory.CreateDbContextAsync();

var open = await db.Offerings
    .AsNoTracking()
    .Where(o => o.Status == "Open")
    .ToListAsync();

OrmLite:

using var db = await dbFactory.OpenDbConnectionAsync();

var open = await db.SelectAsync<Offering>(o => o.Status == "Open");

Dapper:

await using var connection = new ElephantConnection(connectionString);
await connection.OpenAsync();

var open = await connection.QueryAsync<Offering>(
    "SELECT * FROM offerings WHERE status = @status", new { status = "Open" });

DQL:

await using var command = connection.CreateCommand();
command.QueryLanguage = ElephantQueryLanguage.Dql;
command.CommandText = "fetch offerings | filter status == $status | fields id, name, target_amount";
command.Parameters.Add(new ElephantParameter("status", "Open"));

await using var reader = await command.ExecuteReaderAsync();

Get one row

ADO.NET:

await using var command = connection.CreateCommand();
command.CommandText = "SELECT id, name FROM offerings WHERE slug = @slug";
command.Parameters.Add(new ElephantParameter("slug", "seed-round"));

await using var reader = await command.ExecuteReaderAsync();
var found = await reader.ReadAsync();
var name = found ? reader.GetString(reader.GetOrdinal("name")) : null;

Entity Framework Core:

var one = await db.Offerings.SingleOrDefaultAsync(o => o.Slug == "seed-round");
var byKey = await db.Offerings.FindAsync(offeringId);

OrmLite:

var one = await db.SingleAsync<Offering>(o => o.Slug == "seed-round");
var byKey = await db.SingleByIdAsync<Offering>(offeringId);

Dapper:

var one = await connection.QuerySingleOrDefaultAsync<Offering>(
    "SELECT * FROM offerings WHERE slug = @slug", new { slug = "seed-round" });

DQL:

await using var command = connection.CreateCommand();
command.QueryLanguage = ElephantQueryLanguage.Dql;
command.CommandText = "fetch offerings | filter slug == \"seed-round\" | fields id, name | limit 1";

await using var reader = await command.ExecuteReaderAsync();
var found = await reader.ReadAsync();

Count

ADO.NET:

await using var command = connection.CreateCommand();
command.CommandText = "SELECT COUNT(*) AS total FROM offerings WHERE status = @status";
command.Parameters.Add(new ElephantParameter("status", "Open"));

var total = Convert.ToInt64(await command.ExecuteScalarAsync());

Entity Framework Core:

var total = await db.Offerings.CountAsync(o => o.Status == "Open");

OrmLite:

var total = await db.CountAsync<Offering>(o => o.Status == "Open");

Dapper:

var total = await connection.ExecuteScalarAsync<long>(
    "SELECT COUNT(*) AS total FROM offerings WHERE status = @status", new { status = "Open" });

DQL — from TotalItems, or with summarize:

var total = await connection.CountDqlAsync("fetch offerings | filter status == \"Open\"");

command.QueryLanguage = ElephantQueryLanguage.Dql;
command.CommandText = "fetch offerings | filter status == \"Open\" | summarize total = count()";
var counted = Convert.ToInt64(await command.ExecuteScalarAsync());

Page through results

ADO.NET — the paging helper returns one page plus the total match count:

var page = await connection.QueryPageAsync(
    "SELECT id, name FROM offerings ORDER BY name",
    r => new { Id = r.GetGuid(0), Name = r.GetString(1) },
    pageNumber: 2);

var totalRows = page.TotalItems;

Entity Framework Core:

var page = await db.Offerings
    .AsNoTracking()
    .OrderBy(o => o.Name)
    .Skip(20).Take(20)
    .ToListAsync();

OrmLite:

var page = await db.SelectAsync(db.From<Offering>()
    .OrderBy(o => o.Name)
    .Limit(skip: 20, rows: 20));

Dapper:

var page = await connection.QueryAsync<Offering>(
    "SELECT * FROM offerings ORDER BY name LIMIT @take OFFSET @skip",
    new { take = 20, skip = 20 });

DQL:

var page = await connection.QueryDqlPageAsync(
    "fetch offerings | fields id, name | sort name",
    r => new { Id = r.GetGuid(0), Name = r.GetString(1) },
    pageNumber: 2);

var totalRows = page.TotalItems;

Insert

Every API must supply the key: there is no identity or sequence. DQL is read-only, so Insert, Update and Delete have no DQL form.

ADO.NET:

await using var command = connection.CreateCommand();
command.CommandText =
    "INSERT INTO offerings (id, slug, name, status, target_amount) " +
    "VALUES (@id, @slug, @name, @status, @target)";
command.Parameters.Add(new ElephantParameter("id", Guid.NewGuid()));
command.Parameters.Add(new ElephantParameter("slug", "seed-round"));
command.Parameters.Add(new ElephantParameter("name", "Seed Round"));
command.Parameters.Add(new ElephantParameter("status", "Open"));
command.Parameters.Add(new ElephantParameter("target", 2_500_000m));

await command.ExecuteNonQueryAsync();

Entity Framework Core — the Guid key is generated for you on Add:

db.Offerings.Add(new Offering
{
    Slug = "seed-round", Name = "Seed Round", Status = "Open", TargetAmount = 2_500_000m
});
await db.SaveChangesAsync();

OrmLite:

await db.InsertAsync(new Offering
{
    Id = Guid.NewGuid(), Slug = "seed-round", Name = "Seed Round",
    Status = "Open", TargetAmount = 2_500_000m
});

Dapper:

await connection.ExecuteAsync(
    "INSERT INTO offerings (id, slug, name, status, target_amount) " +
    "VALUES (@Id, @Slug, @Name, @Status, @TargetAmount)",
    new Offering
    {
        Id = Guid.NewGuid(), Slug = "seed-round", Name = "Seed Round",
        Status = "Open", TargetAmount = 2_500_000m
    });

Update

UPDATE reports no affected-row count on this engine, so none of the four APIs can tell you whether a row matched (see section 13).

ADO.NET:

await using var command = connection.CreateCommand();
command.CommandText = "UPDATE offerings SET status = @status WHERE id = @id";
command.Parameters.Add(new ElephantParameter("status", "Closed"));
command.Parameters.Add(new ElephantParameter("id", offeringId));

await command.ExecuteNonQueryAsync();   // returns -1: count not known

Entity Framework Core:

var offering = await db.Offerings.FindAsync(offeringId);
offering!.Status = "Closed";
await db.SaveChangesAsync();

OrmLite:

await db.UpdateOnlyAsync(() => new Offering { Status = "Closed" },
    where: o => o.Id == offeringId);

Dapper:

await connection.ExecuteAsync(
    "UPDATE offerings SET status = @status WHERE id = @id",
    new { status = "Closed", id = offeringId });

Delete

ADO.NET:

await using var command = connection.CreateCommand();
command.CommandText = "DELETE FROM offerings WHERE id = @id";
command.Parameters.Add(new ElephantParameter("id", offeringId));

await command.ExecuteNonQueryAsync();

Entity Framework Core:

var offering = await db.Offerings.FindAsync(offeringId);
if (offering is not null)
{
    db.Offerings.Remove(offering);
    await db.SaveChangesAsync();
}

OrmLite:

await db.DeleteByIdAsync<Offering>(offeringId);

Dapper:

await connection.ExecuteAsync("DELETE FROM offerings WHERE id = @id", new { id = offeringId });

Mixing APIs

Because every API runs on ElephantConnection, you can drop down a level whenever it helps:

// From EF Core to Dapper on the same connection
var connection = db.Database.GetDbConnection();
await db.Database.OpenConnectionAsync();
var names = await connection.QueryAsync<string>("SELECT name FROM offerings");

// From OrmLite to ADO.NET
using var ormLite = await dbFactory.OpenDbConnectionAsync();
using var command = ormLite.CreateCommand();
command.CommandText = "SELECT COUNT(*) AS total FROM offerings";
var total = Convert.ToInt64(command.ExecuteScalar());

What the four have in common, and why the rest of this guide applies to all of them:

No transactions — EF Core SaveChanges, OrmLite SaveAsync and multi-statement ADO.NET or Dapper code are all non-atomic. See section 13.
Keys are yours to assign — no identity or sequence in any API.
One set of value formats — Guid, dates and times are stored as text in the same format, so a row written by one API reads back in the others. See section 12.
One parameter binder — values from all four go through ElephantParameterBinder. See section 15.

7. Raw ADO.NET

Query

await using var connection = new ElephantConnection(connectionString);
await connection.OpenAsync();

await using var command = connection.CreateCommand();
command.CommandText = "SELECT id, name, close_at FROM offerings WHERE status = @status";
command.Parameters.Add(new ElephantParameter("status", "Open"));

await using var reader = await command.ExecuteReaderAsync();

while (await reader.ReadAsync())
{
    var id = reader.GetGuid(0);
    var name = reader.GetString(1);
    var closeAt = reader.IsDBNull(2) ? (DateTime?)null : reader.GetDateTime(2);
}

Scalar

await using var command = connection.CreateCommand();
command.CommandText = "SELECT COUNT(*) AS total FROM subscriptions WHERE offering_id = @id";
command.Parameters.Add(new ElephantParameter("id", offeringId));

var total = Convert.ToInt64(await command.ExecuteScalarAsync());

Returns the first column of the first row, or null on an empty result.

Write

await using var command = connection.CreateCommand();
command.CommandText =
    "INSERT INTO offerings (id, slug, name, status) VALUES (@id, @slug, @name, @status)";

command.Parameters.Add(new ElephantParameter("id", Guid.NewGuid()));
command.Parameters.Add(new ElephantParameter("slug", "seed-round"));
command.Parameters.Add(new ElephantParameter("name", "Seed Round"));
command.Parameters.Add(new ElephantParameter("status", "Open"));

var affected = await command.ExecuteNonQueryAsync();

ExecuteNonQuery returns a real row count for INSERT, because the provider loops the rows itself. For UPDATE and DELETE it returns -1 — ADO.NET's "not known" — because the API reports no count and a fabricated 1 would be worse than none.

Saving a file as a record

SAVEFILEASRECORD stores a file — an ONNX model, a document, an image — as a record. Pass it as the command text and run it with ExecuteNonQuery:

await using var connection = new ElephantConnection(connectionString);
await connection.OpenAsync();
connection.ChangeDatabase("postgresql_postgres_public");

await using var command = connection.CreateCommand();
command.CommandText =
    @"SAVEFILEASRECORD ""C:\Dataark Systems LLC\Sourcecode\ESP-FailuresModel\onnx_models\esp_pump\esp_failure_model.onnx"", ""esp_failures_v001""";

await command.ExecuteNonQueryAsync();   // -1 on success; throws ElephantException otherwise

It is the client-side equivalent of:

AuthStatus status = await client.SaveSQLRecordsFromFileAsync(sqlFile, DatabaseName: "postgresql_postgres_public");

The first argument is the file path, the second the record name; both in double quotes. A per-command DatabaseName works here as it does for any statement.
The path is read by the client on the machine running your code, not by the server.
Write the path and name into the command text. Parameters render as single-quoted SQL literals, which is not the form this command takes; @ inside a double-quoted path is left alone.
ExecuteNonQuery returns -1: the API reports a status, not a count.

Reading by column name

while (await reader.ReadAsync())
{
    var id = reader.GetGuid(reader.GetOrdinal("id"));
    var name = reader["name"] as string;
}

Column lookup is case-insensitive. GetOrdinal throws IndexOutOfRangeException for an unknown name.

Choosing the database

Every statement carries a database name, the same DatabaseName argument the client takes on SelectSQLRecordsAsync, InsertSQLRecordsAsync and the rest. By default it is the Database keyword. It can be overridden at two levels:

Level	How	Scope
Connection	`connection.ChangeDatabase("name")`	Every later command on that connection
Command	`command.DatabaseName = "name"`	That command only

The most specific setting wins: command.DatabaseName, then ChangeDatabase, then the Database keyword. Authentication is unaffected — Open always validates against the Database keyword, and an override only changes where statements run.

Per connection — the equivalent of passing the same DatabaseName to every client call:

await using var connection = new ElephantConnection(connectionString);   // Database=dataaDatabase
await connection.OpenAsync();

connection.ChangeDatabase("postgresql_postgres_public");

await using var insert = connection.CreateCommand();
insert.CommandText = "INSERT INTO api_key (id, user_auth_id, created_date) VALUES (@id, @user, @created)";
insert.Parameters.Add(new ElephantParameter("id", ApiKey.NewId()));
insert.Parameters.Add(new ElephantParameter("user", userAuthId));
insert.Parameters.Add(new ElephantParameter("created", DateTime.UtcNow));
await insert.ExecuteNonQueryAsync();                        // written to postgresql_postgres_public

await using var select = connection.CreateCommand();
select.CommandText = "SELECT id, created_date FROM api_key WHERE user_auth_id = @user";
select.Parameters.Add(new ElephantParameter("user", userAuthId));
await using var reader = await select.ExecuteReaderAsync(); // read from postgresql_postgres_public

It is the client-side equivalent of:

await client.InsertSQLRecordsAsync<string>(sql, DatabaseName: "postgresql_postgres_public");
await client.SelectSQLRecordsAsync<string>(sql, DatabaseName: "postgresql_postgres_public");

Per command — one statement against a different database, the rest of the connection unchanged:

await using var command = connection.CreateCommand();
command.CommandText = "SELECT id, name FROM offerings WHERE status = @status";
command.DatabaseName = "postgresql_postgres_public_Wg6JvlNfl8";
command.Parameters.Add(new ElephantParameter("status", "Open"));

await using var reader = await command.ExecuteReaderAsync();

Leaving DatabaseName null (or blank) falls back to the connection.

Reading the current value — connection.Database returns the override if one is set, otherwise the Database keyword:

Assert.Equal("dataaDatabase", connection.Database);
connection.ChangeDatabase("postgresql_postgres_public");
Assert.Equal("postgresql_postgres_public", connection.Database);

Through Dapper and OrmLite — both sit on the same connection, so set it there before running anything:

// Dapper: IDbConnection.ChangeDatabase
await using var connection = new ElephantConnection(connectionString);
await connection.OpenAsync();
connection.ChangeDatabase("postgresql_postgres_public");
var keys = await connection.QueryAsync<ApiKey>("SELECT * FROM api_key WHERE user_auth_id = @u", new { u = userAuthId });

// OrmLite: unwrap to the provider's connection first
using var db = await dbFactory.OpenDbConnectionAsync();
db.ToDbConnection().ChangeDatabase("postgresql_postgres_public");
var rows = await db.SelectAsync<ApiKey>(k => k.UserAuthId == userAuthId);

Things to know:

ChangeDatabase rejects a null or blank name with ArgumentException.
The override lasts until it is changed again or the connection string is replaced; assigning ConnectionString clears it. It is not part of the connection string, so a pooled or factory-created connection starts on the Database keyword.
Nothing is validated on the server when the name is set. A misspelt name surfaces on the first statement — as an empty result for a SELECT, or as rows written where you did not expect them for an INSERT.
INSERT still goes through SaveToDatabaseWithNoResponse with decoded values; the target database is carried in the record envelope's DatabaseName, which the server uses to route the save. UPDATE, DELETE and other statements pass it as the DatabaseName argument.

Listing databases and their schema

GetDatabasesAsync returns the databases the connection's account can see, each with its full schema, read from the client's DatabaseModel records and sorted by display name.

Name is the database's identity — the value ChangeDatabase, command.DatabaseName and the table use — and it never changes. DisplayName is for display only; see Renaming a database.

Provider record	From	Fields
`ElephantDatabase`	`DatabaseModel`	`Name`, `DisplayName`, `Tables`
`ElephantTable`	`TableModel`	`Name`, `Columns`
`ElephantColumn`	`ColumnModel`	`Name`, `DataType`, `IsPrimaryKey`, `IsForeignKey`, `ForeignKey`
`ElephantForeignKey`	`ForeignKeyModel`	`Name`, `ReferencedTable`, `ReferencedColumn`

await using var connection = new ElephantConnection(connectionString);
await connection.OpenAsync();

foreach (var db in await connection.GetDatabasesAsync())
{
    Console.WriteLine($"{db.DisplayName} ({db.Name})");

    foreach (var table in db.Tables)
        Console.WriteLine($"  {table.Name}: {string.Join(", ", table.Columns.Select(c => $"{c.Name} {c.DataType}"))}");
}

// One database, by Name (defaults to connection.Database)
var schema = await connection.GetDatabaseAsync("postgresql_postgres_public");
connection.ChangeDatabase(schema!.Name);

DisplayName is DatabaseDisplayName, or Name when that is blank. Entries are keyed by Name; if two records share a Name, the first wins.
With no DatabaseModel records, GetDatabasesAsync returns a single entry, with no tables, for connection.Database. Pass includeCurrentWhenEmpty: false for an empty list. GetDatabaseAsync matches on Name only and returns null for an unknown name.
It runs select * from DatabaseModel where name != "" typed as DatabaseModel, with no DatabaseName and StringNameOfType: "DatabaseModel", reading every page. It is not affected by ChangeDatabase, and each call is one fresh listing — cache the result if you call it often.

The same data is available through the standard ADO.NET schema API, for tools that discover schema that way. Restrictions are positional; null or empty means any. The database restriction matches Name.

Collection	Columns	Restrictions
`Databases`	`database_name`, `display_name`	—
`Tables`	`database_name`, `table_name`	database, table
`Columns`	`database_name`, `table_name`, `column_name`, `ordinal_position`, `data_type`, `is_primary_key`, `is_foreign_key`	database, table, column
`ForeignKeys`	`database_name`, `table_name`, `column_name`, `constraint_name`, `referenced_table`, `referenced_column`	database, table

DataTable databases = await connection.GetSchemaAsync("Databases");
DataTable tables    = await connection.GetSchemaAsync("Tables",  ["postgresql_postgres_public"]);
DataTable columns   = await connection.GetSchemaAsync("Columns", ["postgresql_postgres_public", "api_key"]);

GetSchema() with no arguments returns MetaDataCollections, listing these four.

Creating a database

CreateDatabaseAsync creates a database (table) for the connection's account, on an open connection, independently of AutoCreateLedger:

await using var connection = new ElephantConnection(connectionString);
await connection.OpenAsync();

await connection.CreateDatabaseAsync("sales_2026");                  // EncryptionAlgorithm from the connection string
await connection.CreateDatabaseAsync("audit_vault", "SHA512");       // explicit algorithm

connection.ChangeDatabase("sales_2026");                             // start using it

The SQL form runs through any command, which is how tools that only speak SQL can do it:

await using var command = connection.CreateCommand();
command.CommandText = "CREATE DATABASE IF NOT EXISTS sales_2026";
await command.ExecuteNonQueryAsync();                                // -1: status, not a count

The name may contain letters, digits, _ and - (1–128 characters); anything else throws ArgumentException. In SQL it may be bare or wrapped in "…", […] or `…`.
It creates the table a connection with Database=<name> would open: the name is composed by the client's GetLedgerName(), exactly as for AutoCreateLedger.
The connection keeps its current database. Call ChangeDatabase, or set command.DatabaseName, to use the new one.
A refusal from the server (a rejected name, a quota, a permission) throws ElephantException.
IF NOT EXISTS runs one lookup — select * from DatabaseModel where name = "<name>" — and does nothing when a database with that Name exists. It does not list every database, and a display name never counts as a match. Without IF NOT EXISTS, the request goes to the server, which decides what an existing name means. The check and the create are two calls, not one atomic step.
CreateDatabase(name) is the synchronous form.

Renaming a database

RenameDatabaseAsync changes a database's display name only. Name — the identity used by ChangeDatabase, command.DatabaseName and the table — is never changed, so existing connection strings, commands and stored rows keep working.

await connection.RenameDatabaseAsync("sales_2026", "Sales FY2026");

var db = await connection.GetDatabaseAsync("sales_2026");   // still found by Name
Console.WriteLine(db!.DisplayName);                          // "Sales FY2026"
connection.ChangeDatabase("sales_2026");                     // Name, not the display name

It reads the DatabaseModel whose Name matches (one lookup), sets DatabaseDisplayName, clears each table's SelectedNodeTable and Link so the model serializes, and saves it over its own record with SaveToDatabaseWithNoResponse (BlockName as the record id, its current BlockHashCode as the existing hash) — the same steps as the management tooling's SaveRenamedDatabaseContext.
It returns the number of DatabaseModel records updated, normally 1. Name is not enforced unique, so every record carrying it is updated.
An unknown Name throws ElephantException (NoDataFound). A display name must be 1–200 characters with no control characters.
There is no SQL form. RenameDatabase(name, displayName) is the synchronous form.

8. Pagination and result metadata

SelectSQLRecordsAsync returns three things — status, rows, and a PaginationDTO. Most ADO.NET consumers map the rows onto objects and discard everything else, which loses TotalItems: the one value a paged UI needs and cannot compute for itself.

The provider keeps all three. ElephantPagination carries the DTO's fields plus the outcome status:

Member	Notes
`PageNumber`	1-based page this result came from
`PageSize`	Rows per page, as reported by the server
`TotalItems`	Rows matching the query across every page
`TotalPages`	Computed from `TotalItems` and `PageSize`
`HasMore`	A further page exists
`IsEmpty`	The query matched nothing
`Status`	`AuthStatus` name for the call — `Success` or `NoDataFound`

Status is a string rather than the client's enum so that IElephantExecutor stays free of the client dependency and the tests can run without it. The typed AuthStatus is on ElephantException for the failure path.

Reading it from the reader

Available before any row is consumed, because TotalItems comes back with the first page:

await using var command = connection.CreateCommand();
command.CommandText = "SELECT id, name FROM offerings WHERE status = @status";
command.Parameters.Add(new ElephantParameter("status", "Open"));

await using var reader = (ElephantDataReader)await command.ExecuteReaderAsync();

var total = reader.TotalItems;                  // 412
var pages = reader.Pagination.TotalPages;       // 17 at PageSize 25
var more = reader.HasMorePages;                 // true
var status = reader.Pagination.Status;          // "Success"

while (await reader.ReadAsync())
{
    // …
}

Reading it from the command

LastPagination is set by ExecuteReader, ExecuteScalar and ExecuteNonQuery, and survives the reader being disposed — useful when a total is needed after the rows have been consumed:

using (await command.ExecuteReaderAsync()) { /* … */ }

var total = command.LastPagination!.TotalItems;

Server-side paging

Setting PageNumber fetches exactly that page and stops the reader walking forward. Without it the reader pages ahead as the consumer reads, which quietly turns a paged query into a full scan:

command.PageNumber = 3;   // exactly page 3, no look-ahead

QueryPageAsync wraps that into one call:

var page = await connection.QueryPageAsync(
    "SELECT id, name FROM offerings WHERE status = @status",
    r => new OfferingSummary(r.GetGuid(0), r.GetString(1)),
    pageNumber: 2,
    parameters: [new ElephantParameter("status", "Open")]);

page.Rows;        // IReadOnlyList<OfferingSummary>
page.PageNumber;  // 2
page.TotalItems;  // 412
page.TotalPages;  // 17
page.HasMore;     // true

Counting without materialising

TotalItems arrives with the first page, so a count is one round trip and no COUNT(*):

var total = await connection.CountAsync(
    "SELECT id FROM subscriptions WHERE offering_id = @id",
    [new ElephantParameter("id", offeringId)]);

Streaming every page

await foreach (var name in connection.QueryAllAsync(
    "SELECT name FROM offerings", r => r.GetString(0), cancellationToken: ct))
{
    // …
}

Each page is a round trip. Bound the query or raise MaxRecords rather than streaming a whole table.

Through an interface-typed call

OrmLite and Dapper hand back IDbCommand and DbDataReader, so the concrete types are erased. Two extension methods recover the pagination:

ElephantPagination? fromCommand = someDbCommand.GetPagination();
ElephantPagination? fromReader = someDbDataReader.GetPagination();

Both return null when the object did not come from this provider.

Empty results

An empty result reports NoDataFound, not Success. That distinction matters: it separates "nothing matched the query" from "this page happened to be short."

if (reader.Pagination.IsEmpty)
{
    // No rows anywhere, not just on this page.
}

9. OrmLite

Entities

[Alias("offerings")]
public class Offering
{
    [PrimaryKey, Alias("id")]
    public Guid Id { get; set; } = Guid.NewGuid();

    [Alias("slug"), StringLength(120)]
    public required string Slug { get; set; }

    [Alias("name"), StringLength(200)]
    public required string Name { get; set; }

    [Alias("status")]
    public OfferingStatus Status { get; set; }

    [Alias("target_amount"), DecimalLength(18, 2)]
    public decimal TargetAmount { get; set; }

    [Alias("close_at")]
    public DateTimeOffset? CloseAt { get; set; }

    [Alias("created_at")]
    public DateTimeOffset CreatedAt { get; set; } = DateTimeOffset.UtcNow;
}

Attributes that behave differently here:

[Schema] is ignored. The table on the connection is the schema, so portal.offerings would name nothing.
[Index] and [Index(Unique = true)] are read and ignored. No index DDL is emitted and no constraint is created.
[AutoIncrement] throws. There is no sequence or identity — assign keys yourself.
[ForeignKey] produces no constraint.

Reads

using var db = await dbFactory.OpenDbConnectionAsync(token: ct);

var open = await db.SelectAsync<Offering>(
    o => o.Status == OfferingStatus.Open, token: ct);

var one = await db.SingleAsync<Offering>(o => o.Slug == slug, token: ct);

var byId = await db.SingleByIdAsync<Offering>(id, token: ct);

var exists = await db.ExistsAsync<Offering>(o => o.Slug == slug, token: ct);

Typed expressions

var query = db.From<Offering>()
    .Where(o => o.Status == OfferingStatus.Open)
    .And(o => o.CloseAt > DateTimeOffset.UtcNow)
    .OrderByDescending(o => o.CreatedAt)
    .Limit(skip: 0, rows: 25);

var page = await db.SelectAsync(query, token: ct);

Limit becomes LIMIT … OFFSET …. Note this sits on top of the client's own pagination: the API returns pages of MaxRecords regardless, and the reader walks them. A LIMIT bounds the logical result; it does not make the fetch one round trip.

Writes

offering.Id = Guid.NewGuid();
offering.CreatedAt = DateTimeOffset.UtcNow;

await db.InsertAsync(offering, token: ct);

offering.Name = "Seed Round (Extended)";
await db.UpdateAsync(offering, token: ct);

await db.DeleteByIdAsync<Offering>(offering.Id, token: ct);

Prefer explicit InsertAsync/UpdateAsync over SaveAsync. OrmLite's upsert paths may reach for a transaction, which throws unless AllowNonTransactional=true.

Raw SQL through OrmLite

var rows = await db.SelectAsync<Offering>(
    "SELECT * FROM offerings WHERE status = @status",
    new { status = "Open" }, token: ct);

var total = await db.ScalarAsync<long>(
    "SELECT COUNT(*) FROM subscriptions WHERE offering_id = @id",
    new { id = offeringId }, token: ct);

Schema calls

// Succeeds and does nothing. The table appears on the first insert.
await db.CreateTableIfNotExistsAsync<Offering>();

// Real: uses information_schema, which the engine supports.
var exists = db.TableExists<Offering>();

Leaving CreateTableIfNotExists in your startup is harmless, but understand that it is not provisioning anything.

10. Dapper

await using var connection = new ElephantConnection(connectionString);
await connection.OpenAsync();

var open = await connection.QueryAsync<Offering>(
    "SELECT id, slug, name FROM offerings WHERE status = @status",
    new { status = "Open" });

var one = await connection.QuerySingleOrDefaultAsync<Offering>(
    "SELECT * FROM offerings WHERE slug = @slug",
    new { slug = "seed-round" });

Dapper's own type handling applies. Guid columns arrive as strings, so register a handler if Dapper's default mapping does not cover your case:

public sealed class GuidTypeHandler : SqlMapper.TypeHandler<Guid>
{
    public override Guid Parse(object value) =>
        value is Guid guid ? guid : Guid.Parse((string)value);

    public override void SetValue(IDbDataParameter parameter, Guid value) =>
        parameter.Value = value.ToString("D");
}

SqlMapper.AddTypeHandler(new GuidTypeHandler());

11. Entity Framework Core

The ElephantSqlDb.Data package includes an EF Core 8 provider, in the ElephantSqlDb.EntityFrameworkCore namespaces, built on the ADO.NET types above. It adds LINQ queries, change tracking and scaffolding; it does not replace or alter ElephantConnection, the OrmLite dialect or Dapper, and all four can run side by side against the same tables.

Installation

Nothing beyond ElephantSqlDb.Data (section 3). The provider depends on Microsoft.EntityFrameworkCore.Relational 8.0.x, which the package brings with it. Add Microsoft.EntityFrameworkCore.Design to the startup project when using the dotnet ef tools. UseElephantSqlDb lives in the Microsoft.EntityFrameworkCore namespace, so no extra using is needed.

ADO.NET and EF Core classes

Role	ADO.NET (namespace `ElephantSqlDb.Data`)	EF Core (namespace `ElephantSqlDb.EntityFrameworkCore.*`)
Connection	`ElephantConnection`	`ElephantRelationalConnection` (wraps `ElephantConnection`)
Configuration	`ElephantConnectionStringBuilder`	`UseElephantSqlDb()`, `ElephantDbContextOptionsBuilder`
Registration	`ElephantProviderFactory`	`AddEntityFrameworkElephantSqlDb()`
Command / execution	`ElephantCommand`, `ElephantSqlDbExecutor`	`ElephantBatchExecutor`, `ElephantModificationCommandBatch`
Parameters	`ElephantParameter`, `ElephantParameterBinder`	Uses `ElephantParameter` through type mappings
Reading results	`ElephantDataReader`	Uses `ElephantDataReader`
SELECT generation	SQL you write	`ElephantQuerySqlGenerator`
INSERT/UPDATE/DELETE	SQL you write	`ElephantUpdateSqlGenerator`
LINQ translation	—	`ElephantStringMethodTranslator`
Type mapping	`ElephantDataReader` getters, OrmLite converters	`ElephantTypeMappingSource`, `ElephantValueFormats`
Transactions	`ElephantTransaction`	None — see SaveChanges semantics
Schema metadata	`GetSchema()`, `GetDatabasesAsync()`	`ElephantDatabaseModelFactory` (scaffolding)
Database create/check	`CreateDatabaseAsync()`, `GetDatabaseAsync()`	`ElephantDatabaseCreator`
Design-time tooling	—	`ElephantDesignTimeServices`, `ElephantCodeGenerator`

Entities and the DbContext

There is no identity or sequence, so keys must be assigned before the write. Guid keys need nothing extra: EF Core generates them on the client. Integer keys need ValueGeneratedNever() and a value you assign.

[Table("offerings")]
public class Offering
{
    [Column("id")] public Guid Id { get; set; }               // generated client-side by EF Core
    [Column("slug")] public string Slug { get; set; } = "";
    [Column("name")] public string Name { get; set; } = "";
    [Column("status")] public string Status { get; set; } = "Draft";
    [Column("target_amount")] public decimal TargetAmount { get; set; }
    [Column("opens_at")] public DateTime OpensAt { get; set; } // stored as UTC text
    public List<Subscription> Subscriptions { get; set; } = [];
}

[Table("subscriptions")]
public class Subscription
{
    [Column("id")] public long Id { get; set; }               // app-assigned, see OnModelCreating
    [Column("offering_id")] public Guid OfferingId { get; set; }
    [Column("investor_email")] public string InvestorEmail { get; set; } = "";
    [Column("amount")] public decimal Amount { get; set; }
}

public class PortalDbContext(DbContextOptions<PortalDbContext> options) : DbContext(options)
{
    public DbSet<Offering> Offerings => Set<Offering>();
    public DbSet<Subscription> Subscriptions => Set<Subscription>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Subscription>()
            .Property(s => s.Id)
            .ValueGeneratedNever();
    }
}

Name tables and columns explicitly with [Table]/[Column] (or ToTable()/ HasColumnName()) whenever OrmLite or Dapper also reads them. EF Core defaults to the DbSet property name (Offerings), OrmLite to the class name (Offering); without an explicit name the two write to different tables.

Dependency injection

var connectionString = builder.Configuration.GetConnectionString("ElephantSqlDb")
    ?? throw new InvalidOperationException("ConnectionStrings:ElephantSqlDb is not set.");

builder.Services.AddDbContext<PortalDbContext>(options =>
    options.UseElephantSqlDb(connectionString));

Blazor Server components outlive a request, so register a factory there and create a short-lived context per operation:

builder.Services.AddDbContextFactory<PortalDbContext>(options =>
    options.UseElephantSqlDb(connectionString));

@inject IDbContextFactory<PortalDbContext> DbFactory

@code {
    private List<Offering> offerings = [];

    protected override async Task OnInitializedAsync()
    {
        await using var db = await DbFactory.CreateDbContextAsync();
        offerings = await db.Offerings.AsNoTracking().OrderBy(o => o.Name).ToListAsync();
    }
}

Provider options go in the second argument:

options.UseElephantSqlDb(connectionString, elephant => elephant
    .QuoteIdentifiers()          // off by default, as in the OrmLite dialect
    .CommandTimeout(60));

Queries

await using var db = await dbFactory.CreateDbContextAsync();

var open = await db.Offerings
    .AsNoTracking()
    .Where(o => o.Status == "Open" && o.TargetAmount >= 1_000_000m)
    .OrderBy(o => o.OpensAt)
    .ToListAsync();

var one = await db.Offerings.SingleOrDefaultAsync(o => o.Slug == "seed-round");

var byKey = await db.Offerings.FindAsync(offeringId);

var openCount = await db.Offerings.CountAsync(o => o.Status == "Open");

Skip/Take become LIMIT/OFFSET, the same paging the OrmLite dialect emits:

var page = await db.Offerings
    .AsNoTracking()
    .OrderBy(o => o.Name)
    .Skip((pageNumber - 1) * pageSize)
    .Take(pageSize)
    .ToListAsync();

String methods translate to LIKE, UPPER and LOWER:

var matches = await db.Offerings
    .Where(o => o.Name.Contains("Series") || o.Slug.StartsWith("seed-"))
    .Where(o => o.Status.ToUpper() == "OPEN")
    .ToListAsync();

Use AsNoTracking() for read-only lists: it skips change tracking and is the right default for grids and reports.

Navigations and Include() generate JOINs. Confirm JOIN support on the engine (see Verification) before relying on them; until then, load related rows with a second query:

var subscriptions = await db.Subscriptions
    .Where(s => s.OfferingId == offeringId)
    .ToListAsync();

Writes

await using var db = await dbFactory.CreateDbContextAsync();

// Insert
var offering = new Offering
{
    Slug = "seed-round",
    Name = "Seed Round",
    Status = "Open",
    TargetAmount = 2_500_000m,
    OpensAt = DateTime.UtcNow
};
db.Offerings.Add(offering);                       // Id assigned here, client-side
await db.SaveChangesAsync();

// Update
offering.Status = "Closed";
await db.SaveChangesAsync();                      // UPDATE ... WHERE Id = ...

// Delete
db.Offerings.Remove(offering);
await db.SaveChangesAsync();

// Integer key: assign it yourself
db.Subscriptions.Add(new Subscription
{
    Id = await NextSubscriptionIdAsync(),
    OfferingId = offering.Id,
    InvestorEmail = "investor@example.com",
    Amount = 25_000m
});
await db.SaveChangesAsync();

Each changed entity is one statement and one round trip, executed with ExecuteNonQuery. Nothing is read back after a write, so defaults, computed columns and server-generated values are not supported; the provider throws NotSupportedException naming the column if a model asks for one.

SaveChanges semantics

Read this before writing code that saves more than one entity at a time.

Not atomic. EF Core normally wraps SaveChanges in a transaction. The engine has none (see section 13), so the provider runs the statements in order without one. If the third of five fails, the first two stay applied and DbUpdateException is thrown for the third.
No concurrency detection. UPDATE and DELETE report no affected-row count, so a write that matched no row succeeds silently. Concurrency tokens ([ConcurrencyCheck], [Timestamp]) are not enforced.
No cascades. Foreign keys are not constraints (see section 14). Delete dependents yourself, before the principal.

Order writes so a partial failure is recoverable, and keep a compensating path for multi-entity changes — the same guidance as for raw ADO.NET and OrmLite:

db.Subscriptions.RemoveRange(
    await db.Subscriptions.Where(s => s.OfferingId == offering.Id).ToListAsync());
await db.SaveChangesAsync();                      // dependents first

db.Offerings.Remove(offering);
await db.SaveChangesAsync();                      // then the principal

Calling db.Database.BeginTransaction() explicitly follows the ADO.NET rules: it throws unless the connection string sets AllowNonTransactional=true, and even then cannot roll back.

Raw SQL and Dapper on the same connection

var rows = await db.Offerings
    .FromSqlInterpolated($"SELECT * FROM offerings WHERE status = {status}")
    .AsNoTracking()
    .ToListAsync();

var total = await db.Database
    .SqlQuery<decimal>($"SELECT SUM(amount) AS Value FROM subscriptions WHERE offering_id = {offeringId}")
    .SingleAsync();

Interpolated values become ElephantParameters and go through ElephantParameterBinder, so they are escaped exactly as in raw ADO.NET.

The context's connection is an ElephantConnection, so Dapper and the pagination helpers work on it directly:

var connection = (ElephantConnection)db.Database.GetDbConnection();
await db.Database.OpenConnectionAsync();

var page = await connection.QueryPageAsync(
    "SELECT id, name FROM offerings ORDER BY name",
    r => new { Id = r.GetGuid(0), Name = r.GetString(1) },
    pageNumber: 2);

var open = await connection.QueryAsync<Offering>(
    "SELECT * FROM offerings WHERE status = @status", new { status = "Open" });

EF Core writes Guid, DateTime, DateTimeOffset, TimeSpan, DateOnly and TimeOnly as text, in the same formats as the OrmLite converters (see section 12). A row written by any of the three reads back the same through the others, provided the table and column names match.

// Written by EF Core...
db.Offerings.Add(new Offering { Slug = "series-a", Name = "Series A", OpensAt = DateTime.UtcNow });
await db.SaveChangesAsync();

// ...read by OrmLite
using var ormLite = await ormLiteFactory.OpenDbConnectionAsync();   // IDbConnectionFactory
var fromOrmLite = await ormLite.SingleAsync<Offering>(o => o.Slug == "series-a");

Creating the database

await db.Database.EnsureCreatedAsync();   // creates the ledger if missing

EnsureCreated creates the database only. Tables are created by the engine on their first write, so there is nothing more to provision. EnsureDeleted throws, and EF Core migrations are not supported because the engine accepts no ALTER, DROP or CREATE INDEX (see section 14). Migrate() throws NotSupportedException with that explanation.

Scaffolding an existing database

Generate entities and a DbContext from tables that already exist:

dotnet tool install --global dotnet-ef
dotnet add package Microsoft.EntityFrameworkCore.Design

dotnet ef dbcontext scaffold "BaseUri=https://api.elephantsqldb.com;Token=...;Database=portal" ^
    ElephantSqlDb.Data --output-dir Models --context PortalDbContext

Scaffolding reads tables, columns, primary keys and foreign keys from the same DatabaseModel listing as GetSchema. That listing carries no nullability, length or index information, so:

every non-key column is generated as nullable (int?, string?);
no indexes are generated;
integer keys are generated with ValueGeneratedNever().

Pass the connection string by name (Name=ConnectionStrings:ElephantSqlDb) rather than inline, to keep the token out of generated code.

Using EF Core with Radzen Blazor

Radzen Blazor components bind to any IQueryable, so a context works with the DataGrid directly. For large tables, page on the server through LoadData:

@inject IDbContextFactory<PortalDbContext> DbFactory

<RadzenDataGrid Data="@offerings" Count="@count" LoadData="@LoadData"
                AllowPaging="true" PageSize="20" AllowSorting="true" TItem="Offering">
    <Columns>
        <RadzenDataGridColumn Property="Name" Title="Name" />
        <RadzenDataGridColumn Property="Status" Title="Status" />
        <RadzenDataGridColumn Property="TargetAmount" Title="Target" FormatString="{0:C0}" />
    </Columns>
</RadzenDataGrid>

@code {
    private IEnumerable<Offering> offerings = [];
    private int count;

    private async Task LoadData(LoadDataArgs args)
    {
        await using var db = await DbFactory.CreateDbContextAsync();

        var query = db.Offerings.AsNoTracking();

        query = string.IsNullOrEmpty(args.OrderBy)
            ? query.OrderBy(o => o.Name)
            : query.OrderBy(args.OrderBy);   // Radzen's dynamic LINQ extension

        count = await query.CountAsync();
        offerings = await query.Skip(args.Skip ?? 0).Take(args.Top ?? 20).ToListAsync();
    }
}

Radzen Blazor Studio's database wizard lists only the providers Radzen ships with. Until ElephantSqlDB is added there, scaffold with dotnet ef (above) and use the generated context in Studio as an existing data source.

EF Core limitations at a glance

Area	Behavior
Keys	No identity or sequences. `Guid` keys work as-is; integer keys need `ValueGeneratedNever()` and an assigned value.
SaveChanges	One statement per round trip, no transaction. Not atomic.
Concurrency	Not enforced; `UPDATE`/`DELETE` report no row count.
Migrations	Not supported. `EnsureCreated` creates the ledger only.
Store-generated values	Not supported (no defaults, computed columns or `RETURNING`).
Identifiers	Unquoted by default; enable with `QuoteIdentifiers()`.
Joins and grouping	Depend on engine support — verify before using `Include()`, `Any()`, `GroupBy()`.

12. Type mapping

CLR type	Column definition	On the wire	Notes
`string`	`TEXT` / `VARCHAR(n)`	string
`bool`	`BOOLEAN`	`1` / `0`	Reads `true`/`false` too
`byte`…`long`	`INTEGER` / `BIGINT`	number
`float`, `double`	`DOUBLE PRECISION`	number
`decimal`	`NUMERIC(38,6)`	number	Invariant culture
`Guid`	`VARCHAR(36)`	canonical `D` string
`DateTime`	`TIMESTAMP`	`yyyy-MM-dd HH:mm:ss.fffffff`	Parsed as UTC
`DateTimeOffset`	`VARCHAR(40)`	UTC, same format	Offset not preserved
`TimeSpan`	`VARCHAR(32)`	`c` format
`byte[]`	`BYTEA`	hex / base64
`Enum`	integer	number

Two things to be deliberate about

DateTimeOffset loses its offset. Values are normalised to UTC on write and read back as UTC. That is a deliberate choice: the transport carries no zone, so keeping local time would mean the same row reads as a different instant depending on which machine read it. If the original offset matters to your domain, store it in a separate column.

Column types are inferred, not declared. Rows arrive as JSON with no schema. The reader fixes column names and ordinals from the first row of the first page, and infers each column's CLR type from the first non-null value in that page. A column that is entirely null on the first page types as object.

That schema is then held for the life of the reader. A later page with different keys would otherwise shift what an ordinal means mid-read, and a consumer that has already mapped ordinal 3 to a property has no way to notice.

13. No transactions

The engine exposes no transaction verbs. BeginTransaction throws by default:

using var transaction = connection.BeginTransaction();
// NotSupportedException

Setting AllowNonTransactional=true returns a scope that satisfies the ADO.NET surface without isolating anything. Even then, Rollback throws — statements were applied as they were issued, and a silent no-op rollback would report a half-written record as cleanly reverted.

// AllowNonTransactional=true
using var transaction = connection.BeginTransaction();

// … statements are already applied as each executes …

transaction.Commit();   // no-op
transaction.Rollback(); // NotSupportedException

What to do instead

Order writes so a partial failure is recoverable. Write the dependent record first and the record that makes it visible last, so a failure leaves an orphan rather than a dangling reference.

// Investor and allocation first. If the subscription write fails, they are
// orphaned - findable and cleanable - rather than referenced by a subscription
// that has no allocation.
await db.InsertAsync(investor, token: ct);
await db.InsertAsync(allocation, token: ct);
await db.InsertAsync(subscription, token: ct);

Compensate explicitly.

var written = new List<Guid>();

try
{
    await db.InsertAsync(investor, token: ct);
    written.Add(investor.Id);

    await db.InsertAsync(allocation, token: ct);
    written.Add(allocation.Id);
}
catch
{
    foreach (var id in written)
        await TryDeleteAsync(id, ct);

    throw;
}

Or keep multi-table writes on a database that has transactions. For a workflow where partial application is genuinely unacceptable — a securities subscription spanning investor, allocation and table records — that is the honest answer.

14. No DDL, no constraints

The engine is schema-on-write. A table comes into being when the first row is written, named for the record type supplied to the save.

Statement	Behaviour
`CREATE TABLE`	Generated, accepted, dropped
`CREATE DATABASE`	Creates the table (`CreateDatabaseAsync`)
`ALTER`, `DROP`, `TRUNCATE`, `CREATE INDEX`	`NotSupportedException`

Destructive DDL throws rather than being ignored, because treating a DROP as a no-op would report a table as removed while it still holds every row.

The part that is easy to miss

PRIMARY KEY, NOT NULL, UNIQUE and foreign keys are not enforced.

An [Index(Unique = true)] on Offering.Slug constrains nothing. A second row with the same slug will be accepted, and /invest/seed-round becomes ambiguous.

Enforce it in the application:

public async Task CreateAsync(Offering offering, CancellationToken ct = default)
{
    using var db = await dbFactory.OpenDbConnectionAsync(token: ct);

    // The engine enforces no unique constraint, so this check is the only one.
    // Note it is a read-then-write with no transaction: two concurrent calls can
    // both pass. Where that matters, serialise upstream.
    if (await db.ExistsAsync<Offering>(o => o.Slug == offering.Slug, token: ct))
        throw new InvalidOperationException($"Slug '{offering.Slug}' is already taken.");

    offering.Id = Guid.NewGuid();
    offering.CreatedAt = DateTimeOffset.UtcNow;

    await db.InsertAsync(offering, token: ct);
}

The race window is real and cannot be closed at the data layer. Where uniqueness is load-bearing, serialise through a single writer, a distributed lock, or a deterministic key that makes collisions impossible.

Provisioning a schema

Through the ElephantSqlDB management portal — the Visual Schema Designer, or a Data Migration import from an existing PostgreSQL or SQLite database. Not from application startup.

15. Parameters and injection

The backend accepts a complete statement and binds nothing, so ElephantParameterBinder renders values into the SQL text. This is the highest-risk file in the package and the one to review most carefully.

What it does:

Walks the statement, skipping string literals and comments, so a marker inside one is left alone
Matches names longest-first, so @id is never substituted inside @id_2
Accepts @name and :name
Formats each value from its CLR type under invariant culture
Doubles embedded quotes and strips NUL
Throws on any type without an explicit rule

That last point matters. There is no ToString fallback, because that fallback is exactly how a value carrying a quote escapes its literal.

// Safe: rendered as a quoted literal with doubled quotes.
command.Parameters.Add(new ElephantParameter("name", "x'; DROP TABLE users; --"));
// → WHERE name = 'x''; DROP TABLE users; --'

// Throws NotSupportedException rather than guessing.
command.Parameters.Add(new ElephantParameter("v", new MyType()));

Convert unusual types before assigning Value. If you add a type rule, add a test in ParameterBinderTests at the same time.

Never concatenate user input into CommandText. The binder only protects values passed as parameters.

16. Performance

Opening a connection is expensive. Each OpenAsync constructs a client and makes an authentication round trip. There is no connection pool. Open once per unit of work:

// Good
using var db = await dbFactory.OpenDbConnectionAsync(token: ct);

foreach (var id in ids)
    results.Add(await db.SingleByIdAsync<Offering>(id, token: ct));

// Bad - one auth round trip per iteration
foreach (var id in ids)
{
    using var db = await dbFactory.OpenDbConnectionAsync(token: ct);
    results.Add(await db.SingleByIdAsync<Offering>(id, token: ct));
}

Every command is an HTTP call. Batch with IN clauses rather than looping:

var offerings = await db.SelectAsync<Offering>(o => ids.Contains(o.Id), token: ct);

Reads are paged. MaxRecords bounds each round trip; the reader fetches the next page when the consumer reads past the end of the current one. A scan of 10,000 rows at the default MaxRecords=100 is 100 HTTP calls. Raise MaxRecords for scan-heavy workloads, or bound the query with LIMIT.

Set PageNumber when you want one page. Left unset, the reader walks forward until the result is exhausted — a query intended as page 1 of a grid becomes a full scan. See section 8.

Use CountAsync rather than COUNT(*). TotalItems arrives with the first page, so a count costs one round trip and a page of rows instead of a second query.

Multi-row inserts are one call per row. InsertAll over 500 records is 500 round trips, with no rollback if one fails partway.

Async is real. The client is HttpClient-based, so ReadAsync and ExecuteReaderAsync do not block a thread-pool thread. Use the async overloads throughout — the sync ones block on the async path.

17. Error handling

try
{
    await db.InsertAsync(offering, token: ct);
}
catch (ElephantException ex)
{
    // Carries the client's AuthStatus.
    logger.LogError(ex, "Insert failed with {Status}.", ex.Status);

    if (ex.Status is AuthStatus.TokenInvalid or AuthStatus.Unauthenticated)
        await RefreshTokenAsync(ct);

    throw;
}
catch (NotSupportedException ex)
{
    // Unsupported DDL, a transaction, or a parameter type with no literal rule.
    logger.LogError(ex, "Unsupported operation.");
    throw;
}

Exception	Cause
`InvalidOperationException`	Connection not open, `CommandText` empty, required keyword missing, unrecognised `QueryLanguage`, DQL `$name` with no parameter
`ElephantException`	Backend returned a non-success `AuthStatus`
`NotSupportedException`	DDL, transaction, unmapped parameter type, DQL the provider cannot translate, or `ExecuteNonQuery` on a DQL command
`DqlSyntaxException`	Malformed DQL; `Position` is the character offset (section 22)
`InvalidCastException`	Column value did not convert to the requested type
`IndexOutOfRangeException`	Unknown column name or ordinal

18. Testing

IElephantExecutor exists so the provider can be tested without a live API. The client's operations are extension methods on IElephantSqlDBAPIService and cannot be substituted, so without the seam nothing above it would be testable.

[Fact]
public async Task Parses_guid_from_string_column()
{
    var id = Guid.Parse("0192f9a0-1111-7222-8333-444455556666");

    var fake = new FakeElephantExecutor().EnqueuePage(
        FakeElephantExecutor.Row(("id", id.ToString("D"))));

    await using var connection = await fake.OpenConnectionAsync();
    using var command = connection.CreateCommand();
    command.CommandText = "SELECT id FROM offerings";

    using var reader = await command.ExecuteReaderAsync();
    Assert.True(await reader.ReadAsync());

    Assert.Equal(id, reader.GetGuid(0));
}

FakeElephantExecutor records every statement after binding, which is how the binder is asserted end to end:

Assert.Equal(
    "SELECT id FROM offerings WHERE slug = 'seed-round'",
    fake.Statements[0]);

Use EnqueuePartialPage to force the reader's paging path — a small fixture never takes it otherwise. It also sets TotalItems independently of the row count, which is how the pagination assertions are written:

var fake = new FakeElephantExecutor()
    .EnqueuePartialPage(1, 25, 412, FakeElephantExecutor.Row(("id", "1")));

// … reader.TotalItems == 412, reader.Pagination.TotalPages == 17

In your own application, inject a custom executor factory:

var connection = new ElephantConnection(connectionString, _ => myFakeExecutor);

Testing DQL

ElephantDql.Translate needs no connection, so DQL tests assert the SQL directly. Fix the clock with DqlOptions.UtcNow so time windows are stable:

[Fact]
public void Relative_from_uses_the_timestamp_field()
{
    var options = new DqlOptions { UtcNow = () => new DateTime(2026, 10, 18, 12, 0, 0, DateTimeKind.Utc) };
    var t = ElephantDql.Translate("fetch logs, from: -2h", options);

    Assert.Equal("SELECT * FROM logs WHERE timestamp >= @__dql0", t.Sql);
    Assert.Equal(new DateTime(2026, 10, 18, 10, 0, 0, DateTimeKind.Utc), t.Parameters[0].Value);
}

Through a command, a fake executor records the bound SQL, as for any other statement. DqlTranslatorTests in the test project covers both.

19. Verification

Against a real table, in this order. Each depends on the one before.

DoesTableExist — exercises connection, command, binder and reader in a single call, and is the only schema operation the documentation confirms.
Guid round trip — insert and read back a primary key.
DateTimeOffset round trip — confirm UTC normalisation survives.
Value fidelity through the parser — parameters are rendered into SQL by the binder, then extracted back out by ElephantSqlParser into InsertValuesRows. Whether a value containing an apostrophe or a comma survives that round trip intact is the open question. Test a string with an apostrophe and a Guid.
Multi-row insert — confirm every row lands.
Paging — a result set larger than MaxRecords.

Steps 2 and 4 are the ones most likely to surface a problem.

For EF Core, after the steps above:

Aliased SELECT — EF Core emits SELECT o.id, o.name FROM offerings AS o. Confirm table aliases and alias-qualified columns are accepted.
Column order — EF Core reads by ordinal, so the reader must return columns in SELECT order. Query two columns in reverse order and check the values.
Add / SaveChanges / Find — round trip one entity with a Guid key.
Skip/Take, Count, Contains — LIMIT/OFFSET, COUNT(*), LIKE.
Include(), Any(), GroupBy() — JOIN, EXISTS, GROUP BY. Use these in application code only once they pass.
QuoteIdentifiers() — if quoted identifiers pass, turn the option on in both EF Core and the OrmLite dialect.

For DQL (section 22), after steps 1–6:

fetch t | limit 1 through a DQL command — confirms routing and translation.
filter name == "O'Brien" — confirms a quote in a DQL string survives.
fetch t, from: -1d against a table with a timestamp (or DqlTimestampField) column — confirms text comparison of the stored UTC format.
contains / startsWith with _ in the value — confirms LIKE … ESCAPE '\'.
summarize count(), by:{x} | filter count() > 1 | sort count() desc — needs GROUP BY and HAVING, the same dependency as step 11.

20. Migrating from PostgreSQL

One line changes:

// Before
new OrmLiteConnectionFactory(connectionString, PostgreSqlDialect.Provider);

// After
new OrmLiteConnectionFactory(connectionString, ElephantOrmLiteDialectProvider.Instance);

What else needs attention:

Concern	Action
`[Schema]` attributes	Ignored. Leave them or remove them.
`search_path` pinning	No equivalent. The table is the schema.
Unique indexes	Not enforced. Add application-level checks.
Foreign keys	Not enforced.
Transactions	Removed. Reorder writes or compensate.
`SchemaBootstrapper` / DDL migrations	Move to a Data Migration import.
Npgsql-specific code	`NpgsqlConnectionStringBuilder`, `set_config`, `DISCARD ALL` behaviour, trigger-based audit SQL all need replacing.
`[AutoIncrement]` keys	Switch to `Guid`.
`DateTimeOffset` columns	Offset is no longer preserved.

The schema itself can be imported through the management portal's Data Migration option, which reads an existing PostgreSQL or SQLite database directly.

21. Troubleshooting

InvalidOperationException: ConnectionStrings:… is not set — the environment variable did not bind. Check the key name and, in Kubernetes, that the secret exists in the right namespace.

ElephantException with TokenInvalid — the bearer token expired. Open validates credentials, so this surfaces at connection time.

ElephantException with CredentialsNotFound or NoTenantDatabaseFound — the account or the table does not exist. Provision it, or set AutoRegisterUser / AutoCreateLedger for a development environment. See section 4.

An empty table appeared — AutoCreateLedger was on and Database held a typo. Turn it off outside development.

NotSupportedException on db.Save() — OrmLite's upsert path reached for a transaction. Use explicit InsertAsync/UpdateAsync, or set AllowNonTransactional=true knowing it buys no atomicity.

InvalidCastException on a column that is sometimes null — the column was entirely null on the first page, so it typed as object. Check IsDBNull first, or order the query so a non-null value appears early.

A SELECT returns fewer rows than expected — MaxRecords bounds each page and the reader pages forward. If you are reading through something that does not walk the reader to the end, you see one page. Check reader.Pagination.TotalItems against what you received.

A paged query is making far more calls than expected — PageNumber was not set, so the reader walked every page. Set it, or use QueryPageAsync.

GetPagination() returns null — the command or reader did not come from this provider. That happens behind an abstraction that wraps or proxies the ADO.NET types.

Duplicate rows where a unique index exists — the index is not a constraint. See section 14.

A row written after ChangeDatabase cannot be read back — the read is running against a different database from the write. Check connection.Database and any command.DatabaseName on the reading command, and check that the connection was not re-created (a new connection starts on the Database keyword). See Choosing the database.

Values read back wrapped in quotes, NULL as text, or '' in place of ' — the rows were written through the client's InsertSQLRecordsAsync (directly, or by an older build of this provider), which stores SQL literals verbatim. Rows written by this provider are decoded; earlier rows need repairing.

DbUpdateException after some rows were saved — EF Core SaveChanges is not atomic on this provider; statements before the failing one stay applied. See SaveChanges semantics.

NotSupportedException naming a column on SaveChanges — the model expects a store-generated value (identity, default or computed). Use a Guid key, or ValueGeneratedNever() and assign the value.

NotSupportedException on Migrate() or EnsureDeleted() — EF Core migrations and database drops are not supported. Use EnsureCreated(); tables appear on first write.

EF Core and OrmLite see different data — they are writing to different tables. EF Core names tables after the DbSet property, OrmLite after the class. Set [Table("...")] on the entity.

NotSupportedException: A DQL query must start with fetch from OrmLite or EF Core — QueryLanguage=Dql is set on a connection they share, so their generated SQL is being read as DQL. Remove the keyword and set command.QueryLanguage per command instead.

NotSupportedException naming a DQL command or function — the provider does not translate it (section 22, What does not translate). Rewrite with the supported commands, or run SQL for that query.

DqlSyntaxException — the DQL is malformed. Position is the character offset; check quotes, commas between arguments, and | between commands.

InvalidOperationException: The DQL query uses $x — add a parameter named x to the command (or to the helper's parameters).

A DQL time window returns nothing — from:, to: and timeframe: filter the timestamp column. Set DqlTimestampField to the column the table actually uses.

'ElephantCommand' does not contain a definition for 'QueryLanguage' — the project references a build of ElephantSqlDb.Data from before DQL support. Reference the project, or update the package.

Three upstream client issues this package works around

Worth raising with whoever owns ElephantSqlDBClient.Core, since the workarounds should not be permanent:

InsertSQLRecordsAsync reads only InsertValuesRows[0] and discards the rest — a multi-row INSERT writes one row. The provider bypasses it and calls SaveToDatabaseWithNoResponse once per row.
InsertSQLRecordsAsync returns AuthStatus.Success unconditionally; the save result is never inspected and every exception is folded into SQLStatementInvalid. The provider inspects the boolean directly.
InsertSQLRecordsAsync stores SQL literals verbatim — 'abc' keeps its quotes, NULL is stored as the text NULL, and '' is not collapsed to '. The provider decodes each token (DecodeLiteral, the inverse of ElephantParameter.FormatLiteral) before saving. Code calling InsertSQLRecordsAsync directly is affected.

NewRecord in ElephantSqlDbExecutor also duplicates the client's private AddCommonInterfaceProperties. If a key is added there and missed here, the server accepts a record that is quietly incomplete — worth making that method internally visible, or pinning it with a test.

22. Dynatrace Query Language (DQL)

ElephantCommand can take its CommandText in the Dynatrace Query Language instead of SQL. The provider translates the DQL into one SQL SELECT, then binds, executes and pages it exactly as it does any SQL command. ElephantSqlDBClient.Core only ever receives SQL; it never sees DQL.

DQL is read-only. ExecuteReader and ExecuteScalar accept it; ExecuteNonQuery throws NotSupportedException.

How a DQL request flows

ElephantCommand sees QueryLanguage = Dql (its own setting, else the connection's QueryLanguage keyword).
ElephantDql.Translate parses the DQL and builds one SELECT. Every literal in the query becomes a generated parameter (@__dql0, @__dql1, …); every $name becomes an @name marker.
ElephantParameterBinder renders the generated parameters and the caller's parameters into the SQL text — the same binder, and the same escaping, as every other API (section 15).
ElephantSqlDbExecutor.QueryAsync sends the SQL to SelectSQLRecordsAsync<string>, and the reader pages it as usual.

command.TranslatedCommandText holds the SQL from step 2, with markers in place of values. Log it when a DQL query returns something unexpected.

Choosing the language

Level	How	Scope
Command	`command.QueryLanguage = ElephantQueryLanguage.Dql`	That command only
Connection	`QueryLanguage=Dql` in the connection string	Every command that does not set its own

ElephantQueryLanguage has two values: Sql (the default) and Dql. command.QueryLanguage is nullable; null falls back to the connection. An unrecognised keyword value (QueryLanguage=Kql) throws InvalidOperationException on Open.

Leave QueryLanguage=Sql on any connection shared with OrmLite or EF Core. Both generate SQL through CreateCommand, and a connection-wide Dql makes every one of those commands parse as DQL. Set the language per command, or give DQL consumers their own connection string:

{
  "ConnectionStrings": {
    "Portal":    "BaseUri=https://api.elephantsqldb.example/;Token=;UserEmail=;Database=portal_table",
    "PortalDql": "BaseUri=https://api.elephantsqldb.example/;Token=;UserEmail=;Database=portal_table;QueryLanguage=Dql;DqlTimestampField=created_at"
  }
}

A first request

await using var connection = new ElephantConnection(connectionString);
await connection.OpenAsync();

await using var command = connection.CreateCommand();
command.QueryLanguage = ElephantQueryLanguage.Dql;
command.CommandText = """
    fetch offerings
    | filter status == "Open" and target_amount >= 1000000
    | fields id, name, close_at
    | sort close_at desc
    | limit 25
    """;

await using var reader = await command.ExecuteReaderAsync();
while (await reader.ReadAsync())
{
    var id = reader.GetGuid(0);
    var name = reader.GetString(1);
    var closeAt = reader.IsDBNull(2) ? (DateTime?)null : reader.GetDateTime(2);
}

Sent to ElephantSqlDB:

SELECT id, name, close_at FROM offerings
WHERE status = 'Open' AND target_amount >= 1000000
ORDER BY close_at DESC LIMIT 25

A scalar works the same way:

command.CommandText = "fetch offerings | summarize count()";
var total = Convert.ToInt64(await command.ExecuteScalarAsync());

Commands

DQL	SQL
`fetch t`	`SELECT * FROM t`
`fetch t, from: -2h` · `to:` · `timeframe: "start/end"`	`WHERE timestamp >= … AND timestamp < …`
`filter cond` (before `summarize`)	`WHERE cond`
`filter cond` (after `summarize`)	`HAVING cond`
`filterOut cond`	`WHERE NOT (cond)`
`fields a, b = expr` · `fieldsKeep`	select list
`fieldsAdd x = expr`	`SELECT *, expr AS x`
`fieldsRemove a` · `fieldsRename new = old`	edit the select list; need an earlier `fields`
`sort a desc, b`	`ORDER BY a DESC, b ASC`
`limit n`	`LIMIT n`
`summarize agg, …, by:{k, k2 = expr}`	`GROUP BY`

Several filter stages are joined with AND. A later sort replaces an earlier one; two limits keep the smaller. // and /* */ comments are allowed, strings use double quotes, and dotted or backticked names (log.level, `my field`) are sent double-quoted.

Filtering

DQL	SQL
`filter status == "Open" and tier > 2`	`WHERE status = 'Open' AND tier > 2`
`filter (status == "Open" or status == "Draft") and target_amount > 0`	`WHERE (status = 'Open' OR status = 'Draft') AND target_amount > 0`
`filterOut status == "Closed"`	`WHERE NOT (status = 'Closed')`
`filter close_at == null`	`WHERE close_at IS NULL`
`filter isNotNull(name)`	`WHERE name IS NOT NULL`
`filter in(status, {"Open", "Draft"})`	`WHERE status IN ('Open', 'Draft')`
`filter contains(name, "Series")`	`WHERE name LIKE '%Series%'`
`filter contains(name, "series", caseSensitive: false)`	`WHERE LOWER(name) LIKE '%series%'`
`filter startsWith(slug, "seed_")`	`WHERE slug LIKE 'seed\_%' ESCAPE '\'`
`filter matchesValue(host, "WEB-*")`	`WHERE LOWER(host) LIKE 'web-%'`
`filter matchesPhrase(content, "timeout")`	`WHERE LOWER(content) LIKE '%timeout%'`

Operators: == != < <= > >= and or xor not + - * / %.

Other functions, usable in filters and fields: isNull, isTrue, isFalse, lower, upper, stringLength (LENGTH), concat (||), abs, ceil, floor, round(x, decimals: n), coalesce.

Time windows

Time expressions are evaluated in .NET and sent as one UTC timestamp parameter each. With now() = 2026-10-18 12:00 UTC:

DQL	SQL
`fetch logs, from: -2h`	`WHERE timestamp >= '2026-10-18 10:00:00.0000000'`
`fetch logs, from: now() - 1d, to: now()`	`WHERE timestamp >= '2026-10-17 12:00:00.0000000' AND timestamp < '2026-10-18 12:00:00.0000000'`
`fetch logs, timeframe: "2026-10-01T00:00:00-05:00/2026-10-02T00:00:00Z"`	`WHERE timestamp >= '2026-10-01 05:00:00.0000000' AND timestamp < '2026-10-02 00:00:00.0000000'`
`filter close_at > now() - 30m`	`WHERE close_at > '2026-10-18 11:30:00.0000000'`
`filter created_at >= toTimestamp("2026-10-01T00:00:00Z")`	`WHERE created_at >= '2026-10-01 00:00:00.0000000'`

Duration units: ns, us, ms, s, m, h, d, w. now() is read once per query, so every now() in one query is the same instant.

from:, to: and timeframe: filter the timestamp column. Set DqlTimestampField in the connection string when a table uses another name, such as created_at.

Timestamps are compared as text. That works because the provider stores DateTime and DateTimeOffset as fixed-width UTC yyyy-MM-dd HH:mm:ss.fffffff (section 12), which sorts the same lexically as chronologically. A duration on its own (filter amount > 5m) throws: durations only offset timestamps.

Fields

DQL	SQL
`fields id, name, close_at`	`SELECT id, name, close_at`
`fields id, title = name, doubled = target_amount * 2`	`SELECT id, name AS title, (target_amount * 2) AS doubled`
`fieldsAdd name_upper = upper(name)`	`SELECT *, UPPER(name) AS name_upper`
`fields id, name, status \\| fieldsRemove status`	`SELECT id, name`
`fields id, name \\| fieldsRename title = name`	`SELECT id, name AS title`

A computed field can be used by later stages; its expression is substituted:

fetch offerings | fieldsAdd k = target_amount / 1000 | filter k > 5

SELECT *, (target_amount / 1000) AS k FROM offerings WHERE (target_amount / 1000) > 5

Computed fields must be named (fieldsAdd x = expr). fieldsRemove and fieldsRename need an earlier fields, because the column list is not known after a bare fetch.

Aggregating with summarize

fetch offerings
| filter target_amount > 0
| summarize c = count(), total = sum(target_amount), by:{status}
| filter c > 2
| sort c desc
| limit 5

SELECT status, COUNT(*) AS c, SUM(target_amount) AS total FROM offerings
WHERE target_amount > 0 GROUP BY status
HAVING COUNT(*) > 2 ORDER BY c DESC LIMIT 5

Aggregation	SQL	Name when not aliased
`count()`	`COUNT(*)`	`count`
`countIf(status == "Open")`	`SUM(CASE WHEN status = 'Open' THEN 1 ELSE 0 END)`	`countIf`
`countDistinct(investor)`	`COUNT(DISTINCT investor)`	`countDistinct_investor`
`sum(amount)` · `avg` · `min` · `max`	`SUM(amount)` · `AVG` · `MIN` · `MAX`	`sum_amount` · `avg_amount` · …

An unaliased aggregation can still be referred to in its DQL form: summarize count(), by:{status} | sort count() desc sorts on count. Group keys may be computed when named: by:{s = lower(status)}. fields after summarize can select or rename its outputs. GROUP BY and HAVING support on the engine is checked by Verification step 17.

Paging and the helpers

Paging, TotalItems and PageNumber behave exactly as for SQL (section 8). Three helpers set the language for you:

// One page plus the total match count
var page = await connection.QueryDqlPageAsync(
    "fetch offerings | filter status == $status | sort name",
    r => new { Id = r.GetGuid(r.GetOrdinal("id")), Name = r.GetString(r.GetOrdinal("name")) },
    pageNumber: 2,
    parameters: [new ElephantParameter("status", "Open")]);

page.Rows;        // this page
page.TotalItems;  // every match
page.HasMore;

// Count without materialising rows
var open = await connection.CountDqlAsync("fetch offerings | filter status == \"Open\"");

// Stream every page
await foreach (var name in connection.QueryDqlAsync(
    "fetch offerings | fields name | limit 500", r => r.GetString(0), cancellationToken: ct))
{
    // …
}

Put limit last. A filter, sort, summarize or fieldsAdd after it would need a subquery, so it throws.

Parameters

$name refers to a command parameter called name:

command.QueryLanguage = ElephantQueryLanguage.Dql;
command.CommandText = "fetch offerings | filter status == $status and target_amount >= $min";
command.Parameters.Add(new ElephantParameter("status", "Open"));
command.Parameters.Add(new ElephantParameter("min", 1_000_000m));

A $name with no matching parameter throws InvalidOperationException before anything is sent.

Literals written into the DQL are just as safe: each becomes a generated parameter, so filter name == "O'Brien" is sent as WHERE name = 'O''Brien'. Identifiers are never parameters, so they are validated instead — a plain name passes through unquoted, and anything else is double-quoted with embedded quotes doubled. As with SQL, never concatenate user input into the query text; use $name for values.

Seeing the SQL, and using Dapper or OrmLite

ElephantDql.Translate returns the SQL without running it:

using ElephantSqlDb.Data.Dql;

DqlTranslation t = ElephantDql.Translate(
    "fetch offerings | filter status == \"Open\" | summarize count(), by:{tier}");

// t.Sql:                  SELECT tier, COUNT(*) AS count FROM offerings WHERE status = @__dql0 GROUP BY tier
// t.Parameters:           [ @__dql0 = "Open" ]
// t.ReferencedParameters: names of any $parameters the query used

Dapper decides which parameters to send by looking for @name markers, and a DQL $name has none — so translate first and pass the result:

var t = ElephantDql.Translate("fetch offerings | filter status == \"Open\" | limit 50");

var args = new DynamicParameters();
foreach (var p in t.Parameters) args.Add(p.ParameterName, p.Value);

var open = await connection.QueryAsync<Offering>(t.Sql, args);

OrmLite takes the same SQL:

var rows = await db.SelectAsync<Offering>(
    t.Sql, t.Parameters.ToDictionary(p => p.ParameterName, p => p.Value));

DqlOptions controls a direct translation: TimestampField, a UtcNow clock (fix it in tests), and the generated ParameterPrefix.

What does not translate

These throw NotSupportedException naming what is missing, rather than returning rows that differ from what the DQL asked for:

Other commands — lookup, join, timeseries, makeTimeseries, parse, dedup, expand, append, data and the rest.
A query that does not start with fetch.
Stage orders that need a subquery — anything but limit or a field selection after limit; a second summarize; fieldsAdd after summarize.
Unknown functions, and aggregations outside summarize.

Malformed DQL throws DqlSyntaxException (a FormatException) whose Position is the character offset of the problem.

try
{
    await using var reader = await command.ExecuteReaderAsync(ct);
    // …
}
catch (DqlSyntaxException ex)
{
    logger.LogWarning("Bad DQL at {Position}: {Message}", ex.Position, ex.Message);
}
catch (NotSupportedException ex)
{
    logger.LogWarning("DQL not supported: {Message}", ex.Message);
}

Semantics that differ from Grail

filterOut becomes NOT (cond), which drops rows where cond is null. DQL keeps them.
matchesPhrase matches any substring, not whole tokens.
contains, startsWith and endsWith are case-sensitive unless caseSensitive: false is passed.
There is no implicit record limit and no default timestamp sort; results are what the query asks for.

Files

File	Role
`Dql/DqlLexer.cs`	Tokens, comments, durations; `DqlSyntaxException`
`Dql/DqlParser.cs`	AST and recursive-descent parser
`Dql/DqlToSqlTranslator.cs`	`ElephantDql`, `DqlOptions`, `DqlTranslation` and the translator
`ElephantQueryLanguage.cs`	`Sql` / `Dql`

23. Logging with Serilog and log4net

The package can write application logs into an ElephantSqlDB table. The ElephantSqlDb.Data.Logging namespaces add a Serilog sink, a log4net appender and a Microsoft.Extensions.Logging provider. All three run on the ADO.NET types in this guide: every log row is an INSERT issued through ElephantConnection and ElephantCommand, with values bound by ElephantParameterBinder. Reading the logs back is ordinary ADO.NET or DQL.

 Serilog ──────────┐
 log4net ──────────┼──▶ ElephantLogWriter ──▶ ElephantConnection / ElephantCommand
 MEL ILogger ──────┘    (batches, lanes,        (INSERT INTO logs ...)
                         retry)                         │
                                                        ▼
                                               ElephantSqlDB table

Packages

The logging support ships in ElephantSqlDb.Data. It brings three dependencies:

Package	Version	Used by
`Serilog`	4.2.0	`ElephantSqlDbSink`
`log4net`	3.5.0	`ElephantSqlDbAppender`
`Microsoft.Extensions.Logging`	10.0.0	`ElephantSqlDbLoggerProvider`

Use log4net 3.3.0 or later. Earlier 3.x releases are flagged with a moderate-severity vulnerability (CVE-2026-40021).

The log table

The engine creates the table on the first write, so there is no DDL. The default name is logs. Column names follow Dynatrace's log fields, so DQL over the table reads the way Dynatrace users expect (section 22).

Column	Type on the wire	Contents
`log_id`	string	32 hex characters, unique per event
`timestamp`	`yyyy-MM-dd HH:mm:ss.fffffff` UTC	When the event was logged
`loglevel`	string	Level name from the framework (`Information`, `WARN`, ...)
`logger`	string	Serilog `SourceContext`, log4net logger name or MEL category
`content`	string	Rendered message
`message_template`	string	Unrendered template (Serilog and MEL)
`exception`	string	`Exception.ToString()`
`attributes`	JSON string	Structured properties, scopes and context
`trace_id`, `span_id`	string	W3C ids from `Activity.Current`
`service_name`, `host_name`	string	Set once per writer

timestamp is stored in the same fixed-width UTC format as every other DateTime (section 12), so DQL time windows work on it with no extra setting.

How log writes behave

The engine writes each INSERT row as its own HTTP call and has no rollback (sections 13 and 16). The writer is built around both facts:

Off the application thread. Serilog's batching queue, or the bounded ElephantLogQueue used by log4net and MEL, holds events; a background task writes them. A log call never waits on the network.
Single-row inserts in parallel. A multi-row INSERT is no faster here and can fail partway. Rows go out as single-row statements across MaxConcurrency lanes (default 8), and each lane keeps one open connection, because OpenAsync costs an authentication round trip.
Retries never duplicate. Each row succeeds or fails on its own, and only failed rows are retried, with backoff, for up to RetryTimeLimit (default 5 minutes).
No transactions. None are opened, so AllowNonTransactional is not needed.
Writes are SQL. A connection string with QueryLanguage=Dql still works; the writer sets QueryLanguage = Sql on its own commands.
Bounded memory. A full queue (default 100,000 events) drops new events and counts them rather than blocking.
A hook for zero loss. Rows that still fail, or that remain at shutdown, go to OnWriteFailure.

Serilog

Register the sink with WriteTo.ElephantSqlDb. The extension lives in the Serilog namespace, so no extra using is needed.

using ElephantSqlDb.Data;
using Serilog;

var connectionString = builder.Configuration.GetConnectionString("Logs")
    ?? throw new InvalidOperationException("ConnectionStrings:Logs is not set.");

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Information()
    .Enrich.FromLogContext()
    .WriteTo.Console()
    .WriteTo.ElephantSqlDb(
        connectionString,
        tableName: "logs",
        serviceName: "FlightOps.Api",
        batchSizeLimit: 200,
        period: TimeSpan.FromSeconds(2))
    .CreateLogger();

try
{
    Log.ForContext("SourceContext", "FlightOps.Gates")
       .Information("Gate change for {Flight} to {Gate}", "UA1234", "C17");

    Log.Warning("Crew check-in delayed {Minutes} min for {Flight}", 12, "UA1234");
}
catch (Exception ex)
{
    Log.Error(ex, "Gate update failed");
}
finally
{
    await Log.CloseAndFlushAsync();   // drains the queue before exit
}

The first call writes one row:

Column	Value
`loglevel`	`Information`
`logger`	`FlightOps.Gates`
`content`	`Gate change for "UA1234" to "C17"`
`message_template`	`Gate change for {Flight} to {Gate}`
`attributes`	`{"Flight":"UA1234","Gate":"C17","SourceContext":"FlightOps.Gates"}`
`service_name`	`FlightOps.Api`

In ASP.NET Core, configure it through the host:

builder.Host.UseSerilog((context, configuration) => configuration
    .ReadFrom.Configuration(context.Configuration)
    .WriteTo.ElephantSqlDb(
        context.Configuration.GetConnectionString("Logs")!,
        serviceName: "FlightOps.Api"));

For full control, pass writer options and Serilog batching options:

using ElephantSqlDb.Data.Logging;
using Serilog.Configuration;

var writerOptions = new ElephantLogWriterOptions
{
    ConnectionString = connectionString,
    TableName = "flight_logs",
    DatabaseName = "observability",          // overrides the Database keyword
    ServiceName = "FlightOps.Api",
    MaxConcurrency = 16,
    RetryTimeLimit = TimeSpan.FromMinutes(10),
    OnWriteFailure = (records, error) => LocalSpool.Append(records)
};

Log.Logger = new LoggerConfiguration()
    .WriteTo.ElephantSqlDb(writerOptions, new BatchingOptions
    {
        BatchSizeLimit = 500,
        BufferingTimeLimit = TimeSpan.FromSeconds(1),
        QueueLimit = 200_000
    })
    .CreateLogger();

log4net

Use ElephantSqlDbAppender. Configure it in XML:

<log4net>
  <appender name="ElephantSqlDb"
            type="ElephantSqlDb.Data.Logging.Log4NetAppender.ElephantSqlDbAppender, ElephantSqlDb.Data">
    <connectionString value="BaseUri=https://api.elephantsqldb.example/;Token=...;UserEmail=svc@example.com;Database=portal_table" />
    <tableName value="logs" />
    <serviceName value="FlightOps.Worker" />
    <maxConcurrency value="8" />
    <batchSize value="200" />
    <flushIntervalMilliseconds value="2000" />
    <queueCapacity value="100000" />
    <retryTimeLimitSeconds value="300" />
    <shutdownTimeoutSeconds value="15" />
  </appender>

  <root>
    <level value="INFO" />
    <appender-ref ref="ElephantSqlDb" />
  </root>
</log4net>

Then log as usual:

using log4net;
using log4net.Config;

XmlConfigurator.Configure(new FileInfo("log4net.config"));
var log = LogManager.GetLogger("FlightOps.Baggage");

ThreadContext.Properties["RequestId"] = requestId;   // stored in attributes
log.Info("Baggage feed connected");
log.Error("Baggage feed failed", new TimeoutException("feed timeout"));

LogManager.Shutdown();   // closes the appender, which drains its queue

Or configure it in code, which keeps the token out of the XML:

using ElephantSqlDb.Data.Logging.Log4NetAppender;
using log4net;
using log4net.Config;

var repository = LogManager.GetRepository(typeof(Program).Assembly);

var appender = new ElephantSqlDbAppender
{
    ConnectionString = builder.Configuration.GetConnectionString("Logs")!,
    TableName = "logs",
    ServiceName = "FlightOps.Worker"
};
appender.ActivateOptions();

BasicConfigurator.Configure(repository, appender);

Use this appender rather than log4net's AdoNetAppender. AdoNetAppender writes synchronously on the logging thread when its buffer fills. It also opens a transaction by default, which this provider refuses unless AllowNonTransactional=true (section 13). log4net loads the appender by its type name, so ElephantSqlDb.Data.Logging.* must be excluded from renaming in the obfuscated build.

Microsoft.Extensions.Logging

builder.Logging.AddElephantSqlDb(options =>
{
    options.ConnectionString = builder.Configuration.GetConnectionString("Logs")!;
    options.TableName = "logs";
    options.ServiceName = "FlightOps.Api";
});

Filter levels with the provider alias:

{
  "Logging": {
    "ElephantSqlDb": { "LogLevel": { "Default": "Information" } }
  }
}

Scope values (logger.BeginScope(...)), EventId and EventName are stored in attributes.

Writing log rows directly with ADO.NET

ElephantLogWriter is the shared write path. Use it directly to load log files, replay a spool, or write from a tool that has no logging framework:

using ElephantSqlDb.Data.Logging;

await using var writer = new ElephantLogWriter(new ElephantLogWriterOptions
{
    ConnectionString = connectionString,
    TableName = "logs",
    ServiceName = "FlightOps.Importer"
});

var records = File.ReadLines("gate-events.log")
    .Select(line => new ElephantLogRecord
    {
        LogLevel = "Information",
        Logger = "GateImport",
        Content = line
    })
    .ToList();

var result = await writer.WriteAsync(records);

if (!result.Succeeded)
    Console.WriteLine($"{result.Unwritten.Count} rows not written: {result.LastError?.Message}");

WriteAsync does not throw for database failures. Written counts the rows that landed; Unwritten holds the rows that did not, and none of those reached the table.

Each row the writer sends is the same statement you would write by hand:

await using var connection = new ElephantConnection(connectionString);
await connection.OpenAsync();

await using var command = connection.CreateCommand();
command.CommandText =
    "INSERT INTO logs (log_id, timestamp, loglevel, logger, content, service_name, host_name) " +
    "VALUES (@log_id, @timestamp, @loglevel, @logger, @content, @service_name, @host_name)";
command.Parameters.Add(new ElephantParameter("log_id", Guid.NewGuid().ToString("N")));
command.Parameters.Add(new ElephantParameter("timestamp", DateTime.UtcNow));
command.Parameters.Add(new ElephantParameter("loglevel", "Warning"));
command.Parameters.Add(new ElephantParameter("logger", "FlightOps.Gates"));
command.Parameters.Add(new ElephantParameter("content", "Gate C17 sensor offline"));
command.Parameters.Add(new ElephantParameter("service_name", "FlightOps.Api"));
command.Parameters.Add(new ElephantParameter("host_name", Environment.MachineName));
await command.ExecuteNonQueryAsync();

Reading logs back with ADO.NET

Logs are rows, so every read in this guide applies. Bound queries with a time window and LIMIT, and set PageNumber for one page (section 8).

await using var connection = new ElephantConnection(connectionString);
await connection.OpenAsync();

await using var command = connection.CreateCommand();
command.CommandText =
    "SELECT timestamp, loglevel, logger, content, exception FROM logs " +
    "WHERE service_name = @service AND loglevel IN ('Error', 'ERROR', 'Fatal', 'FATAL') " +
    "AND timestamp >= @since ORDER BY timestamp DESC LIMIT 100";
command.Parameters.Add(new ElephantParameter("service", "FlightOps.Api"));
command.Parameters.Add(new ElephantParameter("since", DateTime.UtcNow.AddHours(-1)));

await using var reader = await command.ExecuteReaderAsync();
while (await reader.ReadAsync())
{
    var at = reader.GetDateTime(0);
    var level = reader.GetString(1);
    var logger = reader.IsDBNull(2) ? null : reader.GetString(2);
    var content = reader.GetString(3);
    var exception = reader.IsDBNull(4) ? null : reader.GetString(4);
}

Counting errors costs one round trip, because TotalItems comes back with the first page:

var errors = await connection.CountAsync(
    "SELECT log_id FROM logs WHERE loglevel = @level AND service_name = @service",
    [new ElephantParameter("level", "Error"), new ElephantParameter("service", "FlightOps.Api")]);

Querying logs with DQL

The column names match Dynatrace, so familiar DQL works against the table:

await using var command = connection.CreateCommand();
command.QueryLanguage = ElephantQueryLanguage.Dql;
command.CommandText = """
    fetch logs, from: -2h
    | filter loglevel == "Error" and service_name == $service
    | fields timestamp, logger, content
    | sort timestamp desc
    | limit 50
    """;
command.Parameters.Add(new ElephantParameter("service", "FlightOps.Api"));

await using var reader = await command.ExecuteReaderAsync();

Errors per service in the last day:

command.CommandText = """
    fetch logs, from: -1d
    | filter loglevel == "Error"
    | summarize errors = count(), by:{service_name}
    | sort errors desc
    """;

from: -2h filters the timestamp column, which is the default DqlTimestampField, so no connection setting is needed.

Dashboards and alerts on logs

The log table can be charted and alerted on directly from ElephantSqlDB dashboards, beside the application data on the same platform. There is no separate dashboard tool or alerting service to set up.

Dashboards. Any SQL or DQL query over the log table can back a dashboard panel. Useful starting panels:

fetch logs, from: -1h
| filter loglevel == "Error"
| summarize errors = count(), by:{service_name}
| sort errors desc

fetch logs, from: -1d
| summarize events = count(), by:{loglevel}

Alerts. Alerts are raised from user-defined events on a dashboard. An event is defined over a log query and fires when its result meets the condition you set, for example more than 25 errors for one service in the last 15 minutes:

fetch logs, from: -15m
| filter loglevel == "Error" and service_name == "FlightOps.Api"
| summarize errors = count()

Other events worth defining: any Fatal row, a specific exception type appearing in the exception column, or a service that stops writing rows altogether, which usually means the application or its logging is down.

Because each row carries trace_id, an alert on an error row leads straight to the trace and to every other log row for the same request, all through constant-time key lookups.

Writer options

Option	Default	Notes
`ConnectionString`	—	Required. A normal `ElephantConnection` string
`TableName`	`logs`	Letters, digits and `_` only; the one value placed in the SQL text
`DatabaseName`	null	Overrides the `Database` keyword for log writes
`ServiceName`	null	Stored as `service_name`
`HostName`	machine name	Stored as `host_name`
`MaxConcurrency`	8	Parallel lanes; one open connection each
`RetryTimeLimit`	5 minutes	Zero means one attempt
`RetryBaseDelay` / `MaxRetryDelay`	500 ms / 30 s	Exponential backoff with jitter
`MaxFieldLength`	32,000	Truncates `content`, `exception`, `attributes`; 0 = no limit
`CommandTimeoutSeconds`	0	0 uses the connection's `CommandTimeout`
`OnWriteFailure`	Trace	Receives rows that were not written

ElephantLogQueueOptions (log4net and MEL) adds BatchSize (200), FlushInterval (2 s), Capacity (100,000) and ShutdownTimeout (15 s). Serilog uses its own BatchingOptions.

Zero-loss logging

Hook OnWriteFailure to spool rows to local disk, then replay them with the writer when the ledger is back:

var spool = Path.Combine(AppContext.BaseDirectory, "log-spool.jsonl");

var options = new ElephantLogWriterOptions
{
    ConnectionString = connectionString,
    ServiceName = "FlightOps.Api",
    OnWriteFailure = (records, _) =>
    {
        lock (spoolLock)
            File.AppendAllLines(spool, records.Select(r => JsonSerializer.Serialize(r)));
    }
};

// Later, on startup or a timer:
if (File.Exists(spool))
{
    var pending = File.ReadLines(spool)
        .Select(line => JsonSerializer.Deserialize<ElephantLogRecord>(line)!)
        .ToList();

    await using var writer = new ElephantLogWriter(new ElephantLogWriterOptions
    {
        ConnectionString = connectionString,
        ServiceName = "FlightOps.Api"
    });
    var result = await writer.WriteAsync(pending);
    if (result.Succeeded) File.Delete(spool);
}

Each record keeps its log_id, so a replayed row can be checked against rows already in the table.

Testing logging

The writer takes a connection factory, so it runs against a fake executor (section 18):

var fake = new FakeElephantExecutor();
var writer = new ElephantLogWriter(
    new ElephantLogWriterOptions { ConnectionString = connectionString },
    () => new ElephantConnection(connectionString, _ => fake));

await writer.WriteAsync([new ElephantLogRecord { Content = "O'Brien" }]);

Assert.Contains("'O''Brien'", fake.Statements[0]);

The test project's Logging/ folder covers the writer, the queue and all three frameworks offline (Category=Unit), and checks that rows land exactly once against a live ledger (Category=Live).

Files

File	Role
`Logging/Core/ElephantLogRecord.cs`	One log entry in framework-neutral form
`Logging/Core/ElephantLogWriter.cs`	Parallel single-row writes, retry, connection reuse
`Logging/Core/ElephantLogWriterOptions.cs`	Writer options and the failure hook
`Logging/Core/ElephantLogQueue.cs`	Bounded queue and background pump
`Logging/Core/ElephantLogJson.cs`	Properties to JSON
`Logging/Serilog/`	`ElephantSqlDbSink`, `WriteTo.ElephantSqlDb`
`Logging/Log4Net/`	`ElephantSqlDbAppender`
`Logging/MicrosoftExtensions/`	`ElephantSqlDbLoggerProvider`, `AddElephantSqlDb`

Troubleshooting logging

No rows appear — the queue flushes every FlushInterval or period, and on shutdown. Call Log.CloseAndFlushAsync() or LogManager.Shutdown() before exit. Check System.Diagnostics.Trace (or Serilog SelfLog) for write failures.

NotSupportedException from log4net's AdoNetAppender — it opened a transaction. Use ElephantSqlDbAppender.

log4net cannot load the appender type — the obfuscated build renamed ElephantSqlDb.Data.Logging.*. Exclude those types from renaming.

Events dropped — the queue filled while the ledger was unreachable. Raise Capacity or QueueLimit, or hook OnWriteFailure.

ArgumentException on the table name — TableName must be a plain identifier (letters, digits, _, not starting with a digit).

24. Telemetry with OpenTelemetry

The package includes OpenTelemetry exporters that write traces and metrics to ElephantSqlDB tables through the same ADO.NET provider. Together with logging (section 23), an application's three telemetry signals land on one platform, joined by trace_id, and can be charted in ElephantSqlDB dashboards or queried with SQL and DQL.

 OpenTelemetry SDK                              ElephantSqlDB platform
 ─────────────────                              ──────────────────────
 Traces  ─▶ ElephantSqlDbTraceExporter  ─┐
 Metrics ─▶ ElephantSqlDbMetricExporter ─┼─▶ ElephantConnection ─▶ spans · metrics
 Logs    ─▶ Serilog / log4net / MEL     ─┘   (INSERT per row)       logs

Why OpenTelemetry

OpenTelemetry is the .NET standard for telemetry. Exporting from it, rather than adding a new API, means:

One line to adopt. AddElephantSqlDbExporter(...) goes next to the instrumentation the application already registers.
Automatic instrumentation. The standard instrumentation packages produce spans and metrics for incoming HTTP requests, HttpClient calls, database calls and the .NET runtime with no code in the application.
No lock-in. The same application can export to ElephantSqlDB and to any other OpenTelemetry backend at the same time.

Agentless by design

Many observability platforms collect telemetry through an agent: a sidecar in every pod, a node-level agent in every cluster, or a process injected into the application. ElephantSqlDB does not need one. The exporters run inside the application, in the OpenTelemetry SDK it already uses, and write straight to the platform. That means:

Nothing extra to deploy. No sidecar, DaemonSet or container to size, secure, patch and monitor, and nothing competing for container resources that are already allocated.
Less operational debt. One package reference and one line of configuration, versioned and deployed with the application itself.
No agent lock-in. Instrumentation is standard OpenTelemetry; the same application can export to ElephantSqlDB and any other OpenTelemetry backend.
The advantage is in the platform. Collection stays light because the work that matters, storage and retrieval, is where ElephantSqlDB is strong: constant-time lookup of any trace, span or log row by key, however much telemetry is kept.

What it costs, so it can be planned for:

In-process is light, not free. The exporters use some application memory for buffered spans and metrics, background threads, and up to MaxConcurrency open connections. The SDK's queue limits (MaxQueueSize) bound the memory.
Instrumentation is per application. An agent can instrument a process with no code changes; here each application adds the exporter to its configuration. Coverage today is .NET.
A central collector is optional, not required. Organisations that route telemetry through an OpenTelemetry Collector for central buffering, filtering or routing can keep doing so; this package does not need one.

Packages

The exporters ship in ElephantSqlDb.Data, which now depends on OpenTelemetry 1.17.0 (and Microsoft.Extensions.Logging 10.0.0, which that version requires). The application adds the hosting and instrumentation packages it wants:

Package	Provides
`OpenTelemetry.Extensions.Hosting`	`services.AddOpenTelemetry()`
`OpenTelemetry.Instrumentation.AspNetCore`	Spans and metrics for incoming requests
`OpenTelemetry.Instrumentation.Http`	Spans and metrics for `HttpClient` calls
`OpenTelemetry.Instrumentation.Runtime`	GC, thread pool and memory metrics

Setup in ASP.NET Core

using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

var telemetry = builder.Configuration.GetConnectionString("Telemetry")
    ?? throw new InvalidOperationException("ConnectionStrings:Telemetry is not set.");

builder.Services.AddOpenTelemetry()
    .ConfigureResource(r => r.AddService("FlightOps.Api"))
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddSource("FlightOps.*")                 // your own ActivitySources
        .AddElephantSqlDbExporter(telemetry))
    .WithMetrics(metrics => metrics
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddRuntimeInstrumentation()
        .AddMeter("FlightOps.*")                  // your own Meters
        .AddElephantSqlDbExporter(telemetry));

"Telemetry" is an ElephantSqlDB connection string in appsettings.json, the same format as every other connection string in this guide (section 4). The service.name from ConfigureResource is stored as service_name on every row.

Setup without hosting

A console app, worker or test creates the providers directly and disposes them on exit, which flushes anything buffered:

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("FlightOps.Importer"))
    .AddSource("FlightOps.Importer")
    .AddElephantSqlDbExporter(telemetry)
    .Build();

using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .AddMeter("FlightOps.Importer")
    .AddElephantSqlDbExporter(telemetry)
    .Build();

Instrumenting your own code

Spans come from ActivitySource, metrics from Meter. Both are part of .NET:

using System.Diagnostics;
using System.Diagnostics.Metrics;

public sealed class GateService(ILogger<GateService> logger)
{
    private static readonly ActivitySource Source = new("FlightOps.Gates");
    private static readonly Meter Meter = new("FlightOps.Gates");
    private static readonly Counter<long> GateChanges = Meter.CreateCounter<long>("gate.changes");
    private static readonly Histogram<double> LookupMs = Meter.CreateHistogram<double>("gate.lookup.ms", unit: "ms");

    public async Task MoveAsync(string flight, string gate)
    {
        using var activity = Source.StartActivity("move gate");
        activity?.SetTag("flight", flight);
        activity?.SetTag("gate", gate);

        var started = Stopwatch.GetTimestamp();
        try
        {
            await UpdateGateAsync(flight, gate);
            GateChanges.Add(1, new KeyValuePair<string, object?>("terminal", gate[..1]));
            logger.LogInformation("Gate change for {Flight} to {Gate}", flight, gate);
        }
        catch (Exception ex)
        {
            activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
            logger.LogError(ex, "Gate change failed for {Flight}", flight);
            throw;
        }
        finally
        {
            LookupMs.Record(Stopwatch.GetElapsedTime(started).TotalMilliseconds);
        }
    }
}

The span, the metric points and the log rows from this call all carry the same trace_id where a trace is active.

The spans table

One row per span. timestamp is the span's start, so DQL time windows work on it with no extra setting.

Column	Contents
`span_id`, `trace_id`, `parent_span_id`	W3C ids; `parent_span_id` is null for a root span
`name`, `kind`, `source`	Display name, `Server`/`Client`/`Internal`/..., `ActivitySource` name
`timestamp`, `end_time`	Start and end, UTC, in the section 12 format
`duration_ms`	Duration in milliseconds
`status`, `status_description`	`Unset`, `Ok` or `Error`, and the error text
`attributes`	Span tags as JSON
`events`, `links`	JSON arrays; exceptions recorded on a span appear as events
`service_name`, `host_name`	From the resource (or `ServiceName`) and the machine

The metrics table

The SDK aggregates measurements in memory and exports once per interval (60 seconds by default), one row per series: a metric name plus one combination of attribute values. Ten thousand Add calls on one counter with one attribute set become one row per minute.

Column	Contents
`metric_id`	Unique per row
`timestamp`, `start_time`	End and start of the interval, UTC
`name`, `description`, `unit`, `meter`	From the instrument
`type`	`LongSum`, `DoubleSum`, `LongGauge`, `DoubleGauge`, `Histogram`, ...
`temporality`	`Cumulative` (running total, the default) or `Delta` (change in the interval)
`value`	Counters, up-down counters and gauges
`count`, `sum`, `min`, `max`	Histograms
`buckets`	Histogram buckets as JSON: `[{"le":5.0,"count":1}, ..., {"le":"+Inf","count":0}]`
`attributes`	The series' attributes as JSON
`service_name`, `host_name`	As for spans

Set MetricTemporality = MetricReaderTemporalityPreference.Delta when the rows will be charted directly: each row is then the change in its interval, so a chart is a plain SUM by time rather than a difference between running totals.

How exports behave

Exports run on the OpenTelemetry SDK's own background threads, never on the application's. Spans are buffered by the SDK's batch processor (2,048 by default, exported every 5 seconds in batches of up to 512); metrics are collected once per interval. Each export uses the same write strategy as logging (section 23): single-row INSERTs across MaxConcurrency parallel lanes, each with one open connection; only failed rows are retried, so a retry never duplicates a row; no transactions are opened.

If the ledger is unreachable, an export retries for up to RetryTimeLimit (30 seconds by default, since it holds the SDK's export thread), then reports the unwritten rows to OnWriteFailure and returns Failure to the SDK. The application is never affected.

Volume: metrics are aggregated, so their row count depends on the number of series, not the request rate. Spans are one row each; for busy services, sample them:

.WithTracing(t => t
    .SetSampler(new ParentBasedSampler(new TraceIdRatioBasedSampler(0.10)))   // keep 10% of traces
    .AddAspNetCoreInstrumentation()
    .AddElephantSqlDbExporter(telemetry))

Options

AddElephantSqlDbExporter(connectionString, serviceName) covers most cases. For everything else, pass a configure action:

.AddElephantSqlDbExporter(o =>
{
    o.ConnectionString = telemetry;
    o.DatabaseName = "observability";
    o.SpansTable = "flight_spans";
    o.ScheduledDelayMilliseconds = 2000;
    o.OnWriteFailure = (table, count, error) =>
        Console.Error.WriteLine($"{count} rows not written to {table}: {error?.Message}");
})

Option	Default	Notes
`ConnectionString`	—	Required
`DatabaseName`	null	Overrides the `Database` keyword
`SpansTable` / `MetricsTable`	`spans` / `metrics`	Letters, digits and `_` only
`ServiceName`	resource `service.name`	Stored as `service_name`
`HostName`	machine name	Stored as `host_name`
`MaxConcurrency`	8	Parallel write lanes
`RetryTimeLimit`	30 s	Per export
`MaxFieldLength`	32,000	Truncates long text and JSON fields
`MaxQueueSize`	2,048	Spans buffered before new ones are dropped
`ScheduledDelayMilliseconds`	5,000	Span export interval
`MaxExportBatchSize`	512	Spans per export
`MetricExportIntervalMilliseconds`	60,000	Metric export interval
`MetricTemporality`	`Cumulative`	Or `Delta`
`OnWriteFailure`	Trace	`(table, count, error)` for rows not written

Querying telemetry with ADO.NET

The slowest requests in the last hour:

await using var command = connection.CreateCommand();
command.CommandText =
    "SELECT trace_id, name, duration_ms, status FROM spans " +
    "WHERE service_name = @service AND kind = 'Server' AND timestamp >= @since " +
    "ORDER BY duration_ms DESC LIMIT 20";
command.Parameters.Add(new ElephantParameter("service", "FlightOps.Api"));
command.Parameters.Add(new ElephantParameter("since", DateTime.UtcNow.AddHours(-1)));

await using var reader = await command.ExecuteReaderAsync();
while (await reader.ReadAsync())
{
    var traceId = reader.GetString(0);
    var name = reader.GetString(1);
    var durationMs = reader.GetDouble(2);
}

Everything recorded for one request — its spans and its log rows — by trace_id:

async Task<List<string>> ByTraceAsync(string table, string columns, string traceId)
{
    await using var command = connection.CreateCommand();
    command.CommandText = $"SELECT {columns} FROM {table} WHERE trace_id = @trace ORDER BY timestamp";
    command.Parameters.Add(new ElephantParameter("trace", traceId));

    var rows = new List<string>();
    await using var reader = await command.ExecuteReaderAsync();
    while (await reader.ReadAsync()) rows.Add($"{reader.GetDateTime(0):HH:mm:ss.fff}  {reader.GetString(1)}");
    return rows;
}

var spans = await ByTraceAsync("spans", "timestamp, name", traceId);
var logs  = await ByTraceAsync("logs",  "timestamp, content", traceId);

Querying telemetry with DQL

Error spans by operation in the last day:

command.QueryLanguage = ElephantQueryLanguage.Dql;
command.CommandText = """
    fetch spans, from: -1d
    | filter status == "Error" and service_name == $service
    | summarize errors = count(), slowest = max(duration_ms), by:{name}
    | sort errors desc
    """;
command.Parameters.Add(new ElephantParameter("service", "FlightOps.Api"));

Gate changes per service in the last hour, from a counter exported with Delta temporality:

command.CommandText = """
    fetch metrics, from: -1h
    | filter name == "gate.changes" and temporality == "Delta"
    | summarize changes = sum(value), by:{service_name}
    | sort changes desc
    """;

Logs, traces and metrics on one platform

Section 23's advantages extend to all three signals:

From a chart to the cause. A spike on a metrics dashboard leads to the spans in that window, a slow span leads to its trace_id, and the trace_id leads to the log rows and the business record — every step on the same platform, with the same client and the same query languages.
Constant-time trace lookup. Finding every span and log row for one trace_id is a key lookup, so it costs the same however much telemetry is kept.
Long retention. Keeping months of traces is a storage decision, not a performance one.

As with logs, keep telemetry in its own database on the platform (a separate Telemetry connection string, or DatabaseName) so its volume and retention stay separate from application data.

Dashboards and alerts on telemetry

The spans and metrics tables are charted and alerted on from ElephantSqlDB dashboards in the same way as logs and application data.

Dashboards. Typical panels are request volume, error rate and latency per operation from spans, and any counter, gauge or histogram from metrics:

fetch spans, from: -1h
| filter service_name == "FlightOps.Api"
| summarize requests = count(), slowest = max(duration_ms), by:{name}
| sort requests desc

fetch metrics, from: -1h
| filter name == "gate.changes" and temporality == "Delta"
| summarize changes = sum(value), by:{service_name}

Alerts. Define user-defined events on these queries in the dashboard, with the condition that should raise an alert. Examples:

Error spans. More than a set number of spans with status == "Error" for one operation in the last 15 minutes.
Latency. The slowest duration_ms for an operation above its target.
Metric thresholds. A gauge above or below a limit, or a Delta counter that rises sharply or drops to zero.
Silence. No spans or metric rows from a service in the last export interval or two, which usually means the service or its exporter has stopped.

Metrics arrive once per export interval (MetricExportIntervalMilliseconds, 60 seconds by default), so an alert on metrics can react no faster than that interval. Alerts on spans react as soon as a batch is exported.

Testing telemetry

The exporters run under the real OpenTelemetry SDK in tests. With a fake executor behind the connection string (section 18), build a provider, create activities or measurements, call ForceFlush() and assert the recorded statements:

using var source = new ActivitySource("Tests");
using (var provider = Sdk.CreateTracerProviderBuilder()
           .AddSource("Tests")
           .AddElephantSqlDbExporter(fakeConnectionString)
           .Build())
{
    using (source.StartActivity("load gate")) { }
    provider.ForceFlush();
}

Assert.Contains("'load gate'", fake.Statements[0]);

The test project's Telemetry/ folder covers spans, counters, histograms, gauges, temporality, trace_id correlation with logs and ledger-down handling offline (Category=Unit), and checks that rows land exactly once against a live ledger (Category=Live).

Files

File	Role
`Telemetry/Core/ElephantTelemetryOptions.cs`	Options shared by both exporters
`Telemetry/Core/ElephantRowWriter.cs`	Parallel single-row writes, retry, connection reuse
`Telemetry/Core/ElephantTelemetryJson.cs`	Attributes, events, links and buckets to JSON
`Telemetry/Traces/ElephantSqlDbTraceExporter.cs`	`BaseExporter<Activity>` → `spans`
`Telemetry/Traces/ElephantSqlDbTracerProviderBuilderExtensions.cs`	`TracerProviderBuilder.AddElephantSqlDbExporter`
`Telemetry/Metrics/ElephantSqlDbMetricExporter.cs`	`BaseExporter<Metric>` → `metrics`
`Telemetry/Metrics/ElephantSqlDbMeterProviderBuilderExtensions.cs`	`MeterProviderBuilder.AddElephantSqlDbExporter`

Troubleshooting telemetry

No spans appear — the ActivitySource name is not registered with AddSource, or the sampler dropped the trace. Spans are exported every ScheduledDelayMilliseconds and on shutdown; dispose the provider (or let the host stop) before exit.

No metrics appear — the Meter name is not registered with AddMeter, or the first interval (60 seconds by default) has not passed. Call ForceFlush() to export immediately.

NU1605 package downgrade on restore — another package in the application pins Microsoft.Extensions.Logging (or a sibling) below 10.0.0. Raise it to 10.0.x; the 10.x packages target .NET 8.

Counters keep growing — the default Cumulative temporality stores running totals. Use Delta, or chart the difference between consecutive rows.

Telemetry rows missing while the ledger was down — after RetryTimeLimit, rows go to OnWriteFailure. The SDK does not retry a failed export, so hook the callback if those rows matter.

25. ODBC driver

ElephantSqlDb.Data includes a native ODBC 3.8 driver, in the Odbc/ folder alongside the Entity Framework Core and DQL providers. It is written in C# on the same core as the .NET providers, and publishing the project with NativeAOT turns it into an ordinary native library, so any application that speaks ODBC can use ElephantSqlDB without .NET installed:

Languages: Python (pyodbc), R (odbc), PHP (PDO_ODBC), Node.js (odbc), Go, Rust (odbc-api), Ruby, Perl and C/C++.
Tools: Excel, Power BI, Tableau, Qlik, SSIS, SAS and MATLAB, through a DSN with no programming.

Java does not use ODBC; Java, Kotlin and Spark need a JDBC driver, which is separate work.

 ODBC application      Python, R, Excel, Power BI, Tableau ...
        │
 driver manager        Windows ODBC, or unixODBC on Linux and macOS
        │
 ElephantSqlDb.Odbc    native library (NativeAOT)
        │
 ElephantSqlDb.Data    escaping, paging, DQL - the same core as .NET
        │
 ElephantSqlDB

Because the driver runs on the same core, parameter escaping, paging, DQL and the engine rules (section 13: no transactions; section 14: no DDL or constraints) are identical to the .NET providers.

Building the driver

A normal dotnet build compiles the driver into ElephantSqlDb.Data.dll as managed code, which is what the tests use; it adds no dependencies and changes nothing for .NET applications. The native driver comes from publishing the same project with OdbcDriver=true and a runtime identifier:

dotnet publish -c Release -r win-x64 -p:OdbcDriver=true
dotnet publish -c Release -r linux-x64 -p:OdbcDriver=true
dotnet publish -c Release -r osx-arm64 -p:OdbcDriver=true

OdbcDriver=true switches on NativeAOT, names the output ElephantSqlDb.Odbc and turns off NuGet packing for that publish; the NuGet build is unaffected.

The output is a single self-contained file, ElephantSqlDb.Odbc.dll, .so or .dylib, in bin/Release/net8.0/<rid>/publish/, with the Install/ folder beside it. Build each platform on that platform (NativeAOT does not cross-compile between operating systems).

Installing

Windows (elevated PowerShell, in the publish folder):

.\Install\install-windows.ps1
Add-OdbcDsn -Name ElephantSqlDB -DriverName "ElephantSqlDB ODBC Driver" -DsnType System -Platform 64-bit `
  -SetPropertyValue @("BaseUri=https://api.elephantsqldb.com/", "Token=<token>",
                      "UserEmail=<email>", "TenantId=<tenant>", "Database=<database>")

The script registers the driver under HKLM\SOFTWARE\ODBC\ODBCINST.INI. The driver also exports ConfigDSNW, so Add-OdbcDsn, odbcconf and the ODBC Data Source Administrator can add and remove DSNs (there is no configuration dialog; attributes are written as given).

Linux and macOS (requires unixODBC):

sudo ./Install/install-linux.sh
isql -v ElephantSqlDB

Add the DSN to ~/.odbc.ini or /etc/odbc.ini; Install/odbc.ini.sample is a template.

Connection attributes

Every ElephantSqlDb.Data keyword (section 4) can be used in a DSN or connection string. The usual ODBC names are accepted as aliases, so tools that only know UID/PWD still work:

ODBC name	ElephantSqlDb.Data keyword
`UID`, `User`, `User ID`	`UserEmail`
`PWD`	`Password`
`SERVER`, `HOST`, `URL`	`BaseUri`
`CATALOG` (or `Database`)	`Database`
`APIKEY`	`Token`

Attributes in the connection string override the DSN's. DRIVER, DSN, Description and unknown keywords are not passed on. A DSN-less string works too:

Driver={ElephantSqlDB ODBC Driver};BaseUri=https://api.elephantsqldb.com/;Token=<token>;UserEmail=<email>;TenantId=<tenant>;Database=<database>

There is no login dialog. If an attribute is missing, the connection fails with SQLSTATE 08001 and a message naming what to supply.

Using the driver from C#

System.Data.Odbc reaches the driver exactly as any other ODBC application does, which makes it a convenient way to verify an installation:

using System.Data.Odbc;

using var connection = new OdbcConnection("DSN=ElephantSqlDB");
connection.Open();

using var command = new OdbcCommand("SELECT id, name FROM customers WHERE id = ?", connection);
command.Parameters.AddWithValue("id", 42);

using var reader = command.ExecuteReader();
while (reader.Read())
    Console.WriteLine($"{reader.GetInt64(0)} {reader.GetString(1)}");

From Python, R or Excel the same DSN is used unchanged: pyodbc.connect("DSN=ElephantSqlDB", autocommit=True), dbConnect(odbc::odbc(), "ElephantSqlDB"), or Data > Get Data > From ODBC.

SQL through ODBC

Parameters. ? markers become named parameters (@__p1, @__p2 ...) and values go through the provider's literal binder (section 15), the one place values are escaped. Markers inside quotes and comments are left alone. Parameter arrays (SQL_ATTR_PARAMSET_SIZE, executemany) run one statement per row.

Escape clauses. {d '...'}, {t '...'}, {ts '...'}, {fn ...}, {oj ...} and {escape '...'} are expanded to plain SQL. {call ...} is rejected with HYC00: ElephantSqlDB has no stored procedures.

Queries and writes. ODBC has one execute call for every statement. Statements starting with SELECT, WITH, FETCH, VALUES, SHOW, DESCRIBE or EXPLAIN run as queries; everything else runs as a write. With QueryLanguage=Dql in the DSN, every statement is a DQL query.

Empty results. ElephantSqlDB returns rows as JSON objects, so an empty result carries no column names. For SELECT * FROM t and SELECT a, b AS c FROM t the driver recovers the columns from the select list and the table's schema, so tools still see them; for other shapes an empty result reports no columns.

Types

Result types come from the values ElephantSqlDB returns; catalog types come from the stored schema.

Value	ODBC SQL type
text, JSON objects	`SQL_WVARCHAR`
integers	`SQL_BIGINT` (`SQL_INTEGER` in the catalog for `int` columns)
decimals	`SQL_DOUBLE` or `SQL_DECIMAL`
booleans	`SQL_BIT`
date and time	`SQL_TYPE_TIMESTAMP`, `SQL_TYPE_DATE`, `SQL_TYPE_TIME`
UUIDs	`SQL_GUID`
binary	`SQL_VARBINARY`

Values convert to every common C type (character, integer, floating point, numeric, bit, date, time, timestamp, GUID and binary). Long character and binary values can be read in pieces with SQLGetData.

Transactions

The driver reports SQL_TXN_CAPABLE = SQL_TC_NONE, matching the engine. Each statement applies as it runs. Applications that turn autocommit off (pyodbc does by default) still work: the driver accepts it with a warning, SQLEndTran(COMMIT) succeeds, and SQLEndTran(ROLLBACK) after a write fails with HYC00, stating that the statements have already been applied. Pass autocommit=True to pyodbc to avoid the warning.

Catalog functions

ElephantSqlDB databases are ODBC catalogs; there are no schemas. SQLTables, SQLColumns, SQLPrimaryKeys, SQLForeignKeys, SQLSpecialColumns and SQLGetTypeInfo are answered from the stored schema, which is what BI tools use to browse tables. A null catalog means the connection's current database, so tools generate unqualified SQL, which runs against that database. SQLStatistics and the procedure functions return empty results.

Capabilities and limits

Forward-only, read-only cursors; block fetches with SQL_ATTR_ROW_ARRAY_SIZE.
Input parameters only; no SQLPutData (data at execution).
No asynchronous execution, bookmarks or positioned updates.
SQL-dialect capabilities (scalar functions, outer joins, subqueries, aggregates) are reported to applications as unsupported until confirmed against the engine, so tools generate simple SQL rather than SQL that fails.
unixODBC is supported on Linux and macOS; iODBC (four-byte SQLWCHAR) is not.

Testing the driver

The test project's Odbc/ folder drives the API exactly as a driver manager does, with native buffers, against an in-memory ledger:

dotnet test --filter "Area=Odbc&Category=Unit"

The tests cover connection strings and DSN merging, describe and fetch, chunked SQLGetData, block fetches, parameter escaping (including an injection attempt), parameter arrays, empty-result columns, catalog functions, diagnostics, transactions, SQLGetFunctions and invalid handles.

Files

File	Role
`ElephantSqlDb.Data.csproj`	`OdbcDriver=true` publish settings (NativeAOT shared library)
`Odbc/Exports.cs`	Native ODBC entry points
`Odbc/OdbcApi.cs`	Handle checks, locking and diagnostics around each function
`Odbc/Core/OdbcDbc.cs`	Environment and connection handles, connect, catalog cache
`Odbc/Core/OdbcStatement.cs`	Prepare, execute, fetch, `SQLGetData`
`Odbc/Core/SqlRewriter.cs`	`?` markers and ODBC escape clauses
`Odbc/Core/OdbcConnectionString.cs`	Connection strings, DSN merging, aliases
`Odbc/Core/ValueWriter.cs`, `Odbc/Core/ParameterReader.cs`	C type conversion out and in
`Odbc/Core/SqlTypes.cs`, `Odbc/Core/DriverInfo.cs`	Type mapping, `SQLGetInfo`, `SQLGetFunctions`
`Odbc/Catalog/CatalogQueries.cs`	Catalog result sets, empty-result columns
`Odbc/Setup/OdbcInst.cs`	DSN reading and `ConfigDSNW` through the installer library
`Odbc/Install/`	Windows and unixODBC install scripts, sample DSN

Troubleshooting ODBC

IM002 data source name not found — the DSN is missing, or was created for the other bitness. 64-bit applications see only 64-bit DSNs; use -Platform 64-bit with Add-OdbcDsn.

IM003 specified driver could not be loaded — the Driver path in the registry or odbcinst.ini is wrong, or the library was published for another platform.

08001 unable to connect — a required attribute (BaseUri, Token, UserEmail, Database) is missing, or the ledger is unreachable. The message names the cause.

A query returns no columns — the result was empty and the statement is not a simple SELECT ... FROM table; see Empty results above.

Publish warnings about trimming — expected from dependencies that use reflection; the project keeps them whole (TrimMode=partial). A missing-member error at run time means a type was trimmed and should be reported.

Product	Compatible and additional computed target framework versions.
.NET	net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Product

.NET

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net8.0
- ElephantSqlDBClient (>= 1.0.188)
- log4net (>= 3.0.3)
- Microsoft.EntityFrameworkCore.Relational (>= 8.0.10)
- Microsoft.Extensions.Logging (>= 10.0.0)
- Newtonsoft.Json (>= 13.0.3)
- OpenTelemetry (>= 1.17.0)
- Serilog (>= 4.2.0)
- ServiceStack.OrmLite (>= 8.0.0)

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
1.0.193	44	10/29/2026

ElephantSqlDB Client for .NET 8.0 - ADO.NET provider, OrmLite, Dapper dialects and EF Core 8 provider (UseElephantSqlDb, dotnet ef scaffolding). Obfuscated and optimized for production use.

ElephantSqlDb.Data.Provider 1.0.193

ElephantSqlDb.Data — Developer Guide

Contents

1. What this is

2. Architecture

Files

How a query flows

How a write flows

3. Installation

4. Connection strings

Keeping the token out of source

What happens on Open

When to turn them on

Doing it yourself

Building one in code

5. Dependency injection

Program.cs — minimal hosting

Startup.cs — classic hosting

Raw ADO.NET without OrmLite

Registering by invariant name

Do you need a repository per table?

6. Choosing an API: the same tasks four ways

Registration

Entity definitions

Query a list

Get one row

Count

Page through results

Insert

Update

Delete

Mixing APIs

7. Raw ADO.NET

Query

Scalar

Write

Saving a file as a record

Reading by column name

Choosing the database

Listing databases and their schema

Creating a database

Renaming a database

8. Pagination and result metadata

Reading it from the reader

Reading it from the command

Server-side paging

Counting without materialising

Streaming every page

Through an interface-typed call

Empty results

9. OrmLite

Entities

Reads

Typed expressions

Writes

Raw SQL through OrmLite

Schema calls

10. Dapper

11. Entity Framework Core

Installation

ADO.NET and EF Core classes

Entities and the DbContext

Dependency injection

Queries

Writes

SaveChanges semantics

Raw SQL and Dapper on the same connection

Sharing tables with OrmLite and Dapper

Creating the database

Scaffolding an existing database

Using EF Core with Radzen Blazor

EF Core limitations at a glance

12. Type mapping

Two things to be deliberate about

13. No transactions

What to do instead

14. No DDL, no constraints

The part that is easy to miss

Provisioning a schema

15. Parameters and injection