Configuration

Introduction

Configuration is normalized through ConnectionConfig. You can pass plain arrays, and DBLayer applies driver defaults, alias normalization, and basic validation before creating the connection.

Connection Setup

DB::addConnection([
    'driver' => 'mysql',
    'host' => '127.0.0.1',
    'port' => 3306,
    'database' => 'app_db',
    'username' => 'app_user',
    'password' => 'secret',
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
], 'mysql_main');

Default Behavior

• Driver aliases are normalized (for example postgresql -> pgsql).

• Driver-specific defaults are applied when values are missing.

• Security settings are merged with safe defaults.

Important Keys

• driver, host, port, database, username, password

• read / write split

• read_strategy, read_health_cooldown, sticky

• read_latency_ttl, read_probe_sample_size, read_session_read_only

• statement_cache_enabled, statement_cache_size

• query_comment_enabled, query_comment_max_length, query_comment_context

• security limits and transport policy

Read/Write Config Shape

read and write can be provided as:

• Single associative array

• List of associative arrays

• Host-array variant (expanded internally)

That allows compact config in small projects and explicit lists in production.

Replica + Cache + Comment Defaults

• read_latency_ttl: 15 seconds.

• read_probe_sample_size: 0 (probe all eligible replicas).

• read_session_read_only: false.

• statement_cache_enabled: false (default is intentionally conservative).

• statement_cache_size: 64.

• query_comment_enabled: false.

• query_comment_max_length: 160.

• query_comment_context: [].

Statement cache is disabled by default. Enable it only after validating behavior for your driver/workload and benchmarking repeated prepared SQL shapes.

Security Block

'security' => [
    'enabled' => true,
    'max_sql_length' => 16384,
    'max_params' => 512,
    'max_param_bytes' => 1024,
    'queries_per_second' => 0,
    'queries_per_minute' => 0,
    'rate_limit_key' => null,
    'rate_limit_callback' => null,
    'strict_identifiers' => true,
    'require_tls' => null,
    'allow_insecure' => false,
    'raw_sql_policy' => 'allow', // allow | deny | allowlist
    'raw_sql_allowlist' => [],
]

Config-Driven Hardening

• security.require_tls=true forces TLS for MySQL/PostgreSQL.

• security.require_tls=false requires security.allow_insecure=true.

• security.enabled=false requires security.allow_insecure=true.

Facade helpers:

• DB::setSecurityDefaults([...]) enforces defaults over connection-level values.

• DB::hardenProduction() applies hardened defaults (enabled=true, strict_identifiers=true, require_tls=true).

Production Guidance

• Keep security.enabled true unless you have a controlled benchmark-only use case.

• Set explicit query limits for multi-tenant workloads.

• In high-trust production environments, set raw_sql_policy to allowlist and explicitly list permitted fragments.

• Set explicit TLS parameters (sslmode and/or driver TLS keys) for all remote MySQL/PostgreSQL links.

• Use named connections for operational clarity (primary, reporting, etc.).

Recommended Production Baseline

Use this as an opinionated starting point and tune limits for your workload:

DB::addConnection([
    'driver' => 'mysql',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => (int) env('DB_PORT', 3306),
    'database' => env('DB_DATABASE', 'app'),
    'username' => env('DB_USERNAME', 'app'),
    'password' => env('DB_PASSWORD', ''),
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',

    'security' => [
        'enabled' => true,
        'strict_identifiers' => true,
        'require_tls' => true,
        'raw_sql_policy' => 'allowlist',
        'raw_sql_allowlist' => [
            '/^id\\s*=\\s*\\?$/i',
            'count(*)',
        ],
        'max_sql_length' => 16384,
        'max_params' => 512,
        'max_param_bytes' => 2048,
    ],

    // Keep conservative defaults unless profiling proves benefit.
    'statement_cache_enabled' => false,
    'statement_cache_size' => 64,

    // Useful for traceability when comment context is sanitized and bounded.
    'query_comment_enabled' => true,
    'query_comment_max_length' => 160,
    'query_comment_context' => [
        'app' => 'api',
        'env' => 'prod',
    ],
], 'primary');

Why this baseline:

• keeps SQL validation and strict identifiers on

• enforces TLS by default

• blocks unrestricted raw SQL fragments

• keeps statement cache opt-in until benchmarked

• enables low-risk SQL comment trace context

Note

Keep config values environment-driven in deployed environments. Treat connection arrays in source code as examples, not secret storage.