Dotnet Data

Architecture

arturdev@duck.com (Artur Rios) — Mon, 01 Jan 0001 00:00:00 +0000

Architecture

ArturRios.Data is a family of small, focused NuGet packages. This page shows how they fit together, the key types in each, and the design principles they share.

Package dependencies

flowchart TB
Output["ArturRios.Output<br/><i>DataOutput / ProcessOutput envelopes</i>"]
subgraph Relational["Relational stack — EF Core"]
direction TB
Core["ArturRios.Data.Relational.Core<br/><i>interfaces, EfRepository, EfUnitOfWork,<br/>BaseDbContext, IDatabaseProvider seam</i>"]
Sqlite["ArturRios.Data.Sqlite<br/><i>AddSqliteProvider()</i>"]
Postgres["ArturRios.Data.PostgreSql<br/><i>AddPostgreSqlProvider()</i>"]
MySql["ArturRios.Data.MySql<br/><i>(deferred)</i>"]
Dapper["ArturRios.Data.Dapper<br/><i>read-only raw SQL</i>"]
end
subgraph NoSQL["NoSQL stores — standalone"]
direction TB
Mongo["ArturRios.Data.MongoDb<br/><i>document repository + transactions</i>"]
Dynamo["ArturRios.Data.DynamoDb<br/><i>async repository over IDynamoDBContext</i>"]
end
subgraph Export["File export — standalone"]
direction TB
ExportCore["ArturRios.Data.Export<br/><i>exporter factory, column map,<br/>CSV / JSON / TXT / MessagePack</i>"]
ExportExcel["ArturRios.Data.Export.Excel<br/><i>.xlsx add-on</i>"]
end
Sqlite --> Core
Postgres --> Core
MySql --> Core
Dapper --> Core
Core --> Output
Mongo --> Output
Dynamo --> Output
ExportExcel --> ExportCore
ExportCore --> Output
EF["Microsoft.EntityFrameworkCore"]:::ext
EfProviders["Npgsql / Pomelo / Sqlite EF provider"]:::ext
DapperLib["Dapper"]:::ext
MongoLib["MongoDB.Driver"]:::ext
Aws["AWSSDK.DynamoDBv2"]:::ext
MsgPack["MessagePack"]:::ext
ClosedXml["ClosedXML"]:::ext
Core --> EF
Sqlite --> EfProviders
Postgres --> EfProviders
MySql --> EfProviders
Dapper --> DapperLib
Mongo --> MongoLib
Dynamo --> Aws
ExportCore --> MsgPack
ExportExcel --> ClosedXml
classDef ext fill:#8882,stroke-dasharray:3 3;

The families are deliberately separate. The relational providers and the Dapper read path build on ArturRios.Data.Relational.Core (EF Core). The NoSQL packages do not depend on the relational core — pulling EF Core into a MongoDB or DynamoDB app would be wasteful — so they depend only on ArturRios.Output and their native driver. MongoDB and DynamoDB are also separate from each other: their data models diverge too much (composite keys and a key/scan access model in DynamoDB vs. documents with LINQ/predicate queries in MongoDB) to share one interface without becoming leaky. The export packages are independent of all of it — they take any IEnumerable<T>, so they need no store at all.

Excel is split out for the same reason, one level down: ClosedXML is a heavy dependency, so it lives in an add-on that apps opt into. The core keeps no compile-time reference to it — the add-on registers a marker type that the exporter factory resolves at runtime.

The result envelope

Every backend returns the same envelope types from ArturRios.Output. A ProcessOutput carries success state, error messages, and info messages; DataOutput<T> adds a typed payload.

classDiagram
class ProcessOutput {
+bool Success
+List~string~ Messages
+List~string~ Errors
+WithError(string) ProcessOutput
}
class DataOutput~T~ {
+T Data
+WithData(T) DataOutput~T~
}
ProcessOutput <|-- DataOutput

Relational model

