> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Database

> Database architecture and configuration for Runlayer

# Database

Runlayer uses a robust, enterprise-grade database architecture with PostgreSQL as the primary data store and Redis for caching and session management.

## Database Architecture

### PostgreSQL (Primary Database)

```mermaid theme={null}
graph TB
    subgraph "RDS PostgreSQL"
        Primary[(Primary Instance)]
        Standby[(Standby Instance)]
        Backup[(Automated Backups)]
    end

    subgraph "Application Layer"
        App1[Gateway Service]
        App2[Auth Service]
        App3[Worker Service]
    end

    App1 --> Primary
    App2 --> Primary
    App3 --> Primary
    Primary --> Standby
    Primary --> Backup
```

### Redis (Cache & Sessions)

```mermaid theme={null}
graph TB
    subgraph "ElastiCache Redis"
        Redis1[(Redis Primary)]
        Redis2[(Redis Replica)]
    end

    subgraph "Application Layer"
        Gateway[Gateway Service]
        Auth[Auth Service]
    end

    Gateway --> Redis1
    Auth --> Redis1
    Redis1 --> Redis2
```

## PostgreSQL Configuration

### High Availability

* **Multi-AZ Deployment**: Automatic failover to standby instance
* **Read Replicas**: Optional read-only replicas for scaling
* **Automated Backups**: Point-in-time recovery with 35-day retention
* **Maintenance Windows**: Scheduled maintenance with minimal downtime

### Performance Optimization

* **Connection Pooling**: PgBouncer for efficient connection management
* **Query Optimization**: Automated query performance insights
* **Storage**: GP3 SSD with configurable IOPS and throughput
* **Monitoring**: CloudWatch metrics and Performance Insights

### Security

