feat: implement database sharding strategy (#602)

.env.example

@@ -144,7 +144,6 @@ ENABLE_CDN=true
 CLUSTER_MODE=false
 CLUSTER_WORKERS=4
 
-# =============================================================================
 # Secrets Management Configuration
 # =============================================================================
 # Secret provider: 'env' (default), 'aws' (AWS Secrets Manager), or 'vault' (HashiCorp Vault)
@@ -178,3 +177,56 @@ CIRCUIT_BREAKER_RESET_TIMEOUT_MS=30000
 CIRCUIT_BREAKER_ROLLING_COUNT_TIMEOUT=60000
 # Number of stat buckets for rolling window
 CIRCUIT_BREAKER_ROLLING_COUNT_BUCKETS=10
+
+# =============================================================================
+# Database Sharding (#602)
+# =============================================================================
+# Set SHARD_COUNT=0 (or omit) to run in single-shard fallback mode using the
+# DATABASE_* variables above. Set SHARD_COUNT>0 to enable multi-shard routing.
+# =============================================================================
+
+SHARD_COUNT=0
+
+# ── Example: 3-shard setup (uncomment and adjust when SHARD_COUNT=3) ────────
+# SHARD_0_HOST=pg-shard-0.internal
+# SHARD_0_PORT=5432
+# SHARD_0_USER=teachlink
+# SHARD_0_PASSWORD=<secret>
+# SHARD_0_DB=teachlink_0
+# SHARD_0_POOL_MAX=30
+# SHARD_0_POOL_MIN=5
+# SHARD_0_WEIGHT=100
+# SHARD_0_REGION=us-east-1
+# SHARD_0_STATUS=active
+# SHARD_0_REPLICA_COUNT=1
+# SHARD_0_REPLICA_0_HOST=pg-replica-0.internal
+# SHARD_0_REPLICA_0_PORT=5432
+# SHARD_0_REPLICA_0_WEIGHT=100
+
+# SHARD_1_HOST=pg-shard-1.internal
+# SHARD_1_PORT=5432
+# SHARD_1_USER=teachlink
+# SHARD_1_PASSWORD=<secret>
+# SHARD_1_DB=teachlink_1
+# SHARD_1_POOL_MAX=30
+# SHARD_1_POOL_MIN=5
+# SHARD_1_WEIGHT=100
+# SHARD_1_REGION=us-west-2
+# SHARD_1_STATUS=active
+
+# SHARD_2_HOST=pg-shard-2.internal
+# SHARD_2_PORT=5432
+# SHARD_2_USER=teachlink
+# SHARD_2_PASSWORD=<secret>
+# SHARD_2_DB=teachlink_2
+# SHARD_2_POOL_MAX=30
+# SHARD_2_POOL_MIN=5
+# SHARD_2_WEIGHT=100
+# SHARD_2_REGION=eu-west-1
+# SHARD_2_STATUS=active
+
+# ── Rebalance Thresholds ──────────────────────────────────────────────────────
+SHARD_REBALANCE_HIGH_WATERMARK=80
+SHARD_REBALANCE_LOW_WATERMARK=20
+SHARD_REBALANCE_BATCH_SIZE=500
+>>>>>>> e142fba (feat: implement database sharding strategy (#602))