The relational core exposes four repository interfaces (a read-only tier and a full read/write tier, each in a sync and an async flavour), all constrained to T : Entity. EfRepository<T> implements all four; EfUnitOfWork implements both unit-of-work interfaces. Consumers derive their entities from Entity (or VersionedEntity for optimistic concurrency) and their DbContext from BaseDbContext.

classDiagram
class Entity { +long Id }
class VersionedEntity { +Guid ConcurrencyStamp }
Entity <|-- VersionedEntity
class IReadOnlyRepository~T~ {
+Query() IQueryable~T~
+GetAll() DataOutput
+GetById(long) DataOutput
}
class IRepository~T~ {
+Create(T) DataOutput
+CreateRange(items) DataOutput
+Update(T) DataOutput
+UpdateRange(items) DataOutput
+Delete(T) DataOutput
+DeleteRange(ids) DataOutput
}
class IAsyncReadOnlyRepository~T~
class IAsyncRepository~T~
class EfRepository~T~
IReadOnlyRepository <|-- IRepository
IAsyncReadOnlyRepository <|-- IAsyncRepository
IRepository <|.. EfRepository
IAsyncRepository <|.. EfRepository
class IUnitOfWork {
+ExecuteInTransaction(work) ProcessOutput
}
class IAsyncUnitOfWork {
+ExecuteInTransactionAsync(work) Task
}
class EfUnitOfWork
IUnitOfWork <|.. EfUnitOfWork
IAsyncUnitOfWork <|.. EfUnitOfWork

The provider seam

The core never references a specific EF provider. Each provider package implements IDatabaseProvider and registers it as a singleton, exposing which DatabaseType it handles; AddDataConfigFromSettings<TContext> (or AddDataConfigFromEnvironment<TContext>) reads the configured DatabaseType and picks the matching provider out of the registered set to configure the DbContext. This is why you call both AddXProvider() and AddDataConfigFromSettings<TContext>() / AddDataConfigFromEnvironment<TContext>().

Registration validates this eagerly: if it can prove no registered provider matches the configured DatabaseType, it throws a DataAccessException naming the missing package rather than failing on the first query.

classDiagram
class IDatabaseProvider {
+DatabaseType Type
+Configure(builder, connectionString)
}
class SqliteProvider
class PostgreSqlProvider
class MySqlProvider
IDatabaseProvider <|.. SqliteProvider
IDatabaseProvider <|.. PostgreSqlProvider
IDatabaseProvider <|.. MySqlProvider

MongoDB model

MongoDB uses a distinct interface family (IDocumentRepository<T> / IAsyncDocumentRepository<T> plus read-only tiers) with string/ObjectId identity. MongoDocumentRepository<T> implements them over a MongoContext that carries the ambient session used by MongoUnitOfWork transactions.

classDiagram
class Document { +string Id }
class VersionedDocument { +long Version }
Document <|-- VersionedDocument
class IDocumentRepository~T~
class IAsyncDocumentRepository~T~
class MongoDocumentRepository~T~
IDocumentRepository <|.. MongoDocumentRepository
IAsyncDocumentRepository <|.. MongoDocumentRepository
class IMongoUnitOfWork
class IAsyncMongoUnitOfWork
class MongoUnitOfWork
IMongoUnitOfWork <|.. MongoUnitOfWork
IAsyncMongoUnitOfWork <|.. MongoUnitOfWork

DynamoDB model

DynamoDB has no shared base class — items are plain POCOs annotated with AWS attributes. The single async repository interface maps to DynamoDB’s real access model (key-based load, partition-key query, scan, batch).

classDiagram
class IAsyncDynamoRepository~T~ {
+SaveAsync(T) DataOutput
+LoadAsync(hashKey) DataOutput
+LoadAsync(hashKey, rangeKey) DataOutput
+QueryAsync(hashKey) DataOutput
+ScanAsync(conditions) DataOutput
+SaveManyAsync(items) DataOutput
+LoadManyAsync(hashKeys) DataOutput
}
class DynamoRepository~T~
IAsyncDynamoRepository <|.. DynamoRepository

