Table of Contents

Configuration and Model Generation

For most new projects, the CLI-driven path is the right way to get started.

The job here is simple:

  1. create or complete datalinq.json and datalinq.user.json
  2. run generate models
  3. inspect the generated output

Create the Config Files

For a new project, run:

datalinq config init

The wizard writes shared structure to datalinq.json and local connection details to datalinq.user.json. For MySQL and MariaDB password-bearing connection strings, the default password slot is a prompt reference instead of plaintext.

When you clone a project that already has datalinq.json, run the same command. If datalinq.user.json is missing, DataLinq switches into local setup mode and creates only the user file.

New shared configs include the public schema URL for editor autocomplete:

{
  "$schema": "https://datalinq.org/schemas/datalinq.schema.json",
  "Databases": []
}

You can also write the config by hand.

Minimal MariaDB or MySQL example:

{
  "$schema": "https://datalinq.org/schemas/datalinq.schema.json",
  "Databases": [
    {
      "Name": "AppDb",
      "CsType": "AppDb",
      "Namespace": "MyApp.Models",
      "ModelDirectory": "Models",
      "Connections": [
        {
          "Type": "MariaDB",
          "DataSourceName": "appdb",
          "ConnectionString": "Server=localhost;Database=appdb;User ID=app;Password=${env:DATALINQ_APPDB_PASSWORD};"
        }
      ]
    }
  ]
}

For MySQL, change "Type": "MariaDB" to "Type": "MySQL".

Minimal SQLite example:

{
  "$schema": "https://datalinq.org/schemas/datalinq.schema.json",
  "Databases": [
    {
      "Name": "AppDb",
      "CsType": "AppDb",
      "Namespace": "MyApp.Models",
      "ModelDirectory": "Models",
      "Connections": [
        {
          "Type": "SQLite",
          "DataSourceName": "app.db",
          "ConnectionString": "Data Source=app.db;Cache=Shared;"
        }
      ]
    }
  ]
}

Keep Secrets Out of the Shared File

Use datalinq.user.json for machine-local overrides such as real connection strings.

That is the sane setup:

  • datalinq.json for shared structure
  • datalinq.user.json for local connection details

For secrets inside CLI connection strings, use one of these references:

  • ${env:DATALINQ_APPDB_PASSWORD} for CI and shell-managed local setup
  • ${secret:datalinq/AppDb/password} for DataLinq local secrets
  • ${prompt:AppDb password} for interactive one-off runs

Set a DataLinq local secret with:

datalinq secrets set datalinq/AppDb/password

Local DataLinq secrets currently use Windows Credential Manager on Windows. On macOS and Linux, use environment variables or prompt references until a secure local backend is available.

If you want the exact merge behavior and full field reference, use Configuration Files.

Generate Models

Once the config exists, generate the model surface:

datalinq generate models -n AppDb

If the selected database has more than one provider type configured, pass -p as well:

datalinq generate models -n AppDb -p MariaDB

What Gets Generated

After generation, expect a generated model surface that gives you:

  • a database model type such as AppDb
  • generated immutable row types
  • generated mutable row types
  • generated helper extensions such as mutation helpers

Generated C# files begin with a DataLinq generated-file banner and an explicit nullable directive. The default is nullable reference generation on, so new output normally starts with:

// <auto-generated />
// Generated by DataLinq. Supported model class names, property names, relation names, and C# property types may be edited.
// See https://datalinq.org/docs/model-generation.html before changing mapping attributes or using --fresh.
#nullable enable

If you need the old non-nullable-reference generated shape, set "UseNullableReferenceTypes": false on the database entry in datalinq.json. DataLinq then emits #nullable disable in generated files.

The model declaration files are regenerated files with a supported edit surface. It is OK to rename generated model classes, scalar properties, relation properties, and C# property types. Put custom methods and behavior in separate partial classes.

For the exact rules, see Model Generation.

Regenerating With Custom Types

When generate models runs against existing files in ModelDirectory, DataLinq preserves source-defined C# property types that it cannot safely infer from database metadata. This is especially important for enums shared across several model files.

For MySQL and MariaDB ENUM columns:

  • if the enum is not already represented in source, generate models generates a C# enum declaration
  • if the enum declaration is in the model file, regeneration keeps that declaration
  • if the property references an enum declared in another source file, regeneration keeps the property type and [Enum(...)] metadata but does not emit a duplicate enum declaration into the model file

That lets you centralize shared enum types without fighting regeneration.

Existing Namespaces and Usings

If generate models updates existing model files, it preserves the namespace and existing using directives for the database, table, and view files it can match. New files still use the namespace from datalinq.json.

Optional: Generate SQL From Models

If you want schema SQL from the model metadata:

datalinq generate sql -n AppDb -o schema.sql

What to Do Next

Now that the models exist, move to:

Edit this page