* **Encryption at Rest**: AES-256 encryption for all data
* **Encryption in Transit**: Configurable SSL/TLS enforcement via `force_ssl` parameter (defaults to optional)
* **Field-Level Encryption**: Sensitive values such as OAuth access/refresh tokens and client secrets are additionally encrypted at the application level before being written to their columns (see the [OAuth Broker FAQ](/oauth-broker#faq))
* **Network Isolation**: Private subnets with security groups
* **Access Control**: IAM database authentication
* **Transport Security**: Aurora PostgreSQL supports both optional and mandatory SSL connections
* **Parameter Groups**: Custom parameter groups with configurable security policies

## Redis Configuration

### Caching Strategy

* **Session Storage**: User sessions and authentication tokens
* **Application Cache**: Frequently accessed data caching
* **Rate Limiting**: API rate limiting and throttling
* **Background Jobs**: Task queue and job processing

### High Availability

* **Cluster Mode**: Multi-node cluster for high availability
* **Automatic Failover**: Seamless failover to replica nodes
* **Backup and Restore**: Automated snapshots and recovery
* **Cross-AZ Replication**: Data replication across availability zones

## Database Schema

### Core Tables

* **Users**: User accounts and profiles
* **Organizations**: Multi-tenant organization data
* **Resources**: Managed cloud resources
* **Policies**: Governance and access policies
* **Audit Logs**: Comprehensive audit trail
* **Configurations**: System and user configurations

### Indexing Strategy

* **Primary Keys**: Optimized for fast lookups
* **Foreign Keys**: Referential integrity and join performance
* **Composite Indexes**: Multi-column indexes for complex queries
* **Partial Indexes**: Conditional indexes for specific use cases

## Enterprise Database Services

For advanced database requirements, including:

* **Database Design Optimization** - Schema design and query optimization
* **Performance Tuning** - Database performance analysis and tuning
* **Scaling Strategy** - Read replicas and sharding strategies
* **Backup and Recovery** - Custom backup and disaster recovery plans
* **Security Hardening** - Advanced database security configuration
* **Compliance Support** - Regulatory compliance and data governance

<Card title="Enterprise Database Services" icon="database" href="mailto:support@runlayer.com">
  Contact our database experts for optimization, scaling, and advanced
  configuration
</Card>

## Monitoring and Maintenance

### Performance Monitoring

* **Query Performance**: Slow query analysis and optimization
* **Resource Utilization**: CPU, memory, and storage monitoring
* **Connection Monitoring**: Connection pool and session tracking
* **Cache Hit Rates**: Redis cache performance metrics

### Automated Maintenance

* **Backup Verification**: Regular backup integrity testing
* **Index Maintenance**: Automated index optimization
* **Statistics Updates**: Query planner statistics refresh
* **Log Rotation**: Automated log management and archival

## Connection Pool Configuration

### Database Connection Pool Settings

The database connection pool is configurable to handle high-concurrency workloads. These settings control how the application manages database connections:

#### ECS/Terraform Configuration

Configure connection pool settings in your `terraform.tfvars`:

```hcl theme={null}
database_config = {
  # ... other database settings ...

  # Connection pool settings (optional - defaults shown)
  pool_size     = 100       # Base connections maintained in pool (default: 100)
  max_overflow  = 30        # Additional connections beyond pool_size (default: 30)
  pool_timeout  = 30        # Seconds to wait for connection (default: 30)
  pool_recycle  = 3600      # Seconds before recreating connections (default: 3600)
  pool_pre_ping = true      # Test connections before use (default: true)
}
```

**Total Available Connections**: `pool_size + max_overflow` (e.g., 100 + 30 = 130 concurrent connections)

#### Helm Configuration

Configure connection pool settings in your `values.yaml`:

```yaml theme={null}
backend:
  env:
    DB_POOL_SIZE: "100" # Base connections in pool
    DB_MAX_OVERFLOW: "30" # Additional connections beyond pool_size
    DB_POOL_TIMEOUT: "30" # Connection timeout in seconds
    DB_POOL_RECYCLE: "3600" # Connection recreation interval (seconds)
    DB_POOL_PRE_PING: "true" # Enable connection health checks
```

#### Connection Pool Parameters

| Parameter       | Description                                                         | Default | Recommended Range  |
| --------------- | ------------------------------------------------------------------- | ------- | ------------------ |
| `pool_size`     | Base number of connections maintained in the pool                   | 100     | 20-100             |
| `max_overflow`  | Additional connections beyond pool\_size when needed                | 30      | 20-100             |
| `pool_timeout`  | Seconds to wait for an available connection                         | 30      | 15-60              |
| `pool_recycle`  | Seconds before recreating a connection (prevents stale connections) | 3600    | 1800-7200          |
| `pool_pre_ping` | Test connections before use to handle disconnections                | true    | true (recommended) |

#### Sizing Guidelines

* **Low Traffic**: pool\_size=20, max\_overflow=20 (40 total connections)
* **Medium Traffic**: pool\_size=100, max\_overflow=30 (130 total connections)
* **High Traffic**: pool\_size=100, max\_overflow=100 (200 total connections)

⚠️ **Important**: Ensure your RDS instance can handle the total number of connections. Aurora PostgreSQL supports up to 5000 connections per instance by default.

## SSL Connection Configuration

### Database SSL Configuration

The RDS cluster SSL enforcement is configurable via the `force_ssl` parameter in `database_config`:

```hcl theme={null}
database_config = {
  force_ssl = 1  # 1 = SSL required, 0 = SSL optional (default)
}
```

**When `force_ssl = 1` (SSL Required)**:

* All connections without SSL will be rejected
* Applications **must** include SSL parameters in connection strings
* Use `sslmode=require` or stronger in connection strings

**When `force_ssl = 0` (SSL Optional - Default)**:

* Both SSL and non-SSL connections are accepted
* SSL is still recommended for security
* Applications can optionally use SSL parameters

### Application Configuration

### Connection Examples

**Python (SQLAlchemy)**:

```python theme={null}
# When force_ssl = 1 (required)
DATABASE_URL = "postgresql://username:password@host:5432/database?sslmode=require"

# When force_ssl = 0 (optional) - SSL recommended
DATABASE_URL = "postgresql://username:password@host:5432/database?sslmode=prefer"

# When force_ssl = 0 (optional) - Non-SSL (not recommended)
DATABASE_URL = "postgresql://username:password@host:5432/database"
```

**Node.js (pg)**:

```javascript theme={null}
const config = {
  host: "your-aurora-endpoint",
  port: 5432,
  database: "your-database",
  user: "username",
  password: "password",
  ssl: {
    require: true,
    rejectUnauthorized: false, // Set to true in production with proper CA
  },
};
```

**Go (pq)**:

```go theme={null}
connStr := "postgres://username:password@host:5432/database?sslmode=require"
```

### SSL Certificate Download

AWS RDS uses Amazon-provided SSL certificates. Download the certificate bundle:

```bash theme={null}
wget https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem
```

For production environments, use `sslmode=verify-full` with the certificate bundle for maximum security.

## Best Practices

* **Regular Backups**: Automated daily backups with point-in-time recovery
* **Security Updates**: Automated security patching during maintenance windows
* **Performance Monitoring**: Continuous monitoring with alerting
* **Capacity Planning**: Proactive scaling based on usage patterns
* **Data Retention**: Automated data archival and cleanup policies
* **SSL Enforcement**: Always use SSL connections with certificate validation in production

Contact our database team for custom database architecture, performance optimization, and enterprise-grade database management.