Export model

Export has no store and no entity base class — it takes any IEnumerable<T>. IExporter<T> is the one contract; ExporterBase<T> centralizes the null-guarding, envelope conversion, and stream lifetime, so a concrete exporter only implements the format-specific write. IExporterFactory maps an ExportFormat to the right exporter out of the container.

classDiagram
class IExporter~T~ {
+WriteAsync(data, stream) ProcessOutput
+WriteToFileAsync(data, path) ProcessOutput
}
class ExporterBase~T~ {
#WriteCoreAsync(data, stream, ct)
}
IExporter <|.. ExporterBase
class CsvExporter~T~
class JsonExporter~T~
class TxtExporter~T~
class MessagePackExporter~T~
class ExcelExporter~T~
ExporterBase <|-- CsvExporter
ExporterBase <|-- JsonExporter
ExporterBase <|-- TxtExporter
ExporterBase <|-- MessagePackExporter
ExporterBase <|-- ExcelExporter
class IExporterFactory {
+Resolve(format) IExporter~T~
}
class ExporterFactory
IExporterFactory <|.. ExporterFactory
ExporterFactory ..> IExporter : resolves

The columnar formats (CSV, Excel) share one ColumnMap, which compiles and caches a per-type column plan from the record’s public properties, honouring [ExportColumn] and [ExportIgnore].

Design principles

Modular packaging. One package per backend; install only what you use. NoSQL packages don’t drag in EF Core.
Envelopes, not exceptions. Every public repository/unit-of-work method catches infrastructure exceptions and returns them as DataOutput/ProcessOutput errors. Optimistic-concurrency conflicts become a friendly “concurrency conflict” error. The one intentional exception is OperationCanceledException, which propagates so cooperative cancellation stays idiomatic.
Opt-in optimistic concurrency. Derive from VersionedEntity / VersionedDocument, or add [DynamoDBVersion], to get conditional writes; without it, writes are last-writer-wins.
Transactions where the engine supports them. Relational and MongoDB expose a delegate-based unit of work; the Dapper read path enlists in the relational transaction. (DynamoDB transactions are a planned addition.)
Consistent naming. AddDataConfigFromSettings / AddMongoData / AddDynamoData / AddExport for DI; DataOutput<T> / ProcessOutput everywhere; Async suffix + CancellationToken on async members.

See the Relational, MongoDB, DynamoDB, and Export guides for full usage.

DynamoDB

arturdev@duck.com (Artur Rios) — Mon, 01 Jan 0001 00:00:00 +0000

DynamoDB store

ArturRios.Data.DynamoDb is a standalone, async-only repository over the AWS SDK’s high-level object-persistence model (IDynamoDBContext). It does not depend on the relational core. Every method returns a DataOutput / ProcessOutput envelope.

Install

dotnet add package ArturRios.Data.DynamoDb

1. Define an item

There’s no base class — annotate a POCO with the AWS attributes. Keys are a partition (hash) key plus an optional sort (range) key; add [DynamoDBVersion] to opt into optimistic concurrency.

using Amazon.DynamoDBv2.DataModel;

[DynamoDBTable("Products")]
public class Product
{
 [DynamoDBHashKey] public string Category { get; set; } = string.Empty; // partition key
 [DynamoDBRangeKey] public string Sku { get; set; } = string.Empty; // sort key (optional)
 public string Name { get; set; } = string.Empty;
 public decimal Price { get; set; }
 [DynamoDBVersion] public int? Version { get; set; } // opt-in concurrency
}

2. Configure

The default section is "ArturRios.Data.DynamoDb". ServiceUrl is optional — set it to point at DynamoDB Local or LocalStack; omit it to use real AWS (region + the default credential chain, or explicit AccessKey/SecretKey):

{
 "ArturRios.Data.DynamoDb": {
 "Region": "us-east-1",
 "ServiceUrl": "http://localhost:8000"
 }
}

