Configure ADO.NET providers

Orleans ADO.NET providers use a relational database for one or more runtime capabilities:

Capability	Package	Configure on
Clustering	`Microsoft.Orleans.Clustering.AdoNet`	Silos and external clients
Grain storage	`Microsoft.Orleans.Persistence.AdoNet`	Silos
Reminders	`Microsoft.Orleans.Reminders.AdoNet`	Silos
Grain directory	`Microsoft.Orleans.GrainDirectory.AdoNet`	Silos
Streaming	`Microsoft.Orleans.Streaming.AdoNet`	Silos and external clients

Install only the packages for the capabilities the application uses. Also reference the database driver package.

Prepare the database

Run the main script for the database first, followed by each capability script. For example, SQL Server clustering and persistence require:

src/AdoNet/Shared/SQLServer-Main.sql
src/AdoNet/Orleans.Clustering.AdoNet/SQLServer-Clustering.sql
src/AdoNet/Orleans.Persistence.AdoNet/SQLServer-Persistence.sql

See ADO.NET database configuration for schema script and invariant links.

Apply schema changes as a controlled deployment step. Don’t grant silos schema-owner permissions solely so they can create tables at runtime.

The scripts create tables and the OrleansQuery table using the database user’s default schema, and the provider queries refer to those objects by unqualified name. Orleans does not provide an option to select a schema or filegroup. If your production database requires a dedicated schema, filegroups, partitioning, or another storage layout, adapt the scripts as part of your database deployment and keep the resulting table names, columns, parameters, and query result shapes compatible with Orleans. Apply and test those changes outside the application startup path.

Configure SQL Server

Use Microsoft.Data.SqlClient for SQL Server:

public static void ConfigureAdoNetSilo(string[] args)
{
    var builder = Host.CreateApplicationBuilder(args);
    var connectionString =
        builder.Configuration.GetConnectionString("orleans")
        ?? throw new InvalidOperationException(
            "Connection string 'orleans' is required.");

    builder.UseOrleans(siloBuilder =>
    {
        siloBuilder.UseAdoNetClustering(options =>
        {
            options.Invariant = "Microsoft.Data.SqlClient";
            options.ConnectionString = connectionString;
        });

        siloBuilder.UseAdoNetReminderService(options =>
        {
            options.Invariant = "Microsoft.Data.SqlClient";
            options.ConnectionString = connectionString;
        });

        siloBuilder.AddAdoNetGrainStorageAsDefault(options =>
        {
            options.Invariant = "Microsoft.Data.SqlClient";
            options.ConnectionString = connectionString;
        });
    });
}

Configure an external client with the same clustering database:

public static void ConfigureAdoNetClient(
    IHostApplicationBuilder builder,
    string connectionString)
{
    builder.UseOrleansClient(clientBuilder =>
    {
        clientBuilder.UseAdoNetClustering(options =>
        {
            options.Invariant = "Microsoft.Data.SqlClient";
            options.ConnectionString = connectionString;
        });
    });
}

Configure another database

The Orleans configuration shape is the same for PostgreSQL, MySQL/MariaDB, and Oracle. Change the driver package, invariant, connection string, and SQL scripts together:

Database	Driver package	Invariant
SQL Server	`Microsoft.Data.SqlClient`	`Microsoft.Data.SqlClient`
PostgreSQL	`Npgsql`	`Npgsql`
MySQL/MariaDB	`MySql.Data`	`MySql.Data.MySqlClient`
Oracle	`Oracle.ManagedDataAccess.Core`	`Oracle.DataAccess.Client`

Orleans also recognizes MySqlConnector for the MySqlConnector driver. Verify that the selected capability has a script for the chosen database.

Use a data source

Each ADO.NET provider option type accepts either a connection string or a DbDataSource. A data source is useful when the database driver needs configuration which can’t be represented in a connection string, such as a periodically refreshed authentication token.

Configure exactly one connection source. Orleans rejects configurations which supply both ConnectionString and DataSource, or neither. Continue to set Invariant because Orleans uses it to select database-specific queries and behavior.

Register the data source as a singleton and resolve it through the provider’s OptionsBuilder configuration overload. Named Orleans providers can resolve distinct keyed data sources. The dependency injection container or application owns the data source and must keep it alive for the Orleans provider’s lifetime; Orleans opens and disposes individual connections but doesn’t dispose the data source.

Configure declaratively

Installed ADO.NET provider packages register AdoNet for declarative configuration. For example:

{
  "Orleans": {
    "ServiceId": "orders",
    "ClusterId": "orders-production",
    "Clustering": {
      "ProviderType": "AdoNet",
      "Invariant": "Microsoft.Data.SqlClient",
      "ConnectionString": "..."
    },
    "Reminders": {
      "ProviderType": "AdoNet",
      "Invariant": "Microsoft.Data.SqlClient",
      "ConnectionString": "..."
    },
    "GrainStorage": {
      "Default": {
        "ProviderType": "AdoNet",
        "Invariant": "Microsoft.Data.SqlClient",
        "ConnectionString": "..."
      }
    }
  }
}

Store connection strings in a secret provider or deployment environment, not in a committed settings file.

Operational guidance

Keep ServiceId stable so Orleans reads the expected application rows.
Size connection pools for the total number of silo and client processes.
Encrypt connections and use least-privilege database identities.
Monitor database latency, throttling, deadlocks, and pool exhaustion.
Test database failover and rolling deployment behavior under load.
Back up grain state according to application recovery objectives; membership rows are transient and don’t replace state backups.