# Server Groups

Define multi-server database configurations for read replicas, geographic distribution, high availability, and horizontal scaling.

## What are Server Groups?

Server groups allow you to organize multiple database servers for advanced deployment scenarios. They enable read replicas, multi-region deployments, high availability configurations, and sharding strategies directly in your Prax schema.

#### Use Cases

- • Read replica load balancing
- • Geographic distribution (multi-region)
- • High availability with automatic failover
- • Horizontal scaling with sharding
- • Separating analytics from production

#### Strategies

- • ReadReplica - Primary + read replicas
- • MultiRegion - Geographic distribution
- • HighAvailability - Auto failover
- • Sharding - Horizontal partitioning
- • Custom - User-defined strategies

## Basic Server Group

Define a server group with the `serverGroup` keyword. Each server within the group is defined with a name and properties like URL, role, and weight.

## Read Replica Configuration

The most common use case is distributing read queries across replicas while sending writes to the primary. Use the `@@strategy(ReadReplica)` attribute and configure load balancing.

Note: The `weight` property determines the proportion of read traffic each server receives. Higher weights receive more traffic.

## Multi-Region Deployment

For globally distributed applications, use the `MultiRegion` strategy with `Nearest` load balancing to route queries to the geographically closest server.

## High Availability

Configure automatic failover with health checks and priority-based server selection. The `priority` property determines failover order.

## Sharding (Horizontal Scaling)

For very large datasets, shard your data across multiple servers. Each shard handles a specific range of data based on the shard key.

Caution: Sharding adds complexity to your application. Cross-shard queries and transactions require special handling. Consider read replicas or vertical scaling first.

## Separating Analytics

Route heavy analytical queries to dedicated servers to avoid impacting production traffic. Use the `analytics` role for reporting servers.

## Weighted Load Balancing

When servers have different capacities, use weighted load balancing to distribute traffic proportionally. Higher-capacity servers can handle more requests.

## Server Properties Reference

Property | Type | Description
--- | --- | ---
`url` | String | Database connection URL (required)
`role` | String | Server role: primary, replica, analytics, archive, shard
`weight` | Int | Load balancing weight (higher = more traffic)
`priority` | Int | Failover priority (lower = higher priority)
`region` | String | Geographic region identifier
`healthCheck` | String | Health check endpoint path
`maxConnections` | Int | Maximum connection pool size
`readOnly` | Boolean | Mark server as read-only

## Group Attributes Reference

Attribute | Values | Description
--- | --- | ---
`@@strategy()` | ReadReplica, MultiRegion, HighAvailability, Sharding, Custom | Server group strategy
`@@loadBalance()` | RoundRobin, Random, LeastConnections, Weighted, Nearest, Sticky | Load balancing algorithm

## Complete Example

Here's a complete schema with server groups and models:

## Runtime Usage

Server groups are configured at runtime. Prax automatically routes queries based on the configured strategy.

## Best Practices

#### Use Environment Variables for URLs

Always use `env("VAR_NAME")` for database URLs. Never hardcode connection strings in the schema.

#### Configure Health Checks

For high availability setups, configure health check endpoints to enable automatic failover when a server becomes unavailable.

#### Start Simple

Begin with a single server or simple read replica setup. Add complexity (sharding, multi-region) only when needed based on actual load patterns.

#### Consider Replication Lag

Be aware that replicas may have slight replication lag. For operations requiring immediate consistency, use `.use_primary()`.