Table of Contents

Class MySqlDatabaseConfig

Namespace
CL.MySQL2.Configuration
Assembly
CL.MySQL2.dll

Per-database MySQL connection settings.

public sealed class MySqlDatabaseConfig
Inheritance
MySqlDatabaseConfig
Inherited Members

Properties

AllowDestructiveSync

Legacy flag. When true, sync operates at Full regardless of SchemaSyncLevel. Prefer setting SyncMode directly.

[ConfigField(Label = "Allow Destructive Sync (legacy)", Description = "Deprecated — use Sync Mode = Developer/Migration instead.", Group = "Schema Sync", Order = 61, Collapsed = true)]
public bool AllowDestructiveSync { get; set; }

Property Value

bool

AllowPublicKeyRetrieval

Whether to allow servers without RSA public key. Default: false.

[ConfigField(Label = "Allow Public Key Retrieval", Description = "Needed for some MySQL 8+ configurations.", RequiresRestart = true, Group = "Security", Order = 42)]
public bool AllowPublicKeyRetrieval { get; set; }

Property Value

bool

BackupDirectory

Directory for schema backup files. Null = DataDirectory/backups.

[ConfigField(Label = "Backup Directory", Description = "Override where schema backups are stored. Blank = default data/backups folder.", Group = "Schema Sync", Order = 62, Collapsed = true)]
public string? BackupDirectory { get; set; }

Property Value

string

CacheEnabledOverride

Per-database override for the global cache switch. Null = inherit global Enabled; true/false forces on/off for this DB.

[ConfigField(Label = "Cache Enabled Override", Description = "Override the global cache switch for this database only. Leave empty to inherit.", Group = "Cache", Order = 70, Collapsed = true)]
public bool? CacheEnabledOverride { get; set; }

Property Value

bool?

CaptureExplainOnSlowQuery

When a slow query is detected, automatically capture EXPLAIN FORMAT=JSON and attach it to the SlowQueryEvent.

[ConfigField(Label = "Capture EXPLAIN On Slow", Description = "On slow query, run EXPLAIN FORMAT=JSON and attach to the event.", Group = "Observability", Order = 91, Collapsed = true)]
public bool CaptureExplainOnSlowQuery { get; set; }

Property Value

bool

CharacterSet

Connection character set. Default: "utf8mb4".

[ConfigField(Label = "Character Set", RequiresRestart = true, Group = "Advanced", Order = 50, Collapsed = true)]
public string CharacterSet { get; set; }

Property Value

string

Collation

Default collation. Default: "utf8mb4_unicode_ci".

[ConfigField(Label = "Collation", RequiresRestart = true, Group = "Advanced", Order = 51, Collapsed = true)]
public string Collation { get; set; }

Property Value

string

CommandTimeout

Command timeout in seconds. Default: 30.

[ConfigField(Label = "Command Timeout (s)", Min = 1, Max = 3600, Group = "Timeouts", Order = 31, Collapsed = true)]
public int CommandTimeout { get; set; }

Property Value

int

ConnectionLifetime

Maximum connection lifetime in seconds. Default: 300.

[ConfigField(Label = "Connection Lifetime (s)", Min = 0, RequiresRestart = true, Group = "Pooling", Order = 23, Collapsed = true)]
public int ConnectionLifetime { get; set; }

Property Value

int

ConnectionTimeout

Connection timeout in seconds. Default: 30.

[ConfigField(Label = "Connect Timeout (s)", Min = 1, Max = 600, Group = "Timeouts", Order = 30, Collapsed = true)]
public int ConnectionTimeout { get; set; }

Property Value

int

Database

Database (schema) name.

[ConfigField(Label = "Database", Description = "Name of the MySQL schema to use.", Required = true, RequiresRestart = true, Group = "Connection", Order = 12)]
public string Database { get; set; }

Property Value

string

DefaultStringSize

Default VARCHAR length when a string property has no explicit [Column(Size = …)]. Default: 255.

[ConfigField(Label = "Default String Size", Min = 1, Max = 65535, Description = "Default VARCHAR length for string columns without an explicit Size.", Group = "Schema Sync", Order = 63, Collapsed = true)]
public int DefaultStringSize { get; set; }

Property Value

int

