┌─────────────────────────────────────────────────────────────────┐
│                        DatabasePools                            │
├─────────────────────────────────────────────────────────────────┤
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    PostgresRouter                         │  │
│  │  ┌─────────────────┐  ┌─────────────────┐                │  │
│  │  │ persons_reader  │  │ persons_writer  │  ← Persons DB  │  │
│  │  └─────────────────┘  └─────────────────┘    (optional)  │  │
│  │  ┌─────────────────┐  ┌─────────────────┐                │  │
│  │  │ non_persons_    │  │ non_persons_    │  ← Main DB     │  │
│  │  │ reader          │  │ writer          │                │  │
│  │  └─────────────────┘  └─────────────────┘                │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────┐                        │
│  │ behavioral_cohorts (optional)       │  ← Behavioral cohorts  │
│  └─────────────────────────────────────┘    database             │
└─────────────────────────────────────────────────────────────────┘

pub struct PoolConfig {
    pub min_connections: u32,        // Minimum idle connections to maintain
    pub max_connections: u32,        // Maximum connections in the pool
    pub acquire_timeout: Duration,   // Timeout for acquiring a connection
    pub idle_timeout: Option<Duration>, // Close idle connections after this duration
    pub test_before_acquire: bool,   // Validate connection health before use
    pub statement_timeout_ms: Option<u64>, // PostgreSQL statement_timeout per connection
    pub pool_name: Option<String>,   // Pool identity for connection creation metrics
}

With persons DB routing enabled:  4 pools × max_connections
With persons DB routing disabled: 2 pools × max_connections (pools are aliased)

pub struct PostgresRouter {
    pub persons_reader: PostgresReader,
    pub persons_writer: PostgresWriter,
    pub non_persons_reader: PostgresReader,
    pub non_persons_writer: PostgresWriter,
}

// Read person data - always include team_id for partition efficiency
let mut conn = router.get_persons_reader().get_connection().await?;
let person = sqlx::query(
    "SELECT * FROM posthog_person WHERE team_id = $1 AND id = $2"
)
    .bind(team_id)
    .bind(person_id)
    .fetch_optional(&mut *conn)
    .await?;

// Read flag definitions
let mut conn = router.get_non_persons_reader().get_connection().await?;
let flags = sqlx::query("SELECT * FROM posthog_featureflag WHERE team_id = $1")
    .bind(team_id)
    .fetch_all(&mut *conn)
    .await?;

pub fn is_transient_error(error: &SqlxError) -> bool

pub fn is_timeout_error(error: &SqlxError) -> bool
pub fn extract_timeout_type(error: &SqlxError) -> Option<&'static str>

pub fn is_foreign_key_constraint_error(error: &SqlxError) -> bool

let retry_strategy = ExponentialBackoff::from_millis(50)
    .max_delay(Duration::from_millis(300))
    .take(3)  // 3 attempts total
    .map(jitter);

let retry_strategy = ExponentialBackoff::from_millis(100)
    .max_delay(Duration::from_millis(300))
    .take(2)  // 2 attempts for writes
    .map(jitter);

# Connection creation rate per pool
rate(db_connection_created_total{pool="non_persons_reader"}[5m])

# Pool reuse rate (fraction of acquires that reused an existing connection)
1 - (
  rate(db_connection_created_total[5m])
  /
  sum without(operation) (rate(flags_db_connection_time_count[5m]))
)

pub struct PoolStats {
    pub size: u32,      // Current number of connections
    pub num_idle: usize, // Connections not currently in use
}

MAX_PG_CONNECTIONS=25  # Increase pool size
MIN_NON_PERSONS_READER_CONNECTIONS=5  # Keep connections warm
MIN_PERSONS_READER_CONNECTIONS=5

IDLE_TIMEOUT_SECS=600  # Keep connections warm longer
MIN_NON_PERSONS_READER_CONNECTIONS=3  # Pre-warm some connections

NON_PERSONS_READER_STATEMENT_TIMEOUT_MS=5000  # 5s for reads
PERSONS_READER_STATEMENT_TIMEOUT_MS=5000
WRITER_STATEMENT_TIMEOUT_MS=2000  # 2s for writes (should be fast)