3. Register

using ArturRios.Data.DynamoDb.DependencyInjection;

builder.Services.AddDynamoData(builder.Configuration); // binds "ArturRios.Data.DynamoDb"

This registers IAmazonDynamoDB, IDynamoDBContext, and the repository (IAsyncDynamoRepository<T>).

4. Use the repository

Inject IAsyncDynamoRepository<T>. It’s shaped to DynamoDB’s real access model — load by key, query a partition, scan, and batch — not IQueryable:

using ArturRios.Data.DynamoDb.Interfaces;
using ArturRios.Output;

public class CatalogService(IAsyncDynamoRepository<Product> repo)
{
 public Task<DataOutput<Product>> AddAsync(Product p) => repo.SaveAsync(p);

 public async Task<Product?> GetAsync(string category, string sku)
 {
 var result = await repo.LoadAsync(category, sku); // not-found = Success + null
 return result.Success ? result.Data : null;
 }

 public async Task<IEnumerable<Product>> InCategoryAsync(string category) =>
 (await repo.QueryAsync(category)).Data ?? []; // all items in a partition
}

Full surface:

Method	Purpose
`SaveAsync(item)`	Put (create or replace); returns the item
`LoadAsync(hashKey)` / `LoadAsync(hashKey, rangeKey)`	Get by key; not-found is a successful null
`DeleteAsync(item)`	Delete (idempotent); returns `ProcessOutput`
`QueryAsync(hashKey)`	All items in a partition
`QueryAsync(hashKey, op, sortValues)`	Partition + a sort-key condition (`QueryOperator`)
`ScanAsync(conditions)`	Full-table scan with `ScanCondition`s — use sparingly
`SaveManyAsync` / `DeleteManyAsync`	Batch write
`LoadManyAsync(hashKeys)`	Batch get by partition key (hash-key-only tables)

5. Optimistic concurrency

Add [DynamoDBVersion] int? Version to your item. SaveAsync then issues a conditional write; a stale version returns a concurrency-conflict error envelope instead of throwing.

Batch writes bypass concurrency. DynamoDB’s BatchWriteItem has no conditional-write support, so SaveManyAsync / DeleteManyAsync do not enforce [DynamoDBVersion]. Single-item SaveAsync / DeleteAsync still do.

Notes & roadmap

Async-only — the AWS SDK v4 IDynamoDBContext has no synchronous methods.
Scan reads the whole table; prefer Query on a partition key (with a sort condition or a GSI) wherever possible.
Deferred: atomic multi-item transactions (TransactWriteItems) and composite-key batch-get are planned future additions.

Export

arturdev@duck.com (Artur Rios) — Mon, 01 Jan 0001 00:00:00 +0000

File export

ArturRios.Data.Export turns any IEnumerable<T> into CSV, JSON, TXT, or MessagePack, over a stream or straight to a file. ArturRios.Data.Export.Excel adds .xlsx as a separate add-on.

Both are standalone — they work with plain POCOs and depend on neither the relational core nor a database driver. They keep the same enveloped style as the rest of the family: every write returns a ProcessOutput, so a locked file or a serialization failure comes back as an error on the result rather than an unhandled exception.

Install

dotnet add package ArturRios.Data.Export
dotnet add package ArturRios.Data.Export.Excel # optional — adds ExportFormat.Excel

Excel is a separate package on purpose: ClosedXML is a heavy dependency, and only apps that actually export spreadsheets should pay for it.

1. Register

using ArturRios.Data.Export.DependencyInjection;
using ArturRios.Data.Export.Excel.DependencyInjection; // only with the add-on

builder.Services.AddExport();
builder.Services.AddExcelExport(); // only with the add-on

AddExport() registers the IExporterFactory and the four core exporters. AddExcelExport() registers the Excel exporter and makes the factory resolve ExportFormat.Excel.

2. Write something

Inject IExporterFactory and resolve by format:

