Skip to content

Orleans Clustering - ADO.NET

Overview

ADO.NET clustering enables Orleans silos to discover each other and form a cluster using a relational database as the membership table. This is ideal for production environments requiring transactional consistency and supports multiple database providers: SQL Server, PostgreSQL, MySQL/MariaDB, and Oracle.

Configuration

SQL Server Example

{
  "Orleans": {
    "ClusteringSettings": {
      "ProviderType": "AdoNet",
      "AdoNet": {
        "ConnectionString": "Server=localhost;Database=MICROSERVICE_ORLEANS_DATABASE;User Id=sa;Password=YourPassword;MultipleActiveResultSets=true;Encrypt=false;TrustServerCertificate=true;",
        "Invariant": "Microsoft.Data.SqlClient",
        "TableName": "OrleansMembershipTable"
      }
    }
  }
}

PostgreSQL Example

{
  "Orleans": {
    "ClusteringSettings": {
      "ProviderType": "AdoNet",
      "AdoNet": {
        "ConnectionString": "Host=localhost;Port=5432;Database=MICROSERVICE_ORLEANS_DATABASE;Username=postgres;Password=YourPassword;",
        "Invariant": "Npgsql",
        "TableName": "OrleansMembershipTable"
      }
    }
  }
}

MySQL Example

{
  "Orleans": {
    "ClusteringSettings": {
      "ProviderType": "AdoNet",
      "AdoNet": {
        "ConnectionString": "Server=localhost;Port=3306;Database=MICROSERVICE_ORLEANS_DATABASE;user=root;password=YourPassword;SSL Mode=Disabled;",
        "Invariant": "MySql.Data.MySqlClient",
        "TableName": "OrleansMembershipTable"
      }
    }
  }
}

Setup Instructions

1. Database Setup

For SQL Server, the clustering tables are automatically created by executing the SQLServer-Clustering.sql script located at Scripts/OrleansScripts/SqlServer/SQLServer-Clustering.sql.

The script creates: - OrleansMembershipVersionTable - Version table for membership tracking - OrleansMembershipTable - Membership table containing silo information - Required stored procedures and queries

Note: For other database providers (PostgreSQL, MySQL, Oracle), you need to manually create equivalent tables using the appropriate SQL scripts from the Orleans SQL Scripts Repository.

2. Connection String Configuration

Ensure the connection string: - Points to the correct database - Has appropriate permissions (CREATE TABLE, INSERT, UPDATE, DELETE, SELECT) - Uses the correct authentication method

3. Database Provider Invariant

Set the Invariant property to match your database provider:

Database Invariant
SQL Server (.NET Core) Microsoft.Data.SqlClient
SQL Server (.NET Framework) System.Data.SqlClient
PostgreSQL Npgsql
MySQL/MariaDB MySql.Data.MySqlClient
Oracle Oracle.DataAccess.Client

Configuration Options

Property Type Required Default Description
ConnectionString string Yes - Connection string for the ADO.NET clustering database
Invariant string Yes "Microsoft.Data.SqlClient" Database provider invariant name
TableName string No "OrleansMembershipTable" Name of the membership table

Automatic Script Execution

For SQL Server, the clustering script is automatically executed on startup if: - The invariant is Microsoft.Data.SqlClient or System.Data.SqlClient - The database exists (or is created automatically) - The script file is present at Scripts/OrleansScripts/SqlServer/SQLServer-Clustering.sql

Validation

The configuration is validated at startup: - ConnectionString must be provided - Invariant must be provided - Database connectivity is verified

Health Checks

The template includes OrleansAdoNetClusteringHealthCheck which verifies: - Database connectivity - Clustering table existence - Database provider availability

Troubleshooting

Common Issues

  1. Script Execution Failed
  2. Verify the database exists and is accessible
  3. Check that the connection string has CREATE TABLE permissions
  4. Ensure the script file exists at the expected path

  5. Review application logs for detailed error messages

  6. Connection Failed

  7. Verify the connection string is correct
  8. Check database server is running and accessible
  9. Verify network connectivity and firewall rules

  10. Ensure authentication credentials are correct

  11. Table Already Exists

  12. The script uses IF NOT EXISTS checks, so existing tables are preserved

  13. If you need to recreate tables, drop them manually first

  14. Provider Not Found

  15. Ensure the correct database driver NuGet package is installed
  16. Verify the invariant name matches the installed provider
  17. Check that the provider is registered in the application

Best Practices

  1. Use separate databases for different environments (dev, staging, prod)
  2. Implement database backup and recovery strategies
  3. Monitor database performance and connection pool usage
  4. Use connection pooling for better performance
  5. Configure appropriate database indexes for large clusters
  6. Use transactional consistency guarantees for critical deployments

Multi-Silo Deployment

For multi-silo deployments: 1. Ensure all silos use the same ClusterId and ServiceId 2. Point all silos to the same database 3. Verify network connectivity between silos and the database 4. Monitor cluster membership through the Orleans Dashboard

References