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().