using ArturRios.Data.Export.Abstractions;
using ArturRios.Output;

public class ProductReport(IExporterFactory exporters)
{
 public async Task<ProcessOutput> WriteCsvAsync(IEnumerable<Product> products, string path)
 {
 var exporter = exporters.Resolve<Product>(ExportFormat.Csv);
 return await exporter.WriteToFileAsync(products, path);
 }
}

You can also inject a concrete exporter (CsvExporter<Product>, JsonExporter<Product>, …) when the format is fixed at compile time.

Each exporter has two methods:

Method	Behaviour
`WriteAsync(data, stream, ct)`	writes to your stream — it is not disposed
`WriteToFileAsync(data, path, ct)`	creates/truncates the file and writes to it

3. Formats

`ExportFormat`	Exporter	Notes
`Csv`	`CsvExporter<T>`	RFC 4180 quoting/escaping; configurable delimiter and encoding
`Json`	`JsonExporter<T>`	a JSON array via `System.Text.Json`
`Txt`	`TxtExporter<T>`	one line per record; `ToString()` or a custom line selector
`MessagePack`	`MessagePackExporter<T>`	binary; contractless resolver, so no attributes required
`Excel`	`ExcelExporter<T>` (add-on)	.xlsx via ClosedXML; requires `AddExcelExport()`

Resolving ExportFormat.Excel without the add-on registered throws a NotSupportedException naming the missing package and call. The core has no compile-time reference to the Excel package — the add-on drops a registration marker in the container, and the factory picks it up.

TxtExporter<T> has extra overloads taking a Func<T, string> line selector, for when ToString() isn’t the line you want.

4. Shaping columns

The columnar formats (CSV and Excel) build a column plan from the record’s public readable properties. Two attributes adjust it:

using ArturRios.Data.Export.Attributes;

public class Product
{
 [ExportColumn(Name = "Product name", Order = 1)]
 public string Name { get; set; } = string.Empty;

 [ExportColumn(Order = 2)]
 public decimal Price { get; set; }

 [ExportIgnore]
 public string InternalNotes { get; set; } = string.Empty;
}

Columns sort by Order ascending; unordered columns sort last. The plan compiles to delegate getters and is cached per type, so there’s no per-row reflection cost.

Json and MessagePack ignore the column map — they serialize the object graph as-is.

Values in columnar output are rendered culture-invariantly: null becomes empty, strings pass through, and anything IFormattable is formatted with CultureInfo.InvariantCulture.

5. Options

builder.Services.AddExport(options =>
{
 options.Csv.Delimiter = ';';
 options.Csv.IncludeHeader = true;
 options.Csv.Encoding = new UTF8Encoding(false);
 options.Json.WriteIndented = true;
 options.Txt.NewLine = "\n";
});

builder.Services.AddExcelExport(options =>
{
 options.SheetName = "Products"; // default "Sheet1"
 options.IncludeHeader = true;
 options.BoldHeader = true;
 options.AutoFitColumns = true;
});

Json and MessagePack also accept explicit SerializerOptions, used as-is when set. MessagePack otherwise defaults to the contractless standard resolver.

Notes

Excel numeric precision. The .xlsx format stores every number as an IEEE-754 double, so long/ulong beyond 2^53 and high-precision decimal values lose precision. Export those as strings if exactness matters.
Cancellation propagates as OperationCanceledException rather than being folded into the envelope — consistent with the rest of the toolkit.

MongoDB

arturdev@duck.com (Artur Rios) — Mon, 01 Jan 0001 00:00:00 +0000

MongoDB document store

ArturRios.Data.MongoDb is a standalone document-repository package over MongoDB.Driver — it does not depend on the relational core, so it pulls in no EF Core. It keeps the same enveloped style: every method returns a DataOutput / ProcessOutput.

Install

dotnet add package ArturRios.Data.MongoDb

1. Define a document

