# MariaDB Cloud Serverless Architecture

This document provides a comprehensive technical overview of MariaDB Cloud Serverless architecture, explaining how it achieves true serverless capabilities while maintaining full compatibility with MySQL and MariaDB.

## Design Philosophy

MariaDB Cloud Serverless is built on the principle: **"Don't change what works"**. Instead of re-architecting the database engine like other cloud providers, MariaDB Cloud leverages cloud-native techniques to achieve serverless capabilities while preserving the mature, open-source database engine.

### Core Principles

1. **Preserve Open Source**: Keep the proven InnoDB storage engine intact
2. **Cloud-Native Approach**: Use Kubernetes and containers for orchestration
3. **No Forking**: Maintain full compatibility with existing applications
4. **Transparent Operations**: Scaling and management should be invisible to applications

## High-Level Architecture

{% @mermaid/diagram content="---
config:
theme: neutral
layout: dagre
-------------

flowchart LR
subgraph cloud\["Kubernetes Cluster"]
direction TB
proxies\["Intelligent Proxy
Multitenant Intelligent Proxy
• Routing
• Load Balancing
• Failover"]
database\["Database Server"]
serverpool@{ label: "Warm 'hot' DB Server Pool" }
operators\["K8 Operator/Controllers
• Vertical Autoscaler
• Horizontal Autoscaler
• AutoPark"]
end
n3\["Central Control Plane"] -- (1) Request operator to launch --> cloud
n4\["Application Client"] <--> n5\["Elastic Load Balancing"]
n5 <-- (5) Set up DNS endpoint for new service --> cloud
database <--> proxies
operators <-- (4) Register DB --> proxies
proxies --> serverpool
operators <-- (3) Scale to 1SCU --> database
serverpool -- (2) Checkout from pool, assign to user namespace --> database
proxies@{ shape: procs}
database@{ shape: cyl}
serverpool@{ shape: disk}
operators@{ shape: rounded}
n3@{ shape: rounded}
n4@{ shape: rounded}
n5@{ shape: hex}
style database fill:#C8E6C9,stroke:#757575
style serverpool fill:#C8E6C9,stroke:#757575
style n3 fill:#FFF9C4
style cloud fill:#BBDEFB,stroke:#000000
style n4 fill:#FFF9C4
style n5 fill:#FFD600
linkStyle 0 stroke:#FF6D00,fill:none
linkStyle 4 stroke:#FF6D00,fill:none
linkStyle 6 stroke:#FF6D00,fill:none
linkStyle 7 stroke:#FF6D00,fill:none" %}

## Core Components

### Intelligent Proxy

The multi-tenant proxy is the cornerstone of MariaDB Cloud Serverless, providing:

#### Connection Management

* **Always-On Connections**: Maintains application connections even when database scales to zero
* **Connection Pooling**: Efficiently manages database connections behind the scenes
* **Load Balancing**: Distributes requests across available database instances

#### Session State Management

The proxy tracks and preserves:

* System variables: `SET @@session.sort_buffer_size = X`
* User variables: `SET @myvar = 'value'`
* Prepared statements and their definitions
* Transaction isolation levels and other session settings

#### Failover and Recovery

* **Transparent Failover**: Automatically handles database failures
* **Transaction Replay**: Replays partial transactions to ensure data integrity
* **State Recreation**: Re-establishes session state on new connections

### Kubernetes Orchestration

MariaDB Cloud extends Kubernetes with custom controllers for database-specific operations:

#### Custom Resource Definitions (CRDs)

* **DatabaseService**: Defines serverless database configurations
* **ScalingPolicy**: Controls auto-scaling behavior and limits
* **BackupSchedule**: Manages automated backup operations

#### Custom Controllers

* **Resource Monitor Controller**: Tracks CPU, memory, and connection metrics
* **Scaling Controller**: Implements vertical and horizontal scaling decisions
* **Migration Controller**: Handles transparent live migrations
* **Pool Controller**: Manages pre-fabricated database pools

### Prefabricated Database Pools

To achieve millisecond launch times, MariaDB Cloud maintains pools of ready-to-use databases:

#### Pool Management

* **Regional Distribution**: Pools maintained in all supported regions
* **Dynamic Replenishment**: Pools refilled based on demand patterns
* **Resource Optimization**: Minimal resource allocation for pool databases

#### Database Initialization

When a user requests a database:

1. Check out a database from the appropriate pool
2. Resize according to service configuration
3. Execute security procedures (user creation, endpoint configuration)
4. Update control plane tracking
5. Database ready for use

### Auto-Scaling Engine

MariaDB Cloud implements sophisticated auto-scaling across multiple dimensions:

#### Vertical Scaling Algorithm

```
Every 200ms:
  - Sample CPU usage (UsageCoreNanoSeconds)
  - Update 30-second sliding window

Scale-up decision (1-second window):
  - If CPU usage ≥ 90% of allocated budget → Scale up

Scale-down decision (30-second window):
  - If average CPU usage ≤ 20% → Scale down
  - If no active connections for 10s → Scale to 0
```

#### Resource Allocation

* **Granular Scaling**: 0.5 vCPU and 2GB memory increments
* **Dynamic Limits**: Free tier limited to 2 SCUs, paid tiers scale based on configuration
* **Linux cgroups**: Uses cgroupsv2 for precise resource control

## Database States and Lifecycle

### Active State

* **Full Resources**: CPU, memory, and connections allocated based on demand
* **Optimized Cache**: Buffer pool sized and hydrated for current workload
* **Real-time Monitoring**: Continuous performance and resource tracking

### Suspended State

When activity drops to zero:

1. **Scale Down Resources**: Remove active threads, reduce memory allocation
2. **Minimize Buffer Pool**: Reduce to minimum required by InnoDB
3. **Maintain Connections**: Proxy keeps application connections alive
4. **Quick Reactivation**: Instant scale-up when activity resumes

### Parked State

After extended inactivity (several hours):

1. **Terminate Pod**: Database pod completely removed
2. **Preserve Storage**: Volume remains attached to service
3. **Proxy Management**: Proxy tracks parked state
4. **Automatic Recreation**: Pod recreated when activity resumes

## Buffer Pool Management

The database buffer pool is critical for performance. MariaDB Cloud implements intelligent buffer pool management:

### Dynamic Sizing

* **Proportional Scaling**: Buffer pool size adjusted with resource allocation
* **Performance Monitoring**: Track cache hit ratios during scaling operations

### Cache Hydration

When scaling up after a scale-down:

1. **Page Tracking**: Most frequently used pages identified during scale-down
2. **SSD Storage**: Page IDs stored on high-speed SSD storage
3. **Background Loading**: Frequently used pages reloaded into memory
4. **Performance Consistency**: Maintains cache hit ratios across scaling events

### Implementation Details

Buffer pool hydration process:

1. Before scale-down: SHOW ENGINE INNODB STATUS → identify hot pages
2. Store page IDs to fast SSD storage
3. During scale-up: Background process fetches pages from disk
4. Asynchronous hydration maintains query performance

## Live Migration System

For horizontal scaling, MariaDB Cloud implements transparent live migrations:

### Migration Triggers

* **High Watermark**: Migration initiated at \~70% memory utilization
* **Automatic Provisioning**: New instances created if needed
* **Workload Analysis**: Least-used databases migrated first

### Migration Process

1. **Snapshot Creation**: Create database snapshot on target instance
2. **Replication Setup**: Establish replication channel to source
3. **Synchronization**: Wait for replica to catch up
4. **Proxy Redirection**: Transparently redirect connections
5. **Source Cleanup**: Decommission source database

### Zero-Downtime Guarantees

* **Differential Snapshots**: Only changes copied after initial snapshot
* **Connection Preservation**: No application connection drops
* **Session Continuity**: All session state preserved during migration

## Storage Management

### Auto-Scaling Storage

MariaDB Cloud monitors and scales storage automatically:

#### Scaling Thresholds

* **Small Volumes** (< 100GB): Scale at 60% capacity
* **Medium Volumes** (100-500GB): Scale at 80% capacity
* **Large Volumes** (> 500GB): Scale at 95% capacity

#### Implementation

* **Continuous Monitoring**: PersistentVolumeClaim usage tracked
* **Proactive Scaling**: Scaling initiated before capacity exhausted
* **Block Storage Integration**: Currently uses cloud provider block storage (AWS EBS, Azure Disk, Google Persistent Disk)

### Future Storage Innovations

MariaDB Cloud is evaluating distributed storage solutions:

* **Ceph/Rook Integration**: Self-managed distributed storage
* **Multi-Cloud Storage**: Storage spanning multiple cloud providers
* **Performance Optimization**: Custom storage optimizations for database workloads

## Security Architecture

### Network Security

* **Private Networking**: Database pods run in private subnets
* **Encryption in Transit**: TLS/SSL for all connections
* **Firewall Integration**: Cloud-native security group integration

### Data Protection

* **Encryption at Rest**: All storage volumes encrypted
* **Key Management**: Integration with cloud provider key management services
* **Access Controls**: Role-based access control (RBAC)

### Isolation

* **Pod-Level Isolation**: Each database runs in isolated Kubernetes pod
* **Network Policies**: Kubernetes network policies for traffic control
* **Resource Isolation**: cgroups ensure resource isolation between databases

## Monitoring and Observability

### Real-Time Metrics

* **Resource Utilization**: CPU, memory, storage, and network metrics
* **Database Performance**: Query performance, connection counts, cache hit ratios
* **Scaling Events**: Auto-scaling decisions and their impact

### Alerting System

* **Proactive Alerts**: Performance degradation warnings
* **Scaling Notifications**: Automatic scaling event notifications
* **Failure Detection**: Immediate alerts for database failures

### Integration

* **Prometheus**: Metrics collection and storage
* **Grafana**: Visualization and dashboards
* **Custom Metrics**: Database-specific performance indicators

### Other Considerations

* **Vendor Lock-in**: MariaDB Cloud maintains portability
* **Cost Transparency**: No hidden charges or surprise costs
* **Performance**: Better performance due to no compute-storage disaggregation
* **Compatibility**: Full compatibility with existing applications

## Performance Characteristics

### Scaling Performance

* **Vertical Scaling**: Typically completes in < 5 seconds
* **Horizontal Scaling**: Live migration in < 30 seconds
* **Cold Start**: Database ready in < 100 milliseconds

### Query Performance

* **OLTP Workloads**: Equivalent to provisioned instances
* **Cache Performance**: Maintained through buffer pool hydration
* **Connection Overhead**: Minimal proxy overhead (< 1ms latency)

### Scalability Limits

* **Vertical Scaling**: Up to cloud provider instance limits
* **Horizontal Scaling**: Unlimited through live migration
* **Storage Scaling**: Up to cloud provider storage limits

## Future Enhancements

### Planned Features

1. **Analytics Integration**: On-demand OLAP with DuckDB integration
2. **Global Distribution**: Multi-region database deployment
3. **Advanced AI**: Machine learning-driven optimization
4. **Edge Computing**: Edge database deployments

### Research Areas

* **Quantum-Ready Encryption**: Future-proof security
* **Advanced Caching**: Intelligent cache management algorithms
* **Distributed Consensus**: Enhanced distributed database capabilities

## Best Practices

### Application Design

1. **Connection Pooling**: Use connection pooling in applications
2. **Graceful Degradation**: Handle temporary scaling events
3. **Monitoring Integration**: Implement application-level monitoring

### Performance Optimization

1. **Query Optimization**: Optimize queries for scaling environments
2. **Index Strategy**: Maintain appropriate indexes for workload
3. **Connection Management**: Minimize connection overhead

### Cost Optimization

1. **Workload Analysis**: Understand application usage patterns
2. **Scaling Limits**: Set appropriate scaling limits
3. **Resource Right-Sizing**: Monitor and adjust resource allocation

This architecture enables MariaDB Cloud Serverless to provide true serverless capabilities while maintaining the performance, reliability, and compatibility that enterprises require.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mariadb.com/docs/mariadb-cloud/readme/architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.