DataLinq.Tools 0.7.0

DataLinq

Documentation website | Getting started | Changelog

DataLinq is an immutable-first, source-generated ORM for .NET. It is built for applications where repeated reads, relation traversal, predictable object state, and cache behavior matter more than having an ORM translate every possible LINQ expression.

The short version: DataLinq moves work into generation and metadata so the runtime can do less guessing.

Why DataLinq Exists

Most ORMs optimize for convenience first. That is useful, but it often means mutable tracked entities, runtime mapping, hidden query behavior, and late surprises.

DataLinq makes a narrower trade:

• Generated model surface: source generators create the concrete immutable and mutable types.
• Immutable reads: query results are stable objects, not ambient mutable state.
• Explicit writes: updates go through mutable wrappers and transactions instead of hidden dirty tracking.
• Cache-aware relations: repeated primary-key reads and relation traversal can reuse cached rows.
• Honest LINQ support: documented query shapes are backed by tests; unsupported shapes should fail clearly.
• Schema trust tooling: validate and diff compare generated model metadata against live provider metadata without pretending to be full migrations.

It is currently focused on SQLite, MySQL, and MariaDB for .NET 8, .NET 9, and .NET 10.

When It Fits

DataLinq is a strong fit for read-heavy applications, small-to-medium relational databases, generated model workflows, and systems where explicit mutation boundaries are a feature rather than a nuisance.

It is not trying to be a universal EF replacement, a full migration engine, or a provider that translates arbitrary LINQ. That restraint is intentional.

Getting Started

Installation

Install the provider package that matches your runtime database:

# MySQL and MariaDB
dotnet add package DataLinq.MySql

# SQLite
dotnet add package DataLinq.SQLite

The CLI is installed as a dotnet tool named datalinq:

dotnet tool install --global DataLinq.CLI

Current package and repo builds target .NET 8, .NET 9, and .NET 10.

Configuration

The CLI reads datalinq.json and, if present next to it, datalinq.user.json.

Minimal example:

{
  "Databases": [
    {
      "Name": "AppDb",
      "CsType": "AppDb",
      "Namespace": "MyApp.Models",
      "ModelDirectory": "Models",
      "Connections": [
        {
          "Type": "MariaDB",
          "DataSourceName": "appdb",
          "ConnectionString": "Server=localhost;Database=appdb;User ID=app;Password=secret;"
        }
      ]
    }
  ]
}

Generate your data models directly from your database schema:

datalinq create-models -n AppDb

Generated C# files are marked as DataLinq-generated and declare their nullable context. Nullable reference generation is enabled by default; set "UseNullableReferenceTypes": false in the database config to opt out.

Validate your configured models against the live database:

datalinq validate -n AppDb

validate exits with 0 when no drift is found, 1 when schema drift is detected, and 2 for command, configuration, metadata, or validation issues. Use --output json when wiring the result into automation; JSON output includes structured validation issues as well as drift differences.

Generate a conservative SQL suggestion script for supported additive drift:

datalinq diff -n AppDb -o update_schema.sql

diff is read-only. It comments destructive, ambiguous, or unsupported changes instead of applying them. If validation issues exist, diff reports them and writes no SQL file.

If your config contains more than one database, pass -n. If the selected database contains more than one connection type, pass -t.

Code Example

using DataLinq;
using DataLinq.MySql;
using MyApp.Models;

var db = new MySqlDatabase<AppDb>(connectionString);

var activeUsers = db.Query().Users
    .Where(x => x.IsActive)
    .ToList();

var user = db.Query().Users.Single(x => x.UserId == userId);
var updatedUser = user.Mutate(x => x.DisplayName = "Updated Name").Save();

Documentation

If you want the website-first docs experience, start here:

• Website Home
• Docs Intro
• Changelog
• Roadmap
• Installation
• Configuration and Model Generation
• Your First Query and Update

After that, the deeper working docs are:

• Querying
• Caching and Mutation
• Diagnostics and Metrics
• Supported LINQ Queries
• Platform Compatibility
• Transactions
• Attributes and Model Definitions
• Internals
• Troubleshooting

License

DataLinq is open source and distributed under the MIT License. See the LICENSE file for more details.