Derive from Document (a string Id mapped to Mongo’s _id as an ObjectId), or VersionedDocument to opt into optimistic concurrency (adds a long Version).

using ArturRios.Data.MongoDb;

public class Product : Document // or : VersionedDocument
{
 public string Name { get; set; } = string.Empty;
 public decimal Price { get; set; }
}

By default the collection name is the type name. Override it with [MongoCollection("name")] on the document class.

2. Configure

The default section is "ArturRios.Data.MongoDb" — a connection string and a database name:

{
 "ArturRios.Data.MongoDb": {
 "ConnectionString": "mongodb://localhost:27017/?replicaSet=rs0",
 "DatabaseName": "mydb"
 }
}

Multi-document transactions require the server to be a replica set — hence ?replicaSet=rs0 above. A standalone mongod supports everything except transactions.

3. Register

using ArturRios.Data.MongoDb.DependencyInjection;

builder.Services.AddMongoData(builder.Configuration); // binds "ArturRios.Data.MongoDb"

This registers the IMongoClient, a scoped MongoContext, the repository interfaces (IDocumentRepository<T> / IAsyncDocumentRepository<T> and their read-only tiers), and the unit of work (IMongoUnitOfWork / IAsyncMongoUnitOfWork).

4. Use the repository

Inject IAsyncDocumentRepository<T> (or the sync IDocumentRepository<T>). Every method is enveloped:

using ArturRios.Data.MongoDb.Interfaces;
using ArturRios.Output;

public class CatalogService(IAsyncDocumentRepository<Product> repo)
{
 public async Task<string> AddAsync(Product p)
 {
 var result = await repo.CreateAsync(p); // DataOutput<string> — the generated id
 return result.Success ? result.Data! : throw new InvalidOperationException(string.Join(", ", result.Errors));
 }

 public async Task<Product?> GetAsync(string id)
 {
 var result = await repo.GetByIdAsync(id); // not-found = Success + null
 return result.Success ? result.Data : null;
 }

 public async Task<IEnumerable<Product>> ExpensiveAsync() =>
 (await repo.FindAsync(p => p.Price > 100)).Data ?? []; // server-side filter
}

The full surface: GetById, GetAll, Find(predicate) (server-side filter), Create/CreateRange, Update/UpdateRange, Delete/DeleteRange, plus the Query() escape hatch.

Query() returns a composable IQueryable<T> (the driver’s LINQ provider). Note it bypasses the ambient unit-of-work transaction — LINQ reads run outside the session, so they will not see uncommitted writes made earlier in the same transaction. Use Find / GetAll for transaction-aware reads.

5. Transactions

Inject IAsyncMongoUnitOfWork and run repository operations atomically. Operations inside the delegate enlist in the transaction automatically (via the context’s ambient session):

using ArturRios.Data.MongoDb.Transactions;

public class CatalogService(IAsyncDocumentRepository<Product> repo, IAsyncMongoUnitOfWork unitOfWork)
{
 public Task<DataOutput<string>> AddTwoAtomicallyAsync(Product a, Product b) =>
 unitOfWork.ExecuteInTransactionAsync(async () =>
 {
 var first = await repo.CreateAsync(a);
 await repo.CreateAsync(b);
 return first.Data!;
 });
}

Transactions require a replica set. On a standalone server the transaction will fail (and, being enveloped, return Success == false rather than throwing).

6. Optimistic concurrency

Derive from VersionedDocument. On update the stored Version is checked and incremented; a stale write returns a concurrency-conflict error envelope instead of throwing:

var result = await repo.UpdateAsync(product);
if (!result.Success)
{
 // e.g. "Concurrency conflict: the document was modified or removed by another process."
}

Relational

arturdev@duck.com (Artur Rios) — Mon, 01 Jan 0001 00:00:00 +0000

Relational (EF Core)

The relational stack is a provider-agnostic data-access layer over Entity Framework Core. You install the core plus a provider for your engine; the core gives you enveloped repositories, a unit of work, optimistic concurrency, and DI wiring, while the provider teaches it how to talk to PostgreSQL, SQLite, or MySQL.