EffectiveSyncLevel

Effective internal sync level. An explicitly chosen Developer or Migration always maps to Full. Otherwise (Production, the default) the legacy SchemaSyncLevel / AllowDestructiveSync knobs are honored for back-compat — so an old config with SchemaSyncLevel = Full still behaves destructively, while a fresh Production config (default Safe) never drops.

public SchemaSyncLevel EffectiveSyncLevel { get; }

Property Value

SchemaSyncLevel

EnablePooling

Whether connection pooling is enabled. Default: true.

[ConfigField(Label = "Enable Pooling", Description = "Use the MySqlConnector connection pool.", RequiresRestart = true, Group = "Pooling", Order = 20, Collapsed = true)]
public bool EnablePooling { get; set; }

Property Value

bool

EnableSsl

Whether to require SSL/TLS for connections. Default: false.

[ConfigField(Label = "Enable SSL/TLS", RequiresRestart = true, Group = "Security", Order = 40)]
public bool EnableSsl { get; set; }

Property Value

bool

Enabled

Whether this database connection is active.

[ConfigField(Label = "Enabled", Description = "Turn this connection on or off without removing it.", Group = "General", Order = 0)]
public bool Enabled { get; set; }

Property Value

bool

Host

MySQL server hostname or IP address.

[ConfigField(Label = "Host", Description = "MySQL server hostname or IP address.", Required = true, Placeholder = "localhost", RequiresRestart = true, Group = "Connection", Order = 10)]
public string Host { get; set; }

Property Value

string

IsMigrationMode

True when this database is configured for the one-shot Migration mode.

public bool IsMigrationMode { get; }

Property Value

bool

MaxBatchInsertSize

Chunk size used by InsertManyAsync when emitting batched INSERTs.

[ConfigField(Label = "Max Batch Insert Size", Min = 1, Max = 10000, Description = "Number of rows per batched INSERT statement.", Group = "Performance", Order = 80, Collapsed = true)]
public int MaxBatchInsertSize { get; set; }

Property Value

int

MaxInClauseValues

Maximum number of values allowed in a parameterized IN (...) clause.

[ConfigField(Label = "Max IN-Clause Values", Min = 1, Max = 65000, Description = "Above this, IN-clause queries auto-chunk or fall back to a temp table.", Group = "Performance", Order = 81, Collapsed = true)]
public int MaxInClauseValues { get; set; }

Property Value

int

MaxPoolSize

Maximum number of pooled connections. Default: 100.

[ConfigField(Label = "Max Pool Size", Min = 1, RequiresRestart = true, Group = "Pooling", Order = 22, Collapsed = true)]
public int MaxPoolSize { get; set; }

Property Value

int

MinPoolSize

Minimum number of pooled connections. Default: 1.

[ConfigField(Label = "Min Pool Size", Min = 0, RequiresRestart = true, Group = "Pooling", Order = 21, Collapsed = true)]
public int MinPoolSize { get; set; }

Property Value

int

N1DetectorThreshold

Warn when the same query template fires this many times inside a single request scope (AsyncLocal). 0 disables the detector.

[ConfigField(Label = "N+1 Detector Threshold", Min = 0, Description = "Warn when the same query template fires N times in one request scope. 0 disables.", Group = "Observability", Order = 90, Collapsed = true)]
public int N1DetectorThreshold { get; set; }

Property Value

int

Password

MySQL password.

[ConfigField(Label = "Password", InputType = ConfigInputType.Password, Secret = true, RequiresRestart = true, Group = "Connection", Order = 14)]
public string Password { get; set; }

Property Value

string

Port

MySQL server port. Default: 3306.

[ConfigField(Label = "Port", Min = 1, Max = 65535, RequiresRestart = true, Group = "Connection", Order = 11)]
public int Port { get; set; }

Property Value

int

PreparedStatementCacheSize

Per-connection prepared statement cache size.

[ConfigField(Label = "Prepared Statement Cache Size", Min = 0, Description = "Number of prepared statements kept per connection.", Group = "Performance", Order = 82, Collapsed = true)]
public int PreparedStatementCacheSize { get; set; }

Property Value

int

QueryTimeoutMs

