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. Blank (the default) keeps BackupManager writing to DataDirectory/backups; when set, backups for this connection are written to (and read back from) the given directory.

[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 (the default) inherits Enabled; a non-null value wins over it for queries running on this connection.

[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 true, a slow query additionally runs EXPLAIN FORMAT=JSON on a separate pooled connection (never the caller's transaction) and attaches the plan to SlowQueryEvent.ExplainJson. Strictly best-effort: statements that cannot be explained (DDL, multi-statement batches) are skipped and any failure is swallowed — the event still publishes, with a null payload. Default: false.

[ConfigField(Label = "Capture EXPLAIN On Slow", Description = "On a slow query, run EXPLAIN FORMAT=JSON on a separate connection and attach the plan to SlowQueryEvent.", 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". Informational only — it is not written into the connection string; table collation comes from [Table(Collation = ...)].

[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 used by type inference when a string property has no explicit [Column(Size = …)]. Applied process-wide at library initialization from the Default database (or the first enabled one) — DDL generation is not connection-scoped. 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 for InsertManyAsync / UpsertManyAsync: rows per batched statement. Passed to every Repository<T> created by MySQL2Library.GetRepository<T>. Default: 500.

[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

Advisory ceiling on the number of values in a generated IN (...) clause. Nothing is chunked or rejected — a collection Contains still emits one parameter per value — but a translation that exceeds this logs one warning naming the entity and the count. Default: 1000.

[ConfigField(Label = "Max IN-Clause Values", Min = 1, Max = 65000, Description = "Warn (once per query build) when a generated IN (...) list exceeds this many values. Nothing is chunked or rejected.", 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

Publish N1QueryDetectedEvent when the same normalized query template executes this many times on this connection within a one-second rolling window. The event fires once per window, not on every further execution. 0 (the default) disables detection entirely, and costs nothing on the query path.

[ConfigField(Label = "N+1 Detector Threshold", Min = 0, Description = "Publish N1QueryDetectedEvent when one query template repeats this many times within a second. 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

Obsolete and ignored. Statement caching is the provider's concern: set MySqlConnector's IgnorePrepare=false on the connection string instead. Retained so existing config files keep deserializing.

[Obsolete("Statement caching is configured on the MySqlConnector connection string (IgnorePrepare=false); this value is ignored.")]
[ConfigField(Label = "Prepared Statement Cache Size", Min = 0, Description = "Obsolete and ignored — configure statement caching on the MySqlConnector connection string (IgnorePrepare=false).", Group = "Performance", Order = 82, Collapsed = true)]
public int PreparedStatementCacheSize { get; set; }

Property Value

int

QueryTimeoutMs

Default per-query timeout in milliseconds, applied as CommandTimeout on the commands the repository, query builder, projections, joins and the raw-SQL helpers create (rounded up to whole seconds — MySqlConnector's unit). 0 leaves each command at the connection string's CommandTimeout. Default 30000 matches that 30s default, so the effective timeout is unchanged unless you change this.

[ConfigField(Label = "Query Timeout (ms)", Min = 0, Description = "Per-query command timeout in ms (rounded up to seconds). 0 = use the connection's Command Timeout.", 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 PEM certificate-authority file used to verify the server's certificate. Optional; only honoured when EnableSsl is true, in which case it is written to the connection string as MySqlConnector's SslCa and the SSL mode is raised to MySqlConnector.MySqlSslMode.VerifyCA (a CA is pointless without verification). Blank leaves the connection at SslMode=Required with no chain validation.

[ConfigField(Label = "SSL CA Certificate Path", Description = "Optional PEM CA file used to verify the server certificate. Applied only when SSL is enabled; raises SSL mode to VerifyCA.", 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