Install

dotnet add package ArturRios.Data.Relational.Core
dotnet add package ArturRios.Data.Sqlite # or ArturRios.Data.PostgreSql

Provider package	`DatabaseType`	Status
`ArturRios.Data.Sqlite`	`SqLite`	Available
`ArturRios.Data.PostgreSql`	`PostgreSql`	Available
`ArturRios.Data.MySql`	`MySql`	Deferred — see MySQL status

1. Define entities

Derive from Entity (an int Id mapped as the first column), or VersionedEntity to opt into optimistic concurrency (adds a Guid ConcurrencyStamp).

using ArturRios.Data.Relational.Core;

public class Product : Entity // or : VersionedEntity
{
 public string Name { get; set; } = string.Empty;
 public decimal Price { get; set; }
}

2. Define your context

Derive from BaseDbContext and expose your DbSets. BaseDbContext regenerates the ConcurrencyStamp of modified VersionedEntity rows on every SaveChanges / SaveChangesAsync.

using ArturRios.Data.Relational.Core.Configuration;
using Microsoft.EntityFrameworkCore;

public class AppDbContext(DbContextOptions options) : BaseDbContext(options)
{
 public DbSet<Product> Products => Set<Product>();
}

3. Configure

Bind a BaseDbContextOptions (a DatabaseType + a ConnectionString) from configuration. The default section name is "ArturRios.Data.Core" (you can pass a different sectionName to AddDataConfigFromSettings):

{
 "ArturRios.Data.Core": {
 "DatabaseType": "PostgreSql",
 "ConnectionString": "Host=localhost;Database=mydb;Username=app;Password=secret;"
 }
}

