Cluster behavior

One of the key design principles of CrateDB is that all nodes in a cluster are equal. This means that applications and users can connect to any node in the cluster and receive the same response for a given SQL query, regardless of which node handles the request.

As described in the Components of a CrateDB Node, each node includes a SQL handler that can independently parse, analyze, and execute SQL requests. This enables a high degree of flexibility, fault tolerance, and horizontal scalability in both database and application deployment.

Table of Contents

• Request Handling in a CrateDB Cluster

• Traditional Application Architecture (Primary-Secundary)

• Shared-Nothing Architecture with CrateDB

• Summary

---

Request Handling in a CrateDB Cluster

When a client sends a SQL request to a CrateDB node (referred to as the handler node):

1. The request is received using one of the supported protocols:

   • HTTP

   • PostgreSQL Wire Protocol

2. The handler node:

   • Parses the SQL statement into a syntax tree

   • Analyzes the query

   • Builds an execution plan locally

3. The execution plan is distributed across the cluster for processing.

4. The final results are collected by the handler node, which then returns the response to the client.

Important: The handler node does not redirect or delegate the request to another node. It remains responsible for the full lifecycle of that query, including result aggregation.

---

Traditional Application Architecture (Primary-Secondary)

In a conventional database setup based on a primary-secondary (master-slave) model (unlike CrateDB), applications typically rely on a single write node. This architecture introduces scaling bottlenecks and single points of failure (SPoF).

Figure 1: Conventional deployment of an application and database stack.

Limitations:

• Write throughput is limited by the capacity of the primary database node.

• If the primary node becomes unavailable, the entire stack may fail.

• Application scaling is constrained by the fixed database access point.

---

Shared-Nothing Architecture with CrateDB

CrateDB supports a shared-nothing architecture, enabling more resilient and scalable deployments. The same architectural principle can be extended beyond the database to the application layer.

Figure 2: Elastic deployment leveraging a shared-nothing architecture with CrateDB.

Benefits:

• Each application server can run alongside its own CrateDB node.

• Applications communicate only with the local CrateDB instance (e.g., via localhost).

• No centralized bottleneck — the cluster manages coordination and data distribution behind the scenes.

• Deployments become elastic and fault-tolerant.

Load Balancer Behavior:

• Monitors the health of each host (application + CrateDB instance).

• If either the app or database fails on a node, the entire host is removed from load balancing rotation.

• New instances can be added or removed dynamically based on load.

---

Summary

CrateDB's design makes it possible to:

• Build fully decentralized, scalable systems

• Avoid single points of failure across both the database and application layers

• Enable elastic deployments where resources can scale with demand

This architecture aligns especially well with containerized and cloud-native environments, where applications are stateless and infrastructure is dynamic.