Default per-query timeout in milliseconds. Maps to MySqlConnector's command timeout when it's finer than CommandTimeout (which is in seconds).

[ConfigField(Label = "Query Timeout (ms)", Min = 0, Description = "Default per-query timeout in ms. Used when no .WithTimeout() override is set.", Group = "Timeouts", Order = 32, Collapsed = true)]
public int QueryTimeoutMs { get; set; }

Property Value

int

SchemaSyncLevel

Legacy. Lower-level sync aggressiveness. Retained for back-compat; SyncMode takes precedence and maps onto this. See SchemaSyncLevel.

[ConfigField(Label = "Schema Sync Level (legacy)", Description = "Deprecated — use Sync Mode. Lower-level knob: Safe = additive only. Additive = also drops removed indexes/FKs. Full = also drops removed columns.", Group = "Schema Sync", Order = 60, Collapsed = true)]
public SchemaSyncLevel SchemaSyncLevel { get; set; }

Property Value

SchemaSyncLevel

Remarks

  • None — no sync at all.
  • Safe — add missing columns/indexes/FKs + modify existing columns. Never drops.
  • Additive — Safe + drop indexes and foreign keys no longer in the model.
  • Full — Additive + drop columns no longer in the model. Development only.

SlowQueryThresholdMs

Queries exceeding this threshold (ms) are logged as slow queries. Default: 1000.

[ConfigField(Label = "Slow Query Threshold (ms)", Min = 0, Description = "Queries taking longer than this are logged as slow.", Group = "Advanced", Order = 52, Collapsed = true)]
public int SlowQueryThresholdMs { get; set; }

Property Value

int

SslCertificatePath

Path to a client SSL certificate file. Optional.

[ConfigField(Label = "SSL Certificate Path", Description = "Optional path to a client certificate file.", RequiresRestart = true, Group = "Security", Order = 41)]
public string? SslCertificatePath { get; set; }

Property Value

string

SyncMode

Primary schema sync knob. See SyncMode. Default: Production (safe/additive, never drops).

[ConfigField(Label = "Sync Mode", Description = "How schema sync reconciles the DB with entity models. Production = additive only, never drops (default). Developer = drops removed columns/indexes without asking. Migration = one-shot destructive reconcile, then switch back to Production.", Group = "Schema Sync", Order = 59)]
public SyncMode SyncMode { get; set; }

Property Value

SyncMode

Remarks

  • Developer — aggressive rolling updates; drops removed columns/indexes/FKs without asking (every boot).
  • Production — default. Additive only; never drops. A change needing a drop is deferred and flagged DriftPending.
  • Migration — deliberate one-shot destructive reconcile (with backup). Idempotent; warns to switch back to Production once done.

In all modes, models whose stored CRC in __schema_state matches the current model are skipped entirely.

TransientRetryBaseDelayMs

Base backoff in milliseconds for transient retries; the delay grows exponentially (base × 2^attempt) with a little random jitter. Default: 50.

[ConfigField(Label = "Transient Retry Base Delay (ms)", Min = 0, Max = 10000, Description = "Base backoff for transient retries; grows exponentially with jitter.", Group = "Performance", Order = 84, Collapsed = true)]
public int TransientRetryBaseDelayMs { get; set; }

Property Value

int

TransientRetryCount

How many times to automatically retry a single non-transactional statement that fails with a transient error (deadlock 1213, lock-wait timeout 1205). 0 disables. Default: 3. Statements inside an explicit transaction scope are never auto-retried — the whole transaction must be retried by the caller.

[ConfigField(Label = "Transient Retry Count", Min = 0, Max = 10, Description = "Auto-retry deadlock / lock-wait-timeout on single statements. 0 disables.", Group = "Performance", Order = 83, Collapsed = true)]
public int TransientRetryCount { get; set; }

Property Value

int

Username

MySQL username.

[ConfigField(Label = "Username", Required = true, RequiresRestart = true, Group = "Connection", Order = 13)]
public string Username { get; set; }

Property Value

string

Methods

BuildConnectionString()

Builds and returns the MySqlConnector connection string from the current configuration.

public string BuildConnectionString()

Returns

string

Validate()

Validates the per-database configuration.

public ConfigValidationResult Validate()

Returns

ConfigValidationResult
Edit this page