DatabaseType is an enum: PostgreSql, MySql, or SqLite — note the lowercase q in SqLite. (Configuration binding is case-insensitive, so "SQLite" in JSON still binds, but the C# member is DatabaseType.SqLite.)

Registering from environment variables

When configuration lives in environment variables rather than appsettings, call AddDataConfigFromEnvironment<TContext> with a name prefix instead of AddDataConfigFromSettings:

builder.Services.AddDataConfigFromEnvironment<AppDbContext>("ARTURRIOS_DATA");

It reads ARTURRIOS_DATA_DATABASETYPE (one of PostgreSql, MySql, SqLite) and ARTURRIOS_DATA_CONNECTIONSTRING. The appsettings section is not consulted on this path. A missing or invalid ..._DATABASETYPE throws; a missing ..._CONNECTIONSTRING defaults to an empty string.

4. Register

Call your provider’s registration extension and AddDataConfigFromSettings<TContext>. The provider registers its IDatabaseProvider; AddDataConfigFromSettings reads the configured DatabaseType, resolves the matching provider, wires up your DbContext, and registers the repositories and unit of work. It fails fast at registration if no provider matches the configured DatabaseType.

using ArturRios.Data.PostgreSql; // brings AddPostgreSqlProvider()
using ArturRios.Data.Relational.Core.DependencyInjection;

builder.Services.AddPostgreSqlProvider(); // or AddSqliteProvider()
builder.Services.AddDataConfigFromSettings<AppDbContext>(builder.Configuration, "ArturRios.Data.Core");

5. Repositories

AddDataConfigFromSettings registers all four repository interfaces (backed by EfRepository<T>). There are two tiers — read-only and full read/write — each in a sync and an async flavour:

Interface	Members
`IReadOnlyRepository<T>`	`Query()`, `GetAll()`, `GetById(int)`
`IRepository<T>`	the above + `Create`, `CreateRange`, `Update`, `UpdateRange`, `Delete`, `DeleteRange`
`IAsyncReadOnlyRepository<T>`	async mirror of the read-only tier
`IAsyncRepository<T>`	async mirror of the full tier

Inject whichever tier you need. Every method returns a DataOutput<T> envelope — check Success / Data / Errors:

using ArturRios.Data.Relational.Core.Interfaces;
using ArturRios.Output;

public class ProductService(IAsyncRepository<Product> repo)
{
 public async Task<Product?> GetAsync(int id)
 {
 DataOutput<Product?> result = await repo.GetByIdAsync(id); // not-found = Success + null data
 return result.Success ? result.Data : null;
 }

 public async Task<int> CreateAsync(Product p)
 {
 var result = await repo.CreateAsync(p); // DataOutput<int> (the new id)
 return result.Success ? result.Data : throw new InvalidOperationException(string.Join(", ", result.Errors));
 }
}

The Query() escape hatch. When you need composable LINQ or paging, Query() returns a raw, deferred IQueryable<T> (not enveloped — it does no I/O until materialized):

var page = repo.Query()
 .Where(p => p.Price > 10)
 .OrderBy(p => p.Name)
 .Skip(20).Take(10)
 .ToList();

6. Transactions (unit of work)

AddDataConfigFromSettings also registers IUnitOfWork / IAsyncUnitOfWork. Run several repository operations atomically with the delegate helper — it commits on success and rolls back on any exception, returning an envelope:

using ArturRios.Data.Relational.Core.Transactions;

public class OrderService(IAsyncRepository<Product> repo, IAsyncUnitOfWork unitOfWork)
{
 public Task<DataOutput<int>> CreateTwoAtomicallyAsync(Product a, Product b) =>
 unitOfWork.ExecuteInTransactionAsync(async () =>
 {
 var first = await repo.CreateAsync(a);
 await repo.CreateAsync(b);
 return first.Data;
 });
}

7. Optimistic concurrency

Derive an entity from VersionedEntity to opt in. On update, the stored ConcurrencyStamp is checked; if another writer changed the row, the update returns a concurrency-conflict error envelope (Success == false) instead of throwing:

var result = await repo.UpdateAsync(product);
if (!result.Success)
{
 // e.g. "Concurrency conflict: the record was modified or removed by another process."
}

8. Dapper read path (optional)

For raw-SQL reads alongside EF-based persistence, add ArturRios.Data.Dapper and register AddDapper() after AddDataConfigFromSettings:

dotnet add package ArturRios.Data.Dapper

using ArturRios.Data.Dapper;

builder.Services.AddSqliteProvider(); // or AddPostgreSqlProvider()
builder.Services.AddDataConfigFromSettings<AppDbContext>(builder.Configuration, "ArturRios.Data.Core");
builder.Services.AddDapper();

Inject IAsyncSqlQuery (or the sync ISqlQuery) and run enveloped, parameterized queries:

public class ReportService(IAsyncSqlQuery sql)
{
 public async Task<long> ActiveCountAsync()
 {
 var result = await sql.ExecuteScalarAsync<long>(
 "SELECT COUNT(*) FROM Products WHERE IsActive = @active", new { active = true });

 return result.Success ? result.Data : 0;
 }
}

ISqlQuery/IAsyncSqlQuery expose Query<T>, QueryFirstOrDefault<T>, QuerySingleOrDefault<T>, and ExecuteScalar<T> (all enveloped, generic T unconstrained so you can map to DTOs or scalars).

The Dapper path is read-only — all writes go through the EF repositories. It runs on the same DbContext connection and enlists in the active IUnitOfWork transaction, so a Dapper read inside a unit of work sees the not-yet-committed EF writes.

MySQL status

ArturRios.Data.MySql is written but deferred: it depends on Pomelo.EntityFrameworkCore.MySql, whose latest release still targets EF Core 9, while this library is on EF Core 10. The project is kept in the repository (excluded from the build) and will ship once Pomelo publishes an EF Core 10 release. An alternative provider (Oracle’s MySql.EntityFrameworkCore, which does support EF Core 10) is under consideration; it would trade Pomelo’s MySqlConnector (MIT, true async) and MariaDB support for immediate availability.