# Client Library
Source: https://docs.regatta.dev/drivers-and-clients/client-lib

The shared library that powers all Regatta drivers, providing the core API for communicating with your Regatta database.

The Regatta client library is a core component required by all Regatta drivers. It provides the underlying communication layer that enables your applications to interact with the Regatta database. Before installing any language-specific driver or tool, the client library must be installed on your system.

Regatta Drivers & Clients are available in two modes:

* **Bundled** with the Regatta client library for a simplified all-in-one setup. Bundled packages will contain the "full" suffix.
* **Standalone**, allowing dynamic linking to the Regatta client at runtime for greater flexibility.

## Installation

<Tabs>
  <Tab title="Linux">
    ### Prerequisites

    To run a Regatta client, ensure that the following requirements are met:

    1. **Operating system:** Red Hat 8–based distribution such as Oracle Linux 8 or RHEL 8.10
    2. **Architecture:** x86-64 (64-bit)
    3. **Required system dependencies**:

       The following system libraries must be installed on the host:

       * `glibc`
       * `libstdc++`
       * `libgcc`
       * `util-linux-libs`
       * `openssl-libs`
       * `libaio`

    ### Installation

    Copy the client RPM package to your target Linux machine and install it:

    ```bash theme={null}
    sudo rpm -i regatta-client-<version>.el8.x86_64.rpm
    ```

    Once installed, the shared library will be placed in the system library path, typically:

    ```bash theme={null}
    /usr/lib64/libregattaclient1.so.<full.version>
    ```

    You can verify installation with:

    ```
    ls /usr/lib64/libregattaclient1.so.*
    ```

    This confirms that the client library is now available for linking by the drivers.
  </Tab>
</Tabs>


# Connecting Applications to Regatta
Source: https://docs.regatta.dev/drivers-and-clients/connecting-applications-to-regatta



Regatta supports a wide range of integrations to help you connect your applications to the database. These include native drivers, ORMs, CLI tools and more, each designed to fit seamlessly into your development environment.

Explore the languages and frameworks you work with and discover the right tools for building with Regatta.

<CardGroup>
  <Card title="Regatta CLI" icon="square-terminal" href="/drivers-and-clients/regatta-cli" />

  <Card title="Python" icon="python" href="/drivers-and-clients/python/install-your-python-client" />

  <Card title="Java" icon="java" href="/drivers-and-clients/java/install-your-java-client" />

  <Card title="JavaScript" icon="js" href="/drivers-and-clients/javascript/install-your-javascript-client" />
</CardGroup>

<Note>
  Regatta clients and drivers are currently compatible with Linux-based distributions running on x86-64 architecture. Support for additional environments will be added in future releases.
</Note>


# Download Drivers & Clients
Source: https://docs.regatta.dev/drivers-and-clients/download-drivers-and-clients



Regatta makes it simple to obtain the latest drivers, client libraries, and integration tools directly from your Regatta Cloud account.

## Accessing the Download Portal

1. [Log in to your Regatta Cloud account](/regatta-cloud/regatta-cloud/access-the-cloud).
2. In the left-hand navigation bar, click **Clients & Tools**.
3. Select the language or tool you wish to download.
4. Choose the appropriate tab for that client or tool. For example, click **JavaScript** to view NodeJS and TypeORM packages.

## Understanding the Version Matrix Table

Once you select a particular client or tool (e.g., **JavaScript → NodeJS**), you will see a table like this:

| OS | Architecture | Version | Type | Supported DB Versions | |
| - | - | - | - | - | - |
| Linux | Intel | 1.3.0 | Full | 1.0.0.1297 + | \[Download] |
| Linux | Intel | 1.3.0 | Standalone | 1.0.0.1297 + | \[Download] |
| Linux | Intel | 1.1.0 | Full | 1.0.0.1034 – 1.0.0.1296 | \[Download] |
| Linux | Intel | 1.1.0 | Standalone | 1.0.0.1034 – 1.0.0.1296 | \[Download] |

### Column Descriptions

1. **OS** - Indicates the operating system for which this package was built (e.g., Linux).
2. **Architecture** - The CPU architecture supported by this package (e.g., Intel/x86-64).
3. **Version** - The specific release number of the driver or tool. Follows Semantic Versioning `(Major.Minor.Patch)`.
4. **Type**
   * **Full**: Includes the Regatta client library bundled together with the driver. Ideal for a “zero-prep” installation—just copy, extract, and run with no additional dependencies.
   * **Standalone**: Contains only the driver (no embedded client library). Requires you to install the [**Regatta Client Library**](/drivers-and-clients/client-lib) separately. Useful if you want to manage client library upgrades independently of the driver.
5. **Supported DB Versions** - Specifies which Regatta Database cluster versions are compatible with this driver/tool.\
   For example:
   * `1.0.0.1034 – 1.0.0.1296` means “This release works with any Regatta cluster running versions `1.0.0.1034` through `1.0.0.1296`.”
   * `1.0.0.1297 +` means “This release requires Regatta `1.0.0.1297` or later.”
6. **Download Button** - Click **Download** to retrieve the RPM, TAR.GZ, or ZIP package for that row.

## After Download

1. Place the downloaded package in your local workspace.
2. Navigate to the relevant section for [installation instructions](/drivers-and-clients/connecting-applications-to-regatta) and usage examples.


# Install Your Java Client
Source: https://docs.regatta.dev/drivers-and-clients/java/install-your-java-client



## Drivers

<Tabs>
  <Tab title="JDBC">
    1. [Download the JDBC driver](/drivers-and-clients/download-drivers-and-clients). The driver is distributed as a single JAR file.

    <Note>
      Regatta provides a shaded JDBC driver which includes all required dependencies. A non-shaded driver can be provided upon request.
    </Note>

    2. Add the Regatta JDBC driver to your Maven project:

       **Option A — Install locally (recommended):**

       Install the driver locally in your environment:

       ```bash theme={null}
       mvn install:install-file \
         -Dfile=regatta-jdbc-<version>-shaded_full.jar \
         -DgroupId=dev.regatta \
         -DartifactId=regatta-jdbc \
         -Dversion=<version> \
         -Dpackaging=jar
       ```

       Then add the JDBC driver as a dependency to your project:

       ```xml theme={null}
       <dependency>
         <groupId>dev.regatta</groupId>
         <artifactId>regatta-jdbc</artifactId>
         <version>1.8.0</version>
       </dependency>
       ```

       **Option B — Provided scope (when included by your runtime environment):**

       ```xml theme={null}
       <dependency>
         <groupId>dev.regatta</groupId>
         <artifactId>regatta-jdbc</artifactId>
         <version>1.8.0</version>
         <scope>provided</scope>
       </dependency>
       ```

    ### Notes

    * **Java 8** or newer is required to use the Regatta JDBC driver.
    * If you are using the **Full** driver package, the Regatta client library is included automatically. If you are using the **Standalone** version, ensure that the [client library is installed](/drivers-and-clients/client-lib).
    * The Regatta JDBC driver implements the **JDBC 4.2 API**. Refer to the [official JDBC documentation](https://docs.oracle.com/javase/8/docs/api/java/sql/package-summary.html) for full API details
    * Regatta supports most of the common JDBC functionality. If you do use a JDBC command which is not supported, you will receive the following exception:

      ```java theme={null}
      class RegFeatureNotSupportedException extends SQLFeatureNotSupportedException
      ```
  </Tab>
</Tabs>

***

## ORM frameworks

<Tabs>
  <Tab title="Hibernate">
    1. [Download the Regatta Hibernate dialect](/drivers-and-clients/download-drivers-and-clients). The dialect is distributed as a single JAR file.
    2. Add the Regatta Hibernate dialect to your Maven project:

       **Option A — Install locally (recommended):**

       Install the dialect locally in your environment:

       ```bash theme={null}
       mvn install:install-file \
         -Dfile=regatta-hibernate-<version>.jar \
         -DgroupId=dev.regatta \
         -DartifactId=regatta-hibernate \
         -Dversion=<version> \
         -Dpackaging=jar
       ```

       Then add the Hibernate dialect as a dependency to your project:

       ```xml theme={null}
       <dependency>
         <groupId>dev.regatta</groupId>
         <artifactId>regatta-hibernate</artifactId>
         <version>1.1.0</version>
       </dependency>
       ```

       **Option B — Provided scope (when included by your runtime environment):**

       ```xml theme={null}
       <dependency>
         <groupId>dev.regatta</groupId>
         <artifactId>regatta-hibernate</artifactId>
         <version>1.1.0</version>
         <scope>provided</scope>
       </dependency>
       ```

       <Note>
         The Regatta Hibernate dialect is compatible with Hibernate 6.x (built and tested with Hibernate 6.4.4.Final) and requires Java 17 or newer. Refer to the [official Hibernate documentation](https://hibernate.org/orm/documentation/6.4/) for installation instructions and API details.
       </Note>
  </Tab>
</Tabs>


# Run a Hibernate Application
Source: https://docs.regatta.dev/drivers-and-clients/java/run-hibernate-application



Let's create a simple Hibernate application that connects to Regatta using the Regatta JDBC driver and Hibernate dialect.

## Connection Details

Regatta connection parameters are configured in `hibernate.cfg.xml`:

```xml theme={null}
<property name="connection.driver_class">dev.regatta.jdbc1.RegDriver</property>
<property name="connection.url">jdbc:regatta:aaa.bbb.ccc.ddd:ppp</property>
<property name="connection.username">MyUserName</property>
<property name="connection.password">SomeSophisticatedPassword</property>
```

## Example Appliaction

This example application will:

1. Create an `employees` table.
2. Insert four employees using Hibernate ORM.
3. Query and print the results.
4. Delete the rows and drop the table.

### Project Structure

Create a new Maven project folder, for example `regatta-hibernate-example/`, with the following layout:

```bash theme={null}
regatta-hibernate-example/
├── pom.xml
└── src/
    └── main/
        ├── java/
        │   └── dev/
        │       └── regatta/
        │           └── hibernate_example/
        │               ├── Employee.java
        │               └── HibernateExample.java
        └── resources/
            └── hibernate.cfg.xml
```

Start your Java sources with the Regatta example package:

```java theme={null}
package dev.regatta.hibernate_example;
```

Note that you should import all relevant classes based on the functionality of your application and its requirements.

### Employee Entity

Create the `Employee` entity and save it as: `src/main/java/dev/regatta/hibernate_example/Employee.java`

```java theme={null}
package dev.regatta.hibernate_example;

import jakarta.persistence.*;

@Entity
@Table(name = "employees")
public class Employee {

    @Id
    @Column(name = "employee_key")
    private int id;

    @Column(name = "employee_name", nullable = false, length = 40)
    private String name;

    @Column(name = "employee_salary")
    private int salary;

    @Column(name = "employee_department", nullable = false, length = 50)
    private String department;

    // Required by Hibernate
    public Employee() {}

    public Employee(int id, String name, int salary, String department) {
        this.id = id;
        this.name = name;
        this.salary = salary;
        this.department = department;
    }

    public int getId() { return id; }
    public void setId(int id) { this.id = id; }

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    public int getSalary() { return salary; }
    public void setSalary(int salary) { this.salary = salary; }

    public String getDepartment() { return department; }
    public void setDepartment(String department) { this.department = department; }
}
```

### Hibernate Main Program

Create the main program and save it as: `src/main/java/dev/regatta/hibernate_example/HibernateExample.java`

```java theme={null}
package dev.regatta.hibernate_example;

import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.Transaction;
import org.hibernate.cfg.Configuration;

import java.util.Arrays;
import java.util.List;

public class HibernateExample {

    public static void main(String[] args) {

        SessionFactory sessionFactory = new Configuration()
                .configure("hibernate.cfg.xml")
                .addAnnotatedClass(Employee.class)
                .buildSessionFactory();

        try (Session session = sessionFactory.openSession()) {

            // Create table employees
            Transaction transaction = session.beginTransaction();
            session.createNativeQuery(
                    "CREATE TABLE employees (" +
                    "employee_key INT PRIMARY KEY INDEX, " +
                    "employee_name VARCHAR(40) NOT NULL, " +
                    "employee_salary INT, " +
                    "employee_department VARCHAR(50) NOT NULL" +
                    ")"
            ).executeUpdate();
            transaction.commit();

            // Insert data
            transaction = session.beginTransaction();

            List<Employee> employeesInserted =
                    Arrays.asList(
                            new Employee(1, "John Doe", 10932, "DevOps"),
                            new Employee(2, "Richard Roe", 18324, "Legal"),
                            new Employee(3, "Jane Roe", 20411, "SoftwareDev"),
                            new Employee(4, "Rachel Roe", 19555, "Support")
                    );

            for (Employee employee : employeesInserted) {
                session.persist(employee);
            }

            transaction.commit();

            // Query data
            List<Employee> employeesSelected =
                    session.createQuery("from Employee", Employee.class).list();

            for (Employee emp : employeesSelected) {
                System.out.println("Employee Key: " + emp.getId());
                System.out.println("Employee Name: " + emp.getName());
                System.out.println("Employee Salary: " + emp.getSalary());
                System.out.println("Employee Department: " + emp.getDepartment());
                System.out.println();
            }

            // Cleanup: delete rows
            transaction = session.beginTransaction();
            for (Employee emp : employeesInserted) {
                session.remove(emp);
            }
            transaction.commit();

            // Cleanup: drop table
            transaction = session.beginTransaction();
            session.createNativeQuery("DROP TABLE employees").executeUpdate();
            transaction.commit();

        } finally {
            sessionFactory.close();
        }
    }
}
```

### Hiberante Configuration

Save the Hibernate configuration as:`src/main/resources/hibernate.cfg.xml`

```xml theme={null}
<!DOCTYPE hibernate-configuration PUBLIC
        "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
        "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
    <session-factory>

        <!-- JDBC Database connection settings -->
        <property name="connection.driver_class">dev.regatta.jdbc1.RegDriver</property>
        <property name="connection.url">jdbc:regatta:aaa.bbb.ccc.ddd:ppp</property>
        <property name="connection.username">MyUserName</property>
        <property name="connection.password">SomeSophisticatedPassword</property>

        <!-- Regatta Hibernate dialect -->
        <property name="dialect">dev.regatta.hibernate.RegattaDialect</property>

        <!-- Echo SQL to stdout -->
        <property name="show_sql">true</property>

        <!-- Do not auto-manage schema; the example creates/drops explicitly -->
        <property name="hbm2ddl.auto">none</property>

        <!-- Set the current session context -->
        <property name="current_session_context_class">thread</property>

        <!-- Use HikariCP (recommended for production) -->
        <property name="hibernate.connection.provider_class">
            org.hibernate.hikaricp.internal.HikariCPConnectionProvider
        </property>

        <property name="hibernate.hikari.maximumPoolSize">10</property>
        <property name="hibernate.hikari.minimumIdle">1</property>
        <property name="hibernate.hikari.idleTimeout">30000</property>

    </session-factory>
</hibernate-configuration>
```

<Note>
  The property `hbm2ddl.auto` controls whether Hibernate automatically manages your database schema. When set to `none`, Hibernate will not attempt to create, update, validate, or drop tables. If you prefer Hibernate to manage the schema for you during development, you may change this property:

  * create — Drops the existing schema (if any) and creates all tables on startup.
  * create-drop — Creates the schema on startup and drops it on shutdown.
  * update — Tries to update the schema to match your entities without dropping tables.
  * validate — Validates that the schema matches your entities without modifying anything.
</Note>

### Maven Project Setup

Create a `pom.xml` in the project root:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>dev.regatta.example</groupId>
  <artifactId>regatta-hibernate-example</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

  <properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
  </properties>

  <dependencies>
    <!-- Regatta JDBC driver -->
    <dependency>
      <groupId>dev.regatta</groupId>
      <artifactId>regatta-jdbc</artifactId>
      <version>1.8.0</version>
    </dependency>

    <!-- Regatta Hibernate dialect -->
    <dependency>
      <groupId>dev.regatta</groupId>
      <artifactId>regatta-hibernate</artifactId>
      <version>1.1.0</version>
    </dependency>

    <!-- Hibernate ORM -->
    <dependency>
      <groupId>org.hibernate.orm</groupId>
      <artifactId>hibernate-core</artifactId>
      <version>6.4.4.Final</version>
    </dependency>

    <!-- HikariCP integration for Hibernate -->
    <dependency>
      <groupId>org.hibernate.orm</groupId>
      <artifactId>hibernate-hikaricp</artifactId>
      <version>6.4.4.Final</version>
    </dependency>
    <dependency>
      <groupId>com.zaxxer</groupId>
      <artifactId>HikariCP</artifactId>
      <version>5.1.0</version>
    </dependency>

    <!-- Optional: SLF4J -->
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-simple</artifactId>
      <version>2.0.16</version>
      <scope>runtime</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>3.5.0</version>
        <configuration>
          <mainClass>dev.regatta.hibernate_example.HibernateExample</mainClass>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>
```

<Note>
  This `pom.xml` assumes you already [installed the Regatta JDBC driver and Hibernate dialect locally](/drivers-and-clients/java/install-your-java-client).
</Note>

## Running the Application

Compile and run the application:

```bash theme={null}
mvn -q compile exec:java
```

Expected output:

```bash theme={null}
Nov 22, 2025 9:50:30 PM org.hibernate.Version logVersion
INFO: HHH000412: Hibernate ORM core version 6.4.4.Final
Nov 22, 2025 9:50:30 PM org.hibernate.cache.internal.RegionFactoryInitiator initiateService
INFO: HHH000026: Second-level cache disabled
Nov 22, 2025 9:50:30 PM org.hibernate.engine.jdbc.connections.internal.ConnectionProviderInitiator initiateService
INFO: HHH000130: Instantiating explicit connection provider: org.hibernate.hikaricp.internal.HikariCPConnectionProvider
Hibernate: CREATE TABLE employees (employee_key INT PRIMARY KEY INDEX, employee_name VARCHAR(40) NOT NULL, employee_salary INT, employee_department VARCHAR(50) NOT NULL)
Hibernate: insert into employees (employee_department,employee_name,employee_salary,employee_key) values (?,?,?,?)
Hibernate: insert into employees (employee_department,employee_name,employee_salary,employee_key) values (?,?,?,?)
Hibernate: insert into employees (employee_department,employee_name,employee_salary,employee_key) values (?,?,?,?)
Hibernate: insert into employees (employee_department,employee_name,employee_salary,employee_key) values (?,?,?,?)
Hibernate: select e1_0.employee_key,e1_0.employee_department,e1_0.employee_name,e1_0.employee_salary from employees e1_0
Employee Key: 3
Employee Name: Jane Roe
Employee Salary: 20411
Employee Department: SoftwareDev

Employee Key: 1
Employee Name: John Doe
Employee Salary: 10932
Employee Department: DevOps

Employee Key: 4
Employee Name: Rachel Roe
Employee Salary: 19555
Employee Department: Support

Employee Key: 2
Employee Name: Richard Roe
Employee Salary: 18324
Employee Department: Legal

Hibernate: delete from employees where employee_key=?
Hibernate: delete from employees where employee_key=?
Hibernate: delete from employees where employee_key=?
Hibernate: delete from employees where employee_key=?
Hibernate: DROP TABLE employees
```


# Run a JDBC Application
Source: https://docs.regatta.dev/drivers-and-clients/java/run-jdbc-application



Let's create a simple JDBC application that queries the Regatta database. Start by adding the reference to the regatta driver:

```java theme={null}
package dev.regatta.jdbc1;
```

Note that you should import all relevant classes based on the functionality of your application and its requirements.

## Connection Details

Connection parameters will be defined as follows:

```java theme={null}
String url = "jdbc:regatta:aaa.bbb.ccc.ddd:ppp";
String user = "MyUserName";
String password = "SomeSophisticatedPassword";
```

## Example Appliaction

Below is an example of a sample application that creates an `employees` table, adds four rows and then selects them.

Create the main program and save it as: `src/main/java/dev/regatta/jdbc1/DatabaseExample.java`

```Java theme={null}
package dev.regatta.jdbc1;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;
import java.sql.ResultSet;
import java.sql.SQLException;

public class DatabaseExample {
    public static void main(String[] args) {
        // Connection details
        String url = "jdbc:regatta:aaa.bbb.ccc.ddd:ppp";
        String user = "MyUserName";
        String password = "SomeSophisticatedPassword";

        try {
            try (Connection conn = DriverManager.getConnection(url, user, password)) {
                try (Statement stmt = conn.createStatement()) {

                    String createTableSQL =
                        "CREATE TABLE employees (" +
                        "employee_key INT PRIMARY KEY INDEX, " +
                        "employee_name VARCHAR(40) NOT NULL, " +
                        "employee_salary INT, " +
                        "employee_department VARCHAR(50) NOT NULL" +
                        ")";
                    stmt.executeUpdate(createTableSQL);

                    String insertValuesSQL =
                        "INSERT INTO employees " +
                        "(employee_key, employee_name, employee_salary, employee_department) " +
                        "VALUES " +
                        "(1, 'John Doe', 10932, 'DevOps'), " +
                        "(2, 'Richard Roe', 18324, 'Legal'), " +
                        "(3, 'Jane Roe', 20411, 'SoftwareDev'), " +
                        "(4, 'Rachel Roe', 19555, 'Support')";
                    stmt.executeUpdate(insertValuesSQL);

                    ResultSet rs = stmt.executeQuery("SELECT * FROM employees");

                    while (rs.next()) {
                        System.out.println("Employee Key: " + rs.getInt("employee_key"));
                        System.out.println("Employee Name: " + rs.getString("employee_name"));
                        System.out.println("Employee Salary: " + rs.getInt("employee_salary"));
                        System.out.println("Employee Department: " + rs.getString("employee_department"));
                        System.out.println();
                    }

                    stmt.executeUpdate("DROP TABLE employees");
                }
            }
        } catch (SQLException e) {
            System.out.println("Database access error.");
            e.printStackTrace();
        }
    }
}
```

### Maven Project Setup

Create a `pom.xml` alongside your example:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>dev.regatta.example</groupId>
  <artifactId>regatta-jdbc-example</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

  <properties>
    <maven.compiler.source>8</maven.compiler.source>
    <maven.compiler.target>8</maven.compiler.target>
  </properties>

  <dependencies>
    <dependency>
      <groupId>dev.regatta</groupId>
      <artifactId>regatta-jdbc</artifactId>
      <version>1.8.0</version>
    </dependency>

    <!-- Optional: adds a simple SLF4J runtime provider so SLF4J does not print a warning -->
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-simple</artifactId>
      <version>2.0.16</version>
      <scope>runtime</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>3.5.0</version>
        <configuration>
          <mainClass>dev.regatta.jdbc1.DatabaseExample</mainClass>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>
```

<Note>
  This `pom.xml` assumes you already [installed the Regatta JDBC driver locally](/drivers-and-clients/java/install-your-java-client).
</Note>

## Running the Application

Compile and run the application:

```bash theme={null}
mvn -q compile exec:java
```

Expected output:

```bash theme={null}
Employee Key: 1
Employee Name: John Doe
Employee Salary: 10932
Employee Department: DevOps

Employee Key: 2
Employee Name: Richard Roe
Employee Salary: 18324
Employee Department: Legal

Employee Key: 3
Employee Name: Jane Roe
Employee Salary: 20411
Employee Department: SoftwareDev

Employee Key: 4
Employee Name: Rachel Roe
Employee Salary: 19555
Employee Department: Support
```


# Install Your Javascript Client
Source: https://docs.regatta.dev/drivers-and-clients/javascript/install-your-javascript-client



## Drivers

<Tabs>
  <Tab title="Node.js">
    1. [Download the Node.js driver](/drivers-and-clients/download-drivers-and-clients), and save the `.tgz` file locally (typically next to your `package.json`).
    2. Install the driver:

       **Option A — Direct install:**

       Install the driver locally in your environment:

       ```bash theme={null}
       npm install path/to/node-regatta-<version>_<type>.tgz
       ```

       This will install the driver, pull in required dependencies, and update your `package-lock.json`.

       **Option B — Add as a local package dependency:**\
       Add the driver to your project’s `package.json`:

       ```json theme={null}
       "dependencies": {
        "node-regatta": "file: path/to/node-regatta.tgz"
       }
       ```

    ### Notes

    * **Node.js 16** or newer is required to use the Regatta Node.js driver.
    * If you are using the **Full** driver package, the Regatta client library is included automatically. If you are using the **Standalone** version, ensure that the [client library is installed](/drivers-and-clients/client-lib).
  </Tab>
</Tabs>

***

## ORM frameworks

<Tabs>
  <Tab title="TypeORM">
    1. [Download the Regatta TypeORM package](/drivers-and-clients/download-drivers-and-clients).
    2. Install the Regatta TypeORM package:

       ```bash theme={null}
       npm install typeorm-regatta-<version>.tgz
       ```

    <Note>
      Regatta provides a dedicated fork of TypeORM that includes the Regatta dialect inside the TypeORM core. The Regatta TypeORM package (`typeorm-regatta`) is based on [**TypeORM 0.3.20**](https://github.com/typeorm/typeorm/releases/tag/0.3.20) and is distributed as a separate `.tgz` package. Because it is a fork, it should be used instead of the standard `typeorm` dependency, and compatibility is aligned to that upstream version.
    </Note>
  </Tab>
</Tabs>


# Run a Node.js Application
Source: https://docs.regatta.dev/drivers-and-clients/javascript/run-nodejs-application



Let's create a simple Node.js application that queries the Regatta database. Start by adding the reference to the regatta driver:

```javascript theme={null}
const {getConnection} = require("node-regatta");
```

Note that you should import all relevant classes based on the functionality of your application and its requirements.

## Connection Details

Connection parameters will be defined as follows:

```javascript theme={null}
const dbUrl = "aaa:bbb:ccc:ddd:pppp";
const dbUser = "MyUserName ";
const dbPassword = "SomeSophisticatedPassword";
```

## Example Appliaction

To help you get acquainted with the Regatta API for Node.js, we’ve provided a simple code example below. This application demonstrate common tasks such as creating connections, executing queries, and working with cursors. The Regatta API supports both **async/await** and **callback-based** patterns.

Create the main program and save it as: `node_regatta_example.js`

```javascript theme={null}
const { getConnection, ErrorVerbosityLevel } = require('node-regatta');

async function main() {
  /* Enter the Regatta connection URL */
  const dbUrl = 'aaa.bbb.ccc.ddd:pppp';
  /* Enter your Regatta username */
  const dbUser = 'MyUserName';
  /* Enter your Regatta password */
  const dbPassword = 'SomeSophisticatedPassword';

  try {
    /*
     * Establish a connection to the database using the provided credentials
     * and URL.
     * To pass client options or set a timeout for all requests to the database,
     * use custom getConnection:
     * connectCustom(user, password, host, connectionOptions, timeoutMs)
     */
    let connection = await getConnection(dbUser, dbPassword, dbUrl);
    console.log('Connected to the database');

    /*
     * Auto-commit is enabled by default. To use manual commit mode, set
     * auto-commit to false.
     */
    connection.setCommitMode(false);

    /*
     * The transaction isolation level can be set. The default is the Regatta
     * transaction isolation level.
     * const { TransIsoLevel } = require("node-regatta");
     * connection.setTransactionIsolation(TransIsoLevel.READ_COMMITTED);
     */

    /*
     * The default connection timeout to execute each query is set to infinity.
     * A custom timeout can be set using the setTimeout(timeoutMs) method.
     */
    connection.setTimeout(3000);

    /*
     * Optionally, the level of detail for error messages generated by
     * operations using the connection can be set.
     */
    connection.setErrorVerbosity(ErrorVerbosityLevel.HIGH);

    /*
     * Create a new table 'users' with columns for 'id' and 'name'.
     * The 'id' column is the primary key and is indexed.
     */
    await connection.execute(`
      CREATE TABLE users (
         id   INT PRIMARY KEY INDEX,
         name VARCHAR(128)
      )
    `);

    /*
     * When working in manual commit mode, commit the transaction manually
     * using the commit method. This finalizes the transaction and makes the
     * changes permanent.
     */
    await connection.commit();
    console.log("Created table 'users'");

    /*
     * Insert multiple rows of data into the 'users' table using promise style.
     */
    await connection.execute(`
            INSERT INTO users (id, name)
            VALUES (100, 'Mario'),
                   (200, 'Barbara'),
                   (300, 'Marcelo'),
                   (400, 'Henry')
        `);

    /*
     * Commit the transaction manually to finalize the insertion of rows into
     * the 'users' table and make the changes permanent.
     */
    await connection.commit();
    console.log("Inserted data into 'users' table using promise");

    /*
     * Insert multiple rows of data into the 'users' table using callback style.
     */
    await new Promise((resolve, reject) => {
      connection.execute(
        `INSERT INTO users (id, name)
                 VALUES (500, 'Mike'),
                        (600, 'Johnny')`,
        function (err) {
          if (err) {
            console.error('Error inserting data:', err.message);
            return reject(err);
          }

          /* Manually commit the transaction. */
          connection.commit(function (err) {
            if (err) {
              console.error('Error committing transaction:', err.message);
              return reject(err);
            }

            console.log("Inserted data into 'users' table using callback");
            resolve();
          });
        }
      );
    });

    /*
     * Insert multiple rows of data into the 'users' table using batch API.
     */
    connection.addBatch("INSERT INTO users (id, name) VALUES (700, 'Logan')");
    connection.addBatch("INSERT INTO users (id, name) VALUES (800, 'Nick')");

    await connection.executeBatch();

    /* Manually commit the transaction. */
    await connection.commit();
    console.log("Inserted data into 'users' table using batch API");

    /* Retrieve all data from the 'users' table. */
    let cursor = await connection.execute('SELECT * FROM users');

    /* Manually commit the transaction. */
    await connection.commit();

    /*
     * Get cursor description - An array containing objects for each column in
     * the result set, with each object having a name and a SQLTypeCode
     * property.
     */
    console.log('Cursor description:', cursor.description);

    /*
     * Get the total number of rows in the result set for DQL queries (SELECT)
     * or the number of affected rows for DML queries (INSERT, UPDATE, and
     * DELETE).
     */
    console.log('Total number of rows in the result:', cursor.rowCount);

    /* Fetch the first 2 rows from the cursor. */
    let result = await cursor.fetch(2);
    console.log("First 2 rows retrieved from 'users' table:", result.rows);

    /* Fetch all remaining rows. */
    result = await cursor.fetchAll();
    console.log("Remaining rows retrieved from 'users' table:", result.rows);

    /* Close the cursor after retrieving the data. */
    await cursor.close();

    /* Insert a new user and then rollback the transaction. */
    await connection.execute(`
            INSERT INTO users (id, name)
            VALUES (900, 'Paul')
        `);

    /*
     * Rollback the transaction to undo the insertion.
     * After the rollback, the user with ID 900 will not exist in the table.
     * If execution is still running and needs to be stopped,
     * the abort() method can be used instead.
     */
    await connection.rollback();
    console.log('Rollback: insertion of user with ID 900 has been undone.');

    /* Drop the 'users' table to clean up the database. */
    await connection.execute('DROP TABLE users');

    /* Manually commit the transaction. */
    await connection.commit();
    console.log("Dropped table 'users'");

    /*
     * Close the database connection.
     * Closing the connection will also close all open cursors.
     */
    await connection.close();
    console.log('Connection closed');
  } catch (error) {
    /* Handle any errors that occur during the database operations. */
    console.error('Error:', error);
  }
}

/* Execute the main function to perform the database operations. */
main();
```

## Running the Application

Run the application from the directory containing your example:

```bash theme={null}
node node_regatta_example.js
```

Expected output:

```bash theme={null}
Connected to the database
Created table 'users'
Inserted data into 'users' table using promise
Inserted data into 'users' table using callback
Inserted data into 'users' table using batch API
Cursor description: [ { name: 'id', sqlTypeCode: 1 }, { name: 'name', sqlTypeCode: 7 } ]
Total number of rows in the result: 8
First 2 rows retrieved from 'users' table: [ { id: 700, name: 'Logan' }, { id: 500, name: 'Mike' } ]
Remaining rows retrieved from 'users' table: [
  { id: 600, name: 'Johnny' },
  { id: 100, name: 'Mario' },
  { id: 200, name: 'Barbara' },
  { id: 300, name: 'Marcelo' },
  { id: 400, name: 'Henry' },
  { id: 800, name: 'Nick' }
]
Rollback: insertion of user with ID 900 has been undone.
Dropped table 'users'
Connection closed
```


# Running a TypeORM Application
Source: https://docs.regatta.dev/drivers-and-clients/javascript/run-typeorm-application



Let's create a simple TypeORM application that queries the Regatta database. Start by importing the relevant classes from the `typeorm-regatta` package:

```javascript theme={null}
import { Column, DataSource, Entity, PrimaryColumn } from "typeorm-regatta"
```

Note that you should import all relevant classes based on the functionality of your application and its requirements.

## Connection Details

Connection parameters will be defined as follows:

```
const DB_HOST = "aaa.bbb.ccc.ddd:pppp";
const DB_USER = "MyUserName";
const DB_PASSWORD = "SomeSophisticatedPassword";
```

## Example Appliaction

To help you get acquainted with TypeORM on Regatta, we’ve provided a simple code example below.\
This application demonstrates common tasks such as defining entities, initializing a `DataSource`, inserting data, querying, updating, deleting, and cleaning up schema.

### Project Structure

Create the following folder structure:

```bash theme={null}
typeorm-example/
├── package.json
├── tsconfig.json
└── src/
    └── typeorm_example.ts
```

### Example Code

Create the main program and save it as: `src/typeorm_example.ts`

```typescript theme={null}
import { Column, DataSource, Entity, PrimaryColumn } from "typeorm-regatta"
import { v4 as uuidv4 } from "uuid" // Use uuid to generate unique ids
import type { QueryRunner } from "typeorm-regatta"

/**
 * Entity definition.
 * TypeORM will map this class to a "users" table.
 */
@Entity({ name: "users" })
class User {
    @PrimaryColumn()
    id!: string

    @Column()
    firstName!: string

    @Column()
    lastName!: string

    @Column()
    age!: number
}

/**
 * Connection details (replace with your own).
 * Note: In TypeORM-Regatta, host includes "<ip>:<port>".
 */
const DB_HOST = "aaa.bbb.ccc.ddd:pppp"
const DB_USER = "MyUserName"
const DB_PASSWORD = "SomeSophisticatedPassword"

/**
 * Create a new DataSource instance.
 * - `type: "regatta"` is provided by the typeorm-regatta package.
 * - `synchronize: true` tells TypeORM to create the schema automatically.
 * - `extra.deviceNames` is a Regatta-specific device mapping definition.
 */
const dataSource = new DataSource({
    type: "regatta",
    host: DB_HOST,
    username: DB_USER,
    password: DB_PASSWORD,
    entities: [User],
    synchronize: true,
    logging: true,
    extra: {
        deviceNames: ["m10d1"],
    },
})

async function run() {
    try {
        // Initialize the DataSource
        await dataSource.initialize()
        console.log("Data Source has been initialized!")

        const userRepository = dataSource.getRepository(User)

        // Create a new User
        const user = new User()
        user.id = uuidv4()
        user.firstName = "John"
        user.lastName = "Doe"
        user.age = 25

        // Insert
        await userRepository.save(user)
        console.log("User has been saved!")

        // Query
        const users = await userRepository.find()
        console.log("Users:", users)

        // Update
        user.age = 26
        await userRepository.save(user)
        console.log("User has been updated:", user)

        // Delete
        await userRepository.remove(user)
        console.log("User has been removed:", user)
    } catch (error) {
        console.error("Error:", error)
    } finally {
        // Drop the User table
        await dropUserTable()

        // Close the connection
        await dataSource.destroy()
    }
}

async function dropUserTable() {
    let queryRunner: QueryRunner | null = null

    try {
        queryRunner = dataSource.createQueryRunner()
        await queryRunner.connect()
        await queryRunner.startTransaction()

        // Drop the table created by @Entity() -> default table name is "user"
        await queryRunner.query('DROP TABLE "users"')
        console.log("User table has been dropped!")

        await queryRunner.commitTransaction()
    } catch (error) {
        console.error("Error dropping table:", error)
        if (queryRunner) {
            await queryRunner.rollbackTransaction()
        }
    } finally {
        if (queryRunner) {
            await queryRunner.release()
        }
    }
}

// Run the example app
run()
```

### TypeScript Configuration

Create `tsconfig.json` in the project root:

```json theme={null}
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "strictPropertyInitialization": false,
    "emitDecoratorMetadata": true,
    "outDir": "./dist",
    "lib": ["ES2020", "DOM"],
    "typeRoots": ["./node_modules/@types"]
  },
  "include": ["src/typeorm_example.ts"]
}
```

### Package Setup

Create a `package.json` in the project root:

```json theme={null}
{
  "name": "typeorm-regatta-example",
  "version": "1.0.0",
  "private": true,
  "type": "commonjs",
  "scripts": {
    "build": "tsc",
    "start": "node dist/typeorm_example.js"
  },
  "dependencies": {
    "typeorm-regatta": "file:path/to/typeorm-regatta-<version>.tgz",
    "node-regatta": "file:path/to/node-regatta-<version>_<type>.tgz",
    "uuid": "^9.0.0",
    "reflect-metadata": "^0.2.0"
  },
  "devDependencies": {
    "typescript": "^5.3.3",
    "@types/node": "^18.13.0",
    "@types/uuid": "^9.0.0"
  }
}
```

<Note>
  This `package.json` assumes you already downloaded the [**Regatta TypeORM package and the Node.js driver**](/drivers-and-clients/javascript/install-your-javascript-client), and have them available on your local environment.

  Please ensure that you update the `package.json` file with the correct paths to the downloaded `.tgz` files before proceeding.
</Note>

## Running the Application

From the project root run:

```bash theme={null}
npm install
npm run build
npm start
```

Expected output:

```bash theme={null}
query: SHOW TABLES LIKE 'users'
query: CREATE TABLE SET NOT READY "users" ("id" varchar PRIMARY KEY INDEX WITH (devices = (m10d1)), "firstName" varchar NOT NULL, "lastName" varchar NOT NULL, "age" int8 NOT NULL) WITH (devices = (m10d1))
query: ALTER TABLE "users" SET READY
Data Source has been initialized!
query: SELECT "User"."id" AS "User_id", "User"."firstName" AS "User_firstName", "User"."lastName" AS "User_lastName", "User"."age" AS "User_age" FROM "users" "User" WHERE "User"."id" IN ($1) -- PARAMETERS: ["acaf5ed5-223d-40ae-8080-9196717cd54f"]
query: START TRANSACTION
query: INSERT INTO "users"("id", "firstName", "lastName", "age") VALUES ($1, $2, $3, $4) -- PARAMETERS: ["acaf5ed5-223d-40ae-8080-9196717cd54f","John","Doe",25]
query: COMMIT
User has been saved!
query: SELECT "User"."id" AS "User_id", "User"."firstName" AS "User_firstName", "User"."lastName" AS "User_lastName", "User"."age" AS "User_age" FROM "users" "User"
Users: [
  User {
    id: 'acaf5ed5-223d-40ae-8080-9196717cd54f',
    firstName: 'John',
    lastName: 'Doe',
    age: 25
  }
]
query: SELECT "User"."id" AS "User_id", "User"."firstName" AS "User_firstName", "User"."lastName" AS "User_lastName", "User"."age" AS "User_age" FROM "users" "User" WHERE "User"."id" IN ($1) -- PARAMETERS: ["acaf5ed5-223d-40ae-8080-9196717cd54f"]
query: START TRANSACTION
query: UPDATE "users" SET "age" = $1 WHERE "id" IN ($2) -- PARAMETERS: [26,"acaf5ed5-223d-40ae-8080-9196717cd54f"]
query: COMMIT
User has been updated: User {
  id: 'acaf5ed5-223d-40ae-8080-9196717cd54f',
  firstName: 'John',
  lastName: 'Doe',
  age: 26
}
query: SELECT "User"."id" AS "User_id", "User"."firstName" AS "User_firstName", "User"."lastName" AS "User_lastName", "User"."age" AS "User_age" FROM "users" "User" WHERE "User"."id" IN ($1) -- PARAMETERS: ["acaf5ed5-223d-40ae-8080-9196717cd54f"]
query: START TRANSACTION
query: DELETE FROM "users" WHERE "id" = $1 -- PARAMETERS: ["acaf5ed5-223d-40ae-8080-9196717cd54f"]
query: COMMIT
User has been removed: User { id: undefined, firstName: 'John', lastName: 'Doe', age: 26 }
query: START TRANSACTION
query: DROP TABLE "users"
User table has been dropped!
query: COMMIT
```


# Install Your Python Client
Source: https://docs.regatta.dev/drivers-and-clients/python/install-your-python-client



## Drivers

<Tabs>
  <Tab title="Python">
    1. [Download the Python driver](/drivers-and-clients/download-drivers-and-clients).
    2. Install the driver:

       ```bash theme={null}
       $ pip install pyregatta-<version>_<type>.tar.gz
       ```

       ### Notes

       * **Python 3.6** or newer is required to use the Regatta Python driver.
       * If you are using the **Full** driver package, the Regatta client library is included automatically. If you are using the **Standalone** version, ensure that the [client library is installed](/drivers-and-clients/client-lib).
       * The Regatta Python driver follows the PEP 249 / DB-API 2.0 specification. Refer to the [official Python DB-API specification documentation](https://peps.python.org/pep-0249/) for full API details.
  </Tab>
</Tabs>

***

## ORM frameworks

<Tabs>
  <Tab title="SQLAlchemy">
    1. [Download the Regatta SQLAlchemy dialect](/drivers-and-clients/download-drivers-and-clients).
    2. Install the package:

       ```bash theme={null}
       $ pip install sqlalchemy-regatta-<version>.tar.gz
       ```

       <Note>
         Regatta supports SQLAlchemy version 2.0.34 and above. Refer to the [official SQLAlchemy documentation](https://docs.sqlalchemy.org/en/20/intro.html#installation-guide) for installation instructions and API details.
       </Note>
  </Tab>

  <Tab title="Django">
    1. [Download the Regatta Django package](/drivers-and-clients/download-drivers-and-clients).
    2. Install the package:

       ```bash theme={null}
       $ pip install django-regatta-<version>.tar.gz
       ```

       <Note>
         Regatta supports Django version 4.2 and above. Refer to the [official Django documentation](https://docs.djangoproject.com/en/4.2/) for installation instructions and API details.
       </Note>
  </Tab>
</Tabs>


# Run a Python Application
Source: https://docs.regatta.dev/drivers-and-clients/python/run-python-application



Let's create a simple Python application that queries the Regatta database. Start by adding the reference to the regatta driver:

```Python theme={null}
from pyregatta import connect
```

Note that you should import all relevant classes based on the functionality of your application
and its requirements.

## Connection Details

Connection parameters will be defined as follows:

```Python theme={null}
host = "aaa.bbb.ccc.ddd:ppp"
user = "MyUserName"
password = "SomeSophisticatedPassword"
```

## Example Appliaction

Below is an example of a sample application that creates an `employees` table, adds four rows and then selects and prints the rows.

Create the main program and save it as: `database_example.py`

```Python theme={null}
from pyregatta import connect

host = "aaa.bbb.ccc.ddd:pppp"
user = "MyUserName"
password = "SomeSophisticatedPassword"

# The connection and cursor are automatically closed when their blocks are exited
with connect(user, password, host) as conn:
    with conn.cursor() as cursor:
        # Create an employees table
        cursor.execute(
            """
            CREATE TABLE employees
            (
                employee_key        INT PRIMARY KEY INDEX,
                employee_name       VARCHAR(40) NOT NULL,
                employee_salary     INT,
                employee_department VARCHAR(50) NOT NULL
            )
            """
        )
        conn.commit()

        # Insert some sample rows
        cursor.execute(
            """
            INSERT INTO employees (employee_key,
                                   employee_name,
                                   employee_salary,
                                   employee_department)
            VALUES (1, 'John Doe', 10932, 'DevOps'),
                   (2, 'Richard Roe', 18324, 'Legal'),
                   (3, 'Jane Roe', 20411, 'Engineering'),
                   (4, 'Rachel Roe', 19555, 'Support')
            """
        )
        conn.commit()

        # Query data
        cursor.execute("SELECT * FROM employees")

        # Fetch all rows
        rows = cursor.fetchall()

        # Print the results
        for row in rows:
            # Whole row (supports index and attribute access)
            print(row)

            # Example: access a specific column
            # print(row.employee_name)
            # print(row[0])  # employee_key

        conn.commit()
        # Drop the table
        cursor.execute("DROP TABLE employees")
```

## Running the Appliaction

Run the application from the directory containing your example:

```bash theme={null}
python3 database_example.py
```

Expected output:

```bash theme={null}
(1, 'John Doe', 10932, 'DevOps')
John Doe
1
(2, 'Richard Roe', 18324, 'Legal')
Richard Roe
2
(3, 'Jane Roe', 20411, 'Engineering')
Jane Roe
3
(4, 'Rachel Roe', 19555, 'Support')
Rachel Roe
4
```


# Regatta CLI
Source: https://docs.regatta.dev/drivers-and-clients/regatta-cli

A lightweight command-line tool for connecting to, managing, and querying your Regatta database clusters.

The Regatta Command-Line Interface (CLI) provides a quick and convenient way to manage and query your Regatta database. You’ll need:

1. Valid user credentials
2. Network access to an active Regatta cluster

## Installation

<Tabs>
  <Tab title="Linux">
    Copy the Regatta CLI RPM package to your target Linux machine and install it:

    ```bash theme={null}
    sudo rpm -i regatta-cli-<version>.el8.x86_64.rpm
    ```

    Verify the CLI binary is installed:

    ```
    ls /opt/regatta/1.0/clients/cli/bin/client_cli
    ```
  </Tab>
</Tabs>

## Launch the CLI

Start the client:

```bash theme={null}
/opt/regatta/1.0/clients/cli/bin/client_cli
```

You’ll see the prompt:

```powershell theme={null}
rdb>
```

## Connect to Your Cluster

Authenticate with your credentials and cluster address:

```powershell theme={null}
rdb>\connect user=admin pass=RegattaDefault1234! url=aaa.bbb.ccc.ddd:ppp
```

On success, you’ll see:

````
Successfully connected to RegattaDB system 

<Note>
  NOTE: From this point forward the rdb\> prompt will be omitted.
</Note>

## Table Management

### Create a Table

Let's create an `employees` table:

```sql
CREATE TABLE employees (
  employee_key INT PRIMARY KEY INDEX,
  employee_name VARCHAR(40) NOT NULL,
  employee_salary INT,
  employee_department VARCHAR(50) NOT NULL);
````

If successful:

```sql theme={null}
statement executed successfully 
```

Verify with:

```sql theme={null}
SHOW TABLES;
```

```sql theme={null}
| TABLE_NAME    | IS_READY | PRIMARY_KEY_COLUMN | DEVICES |
-----------------------------------------------------------
| employees     | true     | employee_key       | m10d1   |
```

### Insert Data

Insert multiple rows:

```sql theme={null}
INSERT INTO employees (
  employee_key,
  employee_name,
  employee_salary,
  employee_department)
VALUES 
  (1,'John Doe', 10932, 'DevOps'),    
  (2,'Richard Roe', 18324, 'Legal'),
  (3,'Jane Roe', 20411, 'SoftwareDev'),
  (4,'Rachel Roe', 19555, 'Support');
```

```sql theme={null}
statement executed successfully  
```

### Query Data

Select all records:

```sql theme={null}
SELECT * from employees;
```

```sql theme={null}
statement executed successfully
| employee_key | employee_name | employee_salary | employee_department |
------------------------------------------------------------------------
|            1 | John Doe      |           10932 | DevOps              |
|            2 | Richard Roe   |           18324 | Legal               |
|            3 | Jane Roe      |           20411 | SoftwareDev         |
|            4 | Rachel Roe    |           19555 | Support             |
```

Filter with a WHERE clause:

```sql theme={null}
SELECT employee_name, employee_salary
FROM employees
WHERE employee_salary > 18324;
```

```sql theme={null}
statement executed successfully
| employee_name | employee_salary |
-----------------------------------
| Jane Roe      |           20411 |
| Rachel Roe    |           19555 |
```

### Update Records

Give Richard Roe a raise:

```sql theme={null}
UPDATE employees SET employee_salary=20202 WHERE employee_name='Richard Roe';
```

Re-run the previous `SELECT` to confirm:

```sql theme={null}
statement executed successfully
| employee_name | employee_salary |
-----------------------------------
| Richard Roe   |           20202 |
| Jane Roe      |           20411 |
| Rachel Roe    |           19555 |
```

### Delete Records

Remove the employee with the highest salary:

```sql theme={null}
DELETE FROM employees
WHERE employee_salary = (
  SELECT MAX(employee_salary)
  FROM employees
);
```

Verify deletion:

```sql theme={null}
statement executed successfully
| employee_name | employee_salary |
-----------------------------------
| Richard Roe   |           20202 |
| Rachel Roe    |           19555 |
```

### Drop the Table

List tables:

```sql theme={null}
SHOW TABLES;
```

This will present all the tables in the database:

```sql theme={null}
| TABLE_NAME    | IS_READY | PRIMARY_KEY_COLUMN | DEVICES |
-----------------------------------------------------------
| employees     | true     | employee_key       | m10d1   |
```

Drop `employees`:

```sql theme={null}
DROP TABLE employees;
```

Confirm it’s gone:

```sql theme={null}
SHOW TABLES
```

```sql theme={null}
statement executed successfully
| TABLE_NAME | IS_READY | PRIMARY_KEY_COLUMN | DEVICES | TABLE_METADATA |
-------------------------------------------------------------------------
```

## Next Steps

* Explore advanced CLI commands usding the [SQL guide](/sql/specification).
* Integrate with your preferred language using one of our [language-specific drivers.](/drivers-and-clients/connecting-applications-to-regatta)


# Access the Cloud
Source: https://docs.regatta.dev/getting-started/access-the-cloud



To access the Cloud website, click the following URL to enter the login page:

[**Regatta Cloud**](https://cloud.regatta.dev)

You’ll be required to enter your credentials. To login, Enter the email used to register and the password received from Regatta. Note that if the email being used is one associated with Google and you are already signed into Google, you may leverage the Single-Sign-On with the Google option.

Once logged in, the Clusters screen will appear.

If you already have created clusters before, or someone from your account did, they will be listed here.

There are several screens you can select from this page:

* **Clusters** - which is the first page you will see once logged in.
* **Clients & Tools** - which is covered in the [Drivers & Clients](https://docs.regatta.dev/drivers-and-clients/connecting-applications-to-regatta) section.
* **Backup & Restore** - which is covered in the [Backup & Restore](https://docs.regatta.dev/regatta-cloud/database-backup-restore) section.
* **Credits** - which allows you to manage your available cloud credits.
* **Documentation** - Will get you here.
* **Support** - will redirect you to the support channel.


# Creating a Cluster
Source: https://docs.regatta.dev/getting-started/creating-a-cluster



You may select to use one of the available clusters or create a new one. In this example, we will create a new cluster.

Clicking on the **+ CREATE NEW CLUSTER** button will redirect you to the **Create New Cluster** screen.

Choose a name for the cluster (one that wasn’t used before). Here we named it **my-1st-regatta-cluster**.

Please note that this document will refer back to the cluster name in later steps. If you decided to use a different cluster name, substitute it as appropriate in the steps throughout the Getting Started Guide.

Select the Provider from the available list and the Region from the drop-menu.

Please note that currently we only offer **Google Cloud Platform** as a Provider and the **us\_east** as region.

Then select the **Cluster Type**. Once you click on the field, a drop-down menu will appear offering different cluster sizes. Please select the size required. In this example we select the **XSMALL** cluster.

Click the **CONFIRM** button to complete the process. In response, you will go back to the **Clusters** screen and your new cluster will appear in the **Starting** status. Please wait until the cluster becomes available. The status will change from **Starting** to **Running**.

You just created your first Regatta cluster. You can start deploying your database. This can be done via multiple ways of connecting to a Regatta cluster. The following steps will use the Regatta Cloud WebCLI. Other methods of connecting to a Regatta cluster will be covered in subsequent sections.


# Getting Started Using Regatta Cloud
Source: https://docs.regatta.dev/getting-started/getting-started-using-regatta-cloud



The Regatta Cloud is an easy way to get you started. In the following sections we will guide you on how to access Regatta cloud, deploy a Regatta database, and access it using the WebCLI interface.

**Note**: If you would like to create a self-hosted cluster, please refer to the [**Self-Hosted-Deployment**](https://docs.regatta.dev/self-hosted-deployment/prerequisites) section.

It is assumed that you are already registered with Regatta and received a Username (email used to register) and Password to access the Regatta Cloud Platform. It is also assumed that a registered account(s) is associated with the user.

If this is not the case, please reach out to Regatta support.


# Comparing Performance
Source: https://docs.regatta.dev/getting-started/linear-scaling/comparing-performance/comparing-performance



To compare the performance and observe the linear scaling, we will perform a query that will
require heavy processing. The following query calculates the number of items a customer
bought of his or her favorite item. We order it in an ASCENDING fashion based on the Customer
ID and display the first 5.

Though at first glance it might look like a simple query, it involves reading and processing a large
amount of data.

The query for the total number of items bought by a customer:

```SQL theme={null}
SELECT 
    c.Name, 
    c.Item, 
    COUNT(*) AS NumberOfItems
FROM 
    Customers c
JOIN 
    Purchases p ON c.CustomerID = p.CustomerID AND c.Item = p.Item
GROUP BY 
    c.Name, c.Item, c.CustomerID
ORDER BY 
    c.CustomerID ASC
LIMIT 5;
```


# MEDIUM Cluster
Source: https://docs.regatta.dev/getting-started/linear-scaling/comparing-performance/medium-cluster



Let’s connect to our **demo-medium** cluster. Now perform the same query on the larger cluster.
This cluster has 10 nodes and should be around 10 times faster. Let’s run the query again
through the CLI.

<Frame>
  <img alt="image.png" />
</Frame>

As can be seen above, in the larger cluster it took about 2.8 seconds. When comparing with the previous duration of demo-small of roughly 9.4 seconds we can see that the ratio between the two durations is 3⅓ (=3.35) which is 10:3, the ratio between the cluster sizes. The larger cluster executed that same query 3⅓ times faster.

Please note that this is a complex JOIN requires processing a large amount of data. The database must hold a very large amount of intermediate data comprised from all tables to accomplish this task.


# SMALL Cluster
Source: https://docs.regatta.dev/getting-started/linear-scaling/comparing-performance/small-cluster



We shall start with smaller **demo-small** cluster. Run the query through the WebCLI. In the screen below we can see the result:

<Frame>
  <img alt="image.png" />
</Frame>

The query took about 9.4 seconds.

<Note>
  Note: One should appreciate that the time it takes varies and it depends on some factors, such as the interdependency in the query, the actual network and congestion and more.
</Note>


# Creating Demo Clusters
Source: https://docs.regatta.dev/getting-started/linear-scaling/creating-demo-environment/creating-demo-clusters



Now for the 2 clusters.

The first cluster will be **demo-small** - a single‑node cluster with a single device. The other cluster will be **demo-medium** which is comprised of 10 nodes of the same type as **demo‑small**.

To deploy **demo-small**, follow the steps described in Creating a Cluster, select the SMALL cluster type this time, but this time switch on the **Deploy Demo Data** button. Repeat the same steps for **demo-medium** but this time select the MEDIUM type.\
Deploying the clusters will take roughly 10 minutes. Once completed, each of the clusters will have the two tables described previously, populated.

Let’s see the number of nodes for each cluster. Just run the following command for each of the clusters in its respective WebCLI:

```SQL theme={null}
SHOW NODES
```

For each we will see the nodes comprising it.

For \*\*demo-xsmall \*\*there are 3 nodes in the cluster, and for \*\*demo-medium \*\*there are 10 nodes (though you will need to scroll down to see the 10th one).

Both tables in both clusters are now populated with the same data. 1 million rows in **Customers** table and 80 million rows in the **Purchases** table. Performing the following command for each of the tables (namely, Customers and Purchases) will show that.

```SQL theme={null}
SELECT COUNT (*) FROM <table-name>
```


# Creating the Demo Environment
Source: https://docs.regatta.dev/getting-started/linear-scaling/creating-demo-environment/creating-demo-environment



As stated above, we will have 2 clusters with 2 tables. Each table will be populated with data\
where the number of rows is denoted next to the table’s name.

### **Table's Schemas - Sport's Store**

The schemas for the 2 tables are:

`Customers (20M rows)`

* `CustomerID INT`
* `Name VARCHAR (100)`
* `Item VARCHAR (100)`
* `Phone VARCHAR (15)`

`Purchases (20M rows)`

* `PurchaseID INT`
* `CustomerID INT`
* `PurchaseDate DATE`
* `AreaCode VARCHAR (3)`
* `Item VARCHAR (100)`
* `Price DECIMAL(10, 2)`


# Linear Scaling
Source: https://docs.regatta.dev/getting-started/linear-scaling/linear-scaling



One of the most exciting features of the Regatta Database is its **linear scaling** capability: performance scales linearly with cluster size for both OLTP and OLAP workloads.

Next, we’ll demonstrate this using an OLAP query, showing how response times improve in proportion to cluster growth. To do that, we’ll create two clusters and enable the **Deploy Demo Data** option (a toggle on the **Create New Cluster** screen). Enabling it automatically creates two predefined tables and populates them with sample data.


# Create a Table
Source: https://docs.regatta.dev/getting-started/regatta-basics/creating-a-table/create-a-table



In this section we will demonstrate how to create a new table.

Please note that most Regatta SQL commands are exactly like PostgreSQL. When they divert, we will note that clearly.

To create a table (or for executing other SQL commands) we will open the ebWCLI window by clicking the **Connect** button next to our cluster.

In the input line we will enter the desired SQL command.

Assume you would like to create the following table:

`Table: employees`

* `employee_key INT`
* `employee_name VARCHAR (40)`
* `employee_salary INT`

`employee_department VARCHAR (50)`

In Regatta, you may define in which devices (storage devices that are local to each node in the cluster) the table should be stored in as well as indexes if specified. In the following example we will show both methods.


# Default Device Mapping
Source: https://docs.regatta.dev/getting-started/regatta-basics/creating-a-table/default-device-mapping



The simple option is creating the cluster without specifying any device. If that method is chosen, then Regatta will map all tables and indexes for you.

To create the described table, enter the following SQL command:

```SQL theme={null}
 CREATE TABLE employees (
 employee_key INT PRIMARY KEY INDEX,
 employee_name VARCHAR(40) NOT NULL,
 employee_salary INT,
 employee_department VARCHAR(50) NOT NULL)
```

Enter SQL command SHOW TABLES:

```SQL theme={null}
SHOW TABLES
```

In response, the table details will be displayed. We can see the **employee** table with all the columns and the device mappings. If we do not specify the mapping, the system will distribute the table rows across all the devices and choose a single random device for the indexes.

**Notes:**

* When looking at the mapping, you can see that the same device appears three times. This is the out-of-the-box default mapping, which delivers high performance.
* This mapping is not necessarily the most performant, but it is the simplest behavior, and it allows someone to easily get started (which is the purpose of this document).
* When there is more than one device used for indexing, we need to define range separators that will define how to map the indexes to the different devices. It is up to the user to specify this mapping. In the default mapping the indexes are mapped to a single device and therefore there is no need for range separators, so it defaults to ***no range separators***.
* For further details, please refer to the [**Table creation with default data distribution**](https://docs.regatta.dev/tuning-performance/distributing-tables#table-creation-with-default-data-distribution)\*\* \*\*section.


# Selected Device Mapping
Source: https://docs.regatta.dev/getting-started/regatta-basics/creating-a-table/selected-device-mapping



If you do decide to select to define the mapping for either data or indexes, you may do so. If you define one and not the other, Regatta will complete the definition for you. For example, if you do map the table to some devices but not decaler where an indexed key should go, Regatta will select a random device and map the index to it.

The first command should display the devices that are used in the cluster. We enter SHOW DEVICES in the WebCLI command line:

```SQL theme={null}
SHOW DEVICES
```

The next command will be the CREATE TABLE command. This command will look as follows
(note the usage of the devices). Let’s create a similar table called **workers.** Enter the following
command:

```SQL theme={null}
CREATE TABLE workers (
 worker_key INT PRIMARY KEY INDEX WITH (devices = (m10d1)),
 worker_name VARCHAR(40) NOT NULL,
 worker_salary INT,
 worker_department VARCHAR(50) NOT NULL)
WITH (devices = (m10d1))
```

Running it will create the desired table.

Enter the SQL show tables command:

```SQL theme={null}
SHOW TABLES
```

We can see the table with all the columns and the device mapping. Note that in the **workers** table, the data is only mapped once to the device since this is what we chose as opposed to **employees** where Regatta mapped it 3 times.

We will continue here using the **employees** table.


# Credentials
Source: https://docs.regatta.dev/getting-started/regatta-basics/credentials



All Regatta cluster deployments come with a default user. The default user’s credentials are:

* Username: admin
* Password: RegattaDefault1234!

These can be used out-of-the-box.

To change the default password, run the following command in the WebCLI:

```SQL theme={null}
ALTER USER admin WITH PASSWORD '<new_password>'
```

To create a new user to use, run the following command in the WebCLI:
Please note that there are requirements for the username and password format.

```SQL theme={null}
CREATE USER <user_name> WITH PASSWORD '<password>' <new_password>'
```

### Username

* Usernames should be between 1 and up to 64 characters long.
* Begin with a letter (a-z or A-Z) or an underscore (\_).
* Subsequent characters can be letters, underscores, digits (0-9), or dollar signs (\$).
* Unsupported characters are permitted only if they are surrounded by double quotes.
* Reserved words can be used as a username.
* Names are case-sensitive. However, unquoted names are always converted to
  lowercase, and quoted names preserve the case and also allow spaces within the
  names.

### Password

* Password length should be between 8 and 100 characters
* A password must contain at least 3 of the following character classes:
  * Upper case characters
  * Lower case characters
  * Numbers
  * Symbols. Any of the following symbols can be used. The list is enclosed in
    double quotes. “ ' \~ ! @ # \$ % ^ & \* ( ) \_ - + =  \[ ] \ / \< > , . ; ? ‘ : | (space)”


# Delete Entry from Table
Source: https://docs.regatta.dev/getting-started/regatta-basics/delete-entry-from-table



Let's remove the employee with the maximal salary; that will be Jane Roe we have seen previously. We will execute the following SQL command:

```SQL theme={null}
DELETE FROM employees 
WHERE employee_salary = (SELECT max(employee_salary) FROM employees)
```

We will run the previous SELECT again and as expected, Jane Roe was deleted.


# Drop Table
Source: https://docs.regatta.dev/getting-started/regatta-basics/drop-table



Now we will remove the table and get back to an empty database. First, let’s run:

```SQL theme={null}
SHOW TABLES
```

This will present all the tables in the database.

Now, perform the following SQL DROP command:

```SQL theme={null}
DROP TABLE employees
```

And don’t forget to also drop the workers table:

```SQL theme={null}
DROP TABLE workers
```

Then run:

```SQL theme={null}
SHOW TABLES
```

And indeed, there are no tables in the database.


# Insert Values
Source: https://docs.regatta.dev/getting-started/regatta-basics/insert-values



Inserting values into Regatta is no different than PostgreSQL. The following command will insert a few values into the employees table:

```SQL theme={null}
INSERT INTO employees (
 employee_key, employee_name, employee_salary, employee_department)
VALUES 
 (1,'John Doe', 10932, 'DevOps'), (2,'Richard Roe', 18324, 'Legal'),
 (3,'Jane Roe', 20411, 'SoftwareDev'),
 (4,'Rachel Roe', 19555, 'Support')
```

Next we will access these values.


# Select Values from Table
Source: https://docs.regatta.dev/getting-started/regatta-basics/select-values-from-table



The SELECT command is also the same as PostgreSQL. Run the following command to see all values in the table:

```SQL theme={null}
SELECT * from employees
```

The CLI will display all entries.

Obviously, we can perform a more complex SELECT command. For example:

```SQL theme={null}
SELECT employee_name, employee_salary 
FROM employees 
WHERE employee_salary > 18324
```

The output, as expected, will be Jane Doe and Rachel Roe since their salary is more than 18324.


# Update Entry
Source: https://docs.regatta.dev/getting-started/regatta-basics/update-entry



Let’s give Richard Roe a raise.

```SQL theme={null}
UPDATE employees SET employee_salary=20202
WHERE employee_name='Richard Roe'
```

Now let’s run the SELECT command from the previous section and see if Richard Roe appears
now.

Indeed, Richard Roe appears now as he has a higher salary.


# Regatta Documentation
Source: https://docs.regatta.dev/home

Limitless power and scale

**Regatta is a mission-critical, extreme performance transactional and analytical database that brings simplicity alongside powerful features.**

Regatta is a modern SQL database that delivers an all-in-one solution. You can run all your workloads, either analytical or transactional on the same system at the highest performance without losing a beat. Increase the cluster size and see the performance grows linearly with it.

Below you can get access to all the documentation available for Regatta. If it's your first time here, start with the Getting Started link. Otherwise, chose the subject you would like to learn about.

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/getting-started/getting-started-using-regatta-cloud" />
</CardGroup>

<CardGroup>
  <Card title="Drivers & Clients" icon="code" href="/drivers-and-clients/connecting-applications-to-regatta" />

  <Card title="Regatta Cloud" icon="cloud" href="/regatta-cloud/regatta-cloud/regatta-cloud" />

  <Card title="SQL" icon="database" href="/sql/introduction" />

  <Card title="Tuning Performance" icon="server" href="/tuning-performance/introduction/introduction" />
</CardGroup>

***

## Access Regatta Docs Through Your AI Assistant

Connect your AI tools directly to the Regatta documentation using [MCP](https://modelcontextprotocol.io/docs/getting-started/intro). This enables natural-language queries with answers sourced directly from the docs.

<CardGroup>
  <Card title="MCP endpoint" icon="link">
    Use the following MCP URL when adding a custom connector:

    ```bash theme={null}
    https://docs.regatta.dev/mcp
    ```
  </Card>

  <Card title="Connect using Claude" icon="sparkles">
    Follow these steps to enable Regatta Docs inside Claude:

    1. Log in to your [Claude.ai](https://claude.ai) account
    2. Open **Settings → Connectors**
    3. Click **Add custom connector** and paste the Regatta MCP URL
    4. Save the connector
    5. After saving, the **Regatta Docs** tool will automatically appear in the Claude tool list whenever you start a new chat.

    All set! You can now ask Claude questions like *"Search Regatta Docs for data distribuition best practices"* and it will use the MCP server to access the documentation directly.
  </Card>
</CardGroup>


# Access the Cloud
Source: https://docs.regatta.dev/regatta-cloud/regatta-cloud/access-the-cloud



To access the Cloud website, click the following URL to enter the login page:

[https://cloud.regatta.dev](https://cloud.regatta.dev)

The following screen will appear, and you’ll be required to enter your credentials.

<Frame>
  <img />
</Frame>

To login, Enter the email used to register and the password received from Regatta. Note that if
the email being used is one associated with Google and you are already signed into Google, you
may leverage the Single-Sign-On with the Google option.

Once logged in, the Clusters screen will appear:

<Frame>
  <img />
</Frame>

If you already have created clusters before, or someone from your account did, they will be listed here.

There are several screens you can select from this page:

* **Clusters** - which we are on
* **Backup/Restore** - will be covered in Database Backup and Restore
* **Support** - will redirect you to the support channel
* **Documentation** - Will grant access to useful documents (including this)


# Cluster IP
Source: https://docs.regatta.dev/regatta-cloud/regatta-cloud/cluster-ip



To attain a cluster IP, go to the platform and access the desired database by clicking on its name
in the **Cluster Name** column in the **Clusters** page. You will notice that it is a link.

Under the **Security** section in the **Connection Details** tab, you will see the IP and PORT of that
cluster. Copy them for the next steps.


# Creating a Cluster
Source: https://docs.regatta.dev/regatta-cloud/regatta-cloud/create-a-cluster



You may select to use one of the available clusters or create a new one. In this example, we will
create a new cluster.

The following section describes how to create a new cluster.

Clicking on the **+ CREATE NEW CLUSTER** button (see Figure 2 Clusters page) will redirect you to the
**Create New Cluster** screen:

<Frame>
  <img />
</Frame>

Choose a name for the cluster (one that wasn’t used before). Here we named it **my-1st-regatta-cluster**.

Please note that this document will refer back to the cluster name in later steps. If you decided to use a different cluster name, substitute it as appropriate in the steps throughout the Getting Started Guide.

Select the Provider from the available list and the Region from the drop-menu.

Please note that currently we only offer **Google Cloud Platform** as a Provider and the **us\_east** as region.

Then select the **Cluster Type**. Once you click on the field, a drop-down menu will appear offering different cluster sizes (Figure 4). Please select the size required.

<Frame>
  <img />
</Frame>

In this example we select the **XSMALL** cluster.

Click the **CONFIRM** button to complete the process. In response, you will go back to the **Clusters** screen and your new cluster will appear in the **Starting** status.

<Frame>
  <img />
</Frame>

Please wait until the cluster becomes available. The status will change from **Starting** to **Running** as seen below (Frame 6).

<Frame>
  <img />
</Frame>

You just created your first Regatta cluster. You can start deploying your database. This can be done via multiple ways of connecting to a Regatta cluster. The following steps will use the Regatta Cloud user interface CLI. Other methods of connecting to a Regatta cluster will be covered in subsequent sections.


# Delete Cluster
Source: https://docs.regatta.dev/regatta-cloud/regatta-cloud/delete-cluster



Once a cluster has served its purpose, you may delete it. To delete a cluster, go to the clusters page, select the cluster to be deleted by clicking on the cog to its right and selecting Delete by hovering over it.

Click on the **delete** option. A pop up window will ask you to enter the cluster name (don’t worry, it appears at the top of the message). Once the name is entered (no leading or following spaces please), the **CONFIRM** button will become available. Click it.

Once confirmed, a message stating that the deletion started will appear at the top and the
**Status** of the cluster will change to **Deleting.** From this point, the cluster is unavailable. Once
removed completely, it will disappear from the cluster list.


# Regatta Cloud
Source: https://docs.regatta.dev/regatta-cloud/regatta-cloud/regatta-cloud



The Regatta Cloud is an easy way to create and access your Regatta database using the web CLI.

The following sections describe how to simply deploy and access the Regatta database through the web interface.


# Networking
Source: https://docs.regatta.dev/self-hosted-deployment/kubernetes/configuration/networking

How the operator exposes SM and RDB Pods inside and outside your Kubernetes cluster.

The operator gives every module a stable Kubernetes Service, so its address does not change even if Kubernetes reschedules its Pod to a different node:

* The SM Pod gets one Service, always `ClusterIP`, reachable only from inside your Kubernetes cluster.
* Every RDB Pod gets its own Service, also always `ClusterIP`. The operator and SM use these directly for topology-aware routing to a specific RDB replica.
* All RDB Pods together also get one aggregate Service, `ClusterIP` by default or `LoadBalancer` if you set `spec.rdb.service.type`. This is a simple entry point for clients that do not need to target a specific RDB replica.

Setting `spec.rdb.service.type: LoadBalancer` requests an externally reachable address for the aggregate Service. Kubernetes does not fulfill this by itself: it depends on a load-balancer integration already being available in your cluster - built in on managed offerings such as GKE, EKS, and AKS, or provided by an on-prem controller such as MetalLB. If your cluster has no such integration, the Service simply stays `<pending>` with no external IP. When the address is provisioned, traffic sent to it is forwarded to the Service, which then load-balances it across every RDB Pod, the same way any Kubernetes Service load-balances across its backing Pods, and is shared across every client that connects to it rather than reserved for one. It does not target one specific RDB Pod: a client connecting through the aggregate Service may reach any RDB replica.

You can additionally restrict which source IPs may reach it with `spec.rdb.service.loadBalancerSourceRanges` (a list of CIDR blocks). Just like `type: LoadBalancer` itself, Kubernetes does not enforce this field directly: it is fulfilled by the same load-balancer integration, and enforcement varies by platform - for example GKE's translates it into a firewall rule at the network edge, while other cloud providers and on-prem controllers differ or may not support it at all. Verify traffic is actually restricted on your platform rather than assuming it always is; if the integration ignores the field, the Service stays reachable from anywhere.

<Warning>
  The aggregate RDB Service is the only Service the operator itself can expose outside your Kubernetes cluster: the SM Service and per-RDB Services are always generated as `ClusterIP`, with no built-in option to change that. This means RegattaDB management operations have no supported external access path out of the box - it does not mean SM is unreachable from outside the cluster. Nothing stops you from creating your own additional Service (or Ingress) pointed at the SM Pod's selector labels to expose it yourself; the operator simply does not do this for you, will not manage or secure it, and will not know about it.
</Warning>

If you need to run RegattaDB management commands from an external host, run your client as a Pod inside the Kubernetes cluster, use a standard Kubernetes technique such as `kubectl port-forward` to reach SM temporarily, or create your own additional Service restricted to trusted source ranges and take responsibility for securing it. `spec.rdb.service.type` only supports `ClusterIP`/`LoadBalancer` today; if you specifically need a NodePort-style Service, the same applies - you could create your own additional Service alongside the operator-managed ones.


# Configuration Overview
Source: https://docs.regatta.dev/self-hosted-deployment/kubernetes/configuration/overview

The RegattaCluster resource: object header, version and image, and module settings.

Everything you configure lives in a single `RegattaCluster` resource. This page covers the fields you set for every deployment: the object header, RegattaDB version and image, and per-module settings. See [Storage](./storage.mdx), [Networking](./networking.mdx), [Security & Lifecycle](./security-and-lifecycle.mdx), and [Resources & Scheduling](./resources-and-scheduling.mdx) for the rest of the spec.

## A minimal RegattaCluster resource

```yaml theme={null}
apiVersion: regatta.dev/<crd-api-version>
kind: RegattaCluster
metadata:
  name: my-regattadb
  namespace: <namespace>
spec:
  version: "<version>"
  image:
    repository: registry.example.com/regatta
    tag: "<version>"
  security:
    runAsUser: 1000
    runAsGroup: 1001
    fsGroup: 1001
  rdb:
    replicas: 3
    blockStorage:
      size: 60Gi
  repoStorage:
    size: 5Gi
  logs:
    size: 5Gi
```

`spec.version`, `spec.image`, `spec.rdb`, `spec.repoStorage`, and `spec.logs` are required. The rest of this page, and the pages that follow it, walk through every field. See [Quickstart: Single-Node RegattaCluster](../examples/quickstart-single-node.mdx) to apply this example end to end.

## Configure the object header

| Field | Description |
| - | - |
| `apiVersion` | `regatta.dev/<crd-api-version>` |
| `kind` | `RegattaCluster` |
| `metadata.name` | A unique, DNS-compatible name. It is used to name every generated resource, so keep the total generated names under 63 characters |
| `metadata.namespace` | The namespace where you installed the operator |

## Configure version and image

| Field | Required/default | Description |
| - | - | - |
| `spec.version` | Required; immutable after creation | The RegattaDB release version. It must match the release built into your image |
| `spec.image.repository` | Required | The RegattaDB image repository in your registry |
| `spec.image.tag` | Required unless `digest` is set | An image tag |
| `spec.image.digest` | Required unless `tag` is set | An immutable image digest, for example `sha256:...`; prefer this for production |
| `spec.image.pullPolicy` | `IfNotPresent` | `Always`, `IfNotPresent`, or `Never` |
| `spec.image.pullSecrets` | Optional | Names of image-pull Secrets in your namespace, for a private image repository |

You can change `spec.image` after creation as long as `spec.version` stays the same. The operator applies the change as a same-version rolling update of the affected StatefulSet: standard Kubernetes StatefulSet behavior that replaces Pods one at a time, waiting for each replacement Pod to become Ready before moving to the next, rather than restarting every Pod at once. For the SM Pod (a single replica) this means one restart; for RDB, replicas are replaced one at a time so the others keep serving. You cannot control the pace or order of this rollout.

## Configure module settings

RegattaDB has six modules: SM, SNA, Sequencer, GDD, DCM, and RDB. Each has its own `spec.<module>` section with the same fields:

| Field | Required/default | Immutable | Description |
| - | - | - | - |
| `port` | Module default (see table below) | Yes | The RegattaDB process port. Change it only if your release requires a different port. The operator's generated Kubernetes Service exposes it alongside `service_port` |
| `service_port` | Module default (see table below) | Yes | RegattaDB's own internal service port for the module, used for internal service operations |
| `num_threads` | Optional | Yes | The module's thread allocation. If set, `spec.resources` must cover it (see [Resources & Scheduling](./resources-and-scheduling.mdx)) |
| `ram_MB` | Optional | Yes | The module's memory allocation in megabytes. If set, `spec.resources` must cover it |
| `config` | `{}` | No | RegattaDB module settings as string key/value pairs. Every value must be a string, even for numbers or booleans, for example `"1"` rather than `1` |

Default ports:

| Module | `port` | `service_port` |
| - | -: | -: |
| SM | 8840 | 5000 |
| SNA | 8841 | 5001 |
| Sequencer | 8842 | 5002 |
| GDD | 8843 | 5003 |
| DCM | 8844 | 5004 |
| RDB | 8850 | 6001 |

## RegattaCluster examples

`config/examples/` in the release package includes:

* `regatta-minimal.yaml`: the smallest example, shown above.
* `regatta-full.yaml`: a comprehensive example that sets every configurable field, across every module, storage setting, and resource profile. Use it as a field-by-field reference, not as sizing guidance.
* `regatta-static-storage.yaml`: uses pre-created `PersistentVolumes` for RDB block storage instead of a `StorageClass`, with more than one raw block device per RDB Pod. See [Example: Two Local NVMe Devices, One RDB Replica](../examples/static-storage-local-nvme.mdx) for a full walkthrough.

## Next steps

* [Storage](./storage.mdx) for RDB, repo, and log storage.
* [Networking](./networking.mdx) for how RegattaDB is exposed inside and outside the cluster.
* [Security & Lifecycle](./security-and-lifecycle.mdx) for the security context and starting/stopping RegattaDB.
* [Resources & Scheduling](./resources-and-scheduling.mdx) for CPU, RAM, and Pod placement.


# Resources & Scheduling
Source: https://docs.regatta.dev/self-hosted-deployment/kubernetes/configuration/resources-and-scheduling

Size CPU and RAM for the SM and RDB Pods, and control where they are scheduled.

## Configure CPU and RAM

`spec.resources.sm` and `spec.resources.rdb` set the total CPU and RAM for the SM Pod and every RDB Pod.

| Field | Required | Description |
| - | - | - |
| `spec.resources.sm.requests.cpu` / `.memory` | Required if `spec.resources.sm` is set | Requested CPU and RAM for the SM Pod |
| `spec.resources.sm.limits.cpu` / `.memory` | Required if `spec.resources.sm` is set | CPU and RAM limits for the SM Pod |
| `spec.resources.rdb.requests.cpu` / `.memory` | Required if `spec.resources.rdb` is set | Requested CPU and RAM for every RDB Pod |
| `spec.resources.rdb.limits.cpu` / `.memory` | Required if `spec.resources.rdb` is set | CPU and RAM limits for every RDB Pod |

If you omit `spec.resources.sm`/`spec.resources.rdb`, the operator applies fixed minimums for both requests and limits: `6` CPU / `1200M` memory for the SM Pod, `4` CPU / `8000M` memory for every RDB Pod. Values below these minimums are rejected.

CPU and memory values use standard Kubernetes quantity notation:

* CPU: a whole or fractional number of cores, for example `"2"` for 2 cores or `"0.5"` for half a core; or millicores using an `m` suffix, for example `"500m"`, which equals `0.5` cores. `1000m` equals one full core.
* Memory: a number followed by a size suffix. Binary suffixes `Ki`, `Mi`, `Gi`, and `Ti` are powers of 1024, for example `"512Mi"` or `"8Gi"`. Decimal suffixes `k`, `M`, `G`, and `T` are powers of 1000, for example `"500M"`. There is no plain `MB` unit; use `Mi` or `M` explicitly.

This quantity notation applies to `spec.resources.*.requests/limits.memory` and `.cpu` only. The module-level `ram_MB` field (for example `spec.rdb.ram_MB`) is different: it is a plain integer number of megabytes, for example `16000`, not a Kubernetes quantity string.

If you set `num_threads` or `ram_MB` on a module, `spec.resources` for that module's Pod must cover the combined totals: `spec.resources.sm` for modules in the SM Pod, `spec.resources.rdb` for modules in the RDB Pod. SNA counts toward both, since it runs in every Pod type.

There is no separate field to size RegattaDB's memory-backed `/dev/shm` volume: the operator sets its `sizeLimit` equal to the same component's effective `requests.memory` (`spec.resources.sm.requests.memory` for the SM Pod, `spec.resources.rdb.requests.memory` for every RDB Pod).

### Schedule Pods

Use `spec.resources.sm.scheduling` and `spec.resources.rdb.scheduling` to influence where the operator's SM and RDB Pods run. These are standard Kubernetes Pod scheduling settings; omit any setting you do not need:

| Field | Effect |
| - | - |
| `nodeSelector` | Requires the Pod to run on a node with all listed labels. |
| `tolerations` | Allows the Pod to run on nodes with matching taints; tolerations do not select a node by themselves. |
| `affinity` | Sets Kubernetes node-affinity, Pod-affinity, or Pod-anti-affinity rules. |
| `topologySpreadConstraints` | Controls how matching Pods are distributed across topology domains such as zones or nodes. |

For example, this places RDB Pods only on nodes labeled for database workloads, tolerates a matching taint, and spreads matching RDB Pods across availability zones:

```yaml theme={null}
spec:
  resources:
    rdb:
      scheduling:
        nodeSelector:
          workload: database
        tolerations:
          - key: workload
            operator: Equal
            value: database
            effect: NoSchedule
        topologySpreadConstraints:
          - maxSkew: 1
            topologyKey: topology.kubernetes.io/zone
            whenUnsatisfiable: DoNotSchedule
            labelSelector:
              matchLabels:
                app.kubernetes.io/component: rdb
```

The same fields and structure can be placed under `spec.resources.sm.scheduling` to apply to the combined SM Pod. Affinity, tolerations, and topology spread constraints use Kubernetes PodSpec syntax; refer to your Kubernetes documentation for available operators and details.

## CPU and RAM: scheduling behavior

Kubernetes uses `requests` to decide where a Pod can run, and `limits` to cap what it can use once running:

* If no Kubernetes node has enough unreserved CPU or memory to satisfy your `requests`, Kubernetes will not schedule the Pod there. A Pod stuck `Pending` while otherwise healthy often means no node currently has enough spare capacity.
* A CPU limit is enforced by throttling: a container that tries to use more CPU than its limit is slowed down, not killed.
* A memory limit is a hard ceiling: if a container tries to use more memory than its limit, Kubernetes kills it (OOM-killed) and restarts it. This is generic Kubernetes behavior that applies to any container, not something specific to RegattaDB.

`num_threads` and `ram_MB` are RegattaDB application-level settings: they tell RegattaDB how much CPU and RAM to plan for internally, per module. Both are optional - if you leave them unset, RegattaDB's System Manager assigns them automatically.

`spec.resources` is a separate, Kubernetes Pod-level setting: it is the boundary Kubernetes enforces around the whole container. Unlike `num_threads`/`ram_MB`, nothing auto-detects this for you, because the operator has no way to discover your Kubernetes node hardware. If you omit `spec.resources.sm`/`spec.resources.rdb`, the operator applies the fixed minimums from Configure CPU And RAM above, so RegattaDB Pods always get a real Kubernetes QoS guarantee - never `BestEffort`. Size them explicitly when your workload needs more than those minimums, even though you are not required to size every individual module's `num_threads`/`ram_MB` to do so. If you do set `num_threads`/`ram_MB`, `spec.resources.sm`/`spec.resources.rdb` must at least cover their combined totals; RegattaDB's own processes account for the headroom they need within that allocation.


# Security & Lifecycle
Source: https://docs.regatta.dev/self-hosted-deployment/kubernetes/configuration/security-and-lifecycle

Configure the Pod security context, RegattaDB's credentials, and whether the operator starts or stops it.

## Configure lifecycle

These fields control whether the operator actively configures and starts RegattaDB, or leaves it untouched while still managing the surrounding Kubernetes resources. Use them to stage a `RegattaCluster` resource before go-live, or to stop RegattaDB for planned maintenance without deleting anything.

| Field | Default | Description |
| - | - | - |
| `spec.lifecycle.configure` | `true` | Whether the operator configures RegattaDB through the System Manager once Kubernetes is ready. Set `false` only when creating a new, stopped RegattaCluster resource, together with `start: false` |
| `spec.lifecycle.start` | `true` | Whether the operator starts RegattaDB after configuring it. Set `false` to keep Kubernetes Pods running with RegattaDB stopped |

## Configure security

| Field | Default | Description |
| - | - | - |
| `spec.security.runAsUser` | `1000` | The non-root Linux UID RegattaDB processes run as |
| `spec.security.runAsGroup` | `1001` | The non-root Linux GID RegattaDB processes run as |
| `spec.security.fsGroup` | `1001` | The filesystem group applied to mounted storage |
| `spec.security.seccompProfile` | `RuntimeDefault` | A seccomp profile restricts which Linux syscalls a container may make; `RuntimeDefault` applies Kubernetes' standard restricted set, or use `Unconfined` to disable it |
| `spec.security.allowPrivilegeEscalation` | `false` | Whether a RegattaDB process can gain more privileges than its parent (for example through a setuid binary). Keep `false` for production |

Every Pod also always runs as non-root and uses the `OnRootMismatch` file system group-change policy, so mounted volumes are already owned by the right group when the container starts. Neither is configurable; both apply regardless of what you set under `spec.security`.

## Security context and credentials

Every RegattaDB Pod runs with the settings from `spec.security`: non-root UID/GID, the seccomp profile, and `allowPrivilegeEscalation`, as configured. Pods do not mount a Kubernetes `ServiceAccount` token, because RegattaDB itself never calls the Kubernetes API.

The operator's own namespaced permissions let it manage the resources described throughout this section: Services, StatefulSets, ConfigMaps, the credentials Secret, and your `RegattaCluster` status. Its only access outside that namespace is the cluster-scoped read-only permission described in [Prerequisites](../prerequisites.mdx) and [Installation](../installation.mdx).

<Danger>
  The initial RegattaDB administrator credentials, stored in a Secret named like `my-regattadb-credentials`, are deterministic rather than randomly generated per installation. Read them from that Secret rather than assuming a fixed value, and handle it with the same care as any other credential in your Kubernetes cluster. Never print the contents of the credentials Secret while troubleshooting.
</Danger>


# Storage
Source: https://docs.regatta.dev/self-hosted-deployment/kubernetes/configuration/storage

Configure RDB block storage, repo and log storage, and raw block device access.

## Configure RDB replicas and storage

| Field | Required/default | Immutable | Description |
| - | - | - | - |
| `spec.rdb.replicas` | Required; minimum `1` | Yes | The number of RDB Pods. Decide this before creating your `RegattaCluster` resource |
| `spec.rdb.devices` | `1`; minimum `1` | Yes | The number of raw block devices given to every RDB Pod |
| `spec.rdb.service.type` | `ClusterIP` | No | How the aggregate RDB Kubernetes Service (the Service that selects every RDB Pod together) is exposed. `ClusterIP` keeps it reachable only from inside your Kubernetes cluster. `LoadBalancer` additionally requests an externally reachable address; this is optional, and the resulting address is shared/load-balanced across every RDB Pod, not reserved for one client - see [Networking](./networking.mdx) |
| `spec.rdb.service.port` | `spec.rdb.port` | No | The port RegattaDB clients connect to on the aggregate RDB Kubernetes Service, for database queries. It defaults to `spec.rdb.port`, but unlike `spec.rdb.port` (immutable), you can change it later: it only changes the Service's exposed port, not the port RDB listens on inside the container |
| `spec.rdb.service.loadBalancerSourceRanges` | Optional | No | CIDR blocks allowed to reach the aggregate RDB Service when `spec.rdb.service.type` is `LoadBalancer`; ignored for `ClusterIP`. Enforcement depends on your cluster's LoadBalancer integration - GKE enforces it as a firewall rule, but behavior varies by cloud provider and on-prem controller, so verify it actually restricts traffic on your platform before relying on it |
| `spec.rdb.blockStorage.size` | Required | Cannot change | Capacity of each raw block device; must resolve to more than 0 bytes |
| `spec.rdb.blockStorage.storageClassName` | Optional | Cannot change | `StorageClass` that provisions the raw block devices dynamically. If omitted, Kubernetes uses your cluster's default `StorageClass`, if one is set; otherwise the PVCs stay `Pending` |
| `spec.rdb.blockStorage.accessModes` | `[ReadWriteOnce]` | Cannot change | Access modes requested for each raw block device. `ReadWriteOncePod` must be used alone |
| `spec.rdb.blockStorage.provisioning` | `Dynamic` | Cannot change | `Dynamic` provisions devices from the named `StorageClass`. `Static` binds to `PersistentVolumes` you pre-create; see [Choosing dynamic or static RDB storage](#choosing-dynamic-or-static-rdb-storage) below |
| `spec.rdb.blockStorage.selector` | Required for `Static`; rejected for `Dynamic` | Cannot change | Selector (`matchLabels`/`matchExpressions`) matching the `PersistentVolumes` to bind, when using `Static` provisioning |

<Warning>
  Every setting under `spec.rdb.blockStorage` is fixed once your `RegattaCluster` resource is created, because Kubernetes does not allow changing a StatefulSet's storage templates. Choose these values carefully up front.
</Warning>

* `accessModes` is a list mainly so you can request `ReadWriteOncePod` instead of the default `ReadWriteOnce`. `ReadWriteOncePod` restricts the volume to exactly one Pod cluster-wide, stricter than `ReadWriteOnce` (which technically still permits multiple Pods on the same Kubernetes node); some customers prefer it for raw block storage. `ReadOnlyMany` and `ReadWriteMany` are part of the underlying Kubernetes API but are not meaningful choices here - RDB's raw block storage is always single-writer, one device per Pod.
* Every RDB Pod can be given more than one raw block device: set `spec.rdb.devices` to the total device count per Pod. All devices on an RDB Pod share the same `spec.rdb.blockStorage` settings; there is no per-device size or `StorageClass`. Device indexes start at `0`: the first device is `/dev/rdb0`, the second is `/dev/rdb1`, and so on. A `RegattaCluster` with `spec.rdb.replicas: 3` and `spec.rdb.devices: 2` creates 6 raw block PVCs in total (2 per RDB Pod):

```yaml theme={null}
rdb:
  replicas: 3
  devices: 2
  blockStorage:
    size: 500Gi
    storageClassName: <storage-class>
```

### Choosing dynamic or static RDB storage

In short: use `Dynamic` if your cluster has a `StorageClass` that provisions raw block volumes on demand, and use `Static` if your raw block storage is provisioned outside Kubernetes (for example pre-attached local disks) or your environment does not support dynamic block provisioning.

`spec.rdb.blockStorage.provisioning` selects how Kubernetes obtains the raw block `PersistentVolumes` for RDB:

* `Dynamic` (the default): a `StorageClass`, named in `spec.rdb.blockStorage.storageClassName`, provisions a new `PersistentVolume` for every raw block PVC on demand. Use this when your Kubernetes cluster has a `StorageClass` that supports `volumeMode: Block`. Do not set `spec.rdb.blockStorage.selector` with `Dynamic` provisioning: Kubernetes never dynamically provisions a `PersistentVolumeClaim` that has a selector, so the PVC would stay `Pending` indefinitely; the operator rejects this combination up front instead.
* `Static`: you pre-create the `PersistentVolumes` yourself, and `spec.rdb.blockStorage.selector` (`matchLabels` or `matchExpressions`) tells the operator which ones to bind. Use this when your raw block storage is provisioned outside Kubernetes, for example pre-attached local disks, or your environment does not allow dynamic provisioning for raw block storage.

With `Static` provisioning, you need at least `spec.rdb.replicas * spec.rdb.devices` `PersistentVolumes` that match the selector, `StorageClass`, requested access modes, `volumeMode: Block`, and requested capacity, and that are available or already bound to your claims.

The cluster-scoped read-only permission you installed in [Installation](../installation.mdx) lets the operator check these conditions before applying resources, so problems surface early. If that permission is ever missing or denied, the operator skips this check and relies on normal PVC binding as the readiness signal instead.

See [Example: Two Local NVMe Devices, One RDB Replica](../examples/static-storage-local-nvme.mdx) for a full walkthrough of static provisioning.

## Configure repo and log storage

`spec.repoStorage` and `spec.logs` are Pod-level settings, applying equally to the SM Pod and every RDB Pod. `spec.repoStorage` backs RegattaDB's mutable runtime repository paths. `spec.logs` backs RegattaDB's own log output at `/var/log/regatta`. See [Prepare For Deployment](https://docs.regatta.dev/self-hosted-deployment/manual-deployment/prepare-for-deployment) for the underlying storage-sizing guidance this maps to. Neither field has a default size - you must size both for your workload; `storageClassName` falls back to your cluster's default `StorageClass` if omitted.

| Field | Required/default | Immutable | Description |
| - | - | - | - |
| `spec.repoStorage.size` | Required | Cannot change | Filesystem capacity for RegattaDB's mutable repository paths, on every Pod; must resolve to more than 0 bytes |
| `spec.repoStorage.storageClassName` | Optional | Cannot change | `StorageClass` for repository storage. If omitted, Kubernetes uses your cluster's default `StorageClass`, if one is set; otherwise the PVCs stay `Pending` |
| `spec.repoStorage.accessModes` | `[ReadWriteOnce]` | Cannot change | Access modes requested for the repository storage. `ReadWriteOncePod` must be used alone |
| `spec.logs.size` | Required | Cannot change | Filesystem capacity for `/var/log/regatta`, on every Pod; must resolve to more than 0 bytes |
| `spec.logs.storageClassName` | Optional | Cannot change | `StorageClass` for log storage. If omitted, Kubernetes uses your cluster's default `StorageClass`, if one is set; otherwise the PVCs stay `Pending` |
| `spec.logs.accessModes` | `[ReadWriteOnce]` | Cannot change | Access modes requested for the log storage. |

<Warning>
  Storage size, `StorageClass`, and access modes for `spec.repoStorage` and `spec.logs` cannot change once your `RegattaCluster` resource is created, for the same reason as `spec.rdb.blockStorage`. Choose these values carefully up front.
</Warning>

## Multiple RDB devices: naming and readiness

Every raw block device on an RDB Pod is backed by its own `PersistentVolumeClaim`, generated from the claim-template name, the RDB StatefulSet name, and the Pod ordinal. For a `RegattaCluster` named `my-regattadb`, device `0` of RDB Pod `0` produces the PVC `rdb-block-0-my-regattadb-rdb-0`; device `1` of the same Pod produces `rdb-block-1-my-regattadb-rdb-0`, and so on.

Storage readiness requires every one of these PVCs, for every RDB Pod, to be bound before RegattaDB is configured. An RDB Pod with `spec.rdb.devices: 2` stays pending until both of its raw block PVCs are bound, not just one.

## Non-root access to raw block devices

RDB Pods run as the non-root user and group configured in [`spec.security`](./security-and-lifecycle.mdx) (UID `1000`/GID `1001` by default) and additionally receive Linux supplemental group `6`, the conventional `disk` group on most Linux distributions, so that user can open the raw block devices without running as root. The SM Pod does not receive this supplemental group, because it has no raw block devices.

Whether group `6` actually grants access depends on which Linux group your storage and container runtime assign to the device node inside the Pod. For deterministic, non-root device ownership, configure your container runtime to derive device ownership from the Pod's security context: set `device_ownership_from_security_context = true` under containerd, or the equivalent option under `[crio.runtime]` for CRI-O. Validate this on one RDB Pod, for example by checking device ownership inside the Pod, before relying on it for production.


# Quickstart: Single-Node RegattaCluster
Source: https://docs.regatta.dev/self-hosted-deployment/kubernetes/examples/quickstart-single-node

Install the operator and stand up a single-node RegattaDB deployment on Kubernetes end to end.

This page walks you through creating your first `RegattaCluster` resource. Make sure you've completed [Installation](../installation.mdx) first: the operator must already be running in your cluster.

## 1. Create a RegattaCluster resource

A minimal `RegattaCluster` resource looks like this:

```yaml theme={null}
apiVersion: regatta.dev/<crd-api-version>
kind: RegattaCluster
metadata:
  name: my-regattadb
  namespace: <namespace>
spec:
  version: "<version>"
  image:
    repository: registry.example.com/regatta
    tag: "<version>"
  security:
    runAsUser: 1000
    runAsGroup: 1001
    fsGroup: 1001
  rdb:
    replicas: 3
    blockStorage:
      size: 60Gi
  repoStorage:
    size: 5Gi
  logs:
    size: 5Gi
```

Save it to a file under `config/examples/`, for example `config/examples/regatta-minimal.yaml`. See [Configuration Overview](../configuration/overview.mdx) for what every field means.

## 2. Apply and verify

```sh theme={null}
kubectl -n <namespace> apply -f config/examples/regatta-minimal.yaml
kubectl -n <namespace> get rgc
kubectl -n <namespace> get rgc my-regattadb -o yaml
```

You can also list every resource the operator generated in one command:

```sh theme={null}
kubectl -n <namespace> get statefulsets,services,configmaps,secrets,pods,pvc \
  -l app.kubernetes.io/instance=my-regattadb
```

<Note>
  A new `RegattaCluster` resource does not become `Ready` immediately: Kubernetes must provision storage and start Pods before the operator can configure and start RegattaDB through the System Manager. Track `status.conditions` (see [Reading RegattaCluster Status](../operations.mdx#reading-regattacluster-status)) until you see `Ready` reported as `True`, rather than expecting readiness right away.
</Note>

## Next steps

* [Operations](../operations.mdx) to understand how the operator keeps Kubernetes and RegattaDB in sync, and what you can safely change afterward.
* [Example: Two Local NVMe Devices, One RDB Replica](./static-storage-local-nvme.mdx) for a static-storage walkthrough.
* [Troubleshooting](../troubleshooting.mdx) if your `RegattaCluster` resource doesn't reach `Ready`.


# Example: Two Local NVMe Devices, One RDB Replica
Source: https://docs.regatta.dev/self-hosted-deployment/kubernetes/examples/static-storage-local-nvme

Bind pre-existing local NVMe devices to RDB using static RDB storage provisioning.

This walks through binding two pre-existing local NVMe devices to a single RDB replica end to end (`spec.rdb.replicas: 1`, `spec.rdb.devices: 2`). See [Choosing dynamic or static RDB storage](../configuration/storage.mdx#choosing-dynamic-or-static-rdb-storage) for when to use static provisioning.

## 1. Identify the devices

Identify the two raw block devices to dedicate to RDB, for example `/dev/nvme1n1` and `/dev/nvme2n1` on Kubernetes node `worker-1`. Do not format or mount them; RegattaDB manages them directly as raw block devices.

## 2. Create a `PersistentVolume` per device

Create one `PersistentVolume` per device, each pinned to the node that has the device attached:

```yaml theme={null}
apiVersion: v1
kind: PersistentVolume
metadata:
  name: rdb-nvme-0
  labels:
    regatta.dev/cluster: my-regattadb
spec:
  capacity:
    storage: 2Ti
  volumeMode: Block
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: local-nvme
  local:
    path: /dev/nvme1n1
  nodeAffinity:
    required:
      nodeSelectorTerms:
        - matchExpressions:
            - key: kubernetes.io/hostname
              operator: In
              values:
                - worker-1
---
apiVersion: v1
kind: PersistentVolume
metadata:
  name: rdb-nvme-1
  labels:
    regatta.dev/cluster: my-regattadb
spec:
  capacity:
    storage: 2Ti
  volumeMode: Block
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: local-nvme
  local:
    path: /dev/nvme2n1
  nodeAffinity:
    required:
      nodeSelectorTerms:
        - matchExpressions:
            - key: kubernetes.io/hostname
              operator: In
              values:
                - worker-1
```

A Kubernetes `local` volume needs no CSI driver or provisioner for static binding: Kubernetes mounts the given `path` directly on the node named in `nodeAffinity`. Because both `PersistentVolumes` are pinned to `worker-1`, Kubernetes also schedules the RDB Pod on `worker-1`, since that is the only node where both devices exist.

<Note>
  `capacity.storage` is required by the Kubernetes `PersistentVolume` API itself; it is Kubernetes' own bookkeeping value for matching `PersistentVolumeClaims` to `PersistentVolumes`, and does not resize or limit the underlying device - RegattaDB uses the raw device directly regardless of this value.
</Note>

If you have raw devices on more than one Kubernetes node, repeat this pattern once per node: one pair of `PersistentVolumes` (pinned through `nodeAffinity`) for every node that has its own local devices.

## 3. Point your RegattaCluster resource at these `PersistentVolumes`

```yaml theme={null}
rdb:
  replicas: 1
  devices: 2
  blockStorage:
    provisioning: Static
    size: 2Ti
    storageClassName: local-nvme
    selector:
      matchLabels:
        regatta.dev/cluster: my-regattadb
```

## 4. Apply and verify

Apply the `PersistentVolumes`, then apply your `RegattaCluster` resource. With `replicas: 1` and `devices: 2`, the operator expects `1 * 2 = 2` matching `PersistentVolumes`, exactly the two you created. Kubernetes binds one PVC to each `PersistentVolume`; which one binds to which device index is not something a shared selector lets you control directly, but for two identically sized devices on the same `StorageClass` this makes no difference to RegattaDB, since every device is used the same way. Both end up mounted in the single RDB Pod, as `/dev/rdb0` and `/dev/rdb1`.

If you need deterministic control over which physical device becomes `/dev/rdb0` versus `/dev/rdb1`, pre-bind each `PersistentVolume` to its expected PVC name with `claimRef` instead of relying only on the selector; see [Multiple RDB Devices: Naming And Readiness](../configuration/storage.mdx#multiple-rdb-devices-naming-and-readiness) for the exact generated PVC names.

`/dev/rdb0` and `/dev/rdb1` are fixed, operator-assigned paths inside the container; they do not depend on how the host enumerates its own raw devices, so they stay stable across Pod restarts and node reboots.


# Installation
Source: https://docs.regatta.dev/self-hosted-deployment/kubernetes/installation

Extract the release package, import images into your registry, and install the Regatta operator on your cluster.

Make sure you've read [Prerequisites](./prerequisites.mdx) first. This page covers extracting the release package, importing its images into your own registry, and installing the Regatta operator.

## The release package

You receive a single archive:

```text theme={null}
regatta-k8s-<version>-<architecture>.tar.gz
```

It contains everything you need to import RegattaDB and the operator into your own environment and install them on Kubernetes:

* The RegattaDB workload image (the container that runs RegattaDB itself).
* The Regatta operator image.
* The Kubernetes API definition (CRD) for `RegattaCluster`.
* The operator's Kubernetes identity and permissions.
* The operator Deployment.
* RegattaDB deployment examples you can edit.
* `README.md`.
* Licensing and third-party attribution files.
* Release metadata and integrity checksums.

Extracting the archive gives you the following layout:

```text theme={null}
regatta-k8s-<version>-<architecture>/
├── README.md
├── LICENSE
├── THIRD_PARTY_NOTICES
├── CHANGELOG.md
├── MANIFEST.json
├── SHA256SUMS
├── images/
│   ├── regatta-db-<version>-<architecture>.tar
│   └── regatta-operator-<version>-<architecture>.tar
└── config/
    ├── crd/
    │   └── regattacluster-crd.yaml
    ├── rbac/
    │   ├── serviceaccount.yaml
    │   ├── role.yaml
    │   ├── rolebinding.yaml
    │   └── clusterrole-readonly.yaml
    ├── operator/
    │   └── deployment.yaml
    └── examples/
        ├── regatta-minimal.yaml
        ├── regatta-full.yaml
        └── regatta-static-storage.yaml
```

The rest of this page covers extracting the package and installing the operator using the `config/crd`, `config/rbac`, and `config/operator` files above. See [Configuration Overview](/self-hosted-deployment/kubernetes/configuration/overview) and [Storage](/self-hosted-deployment/kubernetes/configuration/storage) for how the `config/examples/` files are used when you create a `RegattaCluster` resource.

## 1. Extract and verify the package

```sh theme={null}
tar -xzf regatta-k8s-<version>-<architecture>.tar.gz
cd regatta-k8s-<version>-<architecture>
sha256sum --check SHA256SUMS
```

<Warning>
  Do not continue if the checksum verification fails.
</Warning>

## 2. Import images into your registry

1. Import and push each image archive to your registry. The recommended tool is `skopeo`, because it copies an image archive directly into a registry without needing a local container runtime, and preserves the exact image digest instead of rebuilding the image. `docker load` and `podman load` followed by `docker push`/`podman push` also work with these archives if you prefer a tool you already have installed:

   ```sh theme={null}
   skopeo copy \
     docker-archive:images/regatta-db-<version>-<architecture>.tar \
     docker://registry.example.com/regatta-db:<version>

   skopeo copy \
     docker-archive:images/regatta-operator-<version>-<architecture>.tar \
     docker://registry.example.com/regatta-operator:<version>
   ```

2. Record the digest your registry assigns to each uploaded image:

   ```sh theme={null}
   skopeo inspect docker://registry.example.com/regatta-db:<version> \
     --format '{{.Digest}}'
   skopeo inspect docker://registry.example.com/regatta-operator:<version> \
     --format '{{.Digest}}'
   ```

   You will use these digests in the next step, as part of a full image reference such as:

   ```text theme={null}
   registry.example.com/regatta-operator@sha256:1a2b3c4d5e6f...
   ```

## 3. Point the manifests at your registry

1. In `config/operator/deployment.yaml`, set the operator container image to your uploaded operator image and digest.
2. In the example you plan to use under `config/examples/`, set `spec.image` to your uploaded RegattaDB image and digest.
3. If your registry requires authentication, create a Kubernetes Secret of type `kubernetes.io/dockerconfigjson` in `<namespace>`, then reference it in `imagePullSecrets` in `config/operator/deployment.yaml` for the operator image, and in `spec.image.pullSecrets` in your `RegattaCluster` example for the RegattaDB image.

## 4. Install the operator

1. Create the namespace:

   ```sh theme={null}
   kubectl create namespace <namespace>
   ```

2. Install the CustomResourceDefinition:

   ```sh theme={null}
   kubectl apply -f config/crd/regattacluster-crd.yaml
   ```

3. Install the operator's Kubernetes identity and permissions:

   ```sh theme={null}
   kubectl -n <namespace> apply -f config/rbac/serviceaccount.yaml
   kubectl -n <namespace> apply -f config/rbac/role.yaml
   kubectl -n <namespace> apply -f config/rbac/rolebinding.yaml
   ```

4. Install the cluster-scoped read-only permission the operator needs. This is required so the operator can discover its configured namespace and the `RegattaCluster` resource type, and recover existing resources after a restart. The same permissions also let it validate static RDB `PersistentVolumes` and `StorageClasses` before applying resources:

   ```sh theme={null}
   kubectl apply -f config/rbac/clusterrole-readonly.yaml
   ```

   Its default binding targets the `regatta-operator` `ServiceAccount` in the `regatta` namespace. If `<namespace>` is not `regatta`, edit the `ClusterRoleBinding`'s subject namespace before applying it.

5. Install the operator Deployment:

   ```sh theme={null}
   kubectl -n <namespace> apply -f config/operator/deployment.yaml
   ```

6. Verify that the operator is running:

   ```sh theme={null}
   kubectl -n <namespace> rollout status deployment/regatta-operator
   kubectl -n <namespace> get pods -l app.kubernetes.io/name=regatta-operator,app.kubernetes.io/component=operator
   kubectl -n <namespace> logs deployment/regatta-operator
   ```

<Note>
  The operator is running at this point, but RegattaDB itself does not exist yet: nothing runs RegattaDB until you apply a `RegattaCluster` resource.
</Note>

## Next steps

Continue to [Configuration Overview](/self-hosted-deployment/kubernetes/configuration/overview), or jump straight to the [Quickstart: Single-Node RegattaCluster](/self-hosted-deployment/kubernetes/examples/quickstart-single-node) to create your first `RegattaCluster` resource.


# Introduction
Source: https://docs.regatta.dev/self-hosted-deployment/kubernetes/introduction

Deploy and operate RegattaDB on Kubernetes with the Regatta operator.

<Note>
  This section assumes you're already familiar with the [RegattaDB software modules](/self-hosted-deployment/manual-deployment/regattadb-software-modules) (SM, SNA, GDD, DCM, Sequencer, RDB) and how they work together in a RegattaDB deployment.
</Note>

The **Regatta operator** is a Kubernetes controller that automates deploying and operating RegattaDB on Kubernetes. Instead of manually creating the Kubernetes resources RegattaDB needs, provisioning its storage, and issuing System Manager (SM) commands yourself, you describe the RegattaDB deployment you want in a single `RegattaCluster` resource and let the operator drive Kubernetes and RegattaDB into that state.

## Kubernetes Concepts You Will Use

| Concept | What it means for this section |
| - | - |
| [Pod](https://kubernetes.io/docs/concepts/workloads/pods/) | Where one or more RegattaDB modules run together; see [Deployment Architecture](#deployment-architecture) below |
| [Kubernetes node](https://kubernetes.io/docs/concepts/architecture/nodes/) | A physical or virtual machine that can run Pods. Kubernetes places Pods on nodes automatically |
| [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) | Keeps a fixed, ordered set of Pods running with stable identities and their own storage. The operator creates one StatefulSet for the SM Pod and one for the RDB Pods |
| [Service](https://kubernetes.io/docs/concepts/services-networking/service/) | A stable network name and address for one or more Pods, even as Pods restart or move between Kubernetes nodes |
| [`PersistentVolumeClaim` (PVC)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) | A request for storage that Kubernetes binds to an actual storage volume or device |
| [Raw block volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#raw-block-volume-support) | A storage device given to a Pod directly, the same way you would give RegattaDB a raw block device in a manual deployment, without a filesystem in between |
| [CustomResourceDefinition (CRD)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) | Registers `RegattaCluster` (full name `regattaclusters.regatta.dev`, short names `regatta`/`rgc`, usable in place of `regattacluster` in `kubectl`) as a Kubernetes resource type, so Kubernetes can store, validate, and let the operator watch it |
| [`spec`](https://kubernetes.io/docs/concepts/overview/working-with-objects/#object-spec-and-status) | The part of your `RegattaCluster` resource where you write the state you want; only you (and the operator's own defaults) ever set it |
| [`status`](https://kubernetes.io/docs/concepts/overview/working-with-objects/#object-spec-and-status) | The part of your `RegattaCluster` resource where the operator reports the state it observed; never edit it yourself |
| [Operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) | The program that continuously watches your `RegattaCluster` resource and keeps Kubernetes and RegattaDB matching it |

## What the operator does for you

* **Describes your deployment as a single Kubernetes resource**: the `RegattaCluster` resource captures the RegattaDB version, image, module settings, storage, and resource sizing you want.
* **Creates and maintains the Kubernetes resources RegattaDB needs**: StatefulSets, Services, ConfigMaps, and storage claims, generated and kept in sync automatically.
* **Configures and starts RegattaDB for you**: once Kubernetes resources are ready, the operator configures RegattaDB modules and starts or stops RegattaDB through the System Manager (SM).
* **Reports readiness continuously**: Kubernetes and RegattaDB health are reflected in the `RegattaCluster` status, so you always know the current state.

## Deployment Architecture

In a manual or RDT-driven RegattaDB deployment, you decide which node runs which modules: one SM, one SNA on every node that hosts an operational module, one GDD, one DCM, one Sequencer, and one or more RDB modules. On Kubernetes, a **Pod** is the unit that runs one or more RegattaDB modules together, the same role a node plays in a manual deployment. The operator places modules for you, using the following default layout:

| Pod | Count | Modules running in this Pod |
| - | - | - |
| SM Pod | One per RegattaDB system | SM, SNA, GDD, DCM, Sequencer |
| RDB Pod | One for every RDB replica you configure | SNA, RDB |

<Frame>
  <img alt="RegattaDB Kubernetes Pod layout" title="RegattaDB Kubernetes Pod layout" />

  <img alt="RegattaDB Kubernetes Pod layout" title="RegattaDB Kubernetes Pod layout" />
</Frame>

Unlike a manual deployment, you do not choose per-Pod module placement here. The operator uses this default layout; the only placement decision you make today is how many RDB replicas to configure.

Each Pod also gets one or more stable Kubernetes Services, giving it a fixed network address, similar to assigning a fixed internal IP address to each node in a manual deployment. The SM Pod has one Service, and every RDB Pod has its own dedicated Service, so its address does not change even if Kubernetes moves the Pod to a different Kubernetes node.

A **Kubernetes node** is a physical or virtual machine in your Kubernetes cluster. It is a different concept from the node used in manual RegattaDB deployment guides: a single Kubernetes node can run many Pods at once, including Pods belonging to other applications, and Kubernetes decides which node each Pod runs on and can move a Pod to a different node later. You do not assign RegattaDB modules to specific Kubernetes nodes yourself, though you can influence which Kubernetes nodes the operator's Pods are eligible to run on using standard scheduling controls; see [Schedule Pods](/self-hosted-deployment/kubernetes/configuration/resources-and-scheduling#schedule-pods).

## How this section is organized

* **[Prerequisites](/self-hosted-deployment/kubernetes/prerequisites)** and **[Installation](/self-hosted-deployment/kubernetes/installation)**: what your cluster needs, and how to install the operator.
* [**Configuration**](/self-hosted-deployment/kubernetes/configuration/overview): the `RegattaCluster` spec reference, covering the object header, version and image, module settings, storage, networking, security and lifecycle, and resources and scheduling.
* [**Examples**](/self-hosted-deployment/kubernetes/examples/quickstart-single-node): end-to-end walkthroughs, from a single-node quickstart to static RDB storage.
* [**Operations**](/self-hosted-deployment/kubernetes/operations): how the operator keeps Kubernetes and RegattaDB in sync, reading status, and making supported changes.
* [**Troubleshooting**](/self-hosted-deployment/kubernetes/troubleshooting) and [**Release Notes**](/self-hosted-deployment/kubernetes/release-notes).

## Next steps

New to the Regatta operator? Start with [Prerequisites](/self-hosted-deployment/kubernetes/prerequisites) and
[Installation](/self-hosted-deployment/kubernetes/installation), then follow the
[Quickstart: Single-Node RegattaCluster](/self-hosted-deployment/kubernetes/examples/quickstart-single-node)
to deploy RegattaDB end to end.


# Operations
Source: https://docs.regatta.dev/self-hosted-deployment/kubernetes/operations

How the operator keeps Kubernetes and RegattaDB in sync, reading status, and making supported changes.

## How the operator keeps things in sync

After you apply a `RegattaCluster` resource, the operator continuously works to bring Kubernetes and RegattaDB into the state you described:

1. It creates or updates the StatefulSets, Services, ConfigMaps, and Secret your `RegattaCluster` resource requires.
2. It waits until the storage your Pods requested is bound, and every Pod is running and ready.
3. Once Kubernetes is ready, it configures and starts, or stops, RegattaDB through the System Manager (SM), using the Service addresses Kubernetes created.
4. It writes what it observed, including readiness, endpoints, and RegattaDB health, back into your `RegattaCluster` resource's status, and repeats this cycle so any drift is corrected automatically, at least every five minutes even without any change.

Kubernetes objects being healthy is necessary but not sufficient: your `RegattaCluster` resource only reports readiness once RegattaDB itself confirms, through the System Manager, that it is active and healthy.

## Reading RegattaCluster status

`status` is owned by the operator; never edit it yourself. Useful fields:

* `status.observedGeneration`: the most recent `spec` generation the operator has reconciled. If this lags behind `metadata.generation`, the operator has not caught up yet.
* `status.endpoints.sm` and `status.endpoints.rdbs[]`: the Service names, DNS names, ClusterIPs, and ports the operator advertised to RegattaDB. RegattaDB clients and management tools should use these addresses from `status`; `spec` never contains live connection addresses, only your desired configuration.
* `status.rdb`: `desiredReplicas`, `readyPods`, `configuredReplicas`, and `activeReplicas` - how many RDB Pods exist, are ready, are configured in RegattaDB, and are active.
* `status.modules`: per-module role summaries (`total`/`active`/`down`), as RegattaDB itself reports them.
* `status.devices`: raw block device health, with a `status`, a `healthy` flag, a `failed` list of device names that are not healthy, and an `items[]` list. Each item includes the device's `name`, `path`, `node`, and `module`.
* `status.regatta`: the raw System Manager observation, including `systemState`, `healthy`, `desiredState`, and recent `actions`.

### Conditions

`status.conditions` follows the standard Kubernetes condition shape (`type`, `status`, `reason`, `message`):

| Condition | True means | False means |
| - | - | - |
| `Progressing` | Waiting for infrastructure to become ready, or a RegattaDB action was just issued and a follow-up check is scheduled | Steady state with nothing pending (`KubernetesResourcesApplied`), or a permanent error blocked reconciliation - check `Degraded` and this condition's `message` |
| `StorageReady` | Every expected `PersistentVolumeClaim` exists and is bound (`StorageHealthy`) | No `PersistentVolumeClaims` observed yet (`WaitingForStorage`), or some are missing, unbound, or otherwise unhealthy (`PVCsNotBound`) |
| `KubernetesReady` | Both StatefulSets are fully rolled out and every expected Pod is Running and Ready (`WorkloadsReady`) | Pods are not ready (`PodsNotReady`), or a StatefulSet has not rolled out (`WorkloadsNotReady`) |
| `Ready` | RegattaDB itself, through the System Manager, confirms it is active and healthy, in addition to Kubernetes being ready | Kubernetes is not ready yet (`InfrastructureNotReady`), or Kubernetes is ready but SM has not confirmed active and healthy yet (`RegattaStatusPending`) |
| `Degraded` | A permanent error blocked reconciliation - for example, reason `ValidationFailed` for spec values only caught at reconcile time; check the condition's `message` for the cause | Normal operation, including a `RegattaCluster` resource you deliberately stopped (`spec.lifecycle.start: false`), which is not treated as degraded |
| `RegattaStopped` | Present only when `spec.lifecycle.start: false`. SM confirms RegattaDB is stopped | The stop is still in progress (`RegattaStopping`) |

<Note>
  `Ready=True` always requires both Kubernetes readiness and SM-confirmed RegattaDB health together; Kubernetes readiness alone is never enough.
</Note>

## Making supported changes

Once your `RegattaCluster` resource exists, a small set of fields remain mutable, though some have side effects worth planning for:

* `spec.image` (`tag`, `digest`, `pullPolicy`, `pullSecrets`), as long as `spec.version` stays the same. The operator applies this as a same-version rolling update - see [Configure Version And Image](./configuration/overview.mdx#configure-version-and-image) for what that means and what you can/cannot control.
* `config` on any module. Note that changing it restarts the Pod or Pods that host the affected module.
* `spec.rdb.service.type` and `spec.rdb.service.port` (the aggregate RDB Service's own type and exposed port) only affect that Service object. RDB's actual container port stays fixed, and Kubernetes forwards the externally exposed port to it correctly, so both are always safe to change.
* `spec.lifecycle.start`: set to `false` to stop RegattaDB while keeping Kubernetes Pods running, and back to `true` to start it again.

Every other field covered in [Configuration](./configuration/overview.mdx), including `spec.version`, `spec.rdb.replicas`, `spec.rdb.devices`, module `port`/`service_port`/`num_threads`/`ram_MB`, and every storage setting, is immutable once your `RegattaCluster` resource is created.

## Deleting a RegattaCluster

Delete the resource like any other Kubernetes object:

```sh theme={null}
kubectl -n <namespace> delete rgc my-regattadb
```

Deletion:

1. Makes a bounded attempt, up to 30 seconds, to stop RegattaDB through the System Manager if it is running.
2. Continues even if that stop attempt fails, recording a warning Event instead of blocking.
3. Deletes the generated StatefulSets, Services, ConfigMaps, and the credentials Secret.
4. Leaves every `PersistentVolumeClaim` in place, so your data is not deleted along with the `RegattaCluster` resource.

If you are certain the data is no longer needed, delete the retained PVCs explicitly:

```sh theme={null}
kubectl -n <namespace> delete pvc \
  -l app.kubernetes.io/name=regatta,app.kubernetes.io/instance=my-regattadb,app.kubernetes.io/managed-by=regatta-operator
```


# Prerequisites
Source: https://docs.regatta.dev/self-hosted-deployment/kubernetes/prerequisites

What you need before installing the Regatta operator and deploying RegattaDB on Kubernetes.

Before you start, make sure you have:

* Access to a Kubernetes cluster, with a `kubeconfig` that can create namespaces and install a CustomResourceDefinition, RBAC, and a Deployment.
* A namespace to install into. This section uses `<namespace>` as a placeholder for the Kubernetes namespace where you want the operator and RegattaDB to run.
* A registry reachable from every Kubernetes node that will run RegattaDB or the operator, and any credentials it requires for image pulls.
* Enough CPU and RAM on your Kubernetes nodes for the SM Pod and every RDB Pod you plan to run (see [Deployment Architecture](/self-hosted-deployment/kubernetes/introduction#deployment-architecture)).
* Filesystem storage for RegattaDB's repo and log directories, through a `StorageClass` or pre-created `PersistentVolumes`.
* Raw block storage for RDB, through a `StorageClass` or pre-created `PersistentVolumes` that support Kubernetes `volumeMode: Block`. RDB always uses raw block storage. This is not limited to local physical disks: any `StorageClass` or CSI driver that can present a raw block device works, including SAN, NVMe-oF, and distributed-filesystem vendor drivers that provision block-mode volumes backed by their own storage. Non-root access to raw devices, including any container-runtime configuration it requires, is covered in [Storage](/self-hosted-deployment/kubernetes/configuration/storage).

## Next steps

Once prerequisites are met, continue to [Installation](/self-hosted-deployment/kubernetes/installation).


# Release Notes
Source: https://docs.regatta.dev/self-hosted-deployment/kubernetes/release-notes

Changes, fixes, and known limitations for each Regatta operator release.

## \[26.1.0] - 2026-09-16

* Module-to-Pod placement is fixed: SM, SNA, GDD, DCM, and Sequencer always run together in one SM Pod, and SNA and RDB always run together in each RDB Pod. There is no supported way to configure a different placement.
* Changing a module's `config` settings is not a live update: it restarts the Pod or Pods that host the affected module.
* `spec.rdb.service.type: LoadBalancer` exposes a single external address shared by every RDB replica; it does not provide per-replica external routing. A client that needs to reach a specific RDB Pod directly must do so from inside your Kubernetes cluster.
* The operator configures RegattaDB with its default administrator account - the account RegattaDB itself uses to authenticate and manage the database, separate from any Kubernetes or operator credential. There is no current support for custom database credentials.
* SM's Service is always `ClusterIP`, with no built-in, operator-managed way to expose it outside your Kubernetes cluster. This is not the same as SM being technically unreachable from outside the cluster: you can create your own additional Service (or use `kubectl port-forward`) pointed at the SM Pod yourself - the operator just does not provide, manage, or secure one for you, and doing so is your own responsibility.


# Troubleshooting
Source: https://docs.regatta.dev/self-hosted-deployment/kubernetes/troubleshooting

Diagnose a RegattaCluster resource that isn't reaching Ready.

Start with the resource's own status and Events:

```sh theme={null}
kubectl -n <namespace> describe rgc my-regattadb
kubectl -n <namespace> get events --sort-by=.lastTimestamp
```

The issues below are ordered by how the operator brings a `RegattaCluster` resource up: work through them in order, since later ones only make sense once the earlier conditions pass.

## The resource is rejected on `apply`

The CRD schema or an immutability rule rejected your change before the operator ever saw it.

**Solution:** check the error Kubernetes printed; it names the field to fix.

## `StorageReady` is `False`

Kubernetes hasn't bound all the storage your `RegattaCluster` resource needs yet.

**Solution:** check the `PersistentVolumeClaims`, `PersistentVolumes`, and `StorageClasses` involved:

```sh theme={null}
kubectl -n <namespace> get pvc -l app.kubernetes.io/instance=my-regattadb
kubectl -n <namespace> describe pvc <pvc-name>
```

## `KubernetesReady` is `False`

One or both StatefulSets haven't finished rolling out, or their Pods aren't Running and Ready yet.

**Solution:** check StatefulSet rollout and Pod scheduling, image pulls, init containers, and readiness:

```sh theme={null}
kubectl -n <namespace> rollout status statefulset/my-regattadb-sm
kubectl -n <namespace> rollout status statefulset/my-regattadb-rdb
kubectl -n <namespace> get pods -l app.kubernetes.io/instance=my-regattadb
kubectl -n <namespace> describe pod <pod-name>
```

## `StorageReady` and `KubernetesReady` are `True`, but `Ready` is still `False`

Kubernetes is healthy; RegattaDB itself is not confirmed healthy yet.

**Solution:** check `status.regatta`, `status.modules`, and `status.devices`, and the operator's own logs:

```sh theme={null}
kubectl -n <namespace> logs deployment/regatta-operator
```

<Danger>
  Never print the contents of the credentials Secret while troubleshooting; nothing in it is needed to diagnose any of these conditions.
</Danger>

See [Reading RegattaCluster Status](./operations.mdx#reading-regattacluster-status) for what each condition and status field means.


# Deployment Example
Source: https://docs.regatta.dev/self-hosted-deployment/manual-deployment/deployment-example



This page walks through the deployment of a 10-Node RegattaDB system.

### Step 1: Node Identification and IP Assignment

In this example, the cluster nodes are assigned the following RegattaDB modules:

* **Node01** – Hosts the **SM**, **GDD**, **DCM**, and **Sequencer** modules, along with its local **SNA** and **RDB** modules. The node hosting the **SM** is commonly referred to as the *Management Node*.
* **Node02–Node10** – Each node hosts an **SNA** module and an **RDB** module.

Identify the nodes that will participate in the RegattaDB system. For each node, define:

* An internal IP address for cluster communication.
* An external IP address for client application access (if applicable).

For this deployment, we will use the following IP assignments:

* **Node01**
  * Internal: `10.0.0.1`
  * External: `192.168.1.101`
* **Node02–Node10**
  * Internal: `10.0.0.2`–`10.0.0.10`
  * External: `192.168.1.102`–`192.168.1.110`

The module communication and service ports will use the default port assignments described in the [Prepare for Deployment](/self-hosted-deployment/manual-deployment-copied-1/prepare-for-deployment#ip-assignment) guide.

### Step 2: Software Installation (RPM Deployment)

Install the required RPM packages on each node according to its assigned role, following the instructions in the [**Prepare for Deployment**](/self-hosted-deployment/manual-deployment-copied-1/prepare-for-deployment#install-the-rpm-packages) guide.

For this deployment we will be using the default `regatta` user as the deployment user.

### Step 3: Start the Management Services

Start the **SM** service on **Node01** and the **SNA** service on every node in the cluster.

#### Start the SM service

On **Node01**, run:

```shellscript theme={null}
sudo systemctl start regatta-26.0-sm.service
```

#### Start the SNA services

On **Node01** through **Node10**, run:

```shellscript theme={null}
sudo systemctl start regatta-26.0-sna.service
```

#### Verify the services

Verify that the services are running by checking their status with `systemctl`:

```shellscript theme={null}
systemctl status regatta-26.0-sm.service
```

Expected output:

```shellscript theme={null}
● regatta-26.0-sm.service - The Regatta sm service
   Loaded: loaded (/usr/lib/systemd/system/regatta-26.0-sm.service; enabled; vendor preset: disabled)
   Active: active (running) since Sun 2026-07-19 00:06:51 IDT; 35min ago
 Main PID: 158236 (regatta_sm)
    Tasks: 27 (limit: 203820)
   Memory: 256.0M
```

Likewise, verify the SNA service:

```shellscript theme={null}
systemctl status regatta-26.0-sna.service
```

Expected output:

```shellscript theme={null}
● regatta-26.0-sna.service - The Regatta sna service
   Loaded: loaded (/usr/lib/systemd/system/regatta-26.0-sna.service; enabled; vendor preset: disabled)
   Active: active (running) since Sun 2026-07-19 00:06:52 IDT; 37min ago
 Main PID: 158366 (regatta_sna)
    Tasks: 94 (limit: 203820)
   Memory: 12.4G
```

### Step 4: Connect to the System

Before continuing with the deployment, you need a client capable of connecting to the RegattaDB system and executing SQL management commands.

In this example, we will use the RegattaDB CLI, which is included in the deployment package. However, any supported RegattaDB client can be used. For information about the available clients, drivers, and integrations, refer to the [**Drivers & Clients**](/drivers-and-clients/connecting-applications-to-regatta) section.

#### Connection Parameters

To connect to the database, you will need:

* A RegattaDB username and password.
* The address of the **SM** service in the format `<IP>:<PORT>`.

The **SM** can be reached using any of the following addresses:

* **Internal IP:** `10.0.0.1`
* **External IP:** `192.168.1.101`
* **Localhost:** `127.0.0.1` (when running the client on the SM node)

The **SM** listens on the default communication port:

* **Port:** `8840`

For this deployment, we will use the default administrator credentials created during installation. The default connection parameters:

* **Username:** `admin`
* **Password:** `RegattaDefault1234!`
* **URL:** `10.0.0.1:8840`

<Danger>
  Please replace the default password immediately after deployment is completed.
</Danger>

#### Start the RegattaDB CLI

Run the CLI:

```shellscript theme={null}
/opt/regatta/<major.minor>/clients/cli/bin/client_cli
```

The CLI prompt is displayed:

```shellscript theme={null}
rdb>
```

Connect to the database:

```shellscript theme={null}
rdb>\connect user=admin pass=RegattaDefault1234! url=10.0.0.1:8840
```

If the connection is successful, the CLI displays:

```shellscript theme={null}
Successfully connected to RegattaDB system
```

You are now connected to RegattaDB and can execute SQL statements as well as RegattaDB management commands.

The remaining deployment steps assume you are connected to the database through the [RegattaDB CLI](/drivers-and-clients/regatta-cli). For a complete reference of the SQL management commands, see the [**System Management SQL Specification**.](/sql/system-monitoring/system-management/system-state)

### Step 5: Enter the SETUP State

Transition the system to the **SETUP** state. In this state, configuration changes are permitted, allowing you to define the cluster infrastructure, storage, and module assignments.

```sql theme={null}
MANAGE SYSTEM ENTER SETUP;
```

### Step 6: Define the Cluster Infrastructure

Register the deployment nodes with the cluster by assigning each node a unique name and its corresponding internal and external network addresses.

For example, register **Node01**:

```sql theme={null}
MANAGE NODE ADD (
  NAME "Node01",
  NETWORK (
    (INTERNAL IP "10.0.0.1")
    (EXTERNAL IP "192.168.1.101")
  )
);
```

Then register **Node02**:

```sql theme={null}
MANAGE NODE ADD (
  NAME "Node02", 
  NETWORK (
    (INTERNAL IP "10.0.0.2")
    (EXTERNAL IP "192.168.1.102")
  )
); 
```

Repeat this step for **Node03** through **Node10**, updating the node name and IP addresses accordingly.

### Step 7: Provision Storage

In this example, each cluster node is configured with two dedicated storage devices. This step assumes that the storage devices have already been assigned the appropriate ownership and permissions for the RegattaDB deployment user, as described in the [**Prepare for Deployment**](/self-hosted-deployment/manual-deployment-copied-1/prepare-for-deployment#storage-devices) guide.

Register the storage devices for each node by specifying a unique name and the local device path.

```sql theme={null}
MANAGE STORAGE DEVICE ADD (
  NODE "Node01",
  NAME "Node01_Disk1",
  PATH "/dev/nvme0n1"
);

MANAGE STORAGE DEVICE ADD (
  NODE "Node01",
  NAME "Node01_Disk2",
  PATH "/dev/nvme1n1"
);

MANAGE STORAGE DEVICE ADD (
  NODE "Node02",
  NAME "Node02_Disk1",
  PATH "/dev/nvme0n1"
);

MANAGE STORAGE DEVICE ADD (
  NODE "Node02",
  NAME "Node02_Disk2",
  PATH "/dev/nvme1n1"
);
```

Repeat this step for **Node03** through **Node10**, updating the node name, storage device name, and device path as appropriate.

### Step 8: Add the Operational Modules

Register the RegattaDB modules by assigning them to their designated nodes, network endpoints, and, for **RDB** modules, the appropriate storage devices.

<Note>
  **Important:** Always provision the **RDB** modules after provisioning all other modules. This ensures that memory is first allocated to the non-RDB modules, allowing each **RDB** module to utilize the maximum amount of remaining memory available on its host node.
</Note>

#### Add the non-RDB Modules

Run the following commands to add the **DCM**, **Sequencer**, and **GDD** modules on **Node01**.

```sql theme={null}
MANAGE MODULE ADD (
  NODE "Node01",
  NAME "DCM_1",
  ROLE DCM,
  NETWORK (
    (INTERNAL IP "10.0.0.1")
    (EXTERNAL IP "192.168.1.101")
  )
);

MANAGE MODULE ADD (
  NODE "Node01",
  NAME "SEQ_1",
  ROLE SEQUENCER,
  NETWORK (
    (INTERNAL IP "10.0.0.1")
    (EXTERNAL IP "192.168.1.101")
  )
);

MANAGE MODULE ADD (
  NODE "Node01",
  NAME "GDD_1",
  ROLE GDD,
  NETWORK (
    (INTERNAL IP "10.0.0.1")
    (EXTERNAL IP "192.168.1.101")
  )
);
```

#### Add the RDB Modules

After all management modules have been added successfully, add an **RDB** module on each node (**Node01** through **Node10**).

We use the module name `RDB_1` for the local **RDB** instance on each node.

```sql theme={null}
MANAGE MODULE ADD (
  NODE "Node01",
  NAME "RDB_1",
  ROLE RDB,
  STORAGE_DEVICE (
    "Node01_Disk1",
    "Node01_Disk2"
  ),
  NETWORK (
    (INTERNAL IP "10.0.0.1")
    (EXTERNAL IP "192.168.1.101")
  )
);
```

Repeat this step for **Node02** through **Node10**, updating the node name, storage device names, and network addresses as appropriate.

### Step 9: Exit the SETUP State and Activate the System

Finalize the deployment by exiting the **SETUP** state and starting the system. Once the system is running, verify that all modules have been provisioned successfully and that the database has reached the **ACTIVE** state.

```sql theme={null}
MANAGE SYSTEM EXIT SETUP;
MANAGE SYSTEM START;
MANAGE SYSTEM SHOW;
```

Expected output:

```shellscript theme={null}
regatta > MANAGE SYSTEM SHOW;
statement executed successfully
| STATE  |
----------
| Active |
```

**Your RegattaDB system is now fully deployed and ready for use.**


# High-Level Deployment Steps
Source: https://docs.regatta.dev/self-hosted-deployment/manual-deployment/high-level-deployment-steps



The deployment of a RegattaDB system follows the sequence below. This overview assumes that you have already completed the [**Prepare for Deployment**](/self-hosted-deployment/manual-deployment-copied-1/prepare-for-deployment) guide and provisioned your environment accordingly. The following sections summarize the deployment workflow. The next page provides a detailed, step-by-step deployment example covering the entire process.

During the deployment process, you will use SQL management commands to communicate with the **SM**. For a complete reference of the SQL management commands, see the [**System Management SQL Specification**.](/sql/system-monitoring/system-management/system-state)

### Identify the Deployment Nodes

Identify the nodes that will host the RegattaDB modules.

For each node, prepare:

* Internal IP addresses for cluster communication.
* External IP addresses for client application access (if required).

### Deploy the SM

RegattaDB uses a single **SM** (System Manager) module.

* Select the node that will host the **SM**.
* Install the **SM** package.
* Start the **SM** service.

### Deploy the SNA

Deploy an **SNA** on every node that will host one or more Operational Modules.

* Install the **SNA** package.
* Start the **SNA** service.

### Plan Module Placement

Determine which Operational Modules will run on each node. A single node may host one or more modules.

Each deployment requires:

* Exactly one **DCM**
* Exactly one **Sequencer**
* Exactly one **GDD**
* One or more **RDB** modules

### Install the Operational Modules

Install the RPM packages corresponding to the assigned module roles on each node.

### Enter SETUP State

Install the RegattaDB CLI, which is included in the software package. The CLI may be installed on any node that has network connectivity to the **SM**.

Transition the system from the **DOWN** state to the [**SETUP**](/sql/system-management/system-states-and-commands#system-enter-setup) state to enable configuration operations.

### Define the Infrastructure

Register the cluster nodes using their host names and configured IP addresses.

### Configure Storage

[Register the storage devices](/sql/system-management/storage-devices) assigned to each node by specifying a unique name and the local device path for each storage device.

### Add the Operational Modules

[Register each module](/sql/system-management/modules#module-add), assign it to its designated node, and associate it with the appropriate storage device.

<Note>
  By default, RegattaDB automatically allocates memory according to the requirements of each module. Because the **RDB** is designed to consume all remaining available memory, it should always be provisioned **after** the other modules. This ensures it receives the memory that remains after the fixed allocations for the other modules have been reserved. Although RegattaDB supports manual memory allocation on a per-module basis, the default allocation should be used unless your sizing analysis requires otherwise.
</Note>

### Exit SETUP State

Transition the system back to the [**DOWN**](/sql/system-management/system-states-and-commands#system-exit-setup) state to finalize and lock the deployment configuration.

### Activate the System

[Start the system](/sql/system-management/system-states-and-commands#system-start) to transition it to the **ACTIVE** state. During this step, the Operational Modules are started and begin accepting client connections.


# Prepare for Deployment
Source: https://docs.regatta.dev/self-hosted-deployment/manual-deployment/prepare-for-deployment



## Deployment Planning

The first step is defining your deployment topology. The optimal topology depends on your workload profile, performance objectives, and storage requirements. RegattaDB supports a wide range of deployment configurations, allowing the system to be tailored to your specific requirements.

General deployment guidelines:

* Management Modules
  * **SM** - Deploy a single SM module for every RegattaDB system
  * **SNA** - Deploy one agent on every node that hosts at least one Operational Module
* Operational Modules
  * **GDD**, **DCM**, **Sequencer** - Deploy one instance of each module per RegattaDB system
  * **RDB** - Deploy at least one RDB module per RegattaDB system

Below are several common configurations.

#### Single Node

A single-node deployment consists of a single server hosting all RegattaDB modules:

<Frame>
  <img alt="IMG 0279" title="IMG 0279" />

  <img alt="IMG 0279" title="IMG 0279" />
</Frame>

#### Multi-Node – Classic

The most common multi-node deployment uses the following topology:

* One node hosts all RegattaDB modules, as in a single-node deployment.
* All additional nodes host both the **RDB** and **SNA** modules.

<Frame>
  <img alt="IMG 0280" title="IMG 0280" />

  <img alt="IMG 0280" title="IMG 0280" />
</Frame>

#### Multi-Node – Custom

An example of a custom multi-node deployment, which may be common in large-scale deployments. Here module placement is spread across dedicated nodes instead of following the classic layout:

* One node hosts **SM**, **SNA**, **DCM**, and **GDD**.
* A second node hosts **SNA** and **Sequencer**.
* Every additional node (scale-out nodes) hosts **RDB** and **SNA**.

<Frame>
  <img alt="RegattaDB custom multi-node deployment" title="RegattaDB custom multi-node deployment" />

  <img alt="RegattaDB custom multi-node deployment" title="RegattaDB custom multi-node deployment" />
</Frame>

<Info>
  For guidance on sizing and configuring your RegattaDB deployment, refer to **Best Practices** or contact Regatta Support for assistance.
</Info>

### **Provision the Deployment Nodes**

Next, provision the nodes that will host your RegattaDB deployment, ensuring that each node meets the minimum hardware, storage, networking, and software [prerequisites](/self-hosted-deployment/prerequisites).

The exact hardware requirements depend on your deployment topology and workload characteristics. For guidance on sizing your deployment, refer to Best Practices or contact Regatta Support for assistance.

### Download the RegattaDB Software

Next, download the RegattaDB software package. RegattaDB is distributed as a set of RPM packages, each corresponding to a specific module or utility. Copy the required RPM packages to the nodes on which they will be installed according to your planned deployment topology.

The following example shows the contents of a RegattaDB software package.

#### Deployment Software

Each of the RPM packages below corresponds to one of the six RegattaDB modules.

```shellscript theme={null}
regatta-dcm-<version>.el8.x86_64.rpm
regatta-gdd-<version>.el8.x86_64.rpm
regatta-rdb-<version>.el8.x86_64.rpm
regatta-sequencer-<version>.el8.x86_64.rpm
regatta-sm-<version>.el8.x86_64.rpm
regatta-sna-<version>.el8.x86_64.rpm
```

### EULA Acceptance

Before deploying RegattaDB, you must read and accept the **Regatta End User License Agreement (EULA**). Acceptance of the EULA is integrated into the RPM installation process and is required before the installation can be completed.

* **Interactive installations** (for example, using `yum install` or `dnf install`) - You will be prompted to review and accept the EULA during installation
* **Automated installations** - Set the environment variable `ACCEPT_EULA=1` to indicate acceptance of the EULA and suppress the interactive prompt.

If you are using automated installation, we strongly recommend reviewing the EULA in advance. The latest version is available at:

[**https://regatta.dev/eula/**](https://regatta.dev/eula/)

### Install the RPM Packages

Install the required RegattaDB RPM packages using `yum` or `dnf`:

```shellscript theme={null}
sudo yum install regatta-<package-name>-<version>.el8.x86_64.rpm
or
sudo dnf install regatta-<package-name>-<version>.el8.x86_64.rpm
```

During installation, you will be prompted to review and accept the Regatta End User License Agreement (EULA):

```shellscript theme={null}
******************************************************************************
Regatta End User License Agreement (EULA)
URL: https://regatta.dev/eula/
******************************************************************************
To continue installation, type Y and press Enter.
To abort, press any other key and press Enter.
Accept EULA? [y/N]:
```

For unattended or automated installations, pre-approve the EULA by setting the `ACCEPT_EULA=1` environment variable:

```shellscript theme={null}
sudo ACCEPT_EULA=1 yum install regatta-<package-name>-<version>.el8.x86_64.rpm
or
sudo ACCEPT_EULA=1 dnf install regatta-<package-name>-<version>.el8.x86_64.rpm
```

All RegattaDB RPM packages are installed under `/opt/regatta/<major.minor>`. For convenience, you can use the `/opt/regatta/current` symbolic link to reference the current installation. The examples below show the installation directories for the **SM** and **RDB** modules.

**SM:**

```shellscript theme={null}
/opt/regatta/current/sm
├── bin
├── LICENSE
├── sm_1
│   ├── bin
│   ├── conf
│   ├── log -> /var/log/regatta/sm/sm_1
│   └── repo
└── tools
```

**RDB:**

```shellscript theme={null}
/opt/regatta/current/rdb
├── bin
├── LICENSE
├── rdb_1
│   ├── bin
│   ├── conf
│   ├── log -> /var/log/regatta/rdb/rdb_1
│   └── repo
└── tools
```

#### Additional RegattaDB RPM Packages

In addition to the RegattaDB software modules, the RegattaDB self-hosted package includes several utilities that simplify deployment, administration, backup, and troubleshooting.

The following RPM packages are included:

* Regatta Deployment Tool (RDT) - An automated deployment tool for provisioning and configuring RegattaDB. For detailed instructions, refer to the [**Regatta Deployment Tool (RDT)**](/self-hosted-deployment/rdt/introduction) guide.
* Regatta Debug Tool - A Docker-based utility for connecting to running RegattaDB systems to perform live diagnostics, troubleshooting, and debugging.
* Regatta Bench - A benchmarking utility for executing preconfigured workloads against a RegattaDB system to evaluate performance and validate deployments.

```shellscript theme={null}
regatta-bnr-<version>.el8.x86_64.rpm
regatta-rdt-<version>.el8.x86_64.rpm
regatta-debug-<version>.el8.x86_64.rpm
```

#### Client Software

The self-hosted deployment package also includes the RegattaDB client components. For installation and usage instructions, refer to [Drivers & Clients](/drivers-and-clients/connecting-applications-to-regatta).

The following RPM packages are included:

* Regatta Client Library
* Regatta CLI
* Regatta Connect - A collection of drivers, ORMs, and connectors for integrating RegattaDB with external applications, frameworks, and data platforms.

```shellscript theme={null}
regatta-cli-<version>.el8.x86_64.rpm
regatta-client-<version>.el8.x86_64.rpm
regatta-connect-<version>.el8.x86_64.rpm
```

### Storage Devices

RegattaDB is designed to work directly with **raw block storage devices** to minimize filesystem overhead and achieve the highest possible storage performance. Direct access to raw devices allows RegattaDB to optimize data layout and I/O patterns specifically for database workloads.

#### Storage Requirements

Each **RDB** module must be assigned at least one storage device that is not used as the operating system boot device.

RegattaDB supports virtually any raw block storage device, including:

* Local NVMe devices (recommended for best performance)
* Local SSD devices
* SAN-attached block storage (Fibre Channel, iSCSI, etc.)
* Cloud block storage volumes (for example, Amazon EBS, Azure Managed Disks, or Google Persistent Disk)
* Shared block storage presented to the operating system as a raw block device

#### Using Filesystem-Backed Storage

Although direct raw block devices are recommended, RegattaDB can also use file-backed storage devices when raw devices are not available. In this configuration, a regular file located on a mounted filesystem is presented to RegattaDB as a storage device.

For example, the following command creates a sparse 1 TB file on an existing filesystem:

```shellscript theme={null}
sudo fallocate -l 1T /mnt/regatta_storage/rdb_device1.dat
```

The resulting file can then be registered as a storage device during deployment:

```sql theme={null}
MANAGE STORAGE DEVICE ADD (
  NODE "Node01",
  NAME "Node01_Disk1",
  PATH "/mnt/regatta_storage/rdb_device1.dat"
);
```

While this approach is fully supported, direct raw block devices generally provide the best performance.

#### Persistent Module State

Each RegattaDB module maintains a small amount of persistent state under its repository directory:

```shellscript theme={null}
/opt/regatta/current/<module>/<instance>/repo
```

For example, the repository for the first **RDB** module is located at:

```text theme={null}
/opt/regatta/current/rdb/rdb_1/repo
```

If required by your deployment, this directory may reside on persistent storage by mounting the desired storage device at the appropriate location.

#### Storage Permissions

The [deployment user](/self-hosted-deployment/manual-deployment-copied-1/prepare-for-deployment#deployment-user) must have read and write access to all storage devices used by RegattaDB.

For raw block devices, assign ownership to the deployment user and group before deployment:

```shellscript theme={null}
sudo chown <user>:<group> /dev/path/to/device
```

Repeat this step for each storage device assigned to RegattaDB.

### Deployment User

RegattaDB requires a deployment user with the appropriate ownership and permissions for the installation directories, shared memory, log directories, and storage devices.

The deployment owns the following resources:

* Regatta installation directory - `/opt/regatta` - created during RPM installation
* Shared memory directory - `/dev/shm/Regatta` - created automatically by RegattaDB at runtime
* Log directory - `/var/log/regatta` - created during RPM installation
* Storage devices allocated for RegattaDB

During installation, the RPM packages automatically create a default deployment user and group both named `regatta`. If you wish to use a different deployment user, follow these steps:

#### Installing with a Custom Deployment User

To install RegattaDB with a custom deployment user and/or group, set the `REGATTA_USER` and `REGATTA_GROUP` environment variables when installing the RPM package. Each RPM creates the OS user/group if it doesn't already exist, and applies ownership of its installed files to it.

`REGATTA_USER` and `REGATTA_GROUP` must:

* Not be empty
* Not be `root`
* Start with a letter or underscore, and contain only letters, digits, `.`, `_`, or `-`

If a value doesn't meet these requirements, the installation fails immediately with an error. If either variable is left unset, it defaults to `regatta`.

<Warning>
  Use the same `REGATTA_USER`/`REGATTA_GROUP` values for every RegattaDB RPM you install. Each package independently resolves the account and applies ownership to its own files, so using inconsistent values across packages will leave some files owned by the wrong user/group.
</Warning>

**Example**

Given the following RPM packages:

```text theme={null}
regatta-cli-<version>.el8.x86_64.rpm
regatta-client-<version>.el8.x86_64.rpm
```

Install them with a custom deployment user and group, `myuser`/`mygroup`:

```bash theme={null}
sudo REGATTA_USER=myuser REGATTA_GROUP=mygroup yum install \
  regatta-cli-<version>.el8.x86_64.rpm \
  regatta-client-<version>.el8.x86_64.rpm
```

If `myuser`/`mygroup` don't already exist on the system, they are created automatically as a system account (no login shell, no home directory).

### IP Assignment

Assign IP addresses to each node in the RegattaDB cluster. Prepare a list of:

* **Internal IP addresses** used for communication between RegattaDB modules.
* **External IP addresses** used by client applications to access RegattaDB (if applicable).

<Note>
  **Note:** RegattaDB clients automatically use the external IP address when one is configured for a node. Otherwise, they fall back to the node's internal IP address.
</Note>

Each RegattaDB module requires two ports:

* A **Communications Port**, used for communication between RegattaDB modules.
* A **Service Port** used for internal service operations.

By default, RegattaDB uses the port assignments shown below. We recommend using these default values unless your deployment requires otherwise (for example, when running multiple RDB modules on a single node).

| Module | Communications Port | Service Port |
| :- | :- | :- |
| SM | 8840 | 5000 |
| SNA | 8841 | 5001 |
| Sequencer | 8842 | 5002 |
| GDD | 8843 | 5003 |
| DCM | 8844 | 5004 |
| RDB | 8850 | 6001 |

### Firewall Setup

Configure the firewall on each node to allow traffic on the required RegattaDB IPs and ports.

At a minimum, ensure that:

* The communications and service ports are accessible between all RegattaDB nodes.
* Client applications can access the required external endpoints, as defined by your deployment.


# RegattaDB Software Modules
Source: https://docs.regatta.dev/self-hosted-deployment/manual-deployment/regattadb-software-modules



Below we describe the different software modules which together make up a RegattaDB system. A module is an independently deployable user-mode process that handles a specific functional role within the distributed database architecture.

In total, the architecture comprises six distinct modules. Each deployment includes a combination of these modules, distributed across one or more nodes.

<Info>
  A **node** is the fundamental compute unit in a RegattaDB deployment. It represents a server that provides CPU, memory, networking, and storage resources to the cluster. A node may be a physical server, a virtual machine (VM), or a container, and may host one or more RegattaDB modules.
</Info>

RegattaDB modules can be broken down into 2 groups: Management Modules and Operational Modules.

### Management Modules

These modules form the administrative framework of the RegattaDB system, providing the tools necessary to configure, monitor, and maintain the system infrastructure. The management modules are deployed as `systemd` services. They are responsible for starting, stopping, monitoring, and managing the lifecycle of the operational modules.

#### SM – System Manager

System Manager handles the deployment of RegattaDB on all nodes. After deployment, it manages both hardware and software resources, executes administrative commands, and coordinates ongoing system operations.

#### SNA – System Node Agent

The System Node Agent runs on each node where a RegattaDB module is deployed and serves as the local execution layer for the System Manager. It is responsible for managing the lifecycle of all RegattaDB modules on that node.

### Operational Modules

These modules drive the core database engine, handling active workloads, maintaining data consistency, and managing the relational schema.

#### RDB – Regatta Database

The RDB module is RegattaDB’s distributed compute engine, responsible for query execution and data processing. It leverages CPU, network, and I/O resources efficiently, and scales by adding additional RDB modules.

#### Sequencer

Coordinates consistency of the distributed transactions and snapshots between all RegattaDB modules.

#### DCM – Database Catalog Manager

Manages the database catalog which contains all the schema definitions including tables indexes and their attributes.

#### GDD – Global Deadlock Detector

The Global Deadlock Detector (GDD) component is responsible for detecting circular distributed dependencies between transactions in the system and resolving them.


# Prerequisites
Source: https://docs.regatta.dev/self-hosted-deployment/prerequisites



In order to deploy a RegattaDB system, ensure the following requirements are met on all servers that are designated for the deployment:

1. **Operating system:** Red Hat 8–based distribution such as Oracle Linux 8 or RHEL 8.10
2. **Architecture:** x86-64 (64-bit)
3. **Required system dependencies**:
   * `glibc`
   * `libstdc++`
   * `libgcc`
   * `util-linux-libs`
   * `openssl-libs`
   * `libaio`
   * `jemalloc` (recommended)
4. **Hardware Requirements:**
   * Memory: Minimum 32 GB
   * Disk space for RegattaDB installation: Minimum 500 MB
   * CPU: Minimum 4 CPUs
   * Storage: At least one dedicated 350-GB block storage device (preferably NVMe or SSD) that is not the system boot device
5. **Connectivity:**
   * Minimum 10-Gb network connection between all RegattaDB servers
   * Internet access for package downloads (optional)
6. **RegattaDB Software:**<br />Obtain the RegattaDB software package and ensure it is available on all servers designated for the deployment
   <Note>
     If you are using the [**Regatta Deployment Tool (RDT)**](/self-hosted-deployment/rdt/introduction), the software package only needs to be available on the server where the RDT is executed. The RDT automatically distributes the required RPM packages to the remaining servers.
   </Note>


# Global Options & Credentials
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/advanced/global-options-and-credentials

SSH credentials and other options available on every RDT command.

These options can be passed on any `rdt` command, before or after the subcommand name.

| Option | Env var | Description |
| - | - | - |
| `--user`/`-u` | `RDT_USER` | SSH user to connect with |
| `--key`/`-k` | `RDT_KEY_FILE` | SSH private key file to connect with |
| `--password`/`-p` | `RDT_SSH_PASSWORD` | SSH password to connect with |
| `--ask-password`/`-P` | N/A | Prompt for the SSH password interactively instead of passing it on the command line |
| `--verbose`/`-v` | N/A | Increase verbosity. `-v` for info-level logs, `-vv` for debug |
| `--version` | N/A | Print the installed RDT version and exit |

Example:

```bash theme={null}
rdt --user regatta --key ~/.ssh/id_rsa config list
```

## Two separate sets of credentials

RDT talks to your infrastructure in two different ways, each with its own credentials:

* **SSH credentials** (`--user`/`--key`/`--password`/`--ask-password` above): used for
  every node-level operation: distributing files, installing packages, managing
  services, probing hardware, collecting debug info, cleaning, and resetting. Passing
  `--user` or `--key` on **any** command persists it as the default for every
  subsequent command, not just the one you ran. `--password` and `--ask-password` only
  apply to that single invocation.
* **System Manager credentials**: used only by `configure`, `start-cluster`,
  `stop-cluster`, and `reset` (indirectly) to connect to the database itself. These are
  currently fixed to Regatta's default admin account and aren't configurable through the
  CLI today.


# Module & NUMA Configuration
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/advanced/module-and-numa-configuration

Manually pin modules to CPU cores using your node's real NUMA topology.

See [Configuration Overview](../configuration/overview.mdx#core-binding) for the
`core_binded_node`/`core_binded_cores` fields themselves. This page covers how to fill
them in deliberately, using your node's real NUMA topology.

## Inspecting your node's CPU and NUMA layout

Before setting `core_binded_node`/`core_binded_cores` by hand, find your node's real
CPU and NUMA layout. Two common tools:

`lscpu` prints the NUMA node count and, for each node, the CPU ids that belong to it:

```bash theme={null}
lscpu
```

```text theme={null}
NUMA node(s):          2
NUMA node0 CPU(s):     0-7
NUMA node1 CPU(s):     8-15
```

`numactl --hardware` (package `numactl`) gives the same CPU breakdown plus each NUMA
node's local memory:

```bash theme={null}
numactl --hardware
```

```text theme={null}
available: 2 nodes (0-1)
node 0 cpus: 0 1 2 3 4 5 6 7
node 0 size: 131072 MB
node 1 cpus: 8 9 10 11 12 13 14 15
node 1 size: 131072 MB
```

Use this data the same way you'd use probed `numa_specs` below: pick a NUMA node, use
its CPU list (or a subset) as `core_binded_cores`, and set `core_binded_node` to match.

## Reading probed NUMA data

If you created your config with `--probe-nodes` (see
[What Changes on Your Nodes](./node-system-changes.mdx#hardware-discovery---probe-nodes)),
each node's `config.numa_specs` is filled in with something like:

```json theme={null}
"modules": [
  {
    "type": "rdb",
    "id": 11,
    ...,
    "config": {
      "numa_specs": {
        "node0": { "cpu": "0,1,2,3,4,5,6,7", "mem_mb": 131072 },
        "node1": { "cpu": "8,9,10,11,12,13,14,15", "mem_mb": 131072 }
      }
    }
  }
]
```

Each key is a NUMA node, with the CPU ids that belong to it and its local memory. This
is recorded for reference; RDT doesn't automatically bind modules to NUMA nodes for
you, you decide the binding based on this data.

## Setting core binding manually

To pin a module to a set of cores, set both fields in its `config`:

```json theme={null}
"modules": [
  {
    "type": "rdb",
    "id": 11,
    ...,
    "config": {
      "core_binded_node": "0",
      "core_binded_cores": "0-5"
    }
  }
]
```

* `core_binded_node` identifies which NUMA node this binding corresponds to (for your
  own reference; it's not cross-checked against `numa_specs`).
* `core_binded_cores` accepts individual CPU ids, ranges, or a mix, comma-separated
  (e.g. `0-5`, `0,1,2`, or `0-3,8,10-11`). Unlike the flat comma-separated list in
  `numa_specs.cpu`, ranges are written with a hyphen here.
* If `num_threads` is left unset, it's derived automatically from the core count. If
  you set it explicitly, it must not exceed the number of cores in `core_binded_cores`.

A typical pattern: pick a NUMA node from `numa_specs`, use a subset (or all) of its CPU
list as `core_binded_cores`, and set `core_binded_node` to that NUMA node's id.


# What Changes on Your Nodes
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/advanced/node-system-changes

The system-level changes RDT makes on RegattaDB nodes during setup, cleanup, and reset.

This page documents what RDT actually changes on a node's operating system when you run `setup`, `create-cluster`, `clean`, or `reset`. Useful for troubleshooting, or for understanding what you're authorizing when you grant RDT `sudo` access.

## Storage & device setup

* Every storage device referenced by an RDB module has its ownership changed to `regatta:regatta`. For a raw block device, this is done via a `udev` rule written to `/etc/udev/rules.d/99-regatta-storage.rules` (re-applied immediately with `udevadm trigger`, not just after a reboot). For a file-backed device (a regular file used as storage instead of a raw block device), ownership is changed directly, since `udev` rules only apply to block devices.
* Devices used by SM and DCM modules are handled differently: they're formatted as `ext4` and mounted at a fixed path under the Regatta installation directory. This reformats the device: use a raw, unused block device, never one with existing data. Ownership of the mount point is set to `regatta:regatta`.

## Service management

RDT discovers every installed `regatta-*` `systemd` service on a node (except internal/ templated units) and manages all of them together: starting, stopping, or enabling them for boot as a group, based on what you asked for (`start-services`/`stop-services`/ `setup`/etc.).

## Performance tuning (`jemalloc`)

If `libjemalloc` is available on the node (checked under `/usr/lib64`, then as a
fallback via the system's shared library cache), RDT wires it in as `LD_PRELOAD` for the
SM and SNA module environments. If it's not found, `setup` prints a warning and skips
this step; it's a performance optimization, not a requirement.

## Module configuration files

RDT writes each module's configuration file from your RegattaDB config, one per module
instance, under that module's directory in the Regatta installation.

## Cleanup (`clean`)

Removes Regatta's installation, logs, and runtime data from a node. If RDT itself is
installed on that node, `clean` specifically preserves RDT's own installed files and its
own log directory; everything else is removed. If RDT isn't installed there, the wipe
is unconditional (installation directory, symbolic links, logs, lock files, shared memory).

## Reset (`reset`)

Clears RegattaDB's runtime data while leaving the installation itself intact: shared
memory files, core dumps, crash info and lock files, network identifiers, each module's
repository contents, and log directories (events, traces, workload data). Binaries and
configuration files are not touched. See
[RegattaDB Lifecycle](../system-setup/lifecycle.mdx#resetting-regattadb) for the
manual steps needed to bring RegattaDB back up afterward.

## Hardware discovery (`--probe-nodes`)

When you create a config with `--probe-nodes`, RDT connects to each node and reads:

* Total CPU thread count and RAM.
* NUMA topology (which CPUs and how much memory belong to each NUMA node): see
  [Module & NUMA Configuration](./module-and-numa-configuration.mdx).
* Unmounted, unformatted block devices: any large enough one found gets assigned to
  that node's RDB module(s) automatically.

## How RDT connects to nodes

RDT connects to nodes over SSH, in parallel across many nodes at once (so large
deployments aren't set up one node at a time), and reuses connections across the steps of a
single command for speed. Host key verification is skipped by default, so first-time
connections to new nodes won't prompt for confirmation. Make sure you trust your
network path to these nodes accordingly.


# Offline Installation
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/advanced/offline-installation

Install RDT on a control node with no internet access, from a pre-built artifact bundle.

If your control node has no internet access, install RDT from an offline artifact
bundle: a standalone Python build plus pre-built wheels for RDT and its dependencies.
This page assumes you already have that bundle in hand (obtained from your Regatta
distribution or support contact).

## Installing

The bundle is a directory containing `python3.9-build.tar.gz` and a `python-wheels/`
folder. Run:

```bash theme={null}
packaging/offline/install.sh /path/to/bundle
```

If you omit the path, it defaults to the current directory. This:

1. Extracts the standalone Python build to `~/.local/python/`.
2. Installs RDT and all its dependencies from the local wheels, no network access
   required.
3. Adds `~/.local/python/bin` to your `PATH` via `~/.bashrc` (only if not already
   present).

Apply the `PATH` change and confirm:

```bash theme={null}
source ~/.bashrc
rdt --version
```

The `~/.bashrc` PATH update only takes effect in interactive bash shells that source it,
either the current shell (after you `source` it manually) or any new one you open
afterward. It won't apply automatically in a few common cases:

* **Non-interactive contexts**: scripts, cron jobs, or a single non-interactive SSH
  command (e.g. `ssh host 'rdt --version'`) don't source `~/.bashrc` at all. Either call
  `rdt` by its full path (`~/.local/python/bin/rdt`) or export the `PATH` explicitly in
  that context:
  ```bash theme={null}
  export PATH="$HOME/.local/python/bin:$PATH"
  ```
* **A different login shell**: if your default shell isn't bash (e.g. zsh, fish), add
  the same line to that shell's own startup file instead (e.g. `~/.zshrc` for zsh).
* **Login shells that don't source `~/.bashrc`**: some minimal environments only read
  `~/.bash_profile`/`~/.profile` on login and don't chain-load `~/.bashrc`. If a fresh
  login doesn't pick up the change, add the same `export PATH=...` line to whichever of
  those files exists on your system.

This installs entirely into your home directory and doesn't require root. If you'd
rather make this the system-wide `python3`, do so manually (requires root):

```bash theme={null}
sudo alternatives --set python3 "$HOME/.local/python/bin/python3.9"
```

## Compiling native extensions

If installing a wheel needs to compile a C/C++ extension, set `CC`/`CXX` first:

```bash theme={null}
CC=gcc CXX=g++ packaging/offline/install.sh /path/to/bundle
```

## Troubleshooting

* **"file not found"**: confirm the bundle path contains both
  `python3.9-build.tar.gz` and a `python-wheels/` directory.
* **"permission denied"**: everything is installed under `~/.local`, so this usually
  means `~/.local` (or `~/.local/python` from a previous attempt) is owned by a
  different user or has restrictive permissions, or the bundle directory itself isn't
  readable by your user. Check ownership and fix it before retrying:
  `ls -la ~/.local` and `chown -R "$(id -un)" ~/.local` if needed.
* **pip build errors for C extensions**: see the `CC`/`CXX` step above.
* For more detail on what's happening, run with shell tracing:
  `bash -x packaging/offline/install.sh /path/to/bundle`.

## Verifying the install

If `rdt --version` didn't work after installing, use these to isolate which layer
failed: the extracted Python itself, your `PATH`, or the package install:

```bash theme={null}
"$HOME/.local/python/bin/python3" --version   # should report Python 3.9
python3 --version                             # run after `source ~/.bashrc`, should also report
                                               # 3.9 if PATH now resolves python3 to the new install
python3 -m pip list                           # should list rdt and its dependencies
```


# Running RDT in a Container
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/advanced/running-rdt-in-a-container

Run RDT from a pre-built container image instead of installing it directly.

If you've been given a pre-built RDT container image (or an image tar), you can run
`rdt` through it without installing anything on your control node besides Docker.

## Prerequisites

* Docker, or a compatible CLI such as Podman (set `DOCKER=podman` if so).
* The `rdt.sh` wrapper script (shipped alongside the image).

## Running commands

Use the wrapper script exactly as you would the `rdt` binary: it forwards all
arguments:

```bash theme={null}
./rdt.sh --help
./rdt.sh config create --name my-regattadb --from xsmall --ip-list 10.0.0.1
./rdt.sh config list
./rdt.sh create-cluster --name my-regattadb --src /path/to/regatta-rpms
```

It automatically mounts your `~/.rdt` config directory and `~/.ssh` keys into the
container and runs with host networking, so configs and SSH access work the same as a
native install.

## Providing the image

If you weren't given an already-loaded Docker image, load one from a tar file
explicitly:

```bash theme={null}
./rdt.sh --src rdt_image.tar config list
```

Otherwise, the wrapper looks for an image automatically, in this order:

1. An existing Docker image tagged `rdt:<version>` or `rdt:latest`.
2. A tar at `$RDT_DOCKER_IMAGE_PATH` (default: `/opt/regatta/current/tools/rdt/rdt_image.tar`).
3. `rdt_image.tar` in the current working directory.

If none of these are found, the wrapper reports an error. See
`./rdt.sh --help` for the full set of flags and environment variables.

## Environment variables

| Variable | Default | Description |
| - | - | - |
| `DOCKER` | `docker` | Docker CLI binary to use |
| `RDT_DOCKER_IMAGE_FILE` | `rdt_image.tar` | Tar filename used for auto-discovery |
| `RDT_DOCKER_IMAGE_PATH` | `/opt/regatta/current/tools/rdt/rdt_image.tar` | Full tar path used for auto-discovery |


# Command Reference
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/command-reference

Every RDT command, its options, and what it does.

Below is a command reference guide for the RDT. Every command also accepts the [global options](./advanced/global-options-and-credentials.mdx) (`--user`, `--key`, `--password`, `--ask-password`, `--verbose`, `--version`). Each command also has a short alias, shown in parentheses next to its name below (aliases aren't shown in `--help` output, but work the same as the full name). Run `rdt <command>`<br />`--help` at any time for the same information from the CLI itself.

## `config `(alias: `c`)

Manage RegattaDB configuration files. See
[Creating & Managing Configs](./configuration/creating-and-managing-configs.mdx) for a
guided walkthrough.

### `config create` (alias: `cr`)

| Option | Description |
| - | - |
| `--name`/`-n` | Config name (required) |
| `--from`/`-f` | Start from a packaged template (`small` or `xsmall`). Mutually exclusive with `--nodes` |
| `--nodes`/`-no` | Number of nodes to generate (mutually exclusive with `--from`) |
| `--ip-file`/`-ipf` | File containing node IP addresses |
| `--ip-list`/`-ips` | Comma-separated list of node IP addresses |
| `--probe-nodes`/`-p` | Connect to each node over SSH to detect CPU, RAM, and devices |
| `--output`/`-o` | Write to a local file instead of the config store |
| `--force` | Recreate without prompting if a config by this name already exists |

### `config print` (alias: `p`)

| Option | Description |
| - | - |
| `--name`/`-n` | Config name (required) |
| `--validate`/`-v` | Print a warning if the config fails validation. Default: enabled |

### `config edit` (alias: `e`)

| Option | Description |
| - | - |
| `--name`/`-n` | Config name (required). Opens it in `$EDITOR` |

### `config list` (alias: `ls`)

No options. Lists both packaged templates and saved configs.

### `config load` (alias: `l`)

| Option | Description |
| - | - |
| `--file`/`-f` | Local JSON config file to import (required) |
| `--name`/`-n` | Name to save it as. Defaults to the file's name (without `.json`) |

### `config remove` (alias: `rm`)

| Option | Description |
| - | - |
| `--name`/`-n` | Config name to delete (required) |
| `--force` | Delete without prompting for confirmation |

## `distribute` (alias: `di`)

Distributes Regatta RPMs to every node.

| Option | Description |
| - | - |
| `--name`/`-n` | Config name (required) |
| `--src`/`-s` | Path to a directory of RPMs or a `.tar.zst` archive (required) |

## `setup` (alias: `st`)

Installs RPMs and configures nodes (see [System Setup Overview](./system-setup/overview.mdx)).

| Option | Description |
| - | - |
| `--name`/`-n` | Config name (required) |
| `--clean-install`/`-ci` | Remove any previous installation before reinstalling. Default: off |

## `start-services` (alias: `ss`) / stop-services (alias: `sps`)

Starts or stops the System Manager and SNA as node-level services.

| Option | Description |
| - | - |
| `--name`/`-n` | Config name (required) |

## `configure` (alias: `co`)

Registers the nodes, devices, and modules with the System Manager.

| Option | Description |
| - | - |
| `--name`/`-n` | Config name (required) |

## `start-cluster` (alias: `sc`) / stop-cluster (alias: `stop`)

Starts or stops every configured module via the System Manager (`MANAGE SYSTEM START`/
`MANAGE SYSTEM SHUTDOWN`).

| Option | Description |
| - | - |
| `--name`/`-n` | Config name (required) |

## `create-cluster` (alias: `ccl`)

Runs the full pipeline in one command: distribute → setup → start-services → configure →
start-cluster.

| Option | Description |
| - | - |
| `--name`/`-n` | Config name (required) |
| `--src`/`-s` | Path to a directory of RPMs or a `.tar.zst` archive (required) |
| `--clean-install`/`-ci` | Remove any previous installation before reinstalling. Default: off |

## `reset` (alias: `re`)

Stops services, clears all RegattaDB data, and restarts services. Does **not**
automatically reconfigure or restart the database afterward. See
[RegattaDB Lifecycle](./system-setup/lifecycle.mdx#resetting-regattadb).

| Option | Description |
| - | - |
| `--name`/`-n` | Config name (required) |

## `clean` (alias: `cl`)

Removes Regatta's installation, files, logs, and traces from every node (preserving RDT
itself where it's installed; see [What Changes on Your Nodes](./advanced/node-system-changes.mdx#cleanup-clean)).

| Option | Description |
| - | - |
| `--name`/`-n` | Config name (required) |

## `collect` (alias: `coll`)

Collects debug information from RegattaDB nodes.

| Option | Description |
| - | - |
| `--name`/`-n` | Config name (required) |
| `--destination`/`-d` | Local destination path (required) |
| `--nodes`/`-N` | Node name or id to collect from. Repeatable. Defaults to all nodes |
| `--remote-destination`/`-r` | Remote staging directory on each node. Default: `/tmp/regatta-collect` |


# Creating & Managing Configs
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/configuration/creating-and-managing-configs

Commands for creating, editing, validating, and sharing RDT configs.

This page covers the `rdt config` subcommands. See
[Configuration Overview](./overview.mdx) for the JSON schema these commands read and write.

## Create a config

```bash theme={null}
rdt config create --name <name> [options]
```

| Option | Description |
| - | - |
| `--name`/`-n` | Config name (required) |
| `--from`/`-f` | Start from a packaged template (`small` or `xsmall`). Cannot be combined with `--nodes` |
| `--nodes`/`-no` | Generate a config with this many nodes instead of using a template |
| `--ip-file`/`-ipf` | A file containing node IP addresses |
| `--ip-list`/`-ips` | A comma-separated list of node IP addresses (e.g. `10.0.0.1,10.0.0.2`) |
| `--probe-nodes`/`-p` | Connect to each node over SSH to detect its CPU, RAM, and devices |
| `--output`/`-o` | Write the config to a local file instead of `~/.rdt/configs/` (it won't show up in `rdt config list`) |
| `--force` | Recreate the config without prompting if a config by this name already exists |

You must choose either `--from` or `--nodes` (not both) to decide the module layout:

* `--from small` / `--from xsmall`: use one of the packaged templates (see
  [Configuration Overview](./overview.mdx#templates)).
* `--nodes <N>`: generate an N-node config yourself, following the same layout as the
  `small` template: node 1 gets all module types (SM, SNA, Sequencer, GDD, DCM, RDB),
  and every other node gets only SNA and RDB.

### Assigning node IPs

If you provide `--ip-file` or `--ip-list`, those addresses are assigned to the generated
nodes in order. If you provide neither, nodes default to `127.0.0.<node-id>`, fine for
local testing, but you'll need to edit the config afterward with real addresses.

`--ip-file` scans the file for anything that looks like an IPv4 address, so one per
line, comma-separated, or a mix of both all work:

```
10.0.0.1
10.0.0.2, 10.0.0.3
```

`--ip-list` is a simple comma-separated list and additionally accepts IPv6 addresses:

```bash theme={null}
rdt config create --name my-regattadb --from small --ip-list 10.0.0.1,10.0.0.2,10.0.0.3
```

### Examples

```bash theme={null}
# From a template, with real node IPs
rdt config create --name my-regattadb --from small --ip-list 10.0.0.1,10.0.0.2,10.0.0.3

# Generate a 4-node layout from an IP file, probing each node's hardware
rdt config create --name my-regattadb --ip-file ./ips.txt --nodes 4 --probe-nodes
```

## Print a config

```bash theme={null}
rdt config print --name <name> [--validate/--no-validate]
```

Prints the config as JSON. `--validate` (on by default) also prints a warning if the
config fails schema validation.

## Edit a config

```bash theme={null}
rdt config edit --name <name>
```

Opens the config in your `$EDITOR`. On save, it's re-validated; if it's invalid, you're
prompted to save anyway or discard the changes.

## List configs and templates

```bash theme={null}
rdt config list
```

Lists both the packaged templates and your saved configs (`~/.rdt/configs/`).

## Load a config from a file

```bash theme={null}
rdt config load --file <path> [--name <name>]
```

Imports an existing JSON file into `~/.rdt/configs/`. If `--name` is omitted, the config
is named after the file (its filename without the `.json` extension).

## Delete a config

```bash theme={null}
rdt config rm --name <name> [--force]
```

Deletes a saved config. Prompts for confirmation unless `--force` is given.

## Next steps

Once you have a config, continue to
[System Setup Overview](../system-setup/overview.mdx) to deploy RegattaDB from it.


# Configuration Overview
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/configuration/overview

The RDT configuration schema: the Cluster, Node, Device, and Module object types.

RDT describes a RegattaDB deployment with a single JSON configuration file, stored under
`~/.rdt/configs/<name>.json`. This page documents the schema. For the commands used to
create, edit, and manage these files, see
[Creating & Managing Configs](./creating-and-managing-configs.mdx).

## Deployment guidelines

Before designing a configuration, keep RegattaDB's general module placement guidelines
in mind:

* **SM**: exactly one per deployment.
* **SNA**: one per node that hosts at least one operational module (GDD, DCM, Sequencer, or RDB).
* **GDD**, **DCM**, **Sequencer**: exactly one per deployment.
* **RDB**: at least one per deployment; a node may host multiple RDB modules.

With that in mind, here's the JSON schema itself: the fields that make up the `Cluster`,
`Node`, `Device`, and `Module` objects in a config file.

## Cluster

| Field | Type | Description |
| - | - | - |
| `version` | `string` | Configuration schema version |
| `id` | `string/UUID/int` | Cluster identifier. Defaults to `"regatta-cluster"` |
| `nodes` | list of Node | The nodes that make up the deployment. Defaults to empty |

**Cluster-level validation:**

* Node `id` must be unique across the deployment.
* Exactly one instance each of SM, Sequencer, GDD, and DCM across the entire
  deployment (not per node).

## Node

| Field | Type | Description |
| - | - | - |
| `id` | `int` | Unique identifier within the deployment. Defaults to `1` |
| `name` | `string` | Node name. Defaults to `"regatta-node"` |
| `ip` | IP address | Address RDT uses to connect to the node |
| `num_threads` | `int `(optional) | Concurrency level for the node.<br />Leave unset to let the SM automatically set the value |
| `ram_MB` | `int `(optional) | RAM budget for the node, in megabytes. Leave unset to let the SM automatically set the value |
| `devices` | list of Device | Storage devices available on this node. Defaults to empty |
| `modules` | list of Module | Modules to run on this node. Defaults to empty |
| `config` | `object` | Arbitrary node config (e.g. probed hardware data). Defaults to empty |

**Node-level validation:**

* At most one instance each of SM, SNA, Sequencer, GDD, and DCM is allowed per node (mirrors
  the cluster-level rule).
* Module `id`s must be unique within the node.
* Every device name referenced by a module must exist in the node's `devices` list.
* Two modules on the same node cannot reference the same device.

## Device

| Field | Type | Description |
| - | - | - |
| `name` | `string` | Referenced by modules by this name |
| `path` | path | Path to the raw block device |
| `capacity` | `int `(optional) | Capacity in bytes |
| `config` | `object` | Arbitrary device config. Defaults to empty |
| `description` | `string `(optional) | Free-form description |

## Module

All modules share a common set of fields; each module type additionally has fixed
defaults for `id`, `port`, and `service_port`.

| Field | Type | Description |
| - | - | - |
| `type` | `string` | One of `sm`, `sna`, `sequencer`, `gdd`, `dcm`, `rdb` |
| `id` | `int` | Defaults to the type's standard id (see table below) |
| `name` | `string` | Auto-generated as `<type>_<id>` if not set |
| `port` | `int` | Communications port. Defaults to the type's standard port |
| `service_port` | `int` | Service port. Defaults to the type's standard service port |
| `num_threads` | `int `(optional) | Concurrency level for the module.<br />Leave unset to let the SM automatically set the value |
| `ram_MB` | `int `(optional) | RAM budget for the module, in megabytes. <br />Leave unset to let the SM automatically set the value |
| `devices` | list of strings | Names of devices (from the node) used by this module |
| `config` | `object` | Arbitrary module config, e.g. core binding (see below) |

### Module type defaults

| Type | Default id | Port | Service port |
| - | - | - | - |
| SM | 1 | 8840 | 5000 |
| SNA | 2 | 8841 | 5001 |
| Sequencer | 3 | 8842 | 5002 |
| GDD | 4 | 8843 | 5003 |
| DCM | 5 | 8844 | 5004 |
| RDB | 10 | 8850 | 6001 |

### Core binding

A module can be pinned to specific CPU cores via its `config`:

```json theme={null}
"config": {
  "core_binded_node": "0",
  "core_binded_cores": "0-5"
}
```

* `core_binded_node` is required whenever `core_binded_cores` is set.
* If `num_threads` is left unset, it's derived automatically from the core range.
* If `num_threads` is set, it must not exceed the number of cores in the range.

## Example

A minimal single-node config with one RDB storage device:

```json theme={null}
{
  "version": "26.0",
  "id": "my-regattadb",
  "nodes": [
    {
      "id": 1,
      "name": "node_1",
      "ip": "10.0.0.1",
      "devices": [
        { "name": "disk1", "path": "/dev/nvme0n1" }
      ],
      "modules": [
        { "type": "sm", "id": 1, "port": 8840, "service_port": 5000, "config": {}, "devices": [] },
        { "type": "sna", "id": 2, "port": 8841, "service_port": 5001, "config": {}, "devices": [] },
        { "type": "sequencer", "id": 3, "port": 8842, "service_port": 5002, "config": {}, "devices": [] },
        { "type": "gdd", "id": 4, "port": 8843, "service_port": 5003, "config": {}, "devices": [] },
        { "type": "dcm", "id": 5, "port": 8844, "service_port": 5004, "config": {}, "devices": [] },
        { "type": "rdb", "id": 10, "port": 8850, "service_port": 6001, "config": {}, "devices": ["disk1"] }
      ]
    }
  ]
}
```

See [Creating & Managing Configs](./creating-and-managing-configs.mdx) to learn how to generate,
edit, and validate files like this without hand-writing the JSON, and
[Config Recipes](../examples/config-recipes.mdx) for multi-node and probed-hardware examples.

## Templates

`rdt config create --from <template>` starts a config from a packaged template instead
of a blank one. Two templates ship with RDT today:

* **`xsmall`**: a single-node, all-in-one layout: one node running all module types
  (SM, SNA, Sequencer, GDD, DCM, RDB).
* **`small`**: a 3-node "classic" multi-node layout: `node_1` runs every module type
  (like `xsmall`), while `node_2` and `node_3` each run only SNA and RDB.

No devices or CPU/RAM values are specified in either template. Adjust these, the node
IPs, and the node count for your environment.

## Next steps

See [Creating & Managing Configs](./creating-and-managing-configs.mdx) for the commands
that create, edit, validate, and share these configuration files.


# Example: Collecting Debug Information
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/examples/collecting-debug-info

Practical RDT collect invocations for gathering RegattaDB diagnostics.

See [RegattaDB Lifecycle](../system-setup/lifecycle.mdx#collecting-debug-information)
for an overview of what `rdt collect` does. Run `rdt collect --help` at any time for the
full list of options.

## Collect from every node

```bash theme={null}
rdt collect --name my-regattadb --destination ./debug-output
```

## Collect from specific nodes only

By node name:

```bash theme={null}
rdt collect --name my-regattadb --destination ./debug-output --nodes node_1 --nodes node_2
```

By node id:

```bash theme={null}
rdt collect --name my-regattadb --destination ./debug-output --nodes 1
```

## Use a custom remote staging directory

By default, RDT stages collected files under `/tmp/regatta-collect` on each node before
pulling them to your destination. Override it if that path isn't writable or available:

```bash theme={null}
rdt collect --name my-regattadb --destination ./debug-output --remote-destination /data/tmp/regatta-collect
```


# Config Recipes
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/examples/config-recipes

Practical RDT config create recipes: probing hardware, IP files, and importing/exporting configs.

# Config Recipes

See [Creating & Managing Configs](../configuration/creating-and-managing-configs.mdx) for
the full set of `rdt config` options. This page is a set of practical recipes.

## Generate nodes from an IP file, without a template

```bash theme={null}
cat <<EOF > ips.txt
10.0.0.1
10.0.0.2
10.0.0.3
EOF

rdt config create --name my-regattadb --ip-file ips.txt --nodes 3
```

Node 1 gets every module type; nodes 2 and 3 get only SNA and RDB (the same layout as
the `small` template).

## Probe node hardware while creating a config

```bash theme={null}
rdt config create --name my-regattadb --from small \
  --ip-list 10.0.0.1,10.0.0.2,10.0.0.3 --probe-nodes
```

RDT connects to each node over SSH and detects its CPU thread count and RAM, leaving
those unset otherwise (the System Manager decides them at startup if you don't
probe or set them yourself).

Probing also looks for unmounted, unformatted block devices on each node and assigns any
it finds (above \~20GB) to that node's RDB module(s) automatically. If a node has no such
device attached, its RDB module still ends up with no device, and you'll need to add one
manually. See [Quickstart: Single-Node RegattaDB](./quickstart-single-node.mdx#3-create-a-config)
for the manual device-assignment steps.

## Save a config to a local file instead of the config store

```bash theme={null}
rdt config create --name draft --from xsmall --output ./draft-config.json
```

Useful for reviewing or version-controlling a config before importing it. A config
created this way with `--output` isn't saved to `~/.rdt/configs/`, so it won't appear in
`rdt config list` until you load it.

## Import an existing config file

```bash theme={null}
rdt config load --file ./draft-config.json --name my-regattadb
```

If you omit `--name`, the config is named after the file (its filename without the
`.json` extension).

## Export a config for sharing or version control

```bash theme={null}
rdt config print --name my-regattadb > my-regattadb.json
```


# Example: Multi-Node Deployment
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/examples/multi-node-deployment

Create a 3-node classic RegattaDB deployment with RDT.

This page walks you through deploying the "classic" multi-node topology: one node running all modules, and additional nodes running only SNA/RDB.

## 1. Create a config from the `small` template

```bash theme={null}
rdt config create --name prod-regattadb --from small \
  --ip-list 10.0.0.1,10.0.0.2,10.0.0.3
```

This gives you 3 nodes: `node_1` (SM, SNA, Sequencer, GDD, DCM, RDB) and `node_2`/`node_3`
(SNA, RDB only). See [Configuration Overview](../configuration/overview.mdx) for the full
layout.

## 2. Assign real storage devices

The template ships with no devices assigned, and every RDB module needs at least one.
Each node has its own RDB module, so you need a device entry per node. Edit the config
and add one to each node's `devices` list, then reference it from that node's RDB module:

```bash theme={null}
rdt config edit --name prod-regattadb
```

```json theme={null}
// node_1
"devices": [
  { "name": "disk1", "path": "/dev/nvme0n1" }
],
"modules": [
  { "type": "rdb", "id": 11, "devices": ["disk1"], ... }
]
```

```json theme={null}
// node_2
"devices": [
  { "name": "disk1", "path": "/dev/nvme0n1" }
],
"modules": [
  { "type": "rdb", "id": 21, "devices": ["disk1"], ... }
]
```

```json theme={null}
// node_3
"devices": [
  { "name": "disk1", "path": "/dev/nvme0n1" }
],
"modules": [
  { "type": "rdb", "id": 31, "devices": ["disk1"], ... }
]
```

Device names only need to be unique within a node, so reusing `disk1` on every node is
fine as long as it points to that node's own local device. See the full config file in
the [appendix](#appendix-full-config-file) below.

## 3. Probe node hardware (optional)

Instead of hand-editing CPU/RAM/device info, you can have RDT connect to each node and
detect it for you when creating the config:

```bash theme={null}
rdt config create --name prod-regattadb --from small \
  --ip-list 10.0.0.1,10.0.0.2,10.0.0.3 --probe-nodes
```

## 4. Create and start RegattaDB

```bash theme={null}
rdt create-cluster --name prod-regattadb --src /path/to/regatta-rpms --clean-install
```

`--src` points to a directory containing the Regatta RPMs. `--clean-install` removes any
previous installation on the nodes first, useful when reusing nodes from an earlier
deployment.

## Appendix: full config file

```json expandable theme={null}
{
  "version": "26.0",
  "id": "prod-regattadb",
  "nodes": [
    {
      "id": 1,
      "name": "node_1",
      "ip": "10.0.0.1",
      "devices": [
        { "name": "disk1", "path": "/dev/nvme0n1" }
      ],
      "modules": [
        { "type": "sna", "id": 10, "port": 8841, "service_port": 5001, "config": {}, "devices": [] },
        { "type": "rdb", "id": 11, "port": 8850, "service_port": 6001, "config": {}, "devices": ["disk1"] },
        { "type": "sm", "id": 1, "port": 8840, "service_port": 5000, "config": {}, "devices": [] },
        { "type": "sequencer", "id": 3, "port": 8842, "service_port": 5002, "config": {}, "devices": [] },
        { "type": "gdd", "id": 4, "port": 8843, "service_port": 5003, "config": {}, "devices": [] },
        { "type": "dcm", "id": 5, "port": 8844, "service_port": 5004, "config": {}, "devices": [] }
      ]
    },
    {
      "id": 2,
      "name": "node_2",
      "ip": "10.0.0.2",
      "devices": [
        { "name": "disk1", "path": "/dev/nvme0n1" }
      ],
      "modules": [
        { "type": "sna", "id": 20, "port": 8841, "service_port": 5001, "config": {}, "devices": [] },
        { "type": "rdb", "id": 21, "port": 8850, "service_port": 6001, "config": {}, "devices": ["disk1"] }
      ]
    },
    {
      "id": 3,
      "name": "node_3",
      "ip": "10.0.0.3",
      "devices": [
        { "name": "disk1", "path": "/dev/nvme0n1" }
      ],
      "modules": [
        { "type": "sna", "id": 30, "port": 8841, "service_port": 5001, "config": {}, "devices": [] },
        { "type": "rdb", "id": 31, "port": 8850, "service_port": 6001, "config": {}, "devices": ["disk1"] }
      ]
    }
  ]
}
```

## Next steps

* [Config Recipes](./config-recipes.mdx) for more `config create` options.
* [System Setup Overview](../system-setup/overview.mdx) to understand what happens on
  each node during this step.


# Quickstart: Single-Node RegattaDB
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/examples/quickstart-single-node

Install RDT and stand up a single-node RegattaDB deployment end to end.

This page walks you through creating a single-node RegattaDB deployment from scratch. Make sure you've read
[Prerequisites](../prerequisites.mdx) first: you'll need SSH access (key or password)
from your control node to the node you're deploying to.

## 1. Install RDT

```bash theme={null}
sudo dnf -y install regatta-rdt-<version>.el8.x86_64.rpm
```

See [Installation](../installation.mdx) for other install paths.

## 2. Set up SSH access

RDT connects to your node over SSH using either a key or a password. If your SSH user,
key, or password aren't already set up as RDT's defaults, pass them explicitly on every
command:

```bash theme={null}
rdt --user regatta --key ~/.ssh/id_rsa <command> ...
```

See [Global Options & Credentials](../advanced/global-options-and-credentials.mdx) for
all connection options; the rest of this walkthrough omits them for brevity.

## 3. Create a config

```bash theme={null}
rdt config create --name quickstart --from xsmall --ip-list 10.0.0.1
```

This uses the `xsmall` template: a single node running every module type. Replace
`10.0.0.1` with your node's real address.

The template doesn't specify storage devices, and every RDB module needs at least one.
Edit the config and add one before deploying:

```bash theme={null}
rdt config edit --name quickstart
```

```json theme={null}
"devices": [
  { "name": "disk1", "path": "/dev/nvme0n1" }
],
"modules": [
  { "type": "rdb", "id": 11, "devices": ["disk1"], ... }
]
```

Everything else (CPU thread count, RAM) can be left unset, the System Manager decides
those automatically, and storage devices can be auto-detected instead of hand-edited;
see the next step.

Review the result:

```bash theme={null}
rdt config print --name quickstart --validate
```

See [Configuration Overview](../configuration/overview.mdx) for the full schema.

## 4. Probe node hardware (optional)

Instead of hand-editing CPU/RAM/device info, you can have RDT connect to the node and
detect it for you when creating the config:

```bash theme={null}
rdt config create --name quickstart --from xsmall --ip-list 10.0.0.1 --probe-nodes
```

RDT looks for unmounted, unformatted block devices on the node and assigns any it finds
(above \~20GB) to the RDB module automatically. If the node has no such device attached,
you'll still need to add one manually as shown in step 3.

## 5. Create and start RegattaDB

```bash theme={null}
rdt create-cluster --name quickstart --src /path/to/regatta-rpms
```

`--src` points to a directory containing the Regatta RPMs (a `.tar.zst` archive also
works; see [RegattaDB Lifecycle](../system-setup/lifecycle.mdx)).

If something goes wrong partway through, see
[RegattaDB Lifecycle](../system-setup/lifecycle.mdx) for how to retry individual
steps, and [Collecting Debug Information](./collecting-debug-info.mdx) if you need to
gather logs.

## 6. Verify and connect

Once `create-cluster` finishes, connect to RegattaDB to confirm it's up and start
running SQL.

### Connection parameters

* **Username**: `admin`
* **Password**: `RegattaDefault1234!` (the default admin credentials; change this
  immediately after deployment)
* **URL**: `10.0.0.1:8840` (your node's IP and the SM's default communication port)

### Connect with the RegattaDB CLI

```bash theme={null}
/opt/regatta/<major.minor>/clients/cli/bin/client_cli
```

```
rdb>\connect user=admin pass=RegattaDefault1234! url=10.0.0.1:8840
```

If the connection succeeds:

```
Successfully connected to RegattaDB system
```

See [Connecting Applications to Regatta](/drivers-and-clients/connecting-applications-to-regatta)
to connect from your own application instead.

### Confirm the system is active

```sql theme={null}
regatta > MANAGE SYSTEM SHOW;
statement executed successfully
| STATE  |
----------
| Active |
```

A healthy single-node deployment reports `Active`. See
[System States and Commands](https://docs.regatta.dev/sql/system-management/system-states-and-commands#system-show)
for what each state means.

## Next steps

* [Multi-Node Deployment](./multi-node-deployment.mdx) for a realistic production topology.
* [Config Recipes](./config-recipes.mdx) for hardware probing and other config shortcuts.

## Appendix: full config file

```json expandable theme={null}
{
  "version": "26.0",
  "id": "quickstart",
  "nodes": [
    {
      "id": 1,
      "name": "node_1",
      "ip": "10.0.0.1",
      "devices": [
        { "name": "disk1", "path": "/dev/nvme0n1" }
      ],
      "modules": [
        { "type": "sna", "id": 10, "port": 8841, "service_port": 5001, "config": {}, "devices": [] },
        { "type": "rdb", "id": 11, "port": 8850, "service_port": 6001, "config": {}, "devices": ["disk1"] },
        { "type": "sm", "id": 1, "port": 8840, "service_port": 5000, "config": {}, "devices": [] },
        { "type": "sequencer", "id": 3, "port": 8842, "service_port": 5002, "config": {}, "devices": [] },
        { "type": "gdd", "id": 4, "port": 8843, "service_port": 5003, "config": {}, "devices": [] },
        { "type": "dcm", "id": 5, "port": 8844, "service_port": 5004, "config": {}, "devices": [] }
      ]
    }
  ]
}
```


# Installation
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/installation

Install RDT on your control node via RPM or from source.

Make sure you've read [Prerequisites](./prerequisites.mdx) first. This page covers
installing RDT on your control node. If your control node has no internet access, see
[Offline Installation](./advanced/offline-installation.mdx) instead; if you'd rather run
RDT from a container image, see
[Running RDT in a Container](./advanced/running-rdt-in-a-container.mdx).

## Installing via the RDT RPM (recommended)

RDT is distributed as the `regatta-rdt` RPM, one of the utility packages in Regatta's
tools suite. It's installed like
any other RegattaDB RPM package, from the local `.rpm` file included in your RegattaDB
software package (see
[Prepare for Deployment](https://docs.regatta.dev/self-hosted-deployment/manual-deployment/prepare-for-deployment)
for how these packages are delivered):

```bash theme={null}
sudo dnf -y install regatta-rdt-<version>.el8.x86_64.rpm
```

During installation you'll be prompted to accept the Regatta EULA (or set `ACCEPT_EULA=1` for unattended installs; see [EULA Acceptance](https://docs.regatta.dev/self-hosted-deployment/manual-deployment/prepare-for-deployment#eula-acceptance)). By default, the RPM creates and installs for a `regatta` deployment user/group; to use a different one, set `REGATTA_USER`/`REGATTA_GROUP` (see [Deployment User](https://docs.regatta.dev/self-hosted-deployment/manual-deployment/prepare-for-deployment#deployment-user) for the naming rules).

Once installed, the RPM automatically installs RDT itself for the deployment user via
`pip install --user`, bundling the self-contained Regatta Python driver (`pyregatta`) so
no separate driver installation is needed.

### Manual install (skip or retry the automatic step)

To skip the automatic install and only unpack the files, set `AUTO_INSTALL=0` in the
install command:

```bash theme={null}
sudo AUTO_INSTALL=0 dnf -y install regatta-rdt-<version>.el8.x86_64.rpm
```

If the automatic install is skipped, or fails (for example on a node without network
access), the install log is written to `/var/log/regatta/rdt/install.log`. You can then
install (or reinstall) manually, as the deployment user:

```bash theme={null}
bash /opt/regatta/current/tools/rdt/install.sh --user
```

Any extra arguments are forwarded to `pip` (e.g. `--user`, `--break-system-packages`).

Because RDT is installed with `--user`, the `rdt` command lands in `~/.local/bin`. If
it's not on your `PATH`, add it as follows:

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
```

### Uninstalling

Removing the RPM uninstalls RDT automatically for the deployment user:

```bash theme={null}
sudo REGATTA_USER=<user> dnf -y remove regatta-rdt
```

Set `AUTO_INSTALL=0` in the remove command to skip this. You can also uninstall
manually at any time, as that user:

```bash theme={null}
bash /opt/regatta/current/tools/rdt/uninstall.sh
```

Note that uninstalling only removes RDT itself, not the bundled `pyregatta` driver; it
may be shared with other Regatta tools installed for the same user.

## Installing from source

```bash theme={null}
pip install .
```

Installing from source requires the `pyregatta` driver to be available separately (it's
only bundled automatically by the RPM install path above).

## Verifying the install

```bash theme={null}
rdt --version
```

## Next steps

Continue to [Configuration Overview](./configuration/overview.mdx) to create your first
RegattaDB configuration.


# Introduction
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/introduction

Easily automate RegattaDB deployment and management across multiple nodes.

<Note>
  This section assumes you're already familiar with the [RegattaDB software modules](/self-hosted-deployment/manual-deployment/regattadb-software-modules) (SM, SNA, GDD, DCM, Sequencer, RDB) and basic deployment concepts such as a **node** (a physical or virtual machine in your deployment) and a **module** (a RegattaDB component running on a node).
</Note>

**RDT** (**Regatta Deployment Tool**) is a command-line tool that automates deploying and managing a self-hosted RegattaDB deployment across one or more nodes. Instead of manually installing packages, configuring storage devices, and issuing SQL management commands on every node yourself (see [Manual Deployment](/self-hosted-deployment/manual-deployment/high-level-deployment-steps)), you describe your deployment once in a JSON config file and let RDT drive the whole rollout over SSH: distributing RPMs, installing and configuring modules, starting services, and bringing the database online.

## What RDT does for you

* **Describes your deployment as config**: nodes, storage devices, and modules (SM, SNA,
  SEQUENCER, GDD, DCM, RDB) all live in a single JSON file that RDT can generate,
  validate, and edit for you.
* **Connects to your nodes over SSH**, in parallel, so setting up a multi-node deployment
  doesn't mean repeating the same steps manually on every node.
* **Runs the full deployment pipeline in one command** (`create-cluster`), or step by
  step if you want more control: distribute RPMs, install packages, configure the node
  environment, start the System Manager and SNA, register everything with the System
  Manager, and start RegattaDB.
* **Manages RegattaDB's lifecycle** after deployment: starting and stopping services
  or RegattaDB itself, resetting its data, cleaning up an installation entirely, and
  collecting debug information from every node.
* **Probes node hardware** (CPU, RAM, NUMA topology, storage devices) over SSH so you
  don't have to hand-type it into your config.

## How this section is organized

* **[Prerequisites](/self-hosted-deployment/rdt/prerequisites)** and
  **[Installation](/self-hosted-deployment/rdt/installation)**: what your control node
  and RegattaDB nodes need, and how to install the RDT CLI.
* [**Command Reference**](/self-hosted-deployment/rdt/command-reference): every RDT command and option in one place, for quick lookup while you work.
* [**Configuration**](/self-hosted-deployment/rdt/configuration/overview): the JSON config schema, and the `rdt config` commands used to create, edit, validate, and share config files.
* [**System Setup**](/self-hosted-deployment/rdt/system-setup/overview): the setup pipeline RDT runs on your nodes, in order, and the commands that create, start, stop, reset, and clean a RegattaDB deployment.
* [**Examples**](/self-hosted-deployment/rdt/examples/quickstart-single-node): end-to-end walkthroughs, from a single-node QuickStart to a multi-node production topology.
* [**Advanced**](/self-hosted-deployment/rdt/advanced/global-options-and-credentials): SSH credentials and global options, running RDT from a container, installing offline, exactly what RDT changes on your nodes' operating systems, and the NUMA and core-binding details behind module placement.
* [**Troubleshooting**](/self-hosted-deployment/rdt/troubleshooting): common installation and storage issues, and how to resolve them.
* [**Release Notes**](/self-hosted-deployment/rdt/release-notes): changes, fixes, and known limitations for each RDT release.

## Next steps

New to RDT? Start with [Prerequisites](/self-hosted-deployment/rdt/prerequisites) and
[Installation](/self-hosted-deployment/rdt/installation), then follow the
[Quickstart: Single-Node RegattaDB](/self-hosted-deployment/rdt/examples/quickstart-single-node)
to deploy RegattaDB end to end.


# Prerequisites
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/prerequisites

What you need before installing and running RDT to deploy RegattaDB.

Deploying RegattaDB with RDT works with two kinds of machines: the **control node**, where you install and run the RDT CLI, and the **RegattaDB nodes** that RDT connects to and configures. Make sure both sides meet the requirements below before you start.

## Control node

* **Python 3.9 or later**, with `pip` available.
* **Network access to your Python package index** (PyPI or an internal mirror) for the
  online install path. If the control node has no network access, see
  [Offline Installation](./advanced/offline-installation.mdx) instead.
* **Docker** (or a compatible CLI such as Podman), only if you plan to run RDT from a
  provided container image instead of installing it directly. See
  [Running RDT in a Container](./advanced/running-rdt-in-a-container.mdx).

### Software dependencies

RDT depends on two different kinds of packages. You don't need to install either set
manually on a normal install; they're listed here so you can verify them ahead of time
on a minimal or hardened image.

**Python packages**, installed automatically by `pip` when you install RDT:

* `ansible`
* `ansible-runner`
* `pydantic`
* `pyregatta` (Regatta's Python driver; RDT bundles a self-contained build of it)
* `typer`
* `rich`

[**Regatta client dependencies**](/drivers-and-clients/client-lib): must already be present on the control node's OS. These are required by the bundled `pyregatta` driver, which embeds a compiled client library.

## RegattaDB nodes

These nodes must meet RegattaDB's general
[self-hosted deployment prerequisites](https://docs.regatta.dev/self-hosted-deployment/prerequisites)
(OS, architecture, system packages, hardware, and connectivity). RDT adds the following
requirements on top of those, specific to how it connects to and configures nodes:

* **SSH access** from the control node to every node, using either:
  * A key pair (recommended; see `--key`/`-k` in
    [Global Options & Credentials](./advanced/global-options-and-credentials.mdx)), or
  * A shared username/password (`--ask-password` or `--password`).
* `sudo `**access** for the SSH user on every node: installing packages, writing `udev` rules, and managing `systemd` services all require root privileges. Passwordless `sudo` is preferred; a `sudo` password also works, since RDT reuses the SSH password you provide to answer the `sudo` prompt automatically.

## Choosing an installation path

* Nodes with internet access: follow [Installation](./installation.mdx) (RPM or `pip install`).
* Air-gapped nodes: follow [Offline Installation](./advanced/offline-installation.mdx).
* Running RDT itself from a container instead of installing it: follow
  [Running RDT in a Container](./advanced/running-rdt-in-a-container.mdx).

Once prerequisites are met, continue to [Installation](./installation.mdx).


# Release Notes
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/release-notes

Changes, fixes, and known limitations for each RDT release.

## \[26.1.4] - 2026-07-28

* Deployment always uses the `regatta`/`regatta` user and group on managed nodes; there's no support for a custom user/group for RDT-managed files.
* `configure`, `start-cluster`, and `stop-cluster` connect to the System Manager using Regatta's default database credentials for cluster management commands; these aren't currently configurable.
* Known issue: Python 3.12 doesn't currently allow using RDT; downgrade to a lower version (3.9 recommended).


# RegattaDB Lifecycle
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/system-setup/lifecycle

Commands for creating, starting, stopping, resetting, and cleaning a RegattaDB deployment.

These commands run the sequence of steps described in
[System Setup Overview](./overview.mdx). Each one takes `--name <config>` to select which
[config](../configuration/overview.mdx) to act on.

## Deploying RegattaDB

### One-step

```bash theme={null}
rdt create-cluster --name <config> --src <path/to/rpms> [--clean-install]
```

`--src` accepts either a `.tar.zst` archive or a directory containing Regatta RPMs.
`--clean-install` removes any previous installation on the nodes before reinstalling.

### Step-by-step

```bash theme={null}
rdt distribute --name <config> --src <path/to/rpms>
rdt setup --name <config> [--clean-install]
rdt start-services --name <config>
rdt configure --name <config>
rdt start-cluster --name <config>
```

This runs the same sequence as `create-cluster`, one step at a time. Useful if you want
to inspect or troubleshoot a specific stage.

A few things worth knowing:

* Management commands take effect on the System Manager as soon as they're issued.
  There's no transactional rollback. If `configure` fails partway through (for example,
  a node can't be reached), whatever was already applied before the failure stays applied.
* After `start-cluster`, if some modules didn't reach an active state, RDT prints them as
  a warning rather than failing outright. Check the warning and investigate those
  modules before considering RegattaDB ready.

## Starting and stopping

There are two independent layers you can start or stop:

* **`start-services`/`stop-services`**: starts or stops the System Manager and SNA as
  node-level services. This doesn't affect whether the database modules themselves are
  running.
* `start-cluster`**/**`stop-cluster`: tells the System Manager to start or stop the operational modules (RDB, GDD, DCM, Sequencer), bringing the database up or down. Under the hood these issue the `MANAGE SYSTEM START` and `MANAGE SYSTEM SHUTDOWN` management commands (see the [System States and Commands](https://docs.regatta.dev/sql/system-management/system-states-and-commands)).

```bash theme={null}
rdt stop-cluster --name <config>
rdt start-cluster --name <config>
```

## Resetting RegattaDB

```bash theme={null}
rdt reset --name <config>
```

Stops services, clears all RegattaDB data, and restarts services, but it does **not**
automatically reconfigure or restart the database afterward. Run `configure` and
`start-cluster` again once `reset` finishes:

```bash theme={null}
rdt reset --name <config>
rdt configure --name <config>
rdt start-cluster --name <config>
```

## Cleaning up

```bash theme={null}
rdt clean --name <config>
```

Removes Regatta's installation, files, logs, and traces from every node. If RDT itself
is installed on a given node, `clean` preserves RDT and its own logs on that node while
removing everything else; if RDT isn't installed there, the node is wiped completely.

## Collecting debug information

```bash theme={null}
rdt collect --name <config> --destination <path> [--nodes <node>...] [--remote-destination <path>]
```

Collects logs and diagnostics from RegattaDB nodes into a local directory. Use `--nodes`
(repeatable, by node name or id) to limit collection to specific nodes; omit it to
collect from all nodes. `--remote-destination` controls the staging directory used on
each node (defaults to `/tmp/regatta-collect`). Run `rdt collect --help` for the full
list of options for this command.

This command wraps the standalone `regatta-collect` tool that runs on each node. See
that tool's own documentation for its full set of options and additional examples.

## Next steps

See [Examples](../examples/quickstart-single-node.mdx) for end-to-end walkthroughs.


# System Setup Overview
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/system-setup/overview

What RDT does to your nodes, in order, when you set up or deploy RegattaDB.

Once you have a [config](../configuration/overview.mdx), RDT sets up your nodes in a
fixed sequence of steps. This page explains what happens, in order, so you know what to
expect on your machines. For the actual commands, see
[RegattaDB Lifecycle](./lifecycle.mdx).

## The setup pipeline

<Steps>
  <Step title="Distribute RPMs">
    Copy the RPM bundle to every target node.
  </Step>

  <Step title="Remove previous installation (optional)">
    Only when running with `--clean-install`. Skip otherwise.
  </Step>

  <Step title="Install module RPMs">
    Install the distributed module packages.
  </Step>

  <Step title="Configure node environment">
    Apply per-node environment settings.
  </Step>

  <Step title="Generate module configs">
    Render configuration files for each module.
  </Step>

  <Step title="Start SM & SNA services">
    Bring the management services online.
  </Step>

  <Step title="Configure RegattaDB">
    Register nodes, modules and devices with the System Manager.
  </Step>

  <Step title="Start RegattaDB">
    Start the database and verify the system is healthy.
  </Step>
</Steps>

## What each step does

1. **Distribute RPMs**: distributes Regatta RPM packages to every node.
2. **Stop Regatta services**: stops any currently running Regatta services before making changes.
3. **Remove previous installation** (only with `--clean-install`): wipes prior state
   before reinstalling. See [What Changes on Your Nodes](../advanced/node-system-changes.mdx)
   for exactly what is removed and what is preserved.
4. **Install module RPMs**: installs only the packages for the modules you've actually
   configured on that node (e.g. a node with only SNA and RDB doesn't get the SM package).
5. **Configure node environment**: prepares storage devices and performance tuning for
   the modules on that node. See
   [What Changes on Your Nodes](../advanced/node-system-changes.mdx) for the full details
   (device ownership, filesystem setup, performance tuning).
6. **Generate module configs**: writes each module's configuration file from your
   RegattaDB config.
7. **Start SM & SNA services**: starts the System Manager and SNA as node-level
   services and enables them to start on boot. Other module types (RDB, GDD, DCM,
   Sequencer) aren't node-level services; they're started by the System Manager itself
   in the next two steps.
8. **Configure RegattaDB**: connects to the running System Manager and registers your
   nodes, storage devices, and modules with it.
9. **Start RegattaDB**: tells the System Manager to start every configured module,
   bringing the database online.

## Next steps

Continue to [RegattaDB Lifecycle](./lifecycle.mdx) for the commands that run this
pipeline (`setup`, `create-cluster`, and friends).


# Troubleshooting
Source: https://docs.regatta.dev/self-hosted-deployment/rdt/troubleshooting

Diagnose common issues when installing and running RDT.

Start by re-running the failing command with `--verbose` for more detail. If you need to
gather logs from every node to investigate further, see
[Collecting Debug Information](./examples/collecting-debug-info.mdx).

## `rdt` command not found after installing

The RPM installs RDT for the deployment user with `pip install --user`, which places
the `rdt` command under `~/.local/bin`. That directory isn't always on `PATH` by
default.

**Solution:** add it to your `PATH`:

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
```

Add this to your shell profile (e.g. `~/.bashrc`) to make it permanent. See
[Installation](./installation.mdx) for other install paths and details.

## SSH connection or authentication failures

A node-level command (`distribute`, `setup`, `start-services`, `collect`, `clean`,
`reset`, etc.) hangs or fails with a connection or authentication error.

Every node-level operation connects over SSH using the credentials from
[Global Options & Credentials](./advanced/global-options-and-credentials.mdx)
(`--user`/`--key`/`--password`/`--ask-password`), and needs `sudo` access on the node
once connected; see [Prerequisites](./prerequisites.mdx).

**Solution:** verify you can connect manually with the same credentials
(`ssh -i <key> <user>@<node>`), confirm the SSH user has passwordless (or password)
`sudo` access on the node, and pass `--user`/`--key` or `--ask-password` explicitly if
your local SSH defaults differ from RDT's.

## RDB module fails to start because its storage device isn't accessible

The RDB module fails to boot, and its error log shows it couldn't open its storage
device. `ls -la` on the device shows it's still owned by `root:disk` instead of
`regatta:regatta`.

As described in [What Changes on Your Nodes](./advanced/node-system-changes.mdx#storage--device-setup),
RDT changes ownership of every storage device referenced by an RDB module to
`regatta:regatta` via a `udev` rule. If the path you reference in your config is a
symbolic link (for example a device-mapper or multipath alias under `/dev/mapper/`)
rather than the underlying device node itself (for example `/dev/dm-*`), ownership needs
to end up on the real device the link resolves to, not just the link.

**Solution:** resolve the link and fix ownership on both the link and its target:

```bash theme={null}
readlink -f <your-device-path>
chown regatta:regatta <your-device-path> <resolved-target-path>
```

Prefer referencing the resolved device path directly in your config instead of a
symlink, so RDT's ownership change reliably applies to the actual device.

## `setup` warns that `jemalloc` wasn't found

As described in [What Changes on Your Nodes](./advanced/node-system-changes.mdx#performance-tuning-jemalloc),
`setup` looks for `libjemalloc` on the node (under `/usr/lib64`, then as a fallback via
the system's shared library cache) to wire it in as `LD_PRELOAD` for the SM and SNA
module environments. This warning is expected and doesn't block deployment; it's a
performance optimization, not a requirement.

**Solution:** none needed. If you want the performance benefit, install `libjemalloc`
on the node and re-run `setup`.

## Cluster stays down after `reset`

`reset` stops services, clears all RegattaDB data, and restarts services, but it does
**not** automatically reconfigure or restart the database afterward: it leaves you at
the same point as right after `start-services`, with nothing configured or started yet.

**Solution:** run `configure` and `start-cluster` again once `reset` finishes:

```bash theme={null}
rdt configure --name <config>
rdt start-cluster --name <config>
```

See [RegattaDB Lifecycle](./system-setup/lifecycle.mdx#resetting-regattadb) for the full
sequence.


# Database Limitations
Source: https://docs.regatta.dev/sql/appendices/database-limitations



The following are limitations of the current release.

| Limit | Value |
| :- | :- |
| #Tables per DB | 10,000 |
| #Columns per table | 1,024 |
| #Indexes per table | 1,024 |
| Max row length | 1,007,000 bytes |
| Max SQL statement length | 2,097,152 bytes |
| Max `VARCHAR` size | 102,400 chars |
| Max `CHAR` size | 255 chars |
| Max `CHAR`/`VARCHAR` index column size | 239 bytes |
| Max `NUMERIC` index column precision | 464 |


# Identifiers Limitations
Source: https://docs.regatta.dev/sql/appendices/indentifiers-limitations



Identifiers should adhere to the following restrictions:

1. All identifiers except for user name and index name should be between 1 and up to 127 characters long.
2. User names should be between 1 and up to 64 characters long.
3. Index names should be between 1 and up to 264 characters long.
4. Begin with a letter (a-z or A-Z) or an underscore (\_).
5. Subsequent characters can be letters, underscores, digits (0-9), or dollar signs (\$).
6. Unsupported characters or reserved words are permitted only if they are surrounded by double quotes. An exception to that rule is that a reserved word can be used as a user\_name (because user names are not used as part of SQL statements).
7. Names are case-sensitive. However, unquoted names are always converted to lowercase, and quoted names preserve the case and also allow spaces within the names.

   For example: CAMEL, Camel, camel and "camel" all refer to the same name (camel). On the other hand, "CAMEL", "Camel" and "camel" refer to three different names.


# Reserved Words
Source: https://docs.regatta.dev/sql/appendices/reserved-words



Other than the keyword `ROWID` which is added by Regatta, all other Regatta’s reserved words match
PostgreSQL's list of reserved words.

Please see PostgreSQL documentation, chapter [Appendix C. SQL Key Words](https://www.postgresql.org/docs/current/sql-keywords-appendix.html)

These words should not be used as identifiers, unless they are surrounded by double quotes.


# Boolean types
Source: https://docs.regatta.dev/sql/data-types/boolean-types



| Data type | Alias | Size | Ranges |
| :- | :- | :- | :- |
| `BOOLEAN` | `BOOL` | 1 byte | TRUE or FALSE |


# Character types
Source: https://docs.regatta.dev/sql/data-types/character-types



| Data type | Alias | Description |
| :- | :- | :- |
| `CHAR(n)` | `CHARACTER(n)` | Fixed size character string of size n. See [Database Limitations](/sql/appendices/database-limitations). |
| `VARCHAR[(n)]` | `CHARACTER VARYING [(n)]`, `TEXT` | variable-length with optional limit (n).<br /> If n isn’t specified, the maximum is used. See [Database Limitations](/sql/appendices/database-limitations). |

Notes

* Only ASCII characters are supported, 1 char = 1 byte.

* Character type literals should be surrounded by single quotes. Those must be the basic ASCII character 39 ('). Other variants, such as the left single-quote and right single-quote ASCII characters 145-146 (‘like this’), are not supported and would result in an error.


# Date/Time types
Source: https://docs.regatta.dev/sql/data-types/date-time-types



| Data type | Size | Ranges | Resolution | Description |
| :- | :- | :- | :- | :- |
| `TIME [(p)]` | 8 bytes | 00:00:00.000000 to 24:00:00.000000 | Between seconds and microseconds | Time of day |
| `DATE` | 8 bytes | 294240 BC to 294240 AD | days | Date |
| `TIMESTAMP [(p)]` | 8 bytes | 294240 BC to 294240 AD | Between seconds and microseconds | Date and time |

`p` is an optional precision value to specify the number of fractional digits retained in the seconds field. Range of `p` is from 0 to 6. Default is 6.

All these types do not include time zone information.

See relevant information on DATE/TIME formats in [Date and Time Formatting Functions.](/sql/sql-functions-and-operators/date-time-functions-operators)


# Introduction
Source: https://docs.regatta.dev/sql/data-types/introduction



This section lists all the data types supported by Regatta.


# Approximate numeric data type
Source: https://docs.regatta.dev/sql/data-types/numeric-types/approximate-numeric-data-type



| Data type | Alias | Size | Range |
| :- | :- | :- | :- |
| `REAL` | `FLOAT4` | 4 bytes | 6 decimal digits precision |
| `DOUBLE PRECISION` | `DOUBLE`, <br /> `FLOAT8`, <br /> `FLOAT [(p)]` | 8 bytes | 15 decimal digits precision |

You can choose to use the data type `FLOAT(p)`. When it is being used, the optional `p` specifies the minimum acceptable precision in binary digits and it can range between 1 to 53. `FLOAT(1)` to `FLOAT(24)` as selecting the `REAL` type, while `FLOAT(25)` to `FLOAT(53)` select `DOUBLE PRECISION`. A value of `p` outside the allowed range results in an error. The default value is 53 (maximum precision).


# Exact numeric data type
Source: https://docs.regatta.dev/sql/data-types/numeric-types/exact-numeric-data-type



| Data type | Aliases | Size | Range |
| :- | :- | :- | :- |
| `SMALLINT` | `INT2` | 2 bytes | -32768 to +32767 |
| `INT` | `INTEGER`, <br /> `INT4` | 4 bytes | -2147483648 to +2147483647 |
| `BIGINT` | `INT8` | 8 bytes | -9223372036854775808 to <br /> +9223372036854775807 |
| `NUMERIC` \[`(p,s)`] | `DECIMAL` \[`(p,s)`], `DEC` \[`(p,s)`] | variable | Exact numeric of selectable precision. <br /> Boundaries depend on whether or not (p,s) were specified.<br />See notes below. |

Notes:

* The types `SMALLINT`, `INTEGER`, and `BIGINT` store integrals, that is, numbers without fractional components, of various ranges. Attempts to store values outside of the allowed range will result in an error.
* Numeric:
  * The precision (p) is the maximum number of significant digits in the whole number (that is, the number of digits to both sides of the decimal point).
  * `NUMERIC` precision (p) must be between 1 and 1000.
  * The scale (s) is the maximum number of digits to the right of the decimal point.
  * `NUMERIC` scale (s) must be between 0 and 1000.
  * If `p` and `s` are not specified, the column can contain up to 131072 digits before the decimal point, and up to 16383 digits after the decimal point.
  * If only `p` is specified, then the `s` is zero.


# ROW IDs
Source: https://docs.regatta.dev/sql/data-types/row-ids



Every row in every table is automatically assigned a row identifier. Row IDs are 64-bit unsigned integers. Each row has a row ID unique within the containing table. The ID of a row is constant and never changes. The row ID is not part of the table’s schema, and is not considered to be a column of the table. However, it can be queried and used within SQL commands as described below.

Row IDs can be returned from queries instead of table columns or expressions. For example: `SELECT ROWID FROM my_table`. See the [SELECT](/sql/dql/select) command for more details.

Row IDs can also be used in the `WHERE` clause of commands.

Row IDs of the affected rows are returned by the `INSERT`, `UPDATE` and `DELETE` commands if the `RETURNING ROWID` clause is specified.


# Type Conversion
Source: https://docs.regatta.dev/sql/data-types/type-conversion/type-conversion



Type conversion can happen in the following cases:

1. When mixing different data types while combining two result sets with `UNION`.
2. When passing to functions and operators, operands of different types than their input operand types.
3. When assigning values of different types to table row cells.

In these cases, either Regatta implicitly converts them into a data type that allows the operation to continue, or they can be explicitly converted into the desired data type using the general [Convert Function](/sql/sql-functions-and-operators/convert-function) or the type-specific conversion functions listed in the table below.

The following rules apply to type conversions:

1. When combining queries (`UNION` \[`ALL`]), Regatta converts the data types of both queries to the “larger” data type of them.

   E.g: During `UNION` on two queries, if the first returns `DATE` and the other returns `TIMESTAMP`, Regatta converts the `DATE` into `TIMESTAMP`.
2. When converting strings to other data types, the conversion fails if the string is not a valid representation of the value of the target type.

   For example, conversion of '3' to Integer would succeed but conversion of 'ttt' or '3.1' to integer would fail.
3. When converting from `FLOAT4/8` or `DECIMAL` to integers, the value is rounded to the closest integer.
4. During `INSERT` and `UPDATE` operations, Regatta converts the value to the datatype of the affected column. If the value is too large for the target data type, the operation fails.
5. Conversion from `TIMESTAMP` to `DATE` or `TIME` extracts the relevant part of the `TIMESTAMP` into the target element.

   E.g: `SELECT '2023-12-12 23:00:05'::time` returns `23:00:05`.
6. When converting integral types to `BOOLEAN`, `0` is converted to `FALSE` and any other value is converted to `TRUE`.
7. Any conversion (explicit or implicit) to a numeric type (integers, floating point and decimals) would fail if the value cannot fit within the range of the target type.

   For example, `SELECT 1234567::SMALLINT` will fail since the value is out of the `SMALLINT` range.
8. Explicit conversion to [Character types](/sql/data-types/character-types) trims the converted string to fit the size of the target type, however, implicit conversion would not trim the text and would result in an error.

   For example: `CAST(150 as CHAR(2))` returns `15` but assigning `150` to a `CHAR(2)` column without explicit casting would fail.
9. `CHAR` types are implicitly converted to `VARCHAR` (and the trailing spaces are trimmed) when they are used as inputs to any function/operation.

   For example: Comparison of `VARCHAR(10)` containing the value `‘Regatta’` and `CHAR(10)` containing the value `‘Regatta   ’` results in `TRUE`.

   Note: If the `VARCHAR` contains trailing spaces as part of its string, the comparison will return `FALSE`. For example: `CHAR(10)` with the text `'Regatta'` is not equal to `VARCHAR(10)` with the text `'Regatta '`.


# Type conversion table
Source: https://docs.regatta.dev/sql/data-types/type-conversion/type-conversion-table



| **Source type** | **Target type** | **Function (1)** | **Implicit?** |
| :- | :- | :- | :- |
| INT8 | INT4 | INT4 | In assignment |
| INT8 | INT2 | INT2 | In assignment |
| INT8 | DECIMAL | DECIMAL | yes |
| INT8 | FLOAT8 | FLOAT8 | yes |
| INT8 | FLOAT4 | FLOAT4 | yes |
| INT8 | BOOLEAN | BOOL | no |
| INT8 | VARCHAR | TEXT | In assignment |
| INT4 | INT8 | INT8 | yes |
| INT4 | INT2 | INT2 | In assignment |
| INT4 | DECIMAL | DECIMAL | yes |
| INT4 | FLOAT8 | FLOAT8 | yes |
| INT4 | FLOAT4 | FLOAT4 | yes |
| INT4 | BOOLEAN | BOOL | no |
| INT4 | VARCHAR | TEXT | In assignment |
| INT2 | INT8 | INT8 | yes |
| INT2 | INT4 | INT4 | yes |
| INT2 | DECIMAL | DECIMAL | yes |
| INT2 | FLOAT8 | FLOAT8 | yes |
| INT2 | FLOAT4 | FLOAT4 | yes |
| INT2 | BOOLEAN | BOOL | no |
| INT2 | VARCHAR | TEXT | In assignment |
| DECIMAL | INT8 | INT8 | In assignment |
| DECIMAL | INT4 | INT4 | In assignment |
| DECIMAL | INT2 | INT2 | In assignment |
| DECIMAL | DECIMAL | DECIMAL | yes |
| DECIMAL | FLOAT8 | FLOAT8 | yes |
| DECIMAL | FLOAT4 | FLOAT4 | yes |
| DECIMAL | VARCHAR | TEXT | In assignment |
| FLOAT8 | INT8 | INT8 | In assignment |
| FLOAT8 | INT4 | INT4 | In assignment |
| FLOAT8 | INT2 | INT2 | In assignment |
| FLOAT8 | DECIMAL | DECIMAL | In assignment |
| FLOAT8 | FLOAT4 | FLOAT4 | In assignment |
| FLOAT8 | VARCHAR | TEXT | In assignment |
| FLOAT4 | INT8 | INT8 | In assignment |
| FLOAT4 | INT4 | INT4 | In assignment |
| FLOAT4 | INT2 | INT2 | In assignment |
| FLOAT4 | DECIMAL | DECIMAL | In assignment |
| FLOAT4 | FLOAT8 | FLOAT8 | yes |
| FLOAT4 | VARCHAR | TEXT | In assignment |
| VARCHAR | CHARACTER | none (2) | yes |
| VARCHAR | VARCHAR | TEXT | yes |
| CHARACTER (3) | CHARACTER | BPCHAR | yes |
| CHARACTER | VARCHAR | TEXT | yes |
| BOOLEAN | INT8 | INT8 | no |
| BOOLEAN | INT4 | INT4 | no |
| BOOLEAN | INT2 | INT2 | no |
| BOOLEAN | VARCHAR | TEXT | In assignment |
| BOOLEAN | CHARACTER | none | In assignment |
| TIMESTAMP | VARCHAR | TEXT | In assignment |
| TIMESTAMP | DATE | DATE | In assignment |
| TIMESTAMP | TIME | TIME | In assignment |
| DATE | VARCHAR | TEXT | In assignment |
| DATE | TIMESTAMP | TIMESTAMP | yes |
| TIME | VARCHAR | TEXT | In assignment |
| UUID | VARCHAR | none | In assignment |
| UUID | CHARACTER | none | In assignment |
| VARCHAR | UUID | none | No |
| CHARACTER | UUID | none | No |

Notes:

(1) Function: The name of an explicit conversion function (e.g `SELECT FLOAT8(5.2)`)
(2) ‘none’ means there is no explicit conversion function for this case.
(3) Conversion from `CHAR(n)` to the `CHAR(m)` where `M != n`.


# UUID type
Source: https://docs.regatta.dev/sql/data-types/uuid-type



This data type stores Universally Unique Identifiers (UUID) as defined by [RFC 9562](https://datatracker.ietf.org/doc/html/rfc9562), ISO/IEC 9834-8:2005, and related standards. It is 128-bit in size that is generated by an algorithm chosen to make it very unlikely that the same value will be generated more than once using the same algorithm.

Regatta supports generating values using the UUID version 4 algorithm. Alternatively, UUID values can be generated outside Regatta using any algorithm and provided as values in INSERT and UPDATE commands. The data type UUID can be used to store any valid UUID value, regardless of the origin and the UUID version.

A UUID value returned from queries is a sequence of lower-case hexadecimal digits, in several groups separated by hyphens: a group of 8 digits followed by three groups of 4 digits followed by a group of 12 digits. For example: `a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11`

Regatta also accepts the following forms for input:

* Use of upper-case digits (`A-F`) or a mix of upper-case and lower-case digits.
* Surrounding the value with curly braces ( `{value}` )
* Omitting some or all of the hyphens, or adding a hyphen after any group of four digits. (In essence, hyphens are treated as “decoration” and are not part of the actual value.)

However, output is always in the standard form of 5 digit groups separated by hyphens, as specified above.

## Type Conversion Between UUID and String Types

If UUIDs are passed to string functions and operators, they must be explicitly converted to strings. Assignment of UUIDs to a string column implicitly converts the UUID to string.

If strings are passed to UUID functions or assigned to UUID columns, they must be explicitly converted to UUIDs.

When passing a string and a UUID to a comparison operator (e.g., ‘\<’), explicit cast is required on either of the parameters to inform Regatta according to which type the comparison should be performed.

A UUID literal is also a string literal, and therefore it can be passed to string functions and assigned to string columns.

When two UUID literals are passed to a comparison operator, they are compared as two string literals (because UUID literals and string literals are indistinguishable). If any of them is explicitly cast to UUID, the other is implicitly converted to UUID and a UUID comparison is performed. (It should be noted that extra hyphens - if exist in literals - don't impact UUID comparisons but do impact string comparisons.)

**Examples:**

```sql theme={null}
CREATE TABLE t (uuid_col uuid, varchar_col varchar);

-- UUID literals are indistinguishable from string literals
INSERT INTO t VALUES (‘019535d9-3df7-79fb-b466-fa907fa17f9e’, ‘019535d9-3df7-79fb-b466-fa907fa17f9e’); 

-- No implicit conversion on assignment from string to UUID
UPDATE t SET uuid_col = varchar_col; -- ERROR
UPDATE t SET uuid_col = varchar_col::uuid; -- OK

-- Implicit conversion on assignment from UUID to string
UPDATE t SET varchar_col = uuid_col; -- OK

-- No implicit conversion when passing UUID to a string function
SELECT uuid_extract_version(varchar_col) FROM t; -- ERROR
SELECT uuid_extract_version(varchar_col::uuid) FROM t; -- OK

-- No implicit conversion when passing a string to a UUID function
SELECT upper(uuid_col) FROM t; -- ERROR
SELECT upper(uuid_col::varchar) FROM t; -- OK

-- comparison between string and UUID requires explicit cast
SELECT 1 FROM t WHERE uuid_col = varchar_col; -- ERROR
SELECT 1 FROM t WHERE uuid_col::varchar = varchar_col; -- OK
SELECT 1 FROM t WHERE uuid_col = varchar_col::uuid; -- OK

-- comparison between literals:
SELECT '2feebc99-9c0b-4ef8-bf6c-6bb4de380ae5' = '2FEEBC99-9C0B-4EF8-BF6C-6BB4DE380AE5'; -- returns false
SELECT '2feebc99-9c0b-4ef8-bf6c-6bb4de380ae5' = '2FEEBC99-9C0B-4EF8-BF6C-6BB4DE380AE5'::uuid; -- returns true
```


# ALTER TABLE
Source: https://docs.regatta.dev/sql/ddl-commands/alter-table



Modify existing table definitions.

## Synopsis

```
ALTER TABLE table_name
  action [, ... ]

where action is one of:
  SET READY
  ADD [ COLUMN ] column_name data_type [ column_constraint [ ... ] ] [ INDEX [ index_parameters ] ]

where column_constraint is:
{ NULL |
  NOT NULL |
  DEFAULT default_expr |
  UNIQUE |
  PRIMARY KEY |
  REFERENCES reftable [ (refcolumn) ] }

and index_parameters is:
WITH ( storage_parameter [= value] [, ... ] )
```

## Description

`ALTER TABLE` changes the metadata definition of an existing table in the current database.

The table must be in the `NOT READY` state, otherwise the command results in an error. A table is in `NOT READY` state if it’s created with the `CREATE TABLE SET NOT READY` option, and until the `ALTER TABLE SET READY` command is performed on it.

## Parameters

`table_name`

The name of an existing table to alter.

### `action`

`SET READY`

This form finalizes the table’s schema and index set, and makes it accessible for DML operations. Any subsequent ALTER TABLE command will fail as the table transitions to the READY state.

`ADD [ COLUMN ]`

Adds a new column to the table, using the same syntax as in [CREATE TABLE](/sql/ddl-commands/create-table). The column name must be unique within the table and conform with the [Identifiers Limitations](/sql/appendices/indentifiers-limitations).

**`column_name`**

The name of the added column.

**`data_type`**

Data type of the new column. For more information on the supported data types, refer to [Data Types](/sql/data-types).

The rest of the parameters used in this command are described in the [CREATE TABLE](/sql/ddl-commands/create-table) command.

## Examples

***

**Create a table as not ready and alter it to modify its definition:**

```sql theme={null}
CREATE TABLE SET NOT READY parts WITH (devices = (m1d2, m2d5, m3d3));

ALTER TABLE parts
  ADD COLUMN p_partkey INT PRIMARY KEY INDEX WITH (devices = (m1d2)),
  ADD COLUMN p_name VARCHAR(40) NOT NULL UNIQUE INDEX
    WITH (devices = (m1d2, m2d5, m3d3), range_separators = ('j', 'p'));

ALTER TABLE parts
  ADD COLUMN p_date DATE NOT NULL ;

ALTER TABLE parts SET READY;
```

This example creates a table and builds it gradually with `ALTER TABLE` commands, and eventually finalizes it with `SET READY`.

Note that the `ALTER TABLE` command can only work as long as the parts table is defined as `NOT READY`.

## Compatibility

The `ALTER TABLE` command conforms to the SQL standard, with exceptions listed below.

1. `SET READY` is a Regatta extension
2. `WITH` clause is a Regatta extension; storage parameters are not in the standard.


# CREATE TABLE
Source: https://docs.regatta.dev/sql/ddl-commands/create-table



Define a new table.

## Synopsis

```
CREATE TABLE [ SET { READY | NOT READY } ]
  table_name ([
    { column_name data_type [ column_constraint [ ... ] ] [ INDEX [ index_parameters] ]}
    [, ... ]
  ])
[ WITH ( storage_parameter [= value] [, ... ] ] )

where column_constraint is:
{ NULL |
NOT NULL |
DEFAULT default_expr |
UNIQUE |
PRIMARY KEY |
REFERENCES reftable [ (refcolumn) ] }
and index_parameters is:
WITH ( storage_parameter [= value] [, ... ] )
```

## Description

The `CREATE TABLE` command is used to create a new empty table, with columns, indexes and constraints, in the current database.

Once created, unless set as `NOT READY`, the table’s definition is fixed and cannot be altered, additional indexes cannot be added or removed.

Index and constraint names are auto-generated by Regatta.

Note: If there is `UNIQUE`, `PRIMARY KEY` or `REFERENCES` constraints, then there must be an `INDEX` clause following it. Otherwise, there could be either zero or one `INDEX` clause. The `INDEX` clause must be after all the constraint clauses (if any).

## Parameters

### `SET READY`

Set the table as ready to accept Data Manipulation Language (DML) commands.

Once a table is set as ready, changes to its columns, constraints and indexes are not allowed. This is the default behavior.

### `SET NOT READY`

Set the table as not ready to accept DML commands, and allow further changes to its definition such as creating new indexes and adding new columns.

Note: A table with zero columns can be created as long as it’s set to `NOT READY`. At least one column is required in order to set its state to `READY`.

### `table_name`

The name of the table to be created.

The table name must not exist in the database, and conform with the [Identifiers Limitations](/sql/appendices/indentifiers-limitations).

### `column_name`

The name of the column to be created in the new table. Column names should be unique within the table and conform with the [Identifiers Limitations](/sql/appendices/indentifiers-limitations).

### `data_type`

The data type of the column. For more information on the supported data types, refer to [Data Types](/sql/data-types).

### `NULL`

The column is allowed to contain `NULL` values. This is the default.

### `NOT NULL`

The column is not allowed to contain `NULL` values.

### `DEFAULT default_expr`

An optional default value to set in the column level. If no default is specified then the default value is `NULL`. (Note that when the default value is `NULL` and `NOT NULL` constraint is specified, you cannot insert rows with the `DEFAULT` keyword.)

A possible default values are either a literal (e.g, `DEFAULT 'my default'` or `DEFAULT 1`) or a variable-free expression that returns a single value
(suitable to store in a single table cell) that is being evaluated at the time the row is created (e.g., `DEFAULT NOW()` for current date/timestamp (depends on the column data type)). Note that expressions which include other columns in the current table are not allowed.

### `UNIQUE`

The `UNIQUE` constraint specifies that the column can contain only unique values. The constraint therefore enforces that any two rows in the same table must differ in this column (note that Regatta is case-sensitive) (e.g., ‘**Regatta**’ \<> ’**REGATTA**’ \<> ‘**regatta**’).

Note: If the `UNIQUE` constraint is specified, the `NOT NULL` constraint is required.

Unique constraints implicitly create an index on that column, hence the index clause is required.

### `PRIMARY KEY`

The `PRIMARY KEY` constraint specifies this column can contain only unique, non-NULL values. Only one primary key can be specified for a table. Since `PRIMARY KEY` implies `UNIQUE` and `NOT NULL` – if any of the latter two is specified for the same column, it is ignored (as it is already implied by the `PRIMARY KEY` constraint).

<Note>
  *`Note: PostgreSQL allows specifying the combination of PRIMARY KEY with NULL constraint, but it ignores the latter and requires only non-NULL values. In Regatta, specifying this contradictory combination of constraints results in an error.`*
</Note>

A primary key constraint implicitly creates an index on the column, hence the index clause is required.

### `REFERENCES reftable [ refcolumn ] [ ON DELETE referential_action ] [ ON UPDATE referential_action ]`

This clause specifies a foreign key constraint and links data in that table column with another table
primary key. The referenced column must be the `PRIMARY KEY` constraint in the referenced table, in
the same database. With this constraint, a value inserted into the referencing column must match a row
in the referenced table. If **refcolumn** is omitted, the primary key column of the **reftable** is used.

Reference constraints implicitly create an index on that column, hence the index clause is required.

A foreign key column is allowed to be `NULL`. If it is `NULL`, the row is not required to have a match in the
referenced table.

Foreign key restrictions:

1. The referencing column and the reference column must be of the same data type, and have the same type parameters (e.g. a `VARCHAR(200)` column cannot reference a `VARCHAR(100)` column.)
2. A column cannot reference another column in the same table.
3. A column can only reference a primary key column
4. A column can reference at most one other column. In other words, a column cannot have more than one “foreign key” constraint.

ON `DELETE` this clause specifies the action to perform when a referenced row in the referenced table is being deleted.

ON `UPDATE` this clause specifies the action to perform when a referenced column in the referenced table is being updated to a new value in the referenced column.

`Referential_action`

**`RESTRICT`** The `DELETE/UPDATE` fails if the check identifies that a foreign key constraint is about to be violated.

Updating a referenced column is not allowed, and the explicit `RESTRICT` option is supported for compatibility reasons (but that's also the default behavior).

### `INDEX index_parameter`

This clause specifies that an index shall be created for the pertinent column.

The index column size should not exceed the index maximum column size. See [Database Limitations]()

This clause is required if `REFERENCES`, `UNIQUE` or `PRIMARY KEY` constraints are specified, and is optional otherwise.

### Storage parameters

Storage parameters, specified after the keyword `WITH`, are optional for both tables and indexes. Possible storage parameters:

### `devices`

A list of one or more device names, separated by commas, surrounded by parentheses. Device names shall be specified as they appear in the output of the [SHOW DEVICES](/sql/system-monitoring/system-catalog/show-devices). This parameter is required for both tables and indexes.

### **`range_separators`**

Specify key range separators for index segments.

If the number of devices (specified in the `devices` parameter) is 1, this parameter shall not be specified or shall be set to an empty list. If the number of devices is more than 1, this parameter is required and the number of values must be one less than the number of devices.

For example:

```
WITH (devices = (m1d2, m2d5, m3d3), range_separators = ('j', 'p'))
```

Notes:

1. The range separators must be literal constants that match the column data type, and cannot be `NULL`.
2. The list of values must be strictly monotonically increasing.
3. The specified separator values are the first values in each range, starting with the second one. (In the example above, 'j' is the first value within the second range and 'p' is the first value in the third range).
4. `NULL` values are always stored in the beginning of the first range.
5. A device can appear multiple times in the device list, in such case multiple ranges will be stored on the same device.

If storage parameters are not specified for the table, the default is to create one segment of the table in each device in the system. The system will distribute the table rows across all the devices.

If storage parameters are not specified for an index, the default is to create a single segment for the index on a randomly chosen device.

## Examples

**Create a table with a primary key:**

```sql theme={null}
CREATE TABLE customers (
  c_custkey INT PRIMARY KEY INDEX WITH (devices = (m1d2)),
  c_name VARCHAR(40) NOT NULL
    INDEX WITH (devices = (m1d2, m2d5, m3d3), range_separators = ('j', 'p')),
  c_gender CHAR(1)
) WITH (devices = (m1d2, m2d5, m3d3));
```

Create the table `customers` and set it ready for DML. Set the column `c_custkey` as the primary key,
defined with an index, and the `c_name` column with the `NOT NULL` constraint.

The primary key index is using the device (m1d2) - note that it has only 1 device therefore the
`RANGE_SEPARATORS` clause is not needed.

The column `c_name` has an index on it with the following devices:

* Device m1d2 stores values lower than or equal to 'j'
* Device m2d5 stores values greater than 'j' and lower than or equal to 'p',
* Device m3d3 stores values greater than 'p'.

The table data is stored on the devices (m1d2, m2d5, m3d3).

**Create a table with a foreign key:**

```sql theme={null}
CREATE TABLE SET NOT READY orders (
  o_order_id CHAR(10) PRIMARY KEY INDEX WITH (devices = (m1d2)),
  o_name VARCHAR(120) NOT NULL,
  o_custkey INT NOT NULL
    REFERENCES customers INDEX WITH (devices = (m1d3)),
  o_totalprice DECIMAL (5,2),
  o_date date DEFAULT NOW() NOT NULL
) WITH (devices = (m1d4));
```

Create the table `orders` with a foreign key referencing the primary key of the `customers` table.

Set the table as `NOT READY` for DML, so it can still be modified with the [ALTER TABLE](/sql/ddl-commands/alter-table) command.

The table primary key (`o_order_id`) is using an index stored on device `m1d2`

The `o_name` and `o_date` columns have a constraint prohibiting NULL values. The `o_date` also has a default value of the current date (by using the function `NOW()`).

The `o_custkey` column is a foreign key to the primary key of table `customers`. It has the `NOT NULL` constraint, and it must contain values that exist in the primary key (`c_custkey`) in the table customers. This foreign key column has an index, stored on the device `m1d3`.

The table itself is stored on the device `m1d4`.

**Create a table with a calculated column:**

```sql theme={null}
CREATE TABLE transactions (
  transactions_id INT PRIMARY KEY INDEX WITH (devices = (m1d2)),
  transaction_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
  product_name VARCHAR(100) NOT NULL,
  purchse_price FLOAT NOT NULL,
  sale_price FLOAT,
  number_of_sold_items INT,
  profit FLOAT
) WITH (devices = (m1d2, m2d5, m3d3));
```

Create the table `transactions`. Set the `transaction_date` column with the default of setting the current time.

## Compatibility

The `CREATE TABLE` command conforms to the SQL standard, with the following exceptions:

1. `SET READY` | `NOT READY` is a Regatta extension.
2. The `WITH` clause is a Regatta extension; storage parameters are not in the standard.


# DROP TABLE
Source: https://docs.regatta.dev/sql/ddl-commands/drop-table



Remove a table.

## Synopsis

```text theme={null}
DROP TABLE table_name [, ...] [RESTRICT]
```

## Description

The `DROP TABLE` command is used to remove one or more tables from the current database, including all its rows, its metadata and related indexes.

## Parameters

**`table_name`**

The name of the table to be dropped.

`RESTRICT`

Return an error if any column in the table to be dropped is referenced by another table’s column (foreign key).
Note: This is the default behavior even without specifying `RESTRICT`. The option is supported for for compatibility with PostgreSQL.

## Examples

**Drop a table:**

```sql theme={null}
DROP TABLE customers;
```

Drop the table `customers`.

## Compatibility

***

The `DROP TABLE` command conforms to the SQL standard.


# DELETE
Source: https://docs.regatta.dev/sql/dml-commands/delete



Removes rows from an existing table.

## Synopsis

***

```
DELETE FROM table_name [ [ AS ] alias ]
[ WHERE condition ]
[ RETURNING output_expression [[ AS ] output_name ] [, ...] ]
```

## Description

The `DELETE` command removes rows from a specified table. The deletion can be specific by using the `WHERE`clause to identify the needed rows to delete. Without the `WHERE` clause, the command removes all the rows in the table and leaves it empty.

## Parameters

**`table_name`**

The name of the table to delete rows from.

**`alias`**

A substitute alias name for `table_name`. The alias name should match the [Identifiers Limitations](/sql/appendices/indentifiers-limitations).

**`WHERE`**

The condition to filter the rows for deletion. If this parameter is omitted, all the rows in the table are
removed.

The `WHERE` clause can contain the rows `ROWID` with = or `IN` condition.

**`RETURNING output_expression`**

Returns the given expression for every row deleted by the command. Refer to the expression
parameter of [SELECT](/sql/dql/select/select#parameters) for specification of the output\_expression parameter.

## Outputs

On successful completion, the `DELETE` command returns the count of the deleted rows.

## Examples

***

Delete rows based on a specific filter:

```sql theme={null}
DELETE FROM orders WHERE o_date < '2020-1-1' ;
```

Delete rows based on another table filter:

```sql theme={null}
DELETE FROM orders
WHERE o_date <= (SELECT max(o_date) FROM old_orders);
```

Delete a row based on its ROWID:

```sql theme={null}
DELETE FROM orders
WHERE ROWID = 12345678;
```

## Compatibility

***

The `DELETE` command conforms to the SQL standard with the exception of the `RETURNING` functionality.


# INSERT
Source: https://docs.regatta.dev/sql/dml-commands/insert



Inserts data into an existing table.

## Synopsis

```
INSERT INTO table_name [ AS alias ] [ ( column_name [, ...] ) ]
  { VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | query }
  [ WITH devices = ( device_list ) IN MODULES ( module_list ) ]
  [ RETURNING output_expression [[ AS ] output_name ] [, ...] ]

where device_list is a comma-separated list of device numbers and module_list is a comma-separated list of the module identifiers of the modules to which the devices belong.
Note that the device number is the number of the device within the pertinent module, not the system-wide unique device-id.
```

## Description

The `INSERT` command inserts one or more rows into an existing table. The values inserted into each column in the table can either be explicitly-specified using the `VALUES` keyword, or use the result of a query.

## Parameters

**`table_name`**

The name of the table to be inserted with the new rows.

**`alias`**

A substitute alias name for `table_name`. The alias name should match the [Identifiers Limitations](/sql/appendices/indentifiers-limitations).

**`column_name`**

A list of columns in the table. The columns can be listed in any order, as long as the expressions in the VALUES clause are listed in the same order. Each missing column is set to `NULL` or to its default value specified in the `CREATE TABLE` statement. In case of a missing column that has no default value and the column has a `NOT NULL` constraint, the command fails.

This parameter is optional. If no column names were specified, the values are assigned to the columns in the order of columns defined in the table’s creation. If the number of values is less than the number of columns, the values are assigned to the first columns and the rest are assigned default values, or `NULL` for columns with no default value.

**`VALUES`**

Specifies the values to insert into the corresponding columns in the table. The data types of the values should be compatible with the data types of the corresponding columns in the column list (note that in some cases, Regatta will overcome mismatches with implicit conversion).

The list of values can only contain literals (e.g. 'hello'), the `DEFAULT` and `NULL` keywords, expressions or functions that can be computed at the planning time such as `NOW()` or 5\*50.

String literals and date literals in the `VALUES` list must be enclosed by single quotes (').

**`expression`**

An expression or value to assign to the corresponding column. The expression is given as a string and Regatta attempts to convert it to the desired data type.

**`DEFAULT`**

Store the column default value as it's defined for the column at the [CREATE TABLE](/sql/ddl-commands/create-table) or [ALTER TABLE](/sql/ddl-commands/alter-table)
statements.

Note that if all the columns in the table have `DEFAULT` values, the following syntax can be used to insert a single row with all the columns set to the default values: `INSERT INTO <table name> DEFAULT VALUES;`

**`query`**

A SELECT statement that supplies the rows to be inserted. See [SELECT](/sql/dql/select).

`WITH devices = ( device_list ) IN MODULES ( module_list )`

Regatta uses an internal algorithm to distribute the rows of a table across the table storage devices optimally. You can override it by specifying one or more device into which the rows will be inserted. The devices are identified by their internal device number within the pertinent modules, and modules containing the devices should also be specified.

Use of this clause is generally discouraged as it could interfere with Regatta's internal data distribution algorithms and degrade performance and/or cause a storage device to fill up unintentionally. It should be used with care in very specific use cases.

**`RETURNING output_expression`**

Returns the given expression for every row inserted by the command. Refer to the **expression**
parameter of [SELECT](/sql/dql/select/select#parameters) for specification of the **output\_expression** parameter.

If only `ROWID` is specified as the **output\_expression**, the returned ROWIDs are returned in pairs of
(First ROWID, number of rows) for each set of consecutive ROWID numbers.

## Outputs

On successful completion, the `INSERT` command returns the count of the inserted rows.

## Examples

The commands to create the tables referenced in these examples can be found in the [CREATE TABLE](/sql/ddl-commands/create-table/create-table#examples) Examples.

Insert of a single row:

```sql theme={null}
INSERT INTO customers (c_custkey,c_name,c_gender)
VALUES (1,'John Doe1','M');
```

Insert of multiple rows in a single command:

INSERT INTO customers (c\_custkey,c\_name,c\_gender)\
VALUES (2, 'John Doe2', 'M'), (3, 'John Doe3', 'M'), (4, 'John Doe4', 'M');

Insert partial column list:

```sql theme={null}
INSERT INTO orders (o_order_id,o_name,o_custkey,o_date)
VALUES (1022, 'order of John Doe1', 1, DEFAULT);
```

In this example, we specifically write the values of the mentioned columns.

The column `o_date` is loaded with its DEFAULT value as defined in the table definition.

Missing columns (`o_totalprice`) will write their default value, or NULL. If no DEFAULT was defined and the column is set with the NOT NULL constraint, the `INSERT` will fail.

Insert based on a query result:

```sql theme={null}
INSERT INTO old_orders SELECT * FROM orders WHERE o_date < '2020-01-01';
```

## Compatibility

The `INSERT` command conforms to the SQL standard with the exception of the `RETURNING` functionality.


# UPDATE
Source: https://docs.regatta.dev/sql/dml-commands/update



Modifies rows in an existing table.

## Synopsis

```
UPDATE table_name[ [ AS ] alias ]
  SET { column_name = { expression | DEFAULT } |
        ( column_name [, ...] ) = ( { expression | DEFAULT } [, ...] ) |
        ( column_name [, ...] ) = ( sub-SELECT )
      } [, ...]
  [ WHERE condition ]
  [ RETURNING output_expression [[ AS ] output_name ] [, ...] ]
```

## Description

The `UPDATE` command modifies the values of specific columns in all rows that satisfy the command condition.

## Parameters

**`table_name`**

The name of the table to modify its rows.

**`alias`**

A substitute alias name for `table_name`. The alias name should match the [Identifiers Limitations](/sql/appendices/indentifiers-limitations).

**`SET`**

The requested change. Contains a tuple of column names and a tuple of their new values.

**`column_name`**

The name(s) of the column(s) to modify. The columns should not include the table name (`SET tab1.c_id = 1` is invalid).

**`expression`**

The new value to replace the existing value per column.

**`DEFAULT`**

Set the new column value to the column default value as set for the column in the table definition.

**`sub-SELECT`**

Subquery that returns exactly one row. The subquery returned columns should match the `SET` clause columns and their data types.

<Note>
  Note: If the subquery returns no rows, the value of all the updated columns in the updated rows is set to NULL.
</Note>

**`WHERE`**

A filter to decide which rows in the table to update. If no condition is set, all the rows in the table are updated.

The `WHERE` clause can contain the rows `ROWID` with ‘=’ or `‘IN` (`<`list of literals`>`)’
condition.

**`RETURNING output_expression`**

Returns the given expression for every row modified by the command. Refer to the `expression`
parameter of [SELECT](/sql/dql/select/select#parameters) for specification of the **output\_expression** parameter.

## Outputs

On successful completion, the `UPDATE` command returns the count of the updated rows.

## Examples

Update the rows based on a simple predicate:

```sql theme={null}
UPDATE orders SET o_date = '2022-01-01' WHERE c_custkey = 1
```

Update multiple columns and return the update rows ROWIDs:

```sql theme={null}
UPDATE orders SET o_date = '2022-01-01', o_totalprice = O_totalprice * 0.1
WHERE o_name = 'order of John Doe1' AND o_date > '2000-01-01'
RETURNING ROWID;
```

### Update a table based on ROWID

```sql theme={null}
UPDATE orders SET o_date = '2022-01-01'
WHERE ROWID in (12345678, 12345677, 12345676);
```

### Update a table using a result from a non-correlated subquery

```sql theme={null}
UPDATE orders
SET o_totalprice = (SELECT MAX(o_totalprice * 1.10) FROM old_orders)
WHERE o_date > '2022-12-12';
```

## Compatibility

The `UPDATE` command conforms to the SQL standard with the exception of the RETURNING functionality.


# EXPLAIN
Source: https://docs.regatta.dev/sql/dql/explain



The command returns the execution plan of a statement, without actually executing it.

## Synopsis

```
EXPLAIN statement
```

## Description

The `EXPLAIN` command displays the execution plan that would be generated for the given statement.

## Parameters

**`statement`**

The SQL statement.

The statement can be any `SELECT`, `UPDATE`, `INSERT`, or `DELETE` statement.

## Outputs

The output of the command is the execution plan in tabular format, with the following details:

| **Column** | **Description** |
| :- | :- |
| ID | Unique identifier assigned to each operation in the query plan. |
| Parent ID | The Identifier of the parent operation. |
| Operation | The name of the operation, e.g. FILTER, FULL SCAN, JOIN, etc. |
| Information | Either the name of the object (e.g. table or index) referenced by the operation, or an expression the operation applies (e.g. a JOIN operation condition). |

The output is a table that represents a tree structure. Each row represents a node in the tree. The row with ID=1 is the root of the tree and all other rows have a Parent ID that indicates the parent node ID.

Following is a list of operation names that may appear in the Operation column:

`FULL SCAN` – a scan of all the rows in a table.

`PARTIAL SCAN` – a scan of one or more rows in a table.

`VALUES SCAN` – a sequential scan of all the values that are either given in the SQL statement or produced by another operation.

`INDEX SCAN` – a scan on an index. That includes full scan, range scan, or lookup of one or more specific values.

`INDEX RANGE` – when an index scan has a range predicate, this specifies the range.

`FILTER` – filter the results of another operation based on a boolean predicate.

`SELECTION` – an operation that applies a set of filters to a set of records produced by another operation. The operation and the filters are children of the SELECTION operation.

`SORT` – sort the results of another operation.

`UNION` – combine the results of two other operations.

`DISTINCT` – eliminate duplicates from a sorted list of records produced by another operation.

`JOIN` – intersect the results of two other operations. Each such operation has two parameters, algorithmic and functional. See the list of options below.

`GROUP BY` – group the results of another operation according to the value of a certain set of columns. OFFSET – Trim the beginning of the results of another operation by a given number of records.

`LIMIT` – Trim the end of the results of another operation, leaving only the first given number of records. INSERT – insert rows into a table.

`UPDATE` – update existing rows of a table.

`DELETE` – delete rows of a table.

`MULTI OP` – this represents a node in the execution tree which aggregates two or more operations that are performed in combination in parallel. (For example, `FULL SCAN` and `FILTER`.) Those operations are children of this node in the execution tree.

`SINGLE ROW SUBQUERY` – a query that is expected to return a single record. If it returns more than one record, the execution fails.

<Note>
  The `UNION` operation stands for combining two sets or records without eliminating duplicate records. When duplicate records should be eliminated, the output contains a `DISTINCT` operation which is parent of the `UNION` operation, and applies to the result of the `UNION` operation.
</Note>

**Join operation details:**

Each join operation in the output is a 3-token string of the form: `algorithm variant JOIN`

**algorithm** is one of the following: `HASH`, `MERGE`, `LOOP`

**variant** is one of the following: `INNER`, `LEFT` `[SEMI]`, `RIGHT` `[SEMI]`, `FULL`, `CROSS`

<Note>
  Note: By algorithm we refer to the algorithm used to process the two input record sets inside each module participating in the join operation. There is also the distribution algorithm, which is either `broadcast` or `hash partitioning`, but this is not included in the `EXPLAIN` output.
</Note>

## Examples

Query on a table, filtering by a column that is not indexed:

```SQL theme={null}
EXPLAIN SELECT name FROM employees WHERE num_rewards = 0;
+----+--------+------------------+-----------------------------------------+
| id | parent | operation | information                                    |
+----+--------+------------------+-----------------------------------------+
| 1  | 0      | MULTI OP  |                                                |
| 2  | 1      | FULL SCAN | on: employees                                  |
| 3  | 1      | FILTER    | num_rewards = 0                                |
+----+--------+------------------+-----------------------------------------+
```

The same query, when the column is indexed and the query planner chooses to use the index to determine which rows should be deleted:

```sql theme={null}
EXPLAIN SELECT name FROM employees WHERE num_rewards = 0;
+----+--------+--------------+---------------------------------------------+
| id | parent | operation    | information                                 |
+----+--------+--------------+---------------------------------------------+
| 1  | 0      | PARTIAL SCAN | on: employees                               |
| 2  | 1      | INDEX SCAN   | using key: num_rewards                      |
| 3  | 2      | VALUES SCAN  |                                             |
+----+--------+--------------+---------------------------------------------+
```

In processing the above query, the DB treats the expression in the WHERE clause as a list of values (one value in this case) that are looked up in the index.

In the following query, it is treated as a boolean expression that generate a range scan, thus there is no values scan in the plan:

```sql theme={null}
EXPLAIN SELECT name FROM employees WHERE num_rewards > 3;
+----+--------+--------------+---------------------------------------------+
| id | parent | operation    | information                                 |
+----+--------+--------------+---------------------------------------------+
| 1  | 0      | PARTIAL SCAN | on: employees                               |
| 2  | 1      | INDEX SCAN   | using key: num_rewards                      |
+----+--------+--------------+---------------------------------------------+
```

## Compatibility

The `EXPLAIN` statement isn’t part of the SQL standard.


# SELECT
Source: https://docs.regatta.dev/sql/dql/select



The command to read and process data.

## Synopsis

```
[ WITH with_query [, ...] ]
SELECT [ ALL | DISTINCT [ ON ( expression [, ...] ) ] ]
  [ ROWID | * | expression [ [ AS ] output_name ] [, ...] ]
  [ FROM from_item [, ...] ]
  [ WHERE condition ]
  [ GROUP BY grouping_element [, ...] ]
  [ HAVING condition ]
  [ UNION [ ALL | DISTINCT ] select ]
  [ ORDER BY expression [ ASC | DESC ] [ NULLS { FIRST | LAST } ] [, ...] ]
  [ LIMIT { count | ALL } ]
  [ OFFSET start ]

where from_item can be one of:
  table_name[ [ AS ] alias [ ( column_alias [, ...] ) ] ]
  from_item join_type from_item ON join_condition ( select ) [ AS ] alias

and with_query is:
  with_query_name AS ( select )
where select is a SELECT subquery.
```

## Description

The `SELECT` command can be used as either a statement on its own, or as a clause within other statements (e.g: `INSERT AS SELECT`). The `SELECT` is often referred to as the query, while its output is often referred to as the result set.

Note, when querying multiple data sources with ambiguous column names, the `table_name` or the alias must be used before each `column_name`.

Note: Both implicit joins (`SELECT FROM A,B WHERE a.id=b.id`) and explicit joins (`SELECT FROM a JOIN b ON a.id=b.id`) are supported. More details below.

## Parameters

**`WITH clause`**

The `WITH` clause allows you to specify one or more subqueries that can be referenced by name in the primary query. A `WITH` query that is referenced more than once in `FROM` is computed only once. Each subquery should be a `SELECT` statement.

**`ALL`**

Includes duplicate rows (if exist) in the result set.

This is the default.

**`DISTINCT`**

Eliminates duplicate rows from the result set.

**`DISTINCT ON expression`**

Eliminates duplicate rows from the result set, where equality is determined by the specified expressions.

E.g: `SELECT DISTINCT ON(c_gender) c_gender, c_name FROM customers`; to retrieve the first `c_name` and its `c_gender` per `c_gender` column.

Note that the first row of each set is unpredictable unless `ORDER BY` is used to ensure that the desired row appears first.

Notes:

1. The `DISTINCT ON` can use multiple expressions (e.g. `DISTINCT ON (a,b,d)`).
2. The `DISTINCT ON` can use columns that aren't projected (e.g. `SELECT DISTINCT ON(a) b,c`).

**`expression`**

A scalar expression to retrieve in the query. Scalar expressions produce values suitable to store in a single table cell (one column of one row).

The expression can either be a compound of:

* Column name from the data source the query is reading. Column names can be specified as `table_name.column_name`, or just `column_name` if they are not ambiguous in multiple data sources in the queries.
* Constant expressions such as literals (e.g: `SELECT` '`Hello`', `6*1.4`) representing a simple value that doesn't change.
* Functions that can receive both columns and literals (e.g: `SELECT NOW()`, `UPPER(o_name)`, `0.20*o_totalprice`).
* Aggregate functions that operate on a group of rows based on their value. See [Aggregate functions](/sql/sql-functions-and-operators/aggregate-functions).

Or one of the following:

* '`*`' to retrieve all columns in the query data sources (e.g: `SELECT * FROM orders`;)
* '`ROWID`', to return the unique `ROWID` of each row within a specific table. Note that `ROWID` can be retrieved only when the FROM object is a single table, e.g., it cannot be retrieved as a result of a join. In addition, it cannot be retrieved as part of a subquery, and cannot be used in a compound expression (e.g. the expression `ROWID+5 or COUNT(ROWID)` is not allowed).

Notes:

1. expression must not be empty. Empty `SELECT` list (e.g: `SELECT FROM table_name`) is not allowed.
2. Only one aggregated DISTINCT operation is allowed in the query selected fields, unless using the same aggregated input expression. This means that the following example: `SELECT AVG(DISTINCT a), AVG(DISTINCT b) FROM my\_table`; is not valid. While `SELECT AVG(DISTINCT sale_price)`, `STDDEV(DISTINCT sale_price) FROM transactions`; is valid.

**`output_name`**

A substitute alias name for the expression/column name. The alias name should match the [Identifiers Limitations](/sql/appendices/indentifiers-limitations).

<Note>
  Note: The column alias in the `SELECT` section can only be used in the `GROUP BY` / `ORDER BY` / nesting query if this is a subquery. In the `WHERE` and `HAVING` clauses the column should be specified with its origin name.
</Note>

**`FROM`**

Specifies one or more source tables for the `SELECT` to read from.The `FROM` can contain either table name, or subqueries.

The default join type between the `FROM` sources depends on the join syntax:

Explicit join: When `join_type` is specified, the specified `join_item`’s are joined by the specified `join_type` and by the specified `join_condition`. If the `join_type` is simply the keyword `JOIN`, `INNER JOIN` is used as the default join type (see below).

Implicit join: If more than one source is specified in the FROM list without `join_type`, those sources will be joined by the matching join condition at the `WHERE` clause. If no such condition is specified, the join will be a `CROSS JOIN`.

**`table_name`**

The name of the table to read.

**`alias`**

A substitute name for the `FROM` item containing the alias. When an alias is provided, it completely hides the previous name of the table;

E.g: Given `FROM customer AS cust`, the remainder of the statement must refer to this `FROM` item as `cust`, and not as `customers`.

If an alias is used, a column alias list can also be used to provide substitute names for one or more columns of the table. If the column alias list is given for less than the number of table columns, the aliasing is by the columns order: e.g. assuming the table `tab1` has the columns `a,b,c,` with aliasing the `FROM` section, we must now address the columns with the alias it was given. `SELECT x,b,c FROM tab1 AS t(x)`, we can now refer to columns `t.x,t.b,t.c` but `t.a` does not exist.

All alias names should match the [Identifiers Limitations](/sql/appendices/indentifiers-limitations).

**`select`**

A sub-SELECT can appear in the FROM clause. The sub-SELECT must be surrounded by parentheses, and it should be named with an alias.

Note: Correlated subqueries are not supported. In other words, the sub-select must not use values from the outer query.

**`join_type`**

One of the following:

* `[ INNER ] JOIN`

  Returns only the records that have matching values in both record-sets.
* `LEFT [ OUTER ] JOIN`

  Returns all the records from the left record-set and matching records between both record-sets.

  Each left record-set record without a matching right record-set record is extended to the full width of the joined record-set by inserting NULL values for the right-hand columns.
* `RIGHT [ OUTER ] JOIN`

  Returns all the records from the right record-set and matching records between both record-sets.

  Each right record-set record without a matching left record-set record is extended to the full width of the joined record-set by inserting NULL values for the left-hand columns.
* `FULL [ OUTER ] JOIN`

  Combines the result of the left outer join and right outer join.
* `CROSS JOIN`

  Generate a cartesian join by joining each record of one record-set with every record of the other record-set.

**`ON join_condition`**

Relevant for explicit joins. An expression resulting in a boolean that specifies which rows in a join are considered to match. For all joins other than `CROSS JOIN`, the `ON` condition is mandatory.

**`WHERE`**

Filter the result set by specific conditions. Only the rows that satisfy the conditions (evaluate to `TRUE`) are included in the result set.

Rows for which the condition evaluates to 'unknown' (such as when comparing a number to `NULL`) are excluded from the result set.

E.g: `SELECT FROM orders WHERE o_totalprice > 50`; and one of the rows has `NULL` as its `o_totalprice column`, the filter returns `UNKNOWN` on that row and it will not be returned by the query.

The `WHERE` clause can contain `ROWID`with = or `IN` operator as the exclusive filter in the query. Note that the `IN` clause must contain a list of `ROWIDs` and not a subquery.

**`GROUP BY`**

Group all the rows that share the same values for the grouped expressions into a single row. When `GROUP BY` is used, all other columns in the query `SELECT` list, that aren’t part of the `GROUP BY` section, should be aggregated with an aggregation function (see [Aggregate functions](/sql/sql-functions-and-operators/aggregate-functions)), producing a separate value for each group.

Note: There is no support for ungrouped columns which are functionally dependent on the grouped columns (such that the value of the grouped column uniquely determines the value of the ungrouped column). Every element in the select list must be either a grouped column (or more accurately – any expression which doesn’t contain ungrouped columns) or an aggregate function.

For example, suppose a `city` table has a `name` column as primary key and a `province` column; a `resident` table has a `lives_in` column which references `city.name`. Now, we want to list the population of each city, along with its province. The following query would do that:

```sql theme={null}

SELECT city.province, city.name, COUNT(resident.lives_in) as population
FROM city JOIN resident ON city.name = resident.lives_in GROUP BY
city.name ORDER BY city.province, city.name;
```

Although `city.province` is functionally dependent on `city.name`, Regatta doesn’t support this query, and `city.province` must be added to the grouped-by columns set, as follows:

```sql theme={null}
SELECT city.province, city.name, COUNT(resident.lives_in) as population
FROM city JOIN resident ON city.name = resident.lives_in GROUP BY
city.name, city.province ORDER BY city.province, city.name;
```

This doesn’t change the result of the query.

If an aggregation exists without the `GROUP BY` expression, then the query is treated as having a single group comprising all the selected rows (e.g: `SELECT SUM(a) FROM..`).

The `GROUP BY` clause can either contain the columns/expressions as they were written in the `SELECT` list, or their position in the `SELECT` list (1,2, etc).

e.g: `SELECT o_name, COUNT(*) FROM orders GROUP BY 1`;

**`HAVING`**

The `HAVING` clause is used as a filter on top of the `GROUP BY `results. It eliminates grouped rows that do not satisfy its condition.

**`UNION [ ALL | DISTINCT ]`**

`UNION` combines the result from two SELECT statements into a single result set, after omitting duplicate rows. When used with the keyword ALL, duplicate rows aren’t removed (hence, `UNION ALL` is a faster operation).

`UNION DISTINCT` is the default mode, and it will eliminate duplicate records.

Note that combining two result sets with `UNION` or `UNION ALL` doesn’t guarantee maintaining each result set order. If the `UNION [ALL]` output needs to be ordered, use subqueries (see in the examples below).

The different query blocks must produce the same number of columns, and their results should have matching data types (identical types or compatible types that can be implicitly converted).

**`ORDER BY`**

Returns the result set sorted by a specified order of the expressions in the `ORDER BY` clause. Each expression order can be `ASC` (default) or `DESC`.

Optionally you can decide where to locate the NULL values. If `NULLS LAST` is specified, NULL values sort after all non-NULL values; if `NULLS FIRST` is specified, NULL values sort before all non-NULL values.

By default, `NULLS LAST` is used for ASC order and `NULLS FIRST` is used for DESC order. Note that order of character strings is case sensitive.

Note that order of character strings is case sensitive.

**`LIMIT { count | ALL }`**

The `LIMIT` clause restricts the number of rows that are included in the result set by the specified count.

**count** must be a constant expression containing only literal values. When ALL is specified, all the rows of the result set are returned.

**`OFFSET start`**

The `OFFSET` clause specifies the number of rows to skip before starting to return rows. **start** must be a constant expression containing only literal values. When used with `LIMIT`, the `OFFSET` **start** rows are skipped before starting to count the `LIMIT` count rows to be returned.

## Tuple support

***

Tuples in the select expressions are not supported, but tuples are supported in the WHERE clause. For example, getting a list of all employees in rank 3 who earn a salary of 20000:

```sql theme={null}
SELECT id, name from employees WHERE (rank, salary) = (3, 20000);
```

Or getting a list of employees who earn the maximum salary for their rank:

```sql theme={null}
SELECT id, name from employees WHERE (rank, salary) IN (SELECT rank_id,
max_salary FROM ranks);
```

## Examples

**Retrieve specific columns:**

```sql theme={null}
SELECT o_order_id, o_date FROM orders;
```

**Retrieve the ROWID of all the rows that match the filter:**

```sql theme={null}
SELECT ROWID FROM orders WHERE o_name='product0015612';
```

**Retrieve all columns by multiple filters:**

```sql theme={null}
SELECT * FROM orders
WHERE (o_date > '2022-12-12' AND o_name like 'product001%')
OR o_totalprice > 9000 ;
```

Return all the rows and columns of table `orders` if they answer one of the following conditions:

Either there `o_date` is higher than ‘2022-12-12’ and their `o_name` starts with ‘product001’

Or if their `o_totalprice` is greater than 9,000.

**`Use DISTINCT ON:`**

```sql theme={null}
SELECT DISTINCT ON(o_date) o_name,o_date FROM orders;
```

Return a single row for each distinct `o_date`.

**`Retrieve rows based on a GROUP BY:`**

```sql theme={null}
SELECT o_date, sum(o_totalprice), count(o_order_id)
FROM orders
GROUP BY o_date
ORDER BY o_date;
```

Returns the count of `o_order_id` and their total `o_totalprice` grouped by a specific `o_date`, ordered by
the `o_date` value (ascending order).

**`Retrieve rows based on a GROUP BY and HAVING:`**

```sql theme={null}
SELECT o_date, sum(o_totalprice ), count(o_order_id)
FROM orders
GROUP BY o_date
HAVING sum(o_totalprice) > 45000
ORDER BY o_date;
```

Same example as the previous, with an extra filter: return only the rows that their total
`sum(o_totalprice)` is greater than 45,000.

**`Retrieve sorted rows based on a UNION output:`**

```sql theme={null}
SELECT o_date, c_name
FROM
(SELECT o_date, c_name
 FROM old_orders JOIN customers ON o_custkey=c_custkey
 WHERE o_date>'2020-1-1'
 UNION
 SELECT o_date, c_name
 FROM orders JOIN customers ON o_custkey=c_custkey
) AS MY_UNION
ORDER BY o_date;
```

Combine the results and remove duplicates (`UNION`) from the two queries within a subquery, and return the results ordered by the o\_date column.

**`Retrieve with LIMIT and OFFSET:`**

```sql theme={null}
SELECT * FROM customers
ORDER BY c_custkey DESC
OFFSET 2 LIMIT 2;
```

Given 10 rows in the table with the c\_custkey of 1-10 (1,2,3,..10), the following query results with the rows of
c\_custkey 8 and c\_custkey 7.

**`Retrieve rows using both UNION and JOIN:`**

```sql theme={null}
SELECT all_orders.o_date, c_name
FROM
(SELECT o_date,o_custkey FROM orders
UNION
SELECT o_date, o_custkey FROM old_orders
) as all_orders JOIN customers ON all_orders.o_custkey = c_custkey;
```

Join the output of the unioned `orders` and `old_orders` with `customers`.

**`Retrieve rows using LEFT OUTER JOIN:`**

```sql theme={null}
SELECT COUNT(o_order_id), c_name as customer
FROM customers LEFT OUTER JOIN orders on c_custkey = o_custkey
AND o_name not like '%%special%%requests%%'
GROUP BY 2
ORDER BY 1 DESC , 2 DESC;
```

Left outer join the table `customers` with `orders` so that for every `c_name `it returns the count of
`o_order_id` (or NULL if no rows match on the `orders` table).

Rows on the table `orders` are being filtered as `not like` '`%%special%%requests%%`'.

Return the results ordered by the count aggregation in a DESC order, and then by the `c_name` column with
the alias `customer`.

**Retrieving rows using aliases:**

```sql theme={null}
SELECT SUM(o_totalprice), o_name order_name, o_date current_order_date
FROM orders ,
(SELECT o_date as old_orders_date FROM old_orders) as old_orders
WHERE o_date > old_orders_date
GROUP BY order_name , current_order_date;
```

Note that the `o_date` column in the `WHERE` clause had to be used in its original column name (unlike the `current_order_date` alias) because the `WHERE` clause has to receive the columns in their original names (filters can be parsed before the alias is assigned).


# General notes
Source: https://docs.regatta.dev/sql/hints/general-notes



1. Syntax: `/*++ hint [, ...] */`
   * All hints should be given in comments with the ‘++’ sign:
   * Failure to include the “++” right after the comment opening characters will result in regarding the hint as a regular comment, effectively ignoring it.
2. Hints apply only to the statement block in which they appear.
3. A statement block can have only one comment containing hints. The hints-comment must follow a `SELECT`, `UPDATE`, or `DELETE` keyword. A hints comment that appears anywhere else in the SQL statement would result in an error.
4. Statement blocks that can contain hints are:

   4.1. A simple `SELECT`, `UPDATE`, or `DELETE` statement.

   4.2. A parent query or subquery of a complex statement.

   4.3. A part of a compound query (such as when using `UNION`).
5. Multiple hints should be separated by commas: For example: \
   `/*++ JOIN METHOD (HASH), INDEX (b, my_idx) */`
6. A syntax error in a hint-comment may result in a parsing error that would cause ignoring all the hints in the comment, even if some hints are valid.
7. A hint must be applied by the query planner unless it is invalid. Invalid hints should be ignored. A hint is invalid if either of the following holds:

   * It is impossible to apply the hint (e.g., a hint to use an index scan rather than a table scan when the relevant column is not indexed)
   * Applying the hint would lead to incorrect results.

   Hints are either applied or ignored, but never fail the statement.
8. When a hints comment contains multiple hints with a mix of valid and invalid hints, the valid hints are applied.
9. When there are any conflicting hints, all the hints in the pertinent comment are ignored. (The possible contradictions are listed under each hint in the sub-sections below.)
10. If a table appears in a query with an alias, the hint must specify the alias name rather than the table name.
11. Hints related to joins require an explicit join and an alias, and the alias name specified in the hint parameter.
12. If a hint references a table that appears multiple times in a query, the hint relates to first occurrence. An alias can be used in order to apply a hint to other occurrences of the table.


# Hint - Join direction
Source: https://docs.regatta.dev/sql/hints/join-hints/join-direction



### Synopsis

`JOIN DIRECTION [ ( join_alias ) ]`

Joins – except for outer left and right joins – are logically symmetric. However, their execution is often asymmetric. This hint instructs the system how to execute the join in two aspect

1. If the execution plan uses the hash method, the hint defines which side of the join should be loaded into a hash table. (The other side is traversed and each of its records is looked up in the hash table).
2. If the execution plan uses the broadcast distribution method, the hint defines which side of the join should be broadcasted to all the nodes containing the other side.

The **join\_alias** parameter is optional. If it’s absent, the hint applies to all the joins in the statement (including explicit and implicit joins) except for joins that have a hint specifically for them.

Essentially, this hint tells the system that the left side of the join (as it appears in the SQL statement) is the smaller one. Without the hint, the query optimizer tries to figure out by itself which side is the smaller record set.

### Example:

```sql theme={null}
SELECT /*++ JOIN DIRECTION */ s.name, o.id
FROM staff s JOIN org o
ON s.deptno = o.deptno
WHERE o.division = 'EASTERN';
```


# Hint - Join distribution method
Source: https://docs.regatta.dev/sql/hints/join-hints/join-distribution



### Synopsis

`JOIN DISTRIBUTION METHOD ( [ joint_alias, ] { HASH DIVIDE | BROADCAST } )`

This hint instructs the system which method to use for *distributing* the input records for the join operation – either hash-divide or broadcast. This hint is honored as long as it’s possible – some distribution methods are not applicable for certain join methods, and in those cases the hint won’t be applied.

The **join\_alias** parameter is optional. If it’s absent, the hint applies to all the joins in the statement (including explicit and implicit joins). Also, if there is a `JOIN DISTRIBUTION METHOD` hint without alias, any other `JOIN DISTRIBUTION METHOD` hint is contradictory and results in ignoring all the hints.

If no join is specified, the hint will affect all the joins in the statement.

Specifying multiple hints with different distribution methods for the same alias is contradictory and is not allowed.


# Join hints
Source: https://docs.regatta.dev/sql/hints/join-hints/join-hints



Join hints can be applied only to explicit joins. In order to use join hints, the join result must be aliased and the alias name specified in the hint to identify the join.


# Hint - Join method
Source: https://docs.regatta.dev/sql/hints/join-hints/join-method



### Synopsis

`JOIN METHOD ( [ joint_alias, ] { HASH | NL } )`

This hint instructs the system which method to use for performing the join operation - either hash-join or nested loop. This hint is honored as long as it’s possible – some joins cannot be done using certain methods, and in those cases the hint won’t be applied.

The **join\_alias** parameter is optional. If it’s absent, the hint applies to all the joins in the statement (including explicit and implicit joins). Also, if there is a `JOIN METHOD` hint without alias, any other `JOIN METHOD` hint is contradictory and results in ignoring all the hints.

Specifying multiple hints with different methods for the same alias is contradictory and is not allowed.

### Example

```sql theme={null}
SELECT /*++ JOIN METHOD (dept_join, HASH) */ name, id
FROM (staff s JOIN org o ON s.deptno = o.deptno) as dept_join
WHERE o.division = 'EASTERN';
```


# Hint - Cardinality
Source: https://docs.regatta.dev/sql/hints/other-hints/hint-cardinality



### Synopsis

`CARDINALITY (object_name, number)`

A hint to specify the expected record set size in a specific operation.

`OBJECT_NAME` can be:

1. A specific table. Contains the expected number of rows in the table. For example:

```sql theme={null}
SELECT /*++ CARDINALITY (o, 100) */ s.name, o.id
FROM staff s JOIN org o
ON s.deptno = o.deptno
WHERE o.division = 'EASTERN';
```

Here the hint indicates that there are 100 rows in the `org` table (for the purpose of query optimization). It doesn’t say anything about how many of them have `division = ’EASTERN’.`

2. An alias given to a sub-query result. Contains the expected results from it as if it was done **without push down/up**. The sub-query must be aliased, and the alias name passed as the argument of the hint.

For example:

```sql theme={null}
SELECT /*++ CARDINALITY (east_deptnumb, 10000) */
s.name, east_deptnumb.id
FROM staff s JOIN (SELECT o.deptno ,id
                   FROM org o
                   WHERE o.division = 'EASTERN') AS east_deptnumb
ON s.deptno = east_deptnumb.deptno;
```

Specifying multiple hints with the same **object\_name** and different numbers is contradictory and is not allowed.


# Hint - INDEX
Source: https://docs.regatta.dev/sql/hints/other-hints/hint-index



### Synopsis

`INDEX (table_name, { COLUMN column_name | ALL | NONE } )`

This hint affects the use of indexes to evaluate a query. A hint comment can contain one or more INDEX hints per table with column name, or a single INDEX hint for a table with either ALL or NONE.

If `INDEX` hint(s) with **column\_name** exist, those columns’ indexes are used where applicable, and no other indexes of the pertinent table are used.

If an `INDEX` hint with ALL exists for a table, all the indexes of the table are used where applicable.

If an `INDEX` hint with `NONE` exists for a table, none of the table’s indexes is used to evaluate the query.

A combination of **column\_name** and `ALL` for the same table is redundant but valid, a combination of `NONE` and any other `INDEX` hint for the same table is contradictory and results in ignoring the hints.

<Note>*Note: ‘ALL’ is in fact redundant because the current implementation always uses all the indexes it can (given there is no hint telling otherwise). But it’s added here for completeness, and in case the behavior may change at some point to be more dynamically-optimized.*</Note>

### Example

```sql theme={null}
SELECT /*++ INDEX(o, COLUMN deptno), INDEX(s, ALL) */
s.name, o.id
FROM staff s JOIN org o
ON s.deptno = o.deptno
WHERE o.division = 'EASTERN';
```


# Other hints
Source: https://docs.regatta.dev/sql/hints/other-hints/other-hints



Other hints provide guidance to the query optimizer regarding when to use indexes to search within tables and the cardinality (the number of rows) of certain tables or intermediate result sets.


# Overview
Source: https://docs.regatta.dev/sql/hints/overview



SQL, at its core, is a declarative language to access relational data. SQL commands such as SELECT,
INSERT, UPDATE, DELETE specify ***what*** should be done on the DB, not ***how*** it should be done. That leaves a lot of room for the query planner to build an optimal execution plan considering static and dynamic aspects of the query and the involved tables.

Regatta supports various hints that can be specified with the SQL statement that provide guidance to the query planner in cases the client user or application wants to direct the query planner to a specific option according to knowledge it has that the query planner might not have the insight into.

The syntax used to specify the hints is enclosing them with C language style comments and use double plus signs in the beginning of it, i.e. `/*++ <hint> */`.


# Hint for parallelism of distributed operations
Source: https://docs.regatta.dev/sql/hints/parallelism/hints-for-parallelism



With the `DISTRIBUTE` hints, the system will try to distribute the operation specified by the hint across th especified number of nodes. It may not distribute it across more than the given number, but it may distribute it across less than the given number of nodes if there are not enough available nodes.


# Hint - Join distribution
Source: https://docs.regatta.dev/sql/hints/parallelism/join-distribution



### Synopsis

`DISTRIBUTE JOIN ([ join_alias, ] number)`

Define distribution level for the specific `JOIN` by using the keyword **DISTRIBUTE JOIN** followed by the objects to join and the requested distribution number of nodes to execute the join.

Like all the other hints related to joins, this hint requires an explicit join with an alias. If no join is specified, the hint will affect all the joins in the statement.

Specifying multiple hints with the same **join\_alias** and different numbers is contradictory and is not allowed. Specifying multiple hints without **join\_alias** and with different numbers is contradictory and is not allowed.

### Example

```sql theme={null}
SELECT /*++ DISTRIBUTE JOIN (dept_join, 2) */ name, id
FROM (staff s JOIN org o ON s.deptno = o.deptno) as dept_join
WHERE o.division = 'EASTERN';
```


# Hint - Distributed Sorting
Source: https://docs.regatta.dev/sql/hints/parallelism/sorting



### Synopsis

`DISTRIBUTE ORDER BY (number)`

### Example

```sql theme={null}
SELECT /*++ DISTRIBUTE ORDER BY (2) */ s.name, o.id
FROM staff s JOIN org o
ON s.deptno = o.deptno
WHERE o.division = 'EASTERN'
ORDER BY s.name;
```


# Introduction
Source: https://docs.regatta.dev/sql/introduction



This guide contains the Regatta SQL specification.

Regatta implements the PostgreSQL dialect.

**Regatta is compatible with PostgreSQL wherever possible** and as long as it doesn't affect Regatta's performance or functionality.


# ALTER USER
Source: https://docs.regatta.dev/sql/managing-users/alter-user



Modify existing user definitions.

## Synopsis

```
ALTER USER user_name WITH PASSWORD password
```

## Description

The `ALTER USER` command should be used to modify an existing user password.

Currently all the users have the same privileges and can manage users.

## Parameters

**`user_name`**
The name of the user to modify.

**`password`**
The new password string. See [CREATE USER](/sql/managing-users/create-user) for password requirements.

## Examples

Alter the user password:

```sql theme={null}
ALTER USER user1 WITH PASSWORD 'Xr5kg7s3m@aAB'
```

## Compatibility

The `ALTER USER` statement is a Regatta extension as there is no SQL standard for managing users.


# CREATE USER
Source: https://docs.regatta.dev/sql/managing-users/create-user



Create a new user account in the database.

## Synopsis

```
CREATE USER user_name WITH PASSWORD password
```

## Description

`CREATE USER` creates a new user account in the database. Currently all the users have the same privileges and can manage users.

## Parameters

**`user_name`**

The name of the user to create.

The user name should be unique and conform with the [Identifiers Limitations](/sql/appendices/indentifiers-limitations).

**`password`**

The password string.

Password requirements:

* Password length should be between 8 and 100 characters
* A password must contain at least 3 of the following character classes:

  ○ Upper case characters

  ○ Lower case characters

  ○ Numbers

  ○ Symbols. Any of the following symbols can be used. The list is enclosed in double
  quotes. “ ' \~ ! @ # \$ % ^ & \* ( ) \_ - + =   \[ ] \ / \< > , . ; ? ‘ : | (space)”.

## Examples

**Create a new user:**

```sql theme={null}
CREATE USER user1 WITH PASSWORD 'Rdyv#1Cguko';
```

## Compatibility

The `CREATE USER` statement is a Regatta extension as there is no SQL standard for managing users.


# DROP USER
Source: https://docs.regatta.dev/sql/managing-users/drop-user



Remove an existing user.

## Synopsis

```
DROP USER user_name
```

## Description

The `DROP USER` command removes an existing user from the database.

If there is currently a connection to the database by the given user it will be terminated and all running transactions on that connection will be aborted.

Notes:

* A user can remove itself.
* If there is only one user, it cannot be removed.

## Parameters

**`user_name`**

The name of the user to remove.

## Examples

Remove a user:

```sql theme={null}
DROP USER user1;
```

## Compatibility

The `DROP USER` statement is a Regatta extension as there is no SQL standard for managing users.


# Aggregate Functions
Source: https://docs.regatta.dev/sql/sql-functions-and-operators/aggregate-functions/aggregate-functions



Aggregate functions perform the function operation on multiple rows and returns a single value, even when the input contains zero rows.

Aggregate functions can be used in the `SELECT` list, or in a subquery (see examples below).

When used with non-aggregate expression(s), a `GROUP BY` operation is needed on the non-aggregated expression(s). When using `GROUP BY`, each aggregate result is computed over the rows matching that `GROUP BY `column value (see examples below).

The following table shows the available aggregate functions:

Note that all the functions other than `COUNT` return NULL when no rows are selected (`COUNT` returns zero).

| Aggregate function | Return Value | Description |
| :- | :- | :- |
| `AVG(numeric_type)` | `DECIMAL` or `DOUBLE`<br />See notes. | Computes the arithmetic average of all the non-NULL input values. |
| `COUNT(*)` | `BIGINT` | Computes the number of input rows. |
| `COUNT(input_column)` | `BIGINT` | Computes the number of input rows in which the input value is not NULL.<br />See notes. |
| `COUNT(DISTINCT [ any ] column or expression )` | `BIGINT` | Computes the number of unique values in the column or expression with no NULL values.<br />See notes. |
| `MAX(input_column)` | Same data type as the `input_column` | Computes the maximum of the non-NULL input values.<br />Available for any numeric, string and date/time. |
| `MIN(input_column)` | Same data type as the `input_column` | Computes the minimum of the non-NULL input values.<br />Available for any numeric, string and date/time. |
| `SUM(numeric_type)` | `DECIMAL` \| `DOUBLE`<br />See notes. | Computes the sum of the non-NULL input values. |
| `STDDEV(numeric_type)` | `DECIMAL` \| `DOUBLE`<br />See notes. | Returns the sample standard deviation (square root of sample variance) of non-NULL input values.<br />If all records inside a group are NULL, return NULL.<br />Alias to: `STDDEV_SAMP` |

Notes:

1. `AVG()`: When the column data type is integral or `DECIMAL`, the return value is `DECIMAL`. Otherwise, the return value is `DOUBLE`.

2. When the column data type is an approximate numeric data type (`DOUBLE`, `FLOAT`, `REAL`), the return value is `DOUBLE`.

3. `COUNT(input_column)`: When using the `COUNT()` function over a specific column/expression, only the non-NULL values are counted. E.g, if the table has 4 rows and the column values are (`1,2,NULL,4`), the `COUNT()` of this column returns 3.

4. Note that in the case of `COUNT(*)`, all rows are counted, including rows with only NULLs in their column values.

5. `COUNT (DISTINCT)`: The `DISTINCT` can come only once in a given select statement.

6. `SUM()`: The returned value depends on the input data type:

   6.1. When `integral_type` or `DECIMAL`, the returned value is `DECIMAL`

   6.2. When `DOUBLE`, the returned value is `DOUBLE`

7. `STDDEV()`: The return value depends on the column data type:

   7.1. When `integral_type` or `DECIMAL` the return value is `DECIMAL`

   7.2. When `DOUBLE`, the return value is `DOUBLE`.


# Examples
Source: https://docs.regatta.dev/sql/sql-functions-and-operators/aggregate-functions/examples



#### Basic aggregations based on groups of values

```sql theme={null}
SELECT SUM(o_totalprice) AS sum_of_totalprice,
       COUNT(o_totalprice) AS total_number_of_purches,
       AVG(o_totalprice) AS avg_price,
       STDDEV(o_totalprice) AS stddev_from_avg,
       MIN(o_date) AS the_minimum_date,
       MAX(o_date) AS the_maximum_date,
       o_name
FROM orders
GROUP BY o_name
ORDER BY sum_of_totalprice;
```

Calculates the mathematical aggregations for any given different `o_name` value.

#### Using the aggregation as a subquery

```sql theme={null}
SELECT * FROM orders
WHERE o_totalprice = (SELECT MAX(o_totalprice)
                      FROM orders
                     );
```

Returns the row with the highest `o_totalprice`.

#### Using the aggregation with no `GROUP BY` column

```sql theme={null}
SELECT
  SUM((sale_price - purchse_price) * number_of_sold_items) AS total_profit
FROM transactions;
```

Calculate the total profit of all the different transactions.

#### Count by distinct column or expression

```sql theme={null}
SELECT COUNT( DISTINCT c_name) as customers FROM customers;
SELECT COUNT(DISTINCT purchse_price+sale_price) FROM transactions;
```


# Comparison Functions and Operators
Source: https://docs.regatta.dev/sql/sql-functions-and-operators/comparison-function



All the following operators return `BOOLEAN`.

The right arrow (⇒ ) indicates the result.

`datatype` refers to an operand of any supported compatible data type (see [Data Types](/sql/data-types)).

`boolean` refers to an operand of `BOOLEAN` data type.

| Operator | Description and Comments | Example |
| :- | :- | :- |
| `datatype < datatype` | Less than | `8 < 7`<br />⇒ false |
| `datatype > datatype` | Greater than | `8 > 7`<br />⇒ true |
| `datatype <= datatype` | Less than or equal to | `8 <= 8`<br />⇒ true |
| `datatype >= datatype` | Greater than or equal to | `8 >= 8`<br />⇒ true |
| `datatype = datatype` | Equal | `7 = 7`<br />⇒ true |
| `datatype <> datatype` | Not equal | `7 <> 7`<br />⇒ false |
| `datatype != datatype` | Not equal | `7 != 7`<br />⇒ false |
| `datatype BETWEEN datatype AND datatype` | Between (inclusive) the range endpoints.<br />See notes. | `2 BETWEEN 1 AND 3`<br />⇒ true<br />`2 BETWEEN 3 AND 1`<br />⇒ false |
| `datatype NOT BETWEEN datatype AND datatype` | Not between (inclusive) the range endpoints.<br />See notes. | `2 NOT BETWEEN 1 AND 3`<br />⇒ false |
| `datatype BETWEEN SYMMETRIC datatype AND datatype` | Between, after sorting the two endpoint values | `2 BETWEEN SYMMETRIC 3 AND 1`<br />⇒ true |
| `datatype NOT BETWEEN SYMMETRIC datatype AND datatype` | Not between, after sorting the two endpoint values | `2 NOT BETWEEN SYMMETRIC 3 AND 1`<br />⇒ false |
| `datatype IS NULL` | Check whether value is NULL.<br />See notes. | `5 IS NULL`<br />⇒ false |
| `datatype IS NOT NULL` | Check whether value is not NULL.<br />See notes. | `5 IS NOT NULL`<br />⇒ true |
| `boolean IS TRUE` | Check whether boolean expression produces true | `5 < 6 IS TRUE`<br />⇒ false |
| `boolean IS NOT TRUE` | Check whether boolean expression produces false or unknown | `NULL::boolean IS NOT TRUE`<br />⇒ true |
| `boolean IS FALSE` | Check whether boolean expression produces false | `NULL::boolean IS FALSE`<br />⇒ false |
| `boolean IS NOT FALSE` | Check whether boolean expression produces true or unknown | `NULL::boolean IS NOT FALSE`<br />⇒ true |
| `boolean IS UNKNOWN` | Check whether boolean expression produces unknown | `NULL::boolean IS UNKNOWN`<br />⇒ true |
| `boolean IS NOT UNKNOWN` | Check whether boolean expression produces true or false | `NULL::boolean IS NOT UNKNOWN`<br />⇒ false |

#### Comparison Functions and Operators Notes

1. `BETWEEN` operator: it is expected that the first value is lower than the second one. If the first value is
   greater than the second one the result is an empty result set.

   To avoid the need to consider which of the two values is greater than the other, use the keyword `SYMMETRIC`.

   For example:

```sql theme={null}
SELECT o_date FROM orders WHERE (o_order_id BETWEEN SYMMETRIC 10 AND 1);
```

2. `NULL` is not “equal to” `NULL`, therefore, avoid using the expression `= NULL` and use `IS [ NOT ] NULL` instead.


# CAST
Source: https://docs.regatta.dev/sql/sql-functions-and-operators/convert-function/cast



## Synopsis

```sql theme={null}
CAST ( expression AS target_type );
```

Or the operator:

```sql theme={null}
expression :: target_type ;
```

## Description

The `CAST` function or operator are used to explicitly convert a value from one data type into a another data type.

#### Casting Notes

1. Casting `BOOLEAN`:
   * Casting strings: Only valid strings - ‘true’, ’false’, ’t’, ’f’  (case insensitive) - can be casted.
   * Casting numbers: Only `integral_types` can be converted. Note that all integers except 0 are converted to ‘true’. Zero is converted to ‘false’.
2. When casting different string length without specifying the needed length, the result value is `VARCHAR(max)`.

## Parameters

**`expression`**

The expression can be a constant or a column or any expression that resolves to a single value.

**`target_type`**

The target\_type is the data type to which you want to convert the above expression to, as long as it is
qualified as a valid convert.

## Examples

Convert literal representing a `DATE` into `TIMESTAMP`:

```sql theme={null}
SELECT CAST('2022-12-12' AS TIMESTAMP);
```

Returns: `2022-12-12 00:00:00`. Note that the time was added.

Convert literal representing an `INT` into `STRING`:

```sql theme={null}
SELECT 234567::STRING;
```

Returns: '234567'

Convert literal representing `numeric_type` into `DECIMAL`:

```sql theme={null}
SELECT CAST(10.4572 AS DECIMAL);
```

Returns: 10.4572

Convert the column value `o_date` into `TIMESTAMP`:

```sql theme={null}
SELECT CAST(o_date AS TIMESTAMP) FROM orders;
```


# Date and Time Formatting Functions
Source: https://docs.regatta.dev/sql/sql-functions-and-operators/convert-function/date-time-format-functions



The following table describes the functions that convert strings to specific data types and vice versa. Those functions are used when the required input/output format of a specific `DATE/TIMESTAMP` is different from the default `DATE/TIMESTAMP` formats.

The default `DATE` format is: `YYYY-MM-DD`

The default `TIMESTAMP` format is: `YYYY-MM-DD HH24:MI:SS.MS`

In all the functions below, the first argument is the value to be converted and the second argument is a template that defines the output or input format. The input string is of one of the [Character types](/sql/data-types/character-types).

| Function | Description and Comments | Example |
| :- | :- | :- |
| `TO_DATE(STRING, format)` | Converts string to `DATE` according to the given format<br />Returns `DATE` | `to_date('21 Jun 2023', 'dd mon YYYY')`<br />=> 2023-06-21 |
| `TO_TIMESTAMP(STRING, format)` | Converts string to `TIMESTAMP` according to the given format<br />Returns `TIMESTAMP` | `TO_TIMESTAMP('_2023-12-13_ 04:05:06.789', 'yyyy-dd-mm hh24:mi:ss.ms')`<br />=> 2023-12-13 04:05:06.789 |
| `TO_CHAR(DATE, format)` <br /> `TO_CHAR(TIMESTAMP, format)` | Converts a `DATE` or `TIMESTAMP` data type to a string in the given format<br />Returns `VARCHAR`<br />See notes | `TO_CHAR(date '2022-12-12', 'yy-mm-dd')`<br />=> 22-12-12<br /><br />`TO_CHAR(TIMESTAMP '2022-12-24 16:27:30', 'dd-mm-yyyy HH12:MI:SS am')`<br />=> 24-12-2022 04:27:30 pm |

Template Patterns for Date/Time Formatting:

| Pattern | Description and Comments |
| :- | :- |
| `HH` | hour of day (01-12) |
| `HH12` | hour of day (01-12) |
| `HH24` | hour of day (00-23) |
| `MI` | minute (00-59) |
| `SS` | second (00-59) |
| `MS` | millisecond (000-999) |
| `US` | microsecond (000000-999999) |
| `YYYY` | year (4 digits) |
| `YY` | last 2 digits of year |
| `MM` | month number (01-12) |
| `Mon` | First three letters of the month ('Jan', 'Feb', and so on) |
| `DD` | day of month (01-31) |
| `AM`, `am`, `PM`, `pm` | meridiem indicator |

## Examples

Convert the input format to a DATE/TIMESTAMP that can identified as such:

```sql theme={null}
SELECT TO_DATE('2012-JAN-12','YYYY-MON-DD');
SELECT TO_DATE('20/12/12','YY/MM/DD');
SELECT TO_DATE('2012.07.23', 'YYYY.MM.DD');
SELECT TO_DATE('20200526','YYYYMMDD');
SELECT TO_TIMESTAMP('20/12/12 17:12:12.45','YY/MM/DD HH24:MI:SS.MS');
SELECT TO_TIMESTAMP('2010-Aug-09 12:00:01 PM' , 'yyyy-Mon-dd HH:MI:SS PM');
```

Convert the DATE/TIMESTAMP to the desired output format:

```sql theme={null}
SELECT TO_CHAR(TIMESTAMP '2022-12-12 16:27:30.41', 'dd-mm-yyyy HH12:MI:SS
am');
SELECT TO_CHAR(date_column, 'YY-MM-DD HH:MI:SS.MS AM') FROM my_table;
```


# Date/Time Functions and Operators
Source: https://docs.regatta.dev/sql/sql-functions-and-operators/date-time-functions-operators/date-time-functions-operators



The following tables show the Date/Time operators that are available for the `DATE/TIME/TIMESTAMP` data
types. See [Date/Time types](/sql/data-types/date-time-types).

All the following operators and functions return their values without a time zone.

### Date/Time Functions

| Function | Description and Comments | Example |
| :- | :- | :- |
| `CURRENT_DATE` | Return the date in which the current transaction started<br />Returns `DATE` | `SELECT CURRENT_DATE;`<br />=> 2012-03-26 |
| `CURRENT_TIME` | Return current time (start of current transaction)<br />Returns `TIME` | `SELECT CURRENT_TIME;`<br />=> 11:31:46.903633 |
| `CURRENT_TIMESTAMP` | Returns current timestamp (start of current transaction)<br />Returns `TIMESTAMP`<br />See notes | `SELECT CURRENT_TIMESTAMP;`<br />=> 2012-03-26 11:31:46.903633 |
| `NOW()` | Returns current date and time (start of current transaction)<br />Returns `TIMESTAMP`<br />See notes | `SELECT NOW();`<br />=> 2012-03-26 11:31:46.903633 |
| `EXTRACT(unit FROM TIMESTAMP)` | Extracts the specified unit (date or time part) from a date, time, or timestamp<br />Returns `DECIMAL`<br />See notes | `SELECT EXTRACT(YEAR FROM TIMESTAMP '2012-03-26 11:31:46.903633');`<br />=> 2012<br /><br />`SELECT EXTRACT('day' FROM DATE '2012-03-26');`<br />=> 26 |
| `DATE_PART(unit, TIMESTAMP)` | Similar to `EXTRACT()`<br />Returns `DECIMAL`<br />See notes | `SELECT DATE_PART('day', TIMESTAMP '2012-03-26 11:31:46.903633');`<br />=> 26<br /><br />`SELECT DATE_PART('minute', TIME '11:31:46.903633');`<br />=> 31 |

Notes:

1. `NOW()` and `CURRENT_TIMESTAMP`: When using those functions as part of an `INSERT/UPDATE` command, the returned value is converted into the column data type it is writing to. When writing into `TIME` data type, only the time is written, when writing into `DATE` data type, only the date is written, and when writing to `TIMESTAMP` data type, the whole timestamp is written.
   Note that `NOW()` and `CURRENT_TIMESTAMP` refer to the time the transaction starts, and not to each statement time inside the transaction
2. `DATE_PART()` and `EXTRACT()` provide similar functionality and accept the same set of units. However, `DATE_PART` requires the unit argument to be passed as a string (e.g. ‘YEAR”, ‘day’), while `EXTRACT()` also accepts these units as keywords. The following units are supported:

| Time Units | Date Units |
| :- | :- |
| `MICROSECONDS` | `DAY` |
| `MILLISECONDS` | `WEEK` |
| `SECOND` | `MONTH` |
| `MINUTE` | `QUARTER` |
| `HOUR` | `YEAR` |
| | `DECADE` |
| | `CENTURY` |
| | `MILLENNIUM` |

For a `TIMESTAMP` object, both the Date and Time units are supported.

### Date/Time Operators

| Operator | Description and Comments | Example |
| :- | :- | :- |
| `DATE + INT => DATE` | Add a number of days to the given date | `date '2022-12-31' + integer '365'`<br />=> 2023-12-31 as DATE |
| `DATE + TIME => TIMESTAMP` | Add the time of the day to a given date | `date '2022-12-31' + time '01:00:00'`<br />=> 2022-12-31 01:00:00 as TIMESTAMP |
| `DATE - DATE => INT` | Return the number of days between two dates | `date '2022-12-12' - date '2022-01-31'`<br />=> 315 as INT |
| `DATE - INT => DATE` | Subtract days from a given date | `date '2022-12-12' - integer '4'`<br />=> 2022-12-08 as DATE |


# Mathematical Functions
Source: https://docs.regatta.dev/sql/sql-functions-and-operators/maths-functions-operators/maths-functions



The following table shows the mathematical functions that are available for the standard numeric types.

In the table below, the returned data type or value appears following the right arrow (⇒) sign.

| Function | Description and Comments | Example |
| :- | :- | :- |
| `ABS(numeric_type) => numeric_type` | Absolute | `ABS(-88)`<br />=> 88 |
| `CEIL(DECIMAL) => DECIMAL` <br /> `CEIL(DOUBLE) => DOUBLE` | Nearest integer greater than or equal to argument<br />Alias: CEILING() | `CEIL(35.78)`<br />=> 36<br />`CEIL(-35.18)`<br />=> -35 |
| `DIV(y numeric_type, x numeric_type) => int_type` | Integer quotient of y/x | `DIV(18, 3)`<br />=> 6<br />`DIV(18, 5)`<br />=> 3 |
| `EXP(DECIMAL) => DECIMAL` <br /> `EXP(DOUBLE) => DOUBLE` | Exponential | `EXP(1.0)`<br />=> 2.7182818284590452 |
| `FLOOR(DECIMAL) => DECIMAL` <br /> `FLOOR(DOUBLE) => DOUBLE` | Nearest integer less than or equal to argument<br />See notes. | `FLOOR(56.8)`<br />=> 56<br />`FLOOR(-56.8)`<br />=> -57 |
| `LN(DECIMAL) => DECIMAL` <br /> `LN(DOUBLE) => DOUBLE` | Natural logarithm | `LN(2.0)`<br />=> 0.6931471805599453 |
| `LOG(DECIMAL) => DECIMAL` <br /> `LOG(DOUBLE) => DOUBLE` | Base 10 logarithm | `LOG(1000)`<br />=> 3 |
| `LOG(b DECIMAL, x DECIMAL) => DECIMAL` | Logarithm of x to base b | `LOG(2.0, 64)`<br />=> 6.0000000000000000 |
| `LOG10(DECIMAL) => DECIMAL` <br /> `LOG10(DOUBLE) => DOUBLE` | Base 10 logarithm, (same as LOG() with a single argument). | `LOG10(1000)`<br />=> 3 |
| `MOD(y DECIMAL, x DECIMAL)` | Modulo<br />See notes. | `MOD(5, 3)`<br />=> 2 |
| `PI() => DOUBLE` | Return the value of PI. | `PI()`<br />=> 3.141592653589793 |
| `POWER(x DECIMAL, y DECIMAL) => DECIMAL` <br /> `POWER(x DOUBLE, y DOUBLE) => DOUBLE` | x raised to the power of y | `POWER(27, 2)`<br />=> 729 |
| `ROUND(DECIMAL [s INT]) => DECIMAL` <br /> `ROUND(DOUBLE) => DOUBLE` | Rounds to the nearest integer. s represents the optional scale accuracy | `ROUND(67.2)`<br />=> 67<br />`ROUND(67.8)`<br />=> 68 |
| `SIGN(DECIMAL) => DECIMAL` <br /> `SIGN(DOUBLE) => DOUBLE` | Sign of the argument (-1, 0, or +1) | `SIGN(0), SIGN(-2), SIGN(5)`<br />=> 0, -1, 1 |
| `SQRT(DECIMAL) => DECIMAL` <br /> `SQRT(DOUBLE) => DOUBLE` | Square root | `SQRT(9)`<br />=> 3 |
| `TRUNC(DECIMAL) => DECIMAL` <br /> `TRUNC(DOUBLE) => DOUBLE` | Truncates to integer (towards zero) | `TRUNC(67.89)`<br />=> 67 |
| `TRUNC(x DECIMAL, s INT) => DECIMAL` | Truncates x to s decimal places. | `TRUNC(67.89, 1)`<br />=> 67.8 |

Note: `MOD()`: Arguments can be either `integral_type` (`INT`, `BIGINT`, `SMALLINT`) or `DECIMAL`. It cannot be floating-point numbers (`FLOAT` or `REAL`)


# Mathematical Functions and Operators
Source: https://docs.regatta.dev/sql/sql-functions-and-operators/maths-functions-operators/maths-functions-operators



Conventions for all the Mathematical Functions and Operators sections:

* **integral\_type** represents fixed full number data types (`SMALLINT`, `INTEGER`, and `BIGINT`).
* **numeric\_type** refers to all the available [Numeric types](/sql/data-types/numeric-types).
* `DOUBLE` represents approximate numeric data types (`DOUBLE`, `FLOAT`, `REAL`).
* `DECIMAL` represents an exact numeric data type (`NUMERIC`).


# Mathematical Operators
Source: https://docs.regatta.dev/sql/sql-functions-and-operators/maths-functions-operators/maths-operators



The following table shows the mathematical operators that are available for the standard numeric types. Unless noted otherwise, all the operators return the same data type as their argument(s).

The right arrow (⇒ ) is used to indicate the result.

| Operator | Description and Comments | Example |
| :- | :- | :- |
| `numeric_type + numeric_type` | Addition | `10 + 5`<br />=> 15 |
| `+ numeric_type` | Unary plus (no operation) | `+10.5`<br />=> 10.5 |
| `numeric_type - numeric_type` | Subtraction | `10 - 5`<br />=> 5 |
| `- numeric_type` | Negation | `-10`<br />=> (-10) |
| `numeric_type * numeric_type` | Multiplication | `10 * 5`<br />=> 50 |
| `numeric_type / numeric_type` | Division<br />See also DIV(). See notes. | `5 / 2` => 2<br />`6 / 2` => 3 |
| `numeric_type % numeric_type` | Modulo<br />See also MOD(). See notes. | `5 % 3`<br />=> 2 |
| `numeric_type ^ numeric_type` | Exponentiation<br />See also EXP(). See notes. | `2 ^ 3`<br />=> 8<br />`2.0 ^ (3.0 * 3.0)`<br />=> 134217728.0 |
| \|/ numeric\_type | Square root | \|/ 9.0<br />=> 3.0 |
| `@ numeric_type` | Absolute<br />See also `ABS()` | `@ -66.7`<br />=> 66.7 |

Notes:

1. Division operator (/): Dividing `integral_types` returns the quotient of the integer division. To perform real numbers division, at least one of the operands should be non-integer.

   For example:\
   `SELECT 5/2;`

   Result: 2

   `SELECT 5/2::DECIMAL;`
   `SELECT 5.0/2;`

   Result: 2.5000000000000000
2. Exponentiation operator (^): By default, multiple uses of ^ are associated left to right.

   For example:

   `SELECT 2 ^ (3 ^ 3);`

   Result: 134,217,728

   `SELECT 2 ^ 3 ^ 3; `

   Result: 512
3. Modulo operator(`%`): Arguments can be either `integral_type` (`INT`, `BIGINT`, `SMALLINT`) or `DECIMAL`. It cannot be floating-point numbers (`FLOAT` or `REAL`).


# SQL Functions and Operators
Source: https://docs.regatta.dev/sql/sql-functions-and-operators/sql-functions-and-operators



This section describes all the SQL functions and operators supported by Regatta.

A general limitation for functions that accept a variable number of parameters: The number of parameters is limited to a maximum of 32.


# String Functions and Operators
Source: https://docs.regatta.dev/sql/sql-functions-and-operators/string-functions-operators



This following table describes the functions and operators for examining and manipulating string values (`CHAR` and `VARCHAR` data types). See [Character types](/sql/data-types/character-types).

Except where noted, these functions and operators are declared to accept and return type `VARCHAR`.

Notes:

1. Text comparison is case-sensitive (e.g: ‘Regatta’ `<>` ’REGATTA’ `<>` ‘regatta’ and 'A' \< 'B' \< 'a' \< 'b').
2. Values of type `CHAR` are converted to `VARCHAR` before the function or operator is applied, resulting in stripping any trailing spaces in the character value.

| Function | Description and Comments | Example |
| :- | :- | :- |
| `STRING \|\| STRING` | Concatenate of two strings. See also CONCAT(). See notes. | 'This in an ' \|\| 'example' <br /> => This in an example |
| `CONCAT(STRING [, STRING [, ...]])` | Concatenation of all the string arguments. See notes. | `CONCAT('Hello', ' it', ' is me')`<br /> => Hello it is me |
| `LOWER(STRING)` | Converts the string to all lowercase | `LOWER('Hello')`<br /> => hello |
| `UPPER(STRING)` | Converts the string to all uppercase | `UPPER('Hello')`<br /> => HELLO |
| `POSITION(sub_string IN STRING)` | Return the first starting index of the specified substring within the string, or zero if it's not present. Returns an INT | `POSITION('o' IN 'Hello')`<br /> => 5 |
| `SUBSTRING(STRING start_int [, count_int] [FROM start_int] [FOR count_int])` | Extracts the substring of string starting at the start\_int position if that is specified, and stopping after count\_int characters if that is specified.<br /> If start\_int is not specified - default to 1.<br /> If count\_int is not specified - default is until the end of the string.<br /> If start\_int is less than 1, the difference (1 - start\_int) is subtracted from count\_int and the result starts from position 1 | `SUBSTRING('123456789' FROM 4 FOR 4)`<br /> => 4567<br />`SUBSTRING('123456789' FOR 2)`<br /> => 12 <br />`SUBSTRING('123456789' FROM 4)`<br />=> 456789 <br />`SUBSTRING('123456789' FROM -1 FOR 4)`<br />=> 12 |
| `SUBSTRING(STRING start\_int FOR count\_int)` | Alias of SUBSTRING | `SUBSTRING('My example', 3, 5)`<br />=> exam |
| `TRIM( [LEADING \| TRAILING \| BOTH] [trim_chars] FROM string)` | Removes the longest string containing only characters in `trim_chars` (a space by default) from the start, end, or both ends (`BOTH` is the default) of `string`. | `TRIM(LEADING 'xx' FROM 'xxhello')`<br />=> hello <br />`TRIM(FROM ' hello ')`<br />=> hello (no spaces) <br />`TRIM(BOTH 'xyz' FROM 'xthis_is_mezy')`<br />=> this\_is\_me |
| `BTRIM(STRING [, trim_chars])` | Alias of TRIM with BOTH | `BTRIM('this_is_mez', 'xz')`<br />=> this\_is\_me |
| `LTRIM(STRING [, trim_chars])` | Alias of TRIM with LEADING | `LTRIM('xthis_is_mex', 'x')`<br />=> this\_is\_mex |
| `RTRIM(STRING [, trim_chars])` | Alias of TRIM with TRAILING | `RTRIM('xthis_is_mex', 'x')`<br />=> xthis\_is\_me |
| `LEFT(STRING, n_int)` | Returns the first n\_int characters in the string, or when n\_int is negative, returns all but last n\_int characters | `LEFT('This is me', 8)`<br />=> This is <br />`LEFT('This is me', -8)`<br />=> Th |
| `RIGHT(STRING, n_int)` | Returns the last n\_int characters in the string, or when n\_int is negative, returns all but last n\_int characters | `RIGHT('This is me', 8)`<br />=> is me <br />`RIGHT('This is me', -8)`<br />=> me |
| `LENGTH(STRING)` | Returns the number of characters in the string. Returns an INT. See notes. | `LENGTH('This is me')`<br />=> 10 |
| `LPAD(STRING, length_int [, fill_string])` | Extends the string to length\_int length by prepending the fill\_string (a space by default). Returns an INT. See notes. | `LPAD('Hello', 10, '-')`<br />=> -----Hello <br />`LPAD('Hello', 10)`<br />=>      Hello (5 spaces) |
| `RPAD(STRING, length_int [, fill_string])` | Extends the string to length\_int length by appending the fill\_string (a space by default). See notes. | `RPAD('Hello', 10, '-')`<br />=> Hello----- |
| `REPEAT(STRING, n_int)` | Repeats string the specified n\_int times | `REPEAT('Hello', 3)`<br />=> Hello\_Hello\_Hello |
| `REPLACE(STRING, from_text, to_text)` | Replaces all occurrences in string of substring from\_text with substring to\_text | `REPLACE('Hello this is me', 'me', 'you')`<br />=> Hello this is you |
| `REVERSE(STRING)` | Reverses the order of the characters in the string | `REVERSE('Hello')`<br />=> olleH |
| `string [NOT] LIKE pattern [ESCAPE escape-char]` | Matches (or not) string expressions by patterns. The match is case sensitive. Returns BOOLEAN. See notes. | `'This is me' LIKE 'This%'`<br />=> true <br />`'This is me' LIKE '%is%'`<br />=> true <br />`'20% discount' LIKE '20!%' ESCAPE '!'`<br />=> true |

Notes:

1. The string concatenation operator (||) accepts non-string input, so long as at least one input is of string type. Using the operator with `NULL` as one of the operator inputs, returns NULL. For example: `SELECT 'Hello' || NULL || ' this is me';` Return: `NULL`
2. `CONCAT():`
   * All values are implicitly converted to strings
   * `NULL` arguments are ignored. For example: `SELECT CONCAT('Hello', NULL, ' this is me');` Return: 'Hello this is me'
3. `LPAD()` (`RPAD()`): If the string is already longer than the requested `length_int` then it is truncated on the right (left).
4. `LIKE` and `NOT LIKE`: a . String match is case sensitive b . escape character should be a single character. c. Possible patterns:
   * An underscore (\_): stands for a single character
   * A percent sign (%) stands for sequence of zero or more characters
   * If the pattern does not contain percent signs (%) or underscores (\_), then the \[`NOT`] `LIKE` operator matches the full string.


# IN and NOT IN
Source: https://docs.regatta.dev/sql/sql-functions-and-operators/subquery-expressions/not-in/not-in



The `IN` and `NOT IN` operators check if an expression is included or not included in the values returned by a subquery.

## Synopsis

***

```sql theme={null}
expression [NOT] IN (subquery)
row_constructor IN (subquery)
```

## Description

***

The left-hand expression or `row_constructor` are evaluated and compared to each row of the subquery result.

The result of `IN` is “true” if any equal subquery row is found. The result is “false” if no equal row is found. Vice versa, the result of `NOT IN` is “false” if any equal subquery row is found. The result is “true” if no equal row is found. Those two cases include the case where the subquery returns no rows.

## Parameters

***

`expression`

A column\_name or an expression to be compared with the subquery. The subquery (in the right-hand side in the parenthesized) must return exactly one column.

`row_constructor`

A composite value that builds a row value. The subquery (in the right-hand side in the parenthesized) must return the exact same number of columns.

The constructed row columns order should match the subquery columns data types.

## Examples

***

Return the rows that their column value is included in the subquery:

```sql theme={null}
SELECT * FROM customers
WHERE c_custkey IN (SELECT o_custkey FROM orders
                    WHERE o_date>'2022-12-12');
```

Return the rows that their expression is not included in the subquery values:

```sql theme={null}
SELECT * FROM orders
WHERE o_date NOT IN ('2022-12-12','2022-11-12');
```

Return the rows based on a row constructor:

```sql theme={null}
SELECT *
FROM orders
WHERE (o_totalprice,o_name) IN
                            (SELECT MAX(o_totalprice),o_name
                             FROM orders GROUP BY o_name
                            );
```


# Subquery Expressions
Source: https://docs.regatta.dev/sql/sql-functions-and-operators/subquery-expressions/subquery-expressions



This section describes the available subquery expressions.

Note that subqueries can be used only in the `FROM` or the `WHERE` clauses.


# UUID Functions and Operators
Source: https://docs.regatta.dev/sql/sql-functions-and-operators/untitled-page



The following functions are supported for generating UUIDs and extracting parts of UUIDs:

| Function | Description | Example |
| - | - | - |
| `uuidv4()` → UUID | Generates a version-4 UUID | `uuidv4()`<br />=> `b42410ee-132f-42ee-9e4f-09a6485c95b8` |
| `gen_random_uuid()` → UUID | Same as `uuidv4()` | |
| `uuid_extract_timestamp(uuid)` → TIMESTAMP | Extracts a timestamp from a UUID of version 1 or 7.<br />For other versions, this function returns null. | `uuid_extract_timestamp('019535d9-3df7-79fb-b466-​fa907fa17f9e'::uuid)` => `2025-02-23 21:46:24.503` |
| `uuid_extract_version(uuid)` → SMALLINT | Extracts the version from a UUID of one of the variants described by [RFC 9562](https://datatracker.ietf.org/doc/html/rfc9562).<br />For other variants, this function returns null. | `uuid_extract_version('41db1265-8bc1-4ab3-992f-​885799a4af1d'::uuid)` => `4` |


# SQL Syntax Conventions
Source: https://docs.regatta.dev/sql/sql-syntax-convention



The following conventions are used in the synopsis of a command:

1. brackets **\[ ]** indicate optional parts.
2. Braces`{}`and vertical lines **|** indicate that you must choose one alternative.
3. Dots **...** mean that the preceding element can be repeated.
4. ***lowercase bold italic*** font indicates a placeholder which should be replaced with an actual value e.g: ***table\_name***, ***parameter\_name***, etc.
5. `UPPERCASE COURIER NEW` font indicates SQL language literals (e.g. `SELECT`)
6. `lowercase courier new` font indicates parameter names (e.g. `devices`)

All other symbols, including parentheses, should be taken literally.


# Modules
Source: https://docs.regatta.dev/sql/system-management/modules



The Regatta system operates as a cluster of modules. Modules run on nodes, which are physical or virtual computer servers or containers.

Each module in Regatta has a role. Following is a brief description of those roles.

`RDB`

The RDB modules hold the database data and perform the transaction processing. A Regatta system must have at least one RDB module in order to operate on relational data.

`DCM`

The DCM module acts as the Database Catalog Manager. It manages the data definitions including tables, indexes and so on. A Regatta system must have exactly one DCM module.

`SEQUENCER`

The SEQUENCER module serves a system-wide sequence of time points, effectively acting as a global logical clock server. A Regatta system must have exactly one SEQUENCER module.

`GDD`

The GDD module serves as a Global Deadlock Detector, detecting cycles of dependencies among distributed transactions that could cause deadlocks. A Regatta system must have exactly one GDD module.

In order to activate the Regatta system, it must have exactly one <Tooltip>DCM </Tooltip> module, one SEQUENCER module, one <Tooltip>GDD </Tooltip> module and at least one <Tooltip>RDB</Tooltip> module. Multiple modules may be deployed on the same node. However, at least for the RDB modules the common practice is to deploy each module in a separate node for scalable performance.

### States

A module can be in one of the following states:

`ACTIVE`: The module is active and can perform transaction processing.

`DOWN`: The module is down and cannot perform transaction processing. It is a stable state, and the module will stay in that state until a `MODULE START` command is issued.

`STARTING`: The system is in the process of starting the module, either as part of `SYSTEM START` or `MODULE START` command processing.

`SHUTTING DOWN`: The module is in the process of shutting down following a `MODULE SHUTDOWN` command.

### Commands

The module commands have the general form: `MANAGE MODULE command [ parameters ]` .

#### MODULE ADD

This command adds one or more modules to the system.

This command is available only when the system state is `SETUP`.

**Synopsis**

```text theme={null}
MANAGE MODULE ADD ( ( 
	NODE node_name 
	NAME module_name 
	[ DESCRIPTION description ] 
	ROLE role_name 
	NETWORK ( net_address [, ... ] ) 
	[ NUM_CPUS number ] 
	[ RAM_SIZE size_in_mb ] 
	[ STORAGE_DEVICE (device_name [, ... ]) ] 
	[ SERVICE_PORT port_number ] 
	[ VERSION version ] 
) [ , ... ] )

where net_address is:

( { EXTERNAL | INTERNAL } IP ip_addr PORT port_num )
```

**Parameters**

`NODE`

Required parameter. The name of the node in which the module is added. The module will be run always on that node, unless it is moved with the `MODULE MOVE` command.

`NAME`

Required parameter. This name must be unique among all of the system’s modules, and will be used to identify the modules in queries and other commands.

`DESCRIPTION`

Optional parameter. Free text that is added to the module.

`ROLE`

Required parameter. The role of the module. See description of the module roles above.

`NETWORK`

Required parameter. Contains a list of up to 4 external addresses and 4 internal addresses. Must contain at least one address (either internal or external). For each address, there are 2 required parameters – `IP `and `PORT`.

`NUM_CPUS`

Optional parameter. The number of threads that the module will spawn for parallel processing.

If this parameter is not specified, the number of threads will be based on the inspected number of CPU cores in order to maximize parallel processing.

`RAM_SIZE`

Optional parameter. The amount of RAM (in MB) that the module may use. If not specified – Regatta may use all the available RAM.

<Icon icon="circle-exclamation" />  If the intention is to add more modules in the same node, this parameter must be specified and set to a value that leaves out RAM for the additional modules, because the `RAM_SIZE `parameter cannot be decreased after the module is added. Adding a module without specifying this parameter implies that no other modules can be added in this node later.

`STORAGE_DEVICE`

Optional parameter. A comma-separated list of one or more names of storage devices that the module will use to store database data and metadata. The specified devices must be accessible in the given node.

For this version of Regatta, at least one storage device must be specified for an RDB module, and no storage device should be specified for the other module roles.

`SERVICE_PORT`

Optional parameter. The port number to be used by the module for service purposes.

`VERSION`

Optional parameter. By default, the module gets the version from the system. This parameter is intended for use during upgrade.

**Output**

The output of the command is tabular with a row for each module included in the command. The following table lists the output columns.

| Name | Type | Description |
| - | - | - |
| NAME | String | The name of the module |
| ID | Number | The identifier Regatta assigned to the module. (N/A if adding the module failed.) |
| STATUS | String | SUCCESS or FAILURE. If FAILURE, the module was not added |
| ERROR\_REASON | String | In case of failure, this column contains a description of the failure reason. |

#### MODULE START

This command starts a module.

**Synopsis**

```text theme={null}
MANAGE MODULE START module_name
```

This command is allowed only when the system state is `ACTIVE`.

The command is accepted only if the module state is `DOWN`. The result of the command is a transition of the module state to `STARTING`.

#### MODULE SHUTDOWN

This command shuts down a module.

**Synopsis**

```text theme={null}
MANAGE MODULE SHUTDOWN module_name
```

This command is allowed only when the system state is `ACTIVE`.

The command returns after the module state has transitioned to `DOWN`.

#### MODULE RESTART

This command restarts a module.

**Synopsis**

```text theme={null}
MANAGE MODULE RESTART module_name
```

This command is allowed only when the system state is `ACTIVE `and the module state is `ACTIVE `or `STARTING`.

The command returns after the module state has transitioned to `STARTING`.

#### MODULE MODIFY

This command modifies the attributes of a module.

**Synopsis**

```text wrap theme={null}
MANAGE MODULE MODIFY module_name
	[ NETWORK { ADD | REMOVE | SET } ( net_address [, ...] ) ] 
	[ RAM_SIZE size_in_mb ] 
	[ NUM_CPUS [ number ] ] 
	[ SERVICE_PORT port_number ] 
	[ VERSION version ] 
	[ DESCRIPTION description ] 
	[ attr_name attr_value [ ... ] ]

where net_address is: 
	( { EXTERNAL | INTERNAL } IP ip_addr PORT port_num )
```

This command is only allowed when the system is in SETUP state, with the following exception: It is allowed to use it in ACTIVE state with only the NETWORK parameter. In this case the module’s state must be DOWN.

**Parameters**

`NETWORK`

The `NETWORK `clause includes one or more network addresses. It can come with either of the following directives:

* `ADD `– Adds the given network addresses to the list of existing addresses.
* `REMOVE `– Remove each given network address from the list of existing addresses. Each removed network address must be an exact match to an existing one.
* `SET `– Remove all the existing network addresses and replace them with the given network addresses.

`NUM_CPUS`

Optional parameter. The number of threads that the module will spawn for parallel processing. If this parameter is set without a number, the number of threads will be based on the number of CPU cores bound to the module in order to maximize parallel processing.

`RAM_SIZE`

Optional parameter. The amount of RAM (in MB) that the module may use.

<Icon icon="circle-exclamation" /> The RAM size can only be increased. Specifying a value lower than the currently used size will result in an error.

`SERVICE_PORT`

Optional parameter. The port number to be used by the module for service purposes.

`VERSION`

Optional parameter. By default, the module gets the version from the system. This parameter is intended for use during upgrade.

`DESCRIPTION`

Optional parameter. Free text that is added to the module.

#### MODULE MOVE

This command moves a module, along with the device(s) assigned to it, to another node.

The command is accepted only if the system state is `ACTIVE` or `SETUP`, and the modules state is `DOWN`.

Moving a module to another node requires either use shared storage devices that can be made accessible from multiple nodes, or copying over the data from the module’s device(s) in the origin node to the storage device(s) in the destination node. (That copying must be done before the `MODULE MOVE` command and is not done as part of this command.)

**Synopsis**

```text wrap theme={null}
MANAGE MODULE MOVE module_name
	NODE node_name 
	[ NETWORK ( net_address [, ... ] )
```

**Parameters**

`NODE`

Required parameter. The name of the target node to which the module is moved.

`NETWORK`

Optional parameter. Contains a list of up to 4 external addresses and 4 internal addresses. Must contain at least one address (either internal or external). For each address, there are 2 required parameters – `IP `and `PORT`.

#### MODULE SHOW

This command shows the attributes of modules.

**Synopsis**

```text wrap theme={null}
MANAGE MODULE SHOW [ FILTER { STATE module_state | 
							  NODE node_name } ] 
				   [ DETAILED ] 
MANAGE MODULE SHOW ATTR module_name [ FILTER ATTR attribute_name ]
```

This command has two variants:

1. A list of modules and their attributes
2. A detailed list of attributes for a specific module

**Parameters**

`FILTER`

Filter the result by some criterion. In the first variant of this command, modules can be filtered by role, by state or by node name. In the second variant, attributes can be filtered by attribute name. Currently the filtering is by exact match, no support for regular expressions. Only one filter can be specified.

`DETAILED`

Show a more detailed list of attributes for each module. See more details in the Output section below.

**Output**

For the first variant, the output of the command is a tabular, with each row representing a module. The following table lists the columns of the output. If the `DETAILED `option is specified, then in addition to those columns, all the attributes listed below in the output of `MODULE SHOW ATTR` command are also included for each module. In this variant, only their current values are shown and not their set values.

| Name | Type | Description |
| - | - | - |
| NAME | String | The name of the module |
| ID | Number | The identifier of the module. Assigned by Regatta |
| STATE | String | The module’s state |
| ROLE | String | The role of the module |
| NODE\_NAME | String | The node in which the module resides |
| INTERNAL\_NET | String | A comma-separated list of internal network addresses in the form of `<ip_addr>:<port>` |
| EXTERNAL\_NET | String | A comma-separated list of external network addresses in the form of `<ip_addr>:<port>` |

For the second variant, the output of the command is tabular, with each row representing an attribute of the specified module. The following table lists the columns of the output.

| Name | Type | Description |
| - | - | - |
| NAME | String | The name of the attribute |
| CURRENT\_VALUE | String | The current value of the attribute |
| SET\_VALUE | String | The set value of the attribute – if different from the current value <Icon icon="circle-exclamation" /> |
| REASON | String | If the current value differs from the set value, this column contains a reason for the difference. (For example, “Restart required”) |

<Icon icon="circle-exclamation" /> The SET\_VALUE column is displayed only if it’s different than the current value. If it’s equal to the current value, the output cell is empty.

The following table lists the rows included in the output:

| Name | Description | |
| - | - | - |
| NAME | The name of the module | |
| ID | The identifier of the module. Assigned by Regatta. | |
| STATE | The module’s state | |
| ROLE | The module’s role | |
| NODE\_NAME | The name of the node in which the module resides | |
| INTERNAL\_NET | A comma-separated list of internal network addresses in the form of `<ip_addr>:<port>` | |
| EXTERNAL\_NET | A comma-separated list of external network addresses in the form of `<ip_addr>:<port>` | |
| DESCRIPTION | A description of the module (if exists). | |
| STATE\_REASON | If the module is in `DOWN `state, this column will contain the reason for it. | |
| RAM\_SIZE | The RAM size (in MB) that the module may use | |
| NUMA\_NODE | The NUMA node number that the module’s process is bound to | |
| CPU | The list of CPUs that the module’s process is bound to | |
| NUM\_THREADS | The number of threads that the module spawns for parallel processing | |
| SERVICE\_PORT | The port number for Regatta support connection | |
| EXTERNAL\_SERVICE\_NET | External network address for Regatta service connection, in the form of `<ip_addr>:<port>`<Icon icon="circle-exclamation" /> | |
| NUM\_DOWN | The number of times the module was shut down since the system last became active. | |
| NUM\_CRASHES | The number of times the module crashed since the system last became active. | |
| CRASH\_DETAILS | The details (such as failure type and/or reason) of the last crash (if any). | |
| VERSION | The version of the module. | |

<Icon icon="circle-exclamation" /> The SERVICE\_PORT attribute applies to the internal network. For external network service connection, the port number in the EXTERNAL\_SERVICE\_NET attribute may be different.


# Nodes
Source: https://docs.regatta.dev/sql/system-management/nodes



A node is a computer server, either physical or virtual, that can host one or more Regatta modules.

A node can be in either of two states: `AVAILABLE `and `NOT AVAILABLE`.

### Node Commands

All the node commands begin with the prefix `MANAGE NODE`.

#### NODE ADD

This command adds one or more nodes to the system.

This command is accepted only if the system is in `ACTIVE `or `SETUP `state.

**Synopsis**

```text wrap theme={null}
MANAGE NODE ADD [ FORCE ] (( 
	NAME name, 
	NETWORK ( net_address [, ... ] ) 
	[, other_node_params ] 
) [ , ... ] )

where net_address is:

( { EXTERNAL | INTERNAL } IP ip_addr PORT port_num

and other_node_params is a list of comma-separated optional parameters listed below.
```

**Parameters**

`FORCE`

By default, a node will not be added if it already belongs to a different Regatta system. If this option is specified, nodes that belong to another Regatta system will be added. The node will be removed from the other system by force, and the impact on the other system is undefined.

The rest of the parameters should be specified for each node separately.

`NAME`

Required parameter. This name must be unique among all of the system’s nodes, and will be used to identify the node in queries and other commands.

`NETWORK`

Required parameter. Contains a list of up to 4 external addresses and 4 internal addresses. Must contain at least one address (either internal or external). For each address, there are 2 required parameters – IP and PORT.

External addresses are IP addresses that are used by applications to access Regatta. Internal addresses are used only within the Regatta cluster for inter-node communication.

`DESCRIPTION`

Optional parameter. Free text that is added to the node.

`RAM_SIZE`

Optional parameter. The amount of RAM (in MB) that the Regatta modules in this node may use. If not specified – Regatta may use all the available RAM.

`ENV_MACHINE_KIND`

Optional parameter. Used to inform Regatta about the node. If specified, the value must be one of the following: `“PhysicalServer”, “VirtualMachine”, “DockerContainer”`

`ENV_MACHINE_ADDITIONAL_INFO`

Optional parameter. Used to inform Regatta about the node. Can be any string. Currently not used by Regatta.

**Output**

The output of the command is tabular with a row for each node included in the command. The following table lists the output columns.

| Name | Type | Description |
| - | - | - |
| NAME | String | The name of the node |
| ID | Number | The identifier Regatta assigned to the node. (N/A if adding the node failed.) |
| STATUS | String | SUCCESS or FAILURE. If FAILURE, the node was not added. |
| ERROR\_REASON | String | In case of failure, this column contains a description of the failure reason. |

**Example**

This command creates two nodes, named node1 and node2.Note that the RAM size and external service network address are specified only for node 2.

```text wrap theme={null}
MANAGE NODE ADD ( 
	(NAME node1, NETWORK ((INTERNAL IP “127.0.0.1” PORT 8401),(EXTERNAL IP “85.245.254.37” PORT 8402)) , 
	(NAME node2, NETWORK ((INTERNAL IP “127.0.0.1” PORT 8403),(EXTERNAL IP “85.245.253.139” PORT 8404)), RAM_SIZE 24000, EXTERNAL_SERVICE_NET (IP “85.245.253.139” PORT 9876)) 
);
```

#### NODE REMOVE

This command removes a node from the system.

This command is accepted only when the system is in `ACTIVE `or `SETUP `state. A node can be removed only when it contains no modules and no storage devices.

**Synopsis**

```text theme={null}
MANAGE NODE REMOVE node_name
```

#### NODE SHOW

This command shows the attributes of nodes.

**Synopsis**

```text wrap theme={null}
MANAGE NODE SHOW [ FILTER STATE node_state ] [ DETAILED ] 
MANAGE NODE SHOW ATTR node_name [ FILTER ATTR attribute_name ]
```

This command has two variants:

1. A list of nodes and their basic attributes
2. A detailed list of attributes for a specific node

**Parameters**

`FILTER`

Filter the result by some criterion. In the first variant of this command, nodes can be filtered by state. In the second variant, attributes can be filtered by attribute name. Currently the filtering is by exact match, no support for regular expressions. Only one filter can be specified.

`DETAILED`

Show a more detailed list of attributes for each module. See more details in the **Output** section below.

**Output**

For the first variant, the output of the command is a tabular, with each row representing a node. The following table lists the columns of the output. If the `DETAILED `option is specified, then in addition to those columns, all the attributes listed below in the output of `NODE SHOW ATTR` command are also included for each node. In this variant, only their current values are shown and not their set values.

| Name | Type | Description |
| - | - | - |
| NAME | String | The name of the node |
| ID | Number | The identifier of the node. Assigned by **Regatta**. |
| STATE | String | The node state |
| INTERNAL\_NET | String | A comma-separated list of internal network addresses in the form of `<ip_addr>:<port>` |
| EXTERNAL\_NET | String | A comma-separated list of external network addresses in the form of `<ip_addr>:<port>` |

For the second variant, the output of the command is tabular, with each row representing an attribute of the specified module. The following table lists the columns of the output.

| Name | Type | Description |
| - | - | - |
| NAME | String | The name of the attribute |
| CURRENT\_VALUE | String | The current value of the attribute |
| SET\_VALUE | String | The set value of the attribute – if different from the current value  <Icon icon="circle-exclamation" /> |
| REASON | String | If the current value differs from the set value, this column contains a reason for the difference. (For example, “Restart required”). |

<Icon icon="circle-exclamation" />  The SET\_VALUE column is displayed only if it’s different than the current value. If it’s equal to the current value, the output cell is empty.

The following table lists the rows included in the output:

| Name | Description |
| - | - |
| NAME | The name of the node |
| ID | The identifier of the node. Assigned by Regatta. |
| RAM\_SIZE | The RAM size (in MB) that may be used by Regatta |
| SERVICE\_PORT | The port number for Regatta support connection |
| EXTERNAL\_SERVICE\_NET | External network address for Regatta service connection, in the form of `<ip_addr>:<port>`<Icon icon="circle-exclamation" /> |
| DESCRIPTION | Informative description of the node |

<Icon icon="circle-exclamation" />  The SERVICE\_PORT attribute applies to the internal network.

#### NODE MODIFY

This command modifies the properties of a node.

**Synopsis**

```text wrap theme={null}
MANAGE NODE MODIFY node_name 
	[ NETWORK { ADD | REMOVE | SET } ( net_address [, ...] ) ] 
	[ RAM_SIZE [ size_in_mb ]
	[ DESCRIPTION free_text ]

where net_address is:

( { EXTERNAL | INTERNAL } IP ip_addr PORT port_num )
```

The command is accepted only if the system state is `SETUP`.

**Parameters**

`NETWORK`

The `NETWORK `clause includes one or more network addresses. It can come with either of the following directives:

* `ADD `– Adds the given network addresses to the list of existing addresses.
* `REMOVE `– Remove each given network address from the list of existing addresses. Each removed network address must be an exact match to an existing one.
* `SET `– Remove all the existing network addresses and replace them with the given network addresses.

`RAM_SIZE`

Optional parameter. The amount of RAM (in MB) that the Regatta modules in this node may use. If specified without a value – Regatta may use all the available RAM.

<Icon icon="circle-exclamation" />  If modules already exist on the node and the specified value is less than what is already being used, the command will result in an error.

`DESCRIPTION`

Optional parameter. Free text that is added to the module.


# Storage Devices
Source: https://docs.regatta.dev/sql/system-management/storage-devices



Storage Devices are attached to nodes and are used by modules running on the nodes to store database data and metadata. Once a storage device is added to a node, it can be assigned to a module. A device can only be attached to one module and cannot be transferred to another module. A module may have multiple storage devices.

A storage device has a state that can be either `OK `or `ERROR`.

### Commands

The storage device commands have the general form:

`MANAGE STORAGE DEVICE command [ parameters ].`

#### STORAGE DEVICE ADD

This command adds one or more storage devices to the system. A storage device is added to a specific node. It is assigned to a module when the module is added in that node (see [MODULE ADD](/modules) above) and cannot be assigned to an existing module.

This command is accepted only if the system is the `SETUP `state.

**Synopsis**

```text wrap theme={null}
MANAGE STORAGE DEVICE ADD [ FORCE ] ( ( 
	NODE node_name 
	NAME device_name 
	[ DESCRIPTION description ] 
	PATH path 
) [ , ... ] )
```

**Parameters**

`FORCE`

Optional parameter. By default, a storage device will not be added if it already belongs to a different Regatta system. If this option is specified, devices that belong to another Regatta system will be added.

The device will be removed from the other system by force, and the impact on the other system is undefined.

`NODE`

Required parameter. The name of the node in which the storage device is added.

`NAME`

Required parameter. This name must be unique among all of the system’s storage devices, and will be used to identify the devices in queries and other commands.

`DESCRIPTION`

Optional parameter. Free text that is added to the storage device.

`PATH`

Required parameter. Specify the path to the device inside the node.

<Icon icon="circle-exclamation" /> When using shared networked storage devices, it’s important to specify a path that will not change if the node is restarted or if the module is moved to another node. One way to accomplish that is to use a path based on the device’s universally unique ID (UUID).

#### STORAGE DEVICE MODIFY

This command modifies the attributes of a storage device.

**Synopsis**

```text wrap theme={null}
MANAGE STORAGE DEVICE MODIFY device_name 
	PATH path 
	[ DESCRIPTION description ]
```

**Parameters**

`PATH`

Required parameter. Specify the local path to the device inside the node.

<Icon icon="circle-exclamation" />  When using shared networked storage devices, it’s important to specify the uuid-based path so that the module will be reconnected to the same device when it’s moved to another node.

If the device is assigned to an active module, changing the path will take effect in the module only upon module restart.

`DESCRIPTION`

Optional parameter. Free text that is added to the storage device.

#### STORAGE DEVICE SHOW

This command shows the attributes of storage devices.

**Synopsis**

```text theme={null}
MANAGE STORAGE DEVICE SHOW 
	[ FILTER STATE device_state ] [ DETAILED ]

MANAGE STORAGE DEVICE SHOW ATTR device_name [ FILTER ATTR attribute_name ]
```

This command has two variants:

1. A list of storage devices and their basic attributes
2. A detailed list of attributes for a specific storage device

**Parameters**

`FILTER`

Filter the result by some criterion. In the first variant of this command, nodes can be filtered by state. In the second variant, attributes can be filtered by attribute name. Currently the filtering is by exact match, no support for regular expressions. Only one filter can be specified.

`DETAILED`

Show a more detailed list of attributes for each module. See more details in the Output section below.

**Output**

For the first variant, the output of the command is tabular, with each row representing a storage device. The following table lists the columns of the output. If the `DETAILED `option is specified, then in addition to those columns, all the attributes listed below in the output of `STORAGE DEVICE SHOW ATTR` command are also included for each storage device. In this variant, only their current values are shown and not their set values.

| Name | Type | Description |
| - | - | - |
| NAME | String | The name of the device |
| ID | Number | The identifier of the device. Assigned by Regatta. |
| STATE | String | The device state |
| PATH | String | The path to the device inside the node |
| NODE\_NAME | String | The name of the node the device is attached to |
| MODULE\_NAME | String | The name of the module the device is assigned to |
| CAPACITY | Number | The device capacity in bytes |
| DESCRIPTION | String | A description of the device (if exists) |
| LOCAL\_NUMBER | Number | The ordinal number of the device inside the module it’s assigned to. Local numbering starts at zero. |

For the second variant, the output of the command is tabular, with each row representing an attribute of the specified storage device. The following table lists the columns of the output.

| Name | Type | Description |
| - | - | - |
| NAME | String | The name of the attribute |
| CURRENT\_VALUE | String | The current value of the attribute |
| SET\_VALUE | String | The set value of the attribute |
| REASON | String | If the current value differs from the set value, this column contains a reason for the difference. (For example, “Restart required”) |

For each of the columns listed in the output of the first variant, there is a row in the second variant’s output.


# System Manager
Source: https://docs.regatta.dev/sql/system-management/system-manager



The System Manager is the entity that manages the hardware and software components of the system, handles management commands and drives management operations.

### Commands

The System Manager commands have the general form: `MANAGE SYSMGR command [ parameters ]`.

#### SYSMGR SHOW

This command show the attributes of the System Manager.

**Synopsis**

```text theme={null}
MANAGE SYSMGR SHOW
```

**Output**

The output of the command is tabular, with each row representing an attribute of the System Manger. The output has two columns: name and value. The following table lists the attributes that are included in the output:

| Name | Description |
| - | - |
| EXTERNAL\_NET | A comma-separated list of external network addresses in the form of `<ip_addr>:<port>` |
| INTERNAL\_NET | A comma-separated list of internal network addresses in the form of `<ip_addr>:<port>` |
| SERVICE\_PORT | The port number for Regatta support connection |
| EXTERNAL\_SERVICE\_NET | External network address for Regatta service connection, in the form of `<ip_addr>:<port> `<Icon icon="circle-exclamation" /> |
| DESCRIPTION | Informative description of the system. |

<Icon icon="circle-exclamation" />  The SERVICE\_PORT attribute applies to the internal network. For external network service connection, the port number in the EXTERNAL\_SERVICE\_NET attribute may be different.

#### SYSMGR MODIFY

This command modifies attributes of the System Manager.

**Synopsis**

```text wrap theme={null}
MANAGE SYSMGR MODIFY 
	[ NETWORK { ADD | REMOVE | SET } net_address [, ...] ] 
	[ DESCRIPTION free_text ] 

where net_address is: 
	( EXTERNAL IP ip_addr PORT port_num )
```

This command is allowed only when the system state is `SETUP`.

**Parameters**

`NETWORK`

The NETWORK clause includes one or more network addresses. It can come with either of the following directives:

* `ADD `– Adds the given network addresses to the list of existing addresses.
* `REMOVE `– Remove each given network address from the list of existing addresses. Each removed network address must be an exact match to an existing one.
* `SET `– Remove all the existing network addresses and replace them with the given network addresses.

`DESCRIPTION`

Optional parameter. Free text that is added to the module.


# System States and Commands
Source: https://docs.regatta.dev/sql/system-management/system-states-and-commands



## System States

**The Regatta system has a state, which could be one of the following:**

**DOWN**: The system is not operational – the RDB modules don’t accept client connections and system configuration commands are not available. The system can be queried (using the `MANAGE `… `SHOW `commands) but the only two operations accepted in this state are to activate the system or to enter the SETUP state.

**SETUP**: The system is not operational – the RDB modules don’t accept client connections. System configuration commands are allowed.

**STARTING**: The system is in the process of becoming active. The RDB modules may start accepting client connections but are not yet fully operational. System configuration commands are not allowed.

**ACTIVE**: The system is operational, accepting client connections. Some system configuration commands are allowed.

**SHUTTING DOWN**: The system is in the process of shutting down. The RDB modules close all the client connections and stop accepting new connections. System configuration commands are not allowed.

```mermaid placement="top-left" actions={false} theme={null}
flowchart RL
    SETUP([SETUP])
    
    subgraph MainLoop [ ]
        ACTIVE([ACTIVE])
        STARTING([STARTING])
        SHUTTING_DOWN([SHUTTING DOWN])
        DOWN([DOWN])
        
        STARTING -.-> ACTIVE
        ACTIVE -->|Shutdown| SHUTTING_DOWN
        STARTING -->|Shutdown| SHUTTING_DOWN
        SHUTTING_DOWN -.-> DOWN
        DOWN -->|Start| STARTING
    end

    SETUP <-->|Enter/Exit Setup| DOWN

    %% This makes the MainLoop box invisible
    style MainLoop fill:none,stroke:none
```

### System Commands

All the system-wide commands begin with the prefix `MANAGE SYSTEM`

#### SYSTEM START

Synopsis

```text theme={null}
MANAGE SYSTEM START
```

The command is accepted only if the current system state is `DOWN`. The result of executing the command is a state change to `STARTING`.

#### SYSTEM SHUTDOWN

**Synopsis**

```text theme={null}
MANAGE SYSTEM SHUTDOWN [ WAIT seconds ]
```

The command is accepted only if the current system state is either `ACTIVE `or `STARTING`.

The shutdown process is performed asynchronously. The command returns when the system state has changed to `SHUTTING DOWN` .

**Parameters**

`WAIT seconds`

Optional parameter. The system will wait up to the specified number of seconds for ongoing transactions to finish before shutting down. If any transaction remains active after that time elapsed, it will be aborted. By default, ongoing transactions are immediately aborted.

#### SYSTEM ENTER SETUP

**Synopsis**

```text theme={null}
MANAGE SYSTEM ENTER SETUP
```

The command is accepted only if the current system state is `DOWN`. The result of executing the command is a state change to `SETUP`.

#### SYSTEM EXIT SETUP

**Synopsis**

```text theme={null}
MANAGE SYSTEM EXIT SETUP
```

The command is accepted only if the current system state is `SETUP`. The result of executing the command is a state change to `DOWN`.

#### SYSTEM MODIFY

This command modifies parameters of the system.

**Synopsis**

```text theme={null}
MANAGE SYSTEM MODIFY 
	[ RDB_FAILURE_THRESHOLD (FAILURES num_failures DURATION time_window) [ , ... ] ] 
	[ DCM_FAILURE_THRESHOLD (FAILURES num_failures DURATION time_window) [ , ... ] ] 
	[ GDD_FAILURE_THRESHOLD (FAILURES num_failures DURATION time_window) [ , ... ] ] 
	[ SEQUENCER_FAILURE_THRESHOLD (FAILURES num_failures DURATION time_window) [ , ... ] ]
```

**Parameters**

`RDB_FAILURE_THRESHOLD`

Optional parameter. Specify up to 4 failure thresholds for each RDB module. Each threshold is specified by a number of failures and time window (in seconds). A module is restarted automatically when it fails, as long as it hasn’t reached the threshold. Once a threshold is reached, the module is not restarted, and it remains in state `DOWN `until it is started with the `MODULE START` command.

For example, when specifying `RDB_FAILURE_THRESHOLD (FAILURES 3 DURATION 60), (FAILURES 5 DURATION 3600)`, an RDB module will move to state `DOWN `if it fails 3 times within 60 seconds, or if it fails 5 times within an hour.

<Icon icon="circle-exclamation" />  The specified failure thresholds replace the existing set of thresholds.

`DCM_FAILURE_THRESHOLD, GDD_FAILURE_THRESHOLD, SEQUENCER_FAILURE_THRESHOLD`

Optional parameters. These parameters specify up to 4 failure thresholds for the DCM, GDD and SEQUENCER modules, respectively. See description of RDB\_FAILURE\_THRESHOLD above.

#### SYSTEM SHOW

This command shows the state and other attributes of the system.

**Synopsis**

```text theme={null}
MANAGE SYSTEM SHOW [ DETAILED ]
```

**Output**

The output of the command is tabular, containing a single row. The following table lists the columns of the output. The columns marked as “Basic” appear in the basic output, the other columns appear only in the detailed output.

| Name | Type | Basic | Description |
| - | - | :- | - |
| STATE | String | <Icon icon="check" /> | The state of the system. |
| NUM\_NODES | Number | | The number of nodes. |
| NUM\_RDB\_MODULES | Number | | The number of RDB modules. |
| NUM\_UNAVAILABLE\_NODES | Number | | The number of nodes in state `NOT AVAILABLE` |
| NUM\_INACTIVE\_MODULES | Number | | The number of modules that are not in `ACTIVE `state |

<Icon icon="circle-exclamation" />  See description of the failure thresholds in the [SYSTEM MODIFY](#system-modify) command.


# Database Catalog Data
Source: https://docs.regatta.dev/sql/system-monitoring/database-catalog/database-catalog



The database catalog views maintain information about the database objects (tables, indexes, etc.).


# SHOW COLUMNS
Source: https://docs.regatta.dev/sql/system-monitoring/database-catalog/show-columns



This view has a row for every column in every table in the database.

The output is ordered by the (`table_name, column_name`) columns.

Data can be filtered with `IN TABLE` table\_name syntax.

The following table lists the output’s columns:

| Column name | Data type | Description |
| :- | :- | :- |
| TABLE\_NAME | `VARCHAR(127)` | The table name |
| COLUMN\_NAME | `VARCHAR(127)` | The column name. This is the filter column |
| DATA\_TYPE | `VARCHAR(30)` | The column data type. One of the supported data types ([Data Types](/sql/data-types)) |
| COLUMN\_SIZE | `INT` | The number of chars for CHAR, the maximum number of chars for VARCHAR, the precision of the column for NUMERIC, REAL or DOUBLE PRECISION, the number of fractional digits retained in the seconds field for TIME or TIMESTAMP.<br />Null for all other types. |
| SCALE | `INT` | The number of digits to the right of the decimal point in a number.<br />Null when not relevant |
| NOT\_NULL | `BOOLEAN` | True if defined as NOT NULL. |
| DEFAULT | `VARCHAR(8000)` | The column's default value (NULL if there is no default value). |
| ORDINAL\_POSITION | `INT` | Ordinal position of the column within the table (count starts at 1) |


# SHOW CONSTRAINTS
Source: https://docs.regatta.dev/sql/system-monitoring/database-catalog/show-constraints



This view has a row for every constraint in every table in the database, except for `NULL` constraints. Those are presented as the column `IS_NULLABLE` at `SHOW COLUMNS` view.

The output is ordered by the `table_name` column.

Data can be filtered with `IN TABLE` table\_name syntax.

The following table lists the output’s columns:

| Column name | Data type | Description |
| :- | :- | :- |
| TABLE\_NAME | `VARCHAR(127)` | The table name. This is the filter column. |
| COLUMN\_NAME | `VARCHAR(127)` | The column the constraint is set on |
| CONSTRAINT\_TYPE | `CHAR(1)` | `r` = foreign key constraint, `p` = primary key constraint, `u` = unique constraint |
| REF\_TABLE\_NAME | `VARCHAR(127)` | For foreign key constraint: The referenced table the foreign key is pointing to. Otherwise null. |
| REF\_COL\_NAME | `VARCHAR(127)` | For foreign key constraint: The column in the reference table the foreign key is referring to. Otherwise null. |


# SHOW INDEXES
Source: https://docs.regatta.dev/sql/system-monitoring/database-catalog/show-index



This view has a single row for each index in the database. The output is ordered by the
(`table_name,index_name`) columns.

Data can be filtered with `IN TABLE` table\_name syntax.

Note, this view contains both indexes created explicitly by the user and indexes created implicitly for `PRIMARY
KEY` and `UNIQUE` and `REFERENCES` constraints.

The following table lists the output’s columns:

| Column name | Data type | Description |
| - | - | - |
| TABLE\_NAME | VARCHAR(127) | The table name |
| INDEX\_NAME | VARCHAR(127) | The index name. This is the filter column. |
| IS\_UNIQUE | BOOLEAN | True if the index is unique. False if not. |
| COLUMN\_NAME | VARCHAR(127) | The index column name |
| DEVICES | VARCHAR(1000) | List of devices on which the index is stored, separated by comma.<br />Note: The output is trimmed after 1000 chars. To see the full list of devices use [SHOW INDEX DEVICES](/sql/system-monitoring/database-catalog/show-index-devices). |
| RANGE\_SEPARATORS | VARCHAR | Separators of the key ranges of the segments, if any.<br />The column output max size is limited by the [Max SQL statement length](/sql/appendices/database-limitations). |


# SHOW INDEX DEVICES
Source: https://docs.regatta.dev/sql/system-monitoring/database-catalog/show-index-devices



This view returns the list of devices per index in the database.

Note that in this view, specifying the `IN INDEX` index\_name is mandatory.

The output is ordered by the `device_id` column.

The following table lists the output’s columns:

| Column name | Data type | Description |
| :- | :- | :- |
| DEVICE\_ID | `VARCHAR(32)` | The unique device identifier. This is the filter column |
| MODULE\_ID | `INT` | The identifier of the module |
| DEVICE\_TOTAL\_CAPACITY | `BIGINT` | Total size in bytes |

For example:

```sql theme={null}
SHOW INDEX DEVICES IN INDEX 'my_table_idx';
```


# SHOW TABLE DEVICES
Source: https://docs.regatta.dev/sql/system-monitoring/database-catalog/show-table-devices



This view returns the list of devices per table in the database.

Note that in this view, specifying the `IN TABLE` table\_name is mandatory.

The output is ordered by the `device_id` column.

The following table lists the output’s columns:

| Column name | Data type | Description |
| :- | :- | :- |
| DEVICE\_ID | `VARCHAR(32)` | The unique device identifier. Filter column |
| MODULE\_ID | `INT` | The identifier of the module |
| CAPACITY | `BIGINT` | Total capacity of the device in bytes |

For example:

```sql theme={null}
SHOW TABLE DEVICES IN TABLE 'my_table';
```


# SHOW TABLES
Source: https://docs.regatta.dev/sql/system-monitoring/database-catalog/show-tables



This view has a single row for each table in the database.

The output is ordered by the `table_name` column.

The following table lists the output’s columns:

## Output Columns

| Column name | Data type | Description |
| :- | :- | :- |
| TABLE\_NAME | VARCHAR(127) | The table name. This is the view filter column. |
| IS\_READY | BOOLEAN | True if `READY`, False if `NOT READY` |
| PRIMARY\_KEY\_COLUMN | VARCHAR(127) | The primary key column name. (`NULL` if the table has no primary key.) |
| DEVICES | VARCHAR(1000) | List of devices on which the table is stored, separated by comma.<br />Note: The output is trimmed after 1000 chars. To see the full number of devices see [SHOW TABLE DEVICES](/sql/system-monitoring/database-catalog/show-table-devices).<br />Customers can identify that the value was trimmed by finding '...' as the last 3 chars of the value. |
| TABLE\_METADATA | VARCHAR | The `CREATE TABLE` command to use to recreate the table if needed with all its columns/constraint/indexes.<br />This output should include the table indexes as well. The column output max size is limited by the [Max SQL statement length](/sql/appendices/database-limitations). |


# SHOW USERS
Source: https://docs.regatta.dev/sql/system-monitoring/database-catalog/show-users



This view has a row for every user in the database.

The output is ordered by the `user_name` column.

The following table lists the output’s columns:

| Column name | Data type | Description |
| :- | :- | :- |
| USER\_NAME | `VARCHAR(64)` | The username. This is the filter column. |


# Dynamic System Data
Source: https://docs.regatta.dev/sql/system-monitoring/dynamic-system/dynamic-system



These views are dynamic and are being updated in high frequency.


# SHOW DATABASE METRICS
Source: https://docs.regatta.dev/sql/system-monitoring/dynamic-system/show-database-metric



This view returns all the metrics related to the database, meaning that it presents the aggregated metrics for
the whole cluster

The output is ordered by the `metric_name` column.

The following table lists the output’s columns:

| Column name | Data type | Description |
| :- | :- | :- |
| METRIC\_NAME | `VARCHAR(255)` | Unique short name for the metric. This is the filter column. |
| METRIC\_ID | `INT` | The unique metric identifier. Correlates to [SHOW METRIC DESCRIPTION](/sql/system-monitoring/dynamic-system/show-metric-description). |
| VALUE | `INT` | Current value for the metric (rounded up) |
| QUERY\_TIMESTAMP | `TIMESTAMP` | Represent the query time. The output of `current_timestamp` function. |


# SHOW DEVICE METRICS
Source: https://docs.regatta.dev/sql/system-monitoring/dynamic-system/show-device-metrics



This view returns the <u>current</u> metrics of the <u>cluster devices</u>.

Ordered by the (`metric_name, device_id`) columns.

Data can be filtered with the `IN DEVICE device_id` parameter.

The following table lists the output’s columns:

| Column name | Data type | Description |
| :- | :- | :- |
| METRIC\_NAME | `VARCHAR(255)` | Unique short name for the metric. This is the filter column. |
| METRIC\_ID | `INT` | The unique metric identifier. Correlates to [SHOW METRIC DESCRIPTION](/sql/system-monitoring/dynamic-system/show-metric-description). |
| MODULE\_ID | `INT` | The identifier of the module |
| DEVICE\_ID | `VARCHAR(32)` | The unique device identifier. |
| VALUE | `INT` | Current value for the metric (rounded up) |
| QUERY\_TIMESTAMP | `TIMESTAMP` | Represent the query time. The output of `current_timestamp` function. |


# SHOW METRIC DESCRIPTION
Source: https://docs.regatta.dev/sql/system-monitoring/dynamic-system/show-metric-description



Contains information about the dynamic system data metrics (see [Dynamic System Data](/sql/system-monitoring/dynamic-system)).

The output is ordered by the `metric_name` column.

Note: All the metrics are for the current time and not historical or cumulative.

The following table lists the output’s columns:

| Column name | Data type | Description |
| :- | :- | :- |
| METRIC\_NAME | `VARCHAR(255)` | <p> Unique short name for the metric. This is the filter column.</p>  <p> Note that some metrics appear in more than 1 view (in both SHOW DATABASE METRICS and SHOW MODULE METRICS).</p> |
| METRIC\_ID | `INT` | The unique metric identifier. |
| DESCRIPTION | `VARCHAR(4000)` | Metric description. |

The following table lists the available metrics and their descriptions:

| Metric id | Name in SHOW METRIC DESCRIPTION view | Description in SHOW METRIC DESCRIPTION view |
| :- | :- | :- |
| 23 | Average CPU usage percentage | The average CPU usage percentage |
| 22 | Average memory usage percentage | The average memory usage percentage |
| 0 | Deadlock detections rate | The deadlock detections rate per second |
| 1 | DELETE statements average latency | The average execution time of successful DELETE statements in milliseconds |
| 2 | DELETE statements rate | The rate of successful DELETE statements per second |
| 1000 | Device row data consumption percentage | The amount of space used for table rows data, as percentage of the device capacity. (This metric includes capacity reserved for internal operations.) |
| 1001 | Device metadata consumption percentage | The amount of space used for metadata associated with table rows, including indexes, as percentage of the device capacity. |
| 3 | Inbound network throughput | The inbound (from the Client to Regatta) network throughput in bytes per second |
| 4 | Index entry reads rate | The rate of index entry reads per second |
| 5 | Index updates rate | The index updates rate per second |
| 6 | INSERT statements average latency | The average execution time of successful INSERT statements in milliseconds |
| 7 | INSERT statements rate | The rate of successful INSERT statements per second |
| 8 | Longest active statement time | The time of the longest currently active statement in seconds |
| 9 | Number of active transactions | The number of active transactions |
| 10 | Number of open clients connections | The number of open clients connections |
| 11 | Outbound network throughput | The outbound (from Regatta to the Client) network throughput in bytes per second |
| 12 | Row deletions rate | The rate of row deletions per second |
| 13 | Row insertions rate | The rate of row insertions per second |
| 14 | Row output rate | The rate of rows returned in result sets per second |
| 15 | Row updates rate | The rate of row updates per second |
| 16 | Statements error rate | The rate of failed statements per second |
| 24 | SELECT statements average latency | The average execution time of successful SELECT statements in milliseconds |
| 25 | SELECT statements rate | The rate of successful SELECT statements per second |
| 17 | Table row reads rate | The rate of row reads per second |
| 28 | Transaction aborts rate | The rate of transactions aborted per second |
| 19 | Transactions in conflict wait rate | The rate of transactions waiting to commit, due to conflicts with other transactions, per second |
| 20 | UPDATE statements average latency | The average execution time of successful UPDATE statements in milliseconds |
| 21 | UPDATE statements rate | The rate of successful UPDATE statements per second |

<Note>
  Note that `INSERT AS SELECT` is counted as both `INSERT` and `SELECT` statements.
</Note>


# SHOW MODULE METRICS
Source: https://docs.regatta.dev/sql/system-monitoring/dynamic-system/show-module-metrics



This view returns all the metrics related to the module level meaning that it presents multiple rows per metric\_id, according to the number of the RDB modules in the cluster.

The output is ordered by the (`metric_name, module_id`) columns.

Data can be filtered with the `IN MODULE module_id` parameter.

The following table lists the output’s columns:

| Column name | Data type | Description |
| :- | :- | :- |
| METRIC\_NAME | `VARCHAR(255)` | Unique short name for the metric. This is the filter column. |
| METRIC\_ID | `INT` | The unique metric identifier. Correlates to [SHOW METRIC DESCRIPTION](/sql/system-monitoring/dynamic-system/show-metric-description). |
| MODULE\_ID | `INT` | The identifier of the module |
| VALUE | `INT` | Current value for the metric (rounded up) |
| QUERY\_TIMESTAMP | `TIMESTAMP` | Represent the query time. The output of `current_timestamp` function. |


# SHOW SYSTEM VIEWS
Source: https://docs.regatta.dev/sql/system-monitoring/show-system-views



This view has a single row for every system view and a short description of its content.

The output is ordered by the `view_name` column.

The following table lists the output’s columns:

| Column name | Data type | Description |
| :- | :- | :- |
| `VIEW_NAME` | `VARCHAR(127)` | The system view name. A filter column. |
| `FILTER_COLUMN` | `VARCHAR(127)` | The column by which clients can filter the view |
| `IN_PARAM` | `VARCHAR(20)` | The object type by which the view can be filtered (`TABLE` \| `INDEX` \| `DEVICE` \| `NULL`) |
| `ORDER_BY_COLUMNS` | `VARCHAR(127)` | The columns by which the view is ordered |
| `DESCRIPTION` | `VARCHAR(1000)` | A short description on the view content |

The following table lists the available system views and their description:

| view name | filter column | IN\_param | ordered by columns | description |
| :- | :- | :- | :- | :- |
| `show columns` | `column_name` | `TABLE` | `table_name,column_name` | show the columns of all the tables in the database |
| `show constraints` | `table_name` | `TABLE` | `table_name` | show all the constraints in the database |
| `show database metrics` | `metric_name` | `DEVICE` | `metric_name` | shows all the database metrics and their values |
| `show device metrics` | `metric_name` | `DEVICE` | `metric_name,device_id` | show all the devices metrics and their values |
| `show devices` | `device_id` | `--` | `device_id` | show all the devices of the database |
| `show index devices` | `device_id` | `INDEX` | `device_id` | show all the devices of a specific index |
| `show indexes` | `index_name` | `TABLE` | `table_name,index_name` | show all the indexes in the database |
| `show metric description` | `metric_name` | `--` | `metric_name` | show all the database metrics and their description |
| `show module metrics` | `metric_name` | `--` | `metric_name,module_id` | show all the modules metrics and their values |
| `show modules` | `Module_role` | `--` | `Module_role,node_name` | show all the modules in the cluster |
| `show nodes` | `node_name` | `--` | `node_name` | show all the nodes in the cluster |
| `show system views` | `view_name` | `--` | `view_name` | show this view |
| `show table devices` | `device_id` | `TABLE` | `device_id` | show the devices of a specific table |
| `show tables` | `table_name` | `--` | `table_name` | show all the tables in the database |
| `show users` | `user_name` | `--` | `user_name` | show all the users in the database |


# SHOW DEVICES
Source: https://docs.regatta.dev/sql/system-monitoring/system-catalog/show-devices



This view returns a row for every device in the cluster.

The output is ordered by the `device_id` column.

The following table lists the output’s columns:

| Column name | Data type | Description |
| :- | :- | :- |
| DEVICE\_ID | `VARCHAR(32)` | The device unique identifier for the device. This is the filter column. |
| MODULE\_ID | `INT` | The module the device is attached to |
| CAPACITY | `BIGINT` | Total device capacity in bytes |
| TYPE | `VARCHAR(100)` | The device type |


# SHOW MODULES
Source: https://docs.regatta.dev/sql/system-monitoring/system-catalog/show-modules



Contains information about existing modules in the cluster.

Note that several modules with the same role can exist in the cluster, in the same or different nodes.

The output is ordered by the (`module_role, node_name`) columns.

The following table lists the output’s columns:

| Column name | Data type | Description |
| :- | :- | :- |
| MODULE\_ROLE | `VARCHAR(50)` | The module role. This is the filter column. E.g: Sequencer, RDB. |
| MODULE\_ID | `INT` | The unique module identifier. |
| NODE\_NAME | `VARCHAR(8)` | The name of the node the module is running on |
| MODULE\_VERSION | `VARCHAR(20)` | The module version |


# SHOW NODES
Source: https://docs.regatta.dev/sql/system-monitoring/system-catalog/show-nodes



Contains information about the nodes which participate in the cluster.

The output is ordered by the `node_name` column.

The following table lists the output’s columns:

| Column name | Data type | Description |
| :- | :- | :- |
| NODE\_NAME | `VARCHAR(8)` | The identifier of the node. This is the filter column. |
| RAM\_SIZE | `BIGINT` | The memory size in bytes |
| NUMBER\_OF\_CPUS | `INT` | The number of logical CPU in the node |
| CPU\_TYPE | `VARCHAR(20)` | The CPU type |
| CPU\_MODEL | `VARCHAR(20)` | The CPU model |
| IP\_ADDRESS | `VARCHAR(200)` | Node’s IP (list of IPs separated by comma if there are more than 1). |


# The SYSTEM Command
Source: https://docs.regatta.dev/sql/system-monitoring/system-management/system-command



## Synopsis

```
SYSTEM command [ option ... ]
where command is: SHUTDOWN (future commands will be added if needed)
```

## Description

The system commands are used for system management and control. The command follows the `SYSTEM` keyword, and the options vary by command. Currently the only supported command is `SHUTDOWN`.


# SYSTEM SHUTDOWN
Source: https://docs.regatta.dev/sql/system-monitoring/system-management/system-shutdown



## Synopsis

```
SYSTEM SHUTDOWN [ WAIT N ]
```

## Description

This command begins the shutdown of the system. The shutdown process proceeds asynchronously after the command completes. The system will start rejecting new transactions, all the outstanding transactions will be aborted, and the system will shut down.

## Parameters

**`WAIT N`**

Wait up to N seconds to allow ongoing transactions to complete. Any transaction that is still active after N seconds will be aborted. If this parameter is not specified – ongoing transactions will be aborted immediately.


# SHOW SYSTEM STATE
Source: https://docs.regatta.dev/sql/system-monitoring/system-management/system-state



## Synopsis

```
SHOW SYSTEM STATE [ DETAILED ]
```

## Description

This command is used to query the operational state of the system.
The command returns a single row. In its basic form, the row contains a single `STATE` field, which can take one of the following values: `{ACTIVE, SHUTTING DOWN}`. With the `DETAILED` parameter specified, additional fields are included.

## Parameters

**`DETAILED`**

With this optional parameter, the result contains additional columns.
The following table lists the columns of the result, including the ones appearing in the basic view and the ones that are included only in the detailed view.

| Column name | Data type | Included in basic view | Description |
| :- | :- | :- | :- |
| STATE | `VARCHAR(16)` | Yes | The operational state of the system. |
| PHASE | `VARCHAR(32)` | No | In `ACTIVE` state: `NULL`.<br />In `SHUTTING_DOWN` state: the current shutdown phase out of the total number of phases in the form "i / n" (e.g., "2 / 4"). |
| NUMBER OF MODULES | `INT` | No | In `ACTIVE` state: The number of active modules.<br />In `SHUTTING DOWN` state: The number of modules that haven't finished the current shutdown phase. |


# Using System Monitoring Views
Source: https://docs.regatta.dev/sql/system-monitoring/system-monitoring-views/system-monitoring-views



System views are used to track database objects (as part of the [Database Catalog Data](/sql/system-monitoring/database-catalog)), system static configuration (as part of the [System Catalog Data](/sql/system-monitoring/system-catalog)) and dynamic metrics on the system performance (as part of the [Dynamic System Data](/sql/system-monitoring/dynamic-system)).

The system monitoring views are exposed by the `SHOW` commands. Those `SHOW` commands are Regatta proprietary commands and support the options listed below.

## Synopsis

```sql theme={null}
SHOW view_name [ LIKE 'pattern' ][ IN object_type object_name ] [ ROWS BETWEEN n AND m ]

where object_type is:
{ TABLE | INDEX | DEVICE }
```

## Parameters

**`view_name`**

The system catalog view name.

**`LIKE '<pattern>'`**

Filters the view output by its main object (e.g filter by table name in `SHOW TABLES` view, filter by index name in `SHOW INDEXES` view). The filter uses case-sensitive pattern matching, with the support of optional leading and/or trailing percent signs.

The percent sign (%) stands for sequences of zero or more characters.

**`IN object_type object_name`**

Show only results within the scope of a specific object in the relevant system view data. Possible object types and the views to which they apply:

| Object type | System view |
| :- | :- |
| `IN TABLE` | `SHOW INDEXES`,<br />`SHOW COLUMNS`, <br />`SHOW TABLE DEVICES`,<br />`SHOW CONSTRAINTS` |
| `IN INDEX` | `SHOW INDEX DEVICES` |
| `IN DEVICE` | `SHOW DEVICE METRICS` |
| `IN MODULE` | `SHOW MODULE METRICS` |

The **table\_name/index\_name/device\_id** should be the fully-qualified name.

Note that input names are converted to lower-case unless enclosed by double quotes. Therefore: `IN TABLE 'Employees'` and `IN TABLE 'employees'` both refer to the table\
named employees, while `IN TABLE '“Employees”'` refers to the table named\
`Employees`.

**`ROWS BETWEEN n AND m`**

Used to return only part of the output rows. This can be used to retrieve the results in parts and avoid exceeding the client's memory limitations.

Note:

* If the size of the output exceeds the client memory, an error is returned.
* If objects are added and/or removed from the view in between two queries of consequent row ranges, an existing object may be returned in both queries or missing from both queries.
* If the number of requested rows is larger than the actual number of rows in the view, the command should succeed and return only the existing rows.
* The row number is zero-based.

## Examples

```sql theme={null}
SHOW TABLES;
SHOW TABLES LIKE 'my%';
SHOW COLUMNS IN TABLE "my_table";
SHOW COLUMNS LIKE '%product%' IN TABLE "my_table";
SHOW TABLES LIKE '%my' ROWS BETWEEN 100 AND 150;
```


# SET TRANSACTION
Source: https://docs.regatta.dev/sql/tcl-commands/set-transaction



Define the characteristics of the current transaction.

## Synopsis

```
SET TRANSACTION transaction_mode [, ...]

where transaction_mode is one of:
  ISOLATION LEVEL { SERIALIZABLE |
                    REPEATABLE READ |
                    READ COMMITTED }
  { READ WRITE | READ ONLY }
```

## Description

The `SET TRANSACTION` command defines the characteristics of the current transaction. It has no effect on any subsequent transactions.

Note that this command should be the first statement in the transaction (after `BEGIN/START TRANSACTION`). If this is not the case, an error is returned.

## Parameters

**ISOLATION LEVEL**

Defines how the transaction is isolated from other transactions. When not specified in the `SET TRANSACTION` command, the transaction isolation level is the level that was defined for the client connection or the database default.

Note that in all isolation levels, transactions always see their own (uncommitted) changes.

**`READ COMMITTED`**

Each statement sees only data committed before it started execution; it never sees either uncommitted data or changes committed by concurrent transactions during the statement's execution.

Note that two statements can see different data, even though they are within a single transaction, if other transactions commit changes after the first statement starts and before the second statement starts.

This is the database default isolation level.

**`REPEATABLE READ`**

Statements within the transaction only see data committed before the transaction began; it never sees either uncommitted data or changes committed by concurrent transactions during the transaction's execution.

In contrast to `READ COMMITTED` level, in this level all the statements within a transaction see the same version of the data.

**`SERIALIZABLE`**

Each statement within the transaction reads the last committed version of any row. Regatta provides that any concurrent execution of a set of serializable transactions is guaranteed to produce the same effect as running them one at a time in some order. In addition, in Regatta this mode provides *external consistency*: The order of execution of transactions as it appears to any other transaction is the commitment order.

**`READ WRITE`**

Define the transaction as capable of both read and write changes in the database. This is the default.

**`READ ONLY`**

Define the transaction as capable of only reading data from the database. Attempts to write will fail the statement and the transaction.

## Examples

**Start a transaction and set its isolation mode:**

```sql theme={null}
SET TRANSACTION ISOLATION LEVEL READ COMMITTED;
INSERT INTO customers (c_custkey, c_name, c_gender)
VALUES (1, 'John Doe1', 'M');
```

**Start a transaction, set its isolation level and set it to READ ONLY:**

```sql theme={null}
SET TRANSACTION ISOLATION LEVEL REPEATABLE READ , READ ONLY;
SELECT * FROM customers;
```

## Compatibility

The `SET TRANSACTION` command conforms to the SQL standard.


# Transaction Control Language Commands
Source: https://docs.regatta.dev/sql/tcl-commands/tcl-commands



Transactions are the basis of concurrency control, providing strong consistency and preserving the ACID guarantees: Atomicity, Consistency, Isolation and Durability. A transaction is a sequence of SQL statements that is committed or rolled back as a whole, in a single operation. The intermediate states between the statements of a transaction are not visible to other concurrent transactions, and if some failure occurs that prevents the transaction from being completed, then none of its statements affect the database at all.

An active transaction ends either by successful commit, or rollback (abort). Rollback can happen either by the client request, or by the Regatta system itself if it encounters an error or if it detects that the transaction entered a deadlock with other transactions.

The transaction control commands aren’t regular SQL statements. They are executed by calling specific API on the Regatta client drivers. The only exception is the `SET TRANSACTION` command, which can be executed as a statement, provided that it’s the first statement in the transaction. The specification of that command is detailed below.

The Regatta client driver has an `AUTOCOMMIT` mode which can be turned ON/OFF via the client driver API. The `AUTOCOMMIT` mode defines how transaction control is managed:

* When `AUTOCOMMIT` mode is set to ON, the driver receives the statements and automatically starts a transaction for each statement. Once the statement’s execution is complete, the driver automatically commits the transaction. This mode doesn’t support multi-statement transactions.
* When `AUTOCOMMIT` mode is set to OFF, each transaction has to be started and committed (or rolled back) explicitly by using the driver API.

By default, the Regatta client driver `AUTOCOMMIT` mode is set to ON.

Important note: Passing through transaction control commands (`BEGIN/COMMIT/ROLLBACK`) as strings through the regular SQL statement API would result in an error.

### Transaction control and DDL

DDL commands don't conform to the standard transaction ACID rules, therefore, they cannot be executed as part of a transaction like other SQL commands. Technically, they are executed in single-statement pseudo transactions to retain the basic protocol that encapsulates statements within transactions. But those transactions don’t provide the isolation guarantee among transactions.

A DDL statement must be the first statement in a transaction, and it causes an immediate commit of the transaction after its completion, even if `AUTOCOMMIT` mode is set to OFF.

Other concurrent transactions are not isolated from changes made by DDLs, and they may be exposed to changes made by a DDL even before the DDL is completed and even if they run in snapshot-based isolation mode.

For example, a statement that performs a full scan on a table and a DROP TABLE is issued concurrently to the scan execution, may either complete successfully or fail depending on the timing of execution (even if the scan is snapshot-based). However, Regatta guarantees that if it succeeds, it won’t return partial results.


# Creating a Vector Index
Source: https://docs.regatta.dev/sql/vector-index/ddl/creating-vector-index



The following command creates a vector index.

## Synopsis

```sql theme={null}
CREATE VECTOR INDEX [ index_name ] ON table_name  
  USING { HNSW | IVFFLAT } (column_name distance_metric) 
  [ WITH ( option [, ... ] ) ] 

where distance_metric is one of {COSINE, L2, IP} 

and option is in the form of <param> = <value> 

The following options apply to any vector index: 
  parallelism = {FULL, HIGH, MEDIUM, LOW} 
  modules = ((module_idname [, parallelism]), ...) 

Other options are specific to the index type and are listed below. 
```

## Description

A vector index can be created on a vector column to provide appropriate searches for vectors that are “close” to a given vector according to one of the distance metrics described in the previous section. Regatta supports two types of vector indexes: `HNSW `and `IVFFLAT`. 

Each index type supports all the distance metrics, but each index uses a single distance metric and supports approximate searches only for that metric. Multiple vector indexes can be created for the same vector column, as long as they differ in the combination of index type and distance metric. 

An index vector is created for all the rows of a table, or only for rows residing in specific modules. Modules can be added to and removed from the index at any time using the `ALTER VECTOR INDEX` command (see [Modify Vector Indexes](/sql/vector-index/ddl/modifying-vector-index)). However, once the index was built for a specific module, it does not change – it is not updated when rows are inserted or updated. In order to update the index for the rows residing in a module, the module should be removed from the index and added back. This will result in rebuilding the index for the module’s rows. 

The `CREATE VECTOR INDEX` command creates the index and initiates the build process. It returns once the index was created and the build process was initiated. Only after the build process is completed, the index becomes usable for approximate vector search. The `SHOW VECTOR INDEXES` command (see [Show Vector Indexes](/sql/vector-index/show-commands#show-vector-indexes)) can be used to query the status of the index. 

## Parameters

***index\_name*** 

The name of the index. If not specified, RegattaDB generates a name. 

`ON table_name` 

Specifies the table containing the vector column to be indexed. 

`USING { HNSW | IVFFLAT } `

This parameter indicates that the index is a vector index that supports approximate search. 

***column\_name*** 

Specifies the column to be indexed. The column must be of type vector. 

***distance\_metric*** 

This parameter can be one of the following: 

`COSINE `– Cosine similarity between vectors. 

`L2 `– Euclidean distance. 

`IP` – Inner product (also known as dot product) 

`WITH ( option [, ... ] )` 

Specifies various options for the index creation. The options are listed below. Some of them apply to any vector index type, and some are specific to a certain type.

## General Options

`parallelism = {FULL, HIGH, MEDIUM, LOW} `

This is a hint for determining the number of CPU cores that participate in the construction of the index in each module. The default value is FULL, which is the highest level of parallelism. The actual number of cores participating in the index construction is determined by an internal RegattaDB algorithm and depends on the actual number of cores. 

The higher the parallelism is set, the faster the index will be built. On the other hand, highly-parallel build can potentially impact transaction performance, especially when that processing is CPU-intensive. If you create a vector index while the system is running a high load of mission-critical transaction processing, consider using this parameter to lower the parallelism of the index build to avoid impact to the transactions performance. 

`Modules = ((module_name [, parallelism]), ...)` 

Specifies a list of modules for which the vector index should be built, out of the modules in which the table resides. The index will be built only for rows residing in those modules. If this option is not specified, the index is built for all the table rows. 

When modules are specified, an optional parallelism parameter can be used for each specified module. This allows setting parallelism on a per-module basis, overriding the index-wide parameter. 

<Note>
  Modules can be added and removed using the `ALTER VECTOR INDEX` command (see [Modify Vector Indexes](/sql/vector-index/ddl/modifying-vector-index))
</Note>

### Options for the HNSW Index Type 

| Name(s) | Value Range | Default Value | Description |
| - | - | - | - |
| `m connectivity` | `[2, 64]` | 16 | The maximum number of connections per layer for all the layers other than layer 0. |
| `m_0 connectivity_base` | `[m, 64]` | The minimum between 2m and 64 | The maximum number of connections in layer 0. |
| `ef_construction` | `[m_0, 65535]` | max(m\_0, 40) | The size of the dynamic candidate list for constructing the graph. |

### Options for the IVFFLAT Index Type

There is currently one option that applies only to `IVFFLAT `Index type. 

`lists | num_clusters `

This option is applied in each module according to the number of rows residing in the module. The following values can be specified: 

`FUNCTION SQRT [ (c) ] `

The number of clusters is the square root of the number of the rows, multiplied by a constant c. The argument c is optional, the default for c is 1. 

`FUNCTION DIV(n) `

The number of clusters is the number of rows divided by n. 

`FUNCTION MIN_DIV_SQRT(n [, c]) `

The number of clusters is the minimum between `DIV(n)` and `SQRT(c) `

This parameter is optional. The default is `FUNCTION MIN_DIV_SQRT(1000) `

Example:

```sql theme={null}
-- Create an IVEFLAT vector index with default parameters and system- generated name on all the modules the table resides in
CREATE VECTOR INDEX ON mytable USING IVEFLAT (mycol IP);

-- Create an HNSW vector index with your own name and parameter values on a selected set of modules, parallelism control and other options
CREATE VECTOR INDEX mytable_mycol_hnsw_ip ON mytable USING HNSW (mycol L2)
	WITH (parallelisn = HIGH,
		  modules = ((module_a), (module_b, MEDIUM),
		  ef_construction = 32,
		  m = 10
	);
```


# Deleting a Vector Index
Source: https://docs.regatta.dev/sql/vector-index/ddl/deleting-vector-index



The following command deletes a vector index.

## Synopsis

```sql theme={null}
DROP VECTOR INDEX index_name 
```


# Modifying a Vector Index
Source: https://docs.regatta.dev/sql/vector-index/ddl/modifying-vector-index



The following command alters a vector index.

## Synopsis

```sql theme={null}
ALTER VECTOR INDEX index_name 
  action [, ...] 

where action is one of the following: 
  ADD MODULE module_idname [ parallelism ] 
  DROP MODULE module_idname 
  ABORT MODULE ALL 
```

## Description

This command can be used to add modules to and remove modules from an existing vector index. It can also be used to abort the build process for modules on which the index is currently being built. 

Each `ALTER VECTOR INDEX` command may include only one type of clause out of `ADD`, `DROP `and `ABORT`. It can include multiple clauses of the same type. 

Adding modules initiates the build process for the rows residing in the specified modules. The command returns once the build process has been initiated. Only after the build process is completed, the rows residing on those modules are included in approximate vector search. The `SHOW VECTOR INDEX MODULES` command (see [Show Vector Index Modules](/sql/vector-index/show-commands#show-vector-index-modules)) can be used to query the status of the build process on the modules. 

Dropped modules must be in final state, i.e. `COMPLETE `or `FAILED`. (See [Show Vector Index Modules](/sql/vector-index/show-commands#show-vector-index-modules) command for description of module states). Aborted modules must be in state `BUILDING`, i.e., during the build process. 

Dropping all the modules of a vector index does not cause dropping of the index. The index remains with zero modules, and it’s a valid state. However, trying to perform approximate search queries on the index will result in an error. 

The `ABORT `clause aborts index build processes that are in progress. The aborted modules are removed from the index. 

The following limitations apply:

* The `ABORT `clause cannot specify specific modules – it must specify `ALL`and all the modules that have a build process in progress will be aborted. The pertinent modules are removed from the index. 
* While there is a build process in progress in any of the modules, adding and dropping modules is not allowed. 

Examples:

```plsql theme={null}
-- Add two modules
ALTER VECTOR INDEX my_table_vec1_hnsw_ip
	ADD MODULE module_c
	ADD MODULE module_d MEDIUM;

-- Remove one module
ALTER VECTOR INDEX my_table_vec1_hnsw_ip DROP MODULE module_b;

-- Abort any module im which the build process is in the progress
ALTER VECTOR INDEX my_table_vec1_hnsw_ip ABORT MODULE ALL;
```


# Introduction
Source: https://docs.regatta.dev/sql/vector-index/introduction



This section describes the RegattaDB SQL specification for vector indexing. 

The RegattaDB specification follows the style of the `pgvector `extension of PostgreSQL. As in other parts of the SQL specification, there are deviations from PostgreSQL where needed to support RegattaDB’s performance and functionality. 

## The Vector Data Type

In order to support vector indexing and searches, we introduce the `VECTOR `type. This type is not a generic vector. A `VECTOR `column has one parameter that defines the dimension of all the vectors in the table column. In addition, the following applies to vector columns: 

* A vector column’s dimension can be any integer between 1 and 2048 (inclusive). 

* The data type of the vector elements is` REAL (FLOAT4) `

* Elements of the vector cannot be `NULL` and cannot have any of the values Infinity, -Infinity or NaN. 

* A vector column can be nullable. The `NOT NULL` constraint is supported. 

* `UNIQUE `and `PRIMARY KEY` constraints are not supported. 

* A vector column cannot be a foreign key or target of a foreign key. 

* Regular index for a vector column is not supported. 

* Vector values are passed as strings following `pgvector `syntax. 

For example:

```sql theme={null}
CREATE TABLE my_table (id INTEGER PRIMARY KEY INDEX, vec VECTOR(4));
INSERT INTO my_table VALUES (1, '[1,2,3,4]'), (2, '[1.4, 1.8, 2, 2.66]');  
```

## Vector Index Operators

The following are binary operators that return the distance between two vectors. The vectors must be of the same dimension. 

<Icon icon="hyphen" /> L2 distance

<Icon icon="hashtag" /> (negative) Inner product

<Icon icon="equals" /> Cosine distance

<Info>
  * No other operators or functions are supported for the vector type (e.g., no vector arithmetic such as adding vectors or multiplying a vector by a scalar). 
  * No aggregations are supported on vector columns. 
</Info>


# Performing Approximate Vector Searches
Source: https://docs.regatta.dev/sql/vector-index/performing-approximate-vector-searches



## Select Statements

When vector-distance operators appear within a `SELECT `statement, the following behavior applies: 

When the operator is not combined with `ORDER BY` and `LIMIT`, an exact match is applied. That implies full table (or index) scan. 

Examples:

```sql theme={null}
-- Select rows within a certain distance
SELECT * FROM table WHERE vec <-> '[1,2,3]' < 5;

-- Select all rows ordered by their distance from a given vector
SELECT * FROM table ORDER BY vec <=> '[1,2,3]';

-- Returns the distances of all the rows from a given vector
SELECT vec <#> '[1,2,3]' FROM table;
```

When combined with `ORDER_BY` and `LIMIT` ,  the following rules apply:

* If there is **no** vector index for that distance metric, exact match is applied. That implies full table (or index) scan.
* If there is **one** vector index for that distance metric, approximate match is applied.
* If there is **more than one** vector index for that distance metric, the query must specify which vector index to use using the `index_type` param described below.

For example:

```sql theme={null}
-- Select the closest 5 rows, perform approximate search if index exists
SELECT * FROM table ORDER BY vec <-> '[1,2,3]' LIMIT 5;
```

## Query Parameters

### The Supported query parameters

The following are query parameters specific to vector index searches.

`search_type = { EXACT | IVEFLAT }` <br />Specifies whether the approximate or exact search should be done. Note that this can be used to override the rules defined above. In particular, it can be used to force an exact search where otherwise an approximate search would be performed. 

`Index_type = { HNSW | IVFFLAT } `<br />Specifies which index type to use. This is required when there are two vector indexes for the same column and the same distance metric. 

`hnsw_ef_search = number `<br />This parameter is relevant to search using HNSW index. It specifies the size of the dynamic candidate list for searching the graph. Valid values are integers from 1 to 65535 inclusive. If not specified, it defaults to 64. 

`ivfflat_probes = number `<br />This parameter is relevant to search using IVFFLAT index. Specifies the number of clusters to search in. Valid values are integers from 1 to the number of clusters (which was determined in creation). If not specified, it defaults to 1. 

`modules = (module_name [, ...])` <br />By default, a vector index search is performed on all the modules that have a complete vector index. You may specify specific module(s) and limit the query to those modules.

### Examples

In the following examples, assume all vector columns have vector indexes.

```sql theme={null}
SELECT * FROM table
	ORDER BY vec <-> '[1,2,3]' LIMIT 5
	PARAMS (search_type = EXACT); -- override default

SELECT * FROM table
	ORDER BY vec <-> '[1,2,3]' LIMIT 5
	PARAMS (search_type = APPROX); -- this is actually the default

-- approximate search on a vector when there are two vector indexes
-- with the same distance metrics
SELECT * FROM table
	ORDER BY vec <-> '[1,2,3]' LIMIT 5
	PARAMS (index_type = HNSW);

-- perform the query only on a specific set of modules
SELECT * FROM table
	ORDER BY vec <-> '[1,2,3]' LIMIT 5
	PARAMS (hnsw_ef_search = 32, modules = (module_a, module_b));  
```

### Limitations for Approximate Search Queries

The following limitations apply to approximate search queries:

* `OFFSET `is not supported with approximate search queries. 
* `LIMIT `is limited to 65535 with approximate search queries. If a higher number is specified, exact search is performed. Specifying a `LIMIT `higher than 65535 and parameter `search_type = APPROX` is not allowed. 
* It is not allowed to include a vector distance expressions in a hierarchical `ORDER BY `with `LIMIT `using approximate search.

For example, the following queries are not supported and would result in an error:

```sql theme={null}
SELECT * FROM table 
	ORDER BY vec1 <-> '[1,2,3]', vec2 <-> '[5,6,7]' LIMIT 5
	PARAMS (search_type = APPROX);

SELECT * FROM table1 JOIN table2 ON table1.id = table2.id
	ORDER BY table1.vec <-> '[1,2,3]', table2.vec <-> '[5,6,7]' LIMIT 5
	PARAMS (search_type = APPROX);

SELECT * FROM table
	ORDER BY vec1 <-> '[1,2,3]', color LIMIT 50
	PARAMS (search_type = APPROX);

SELECT * FROM table
	ORDER BY color, vec1 <-> '[1,2,3]', LIMIT 50
	PARAMS (search_type = APPROX);
```

<Note>
  All those queries can be performed with exact search by omitting the `PARAMS (search_type = APPROX)` clause.
</Note>

Note that a table **can** have more than one indexed vector column, the limitation applies only to a query that includes a vector column in combination with other columns in the same `ORDER BY` clause. Such query cannot use approximate search. 

Approximate search is not allowed on intermediate results such as join queries, only on table queries. For example: 

```sql theme={null}
-- this will result in an error
SELECT * FROM table1 JOIN table2 ON table1.color = table2.color
	ORDER BY table1.vec1 <-> '[1,2,3]' LIMIT 10

-- this will work
SELECT * FROM
	(SELECT * from table1 ORDER BY table1.vec1 <-> '[1,2,3]' LIMIT 10
		PARAMS (search_type = APPROX) as t1
	JOIN table2 ON t1.color = table2.color;
```


# Show Commands
Source: https://docs.regatta.dev/sql/vector-index/show-commands



The following commands are available to query vector indexes.

## Show Vector Indexes

This command shows all the vector indexes in the system.

### Synopsis

```sql theme={null}
SHOW VECTOR INDEXES [LIKE 'pattern' ] [ IN TABLE table_name ]
```

### Parameters

`LIKE 'pattern'`<br />Filter indexes by names matching the given pattern. 

The pattern is case-sensitive with optional leading and/or trailing ‘%’ signs. The ‘%’ sign stands for a sequence of zero or more characters of any kind. For example, ‘foo%’ will match all the index names beginning with “foo” and ‘%foo%’ will match all the indexes that have “foo” anywhere in their name.

`IN TABLE table_name `<br />Show only the indexes in the given table. 

### Output

The output is tabular, each row represents a vector index. The following table lists the columns.

The output is ordered by `TABLE_NAME`, `INDEX_NAME`

| Name | Type | Description |
| - | - | - |
| `TABLE_NAME` | `VARCHAR(127)` | The name of the table |
| `INDEX_NAME` | `VARCHAR(127)` | The name of the vector index |
| `COLUMN_NAME` | `VARCHAR(127)` | The name of the indexed column |
| `INDEX_TYPE` | `VARCHAR(16)` | The vector index type – either ‘`HNSW`’ or ‘`IVFFLAT`’ |
| `DISTANCE_METRIC` | `VARCHAR(16)` | The distance metric – one of ‘`COSINE`’, ‘`L2`’, ‘`IP`’ |
| `PARAMETERS` | `VARCHAR(127)` | Parameters of the index. |
| `MODULES` | `VARCHAR(1000)` | Comma-separated list of module names. If it doesn’t fit in 1000 characters, includes a partial trimmed list. |
| `STATE` | `VARCHAR(16)` | One of the following: *FAILED* – The index build had failed on at least one module. *BUILDING* – Index build in progress on any of the modules. *COMPLETE* – The index build is complete on all the modules. |
| `FAILURE_REASON` | `VARCHAR(128)` | In case the state is *FAILED*, provides information about the failure. |

## Show Vector Index Modules

This command shows the modules included in a vector index and their states.

### Synopsis

```sql theme={null}
SHOW VECTOR INDEX MODULES IN INDEX index_name [ ALL ]
```

### Parameters

`IN INDEX index_name`<br />Specifies the index to show. This is a <u>mandatory</u> parameter.

`ALL`<br />If this optional parameter is specified, all the modules in which the table may have rows are listed. By default, only the modules that were added to this vector index are included in the output. 

### Output

The output is tabular, each row represents a module. The following table lists the columns.

The output is ordered by `NAME`.

| Name | Type | Description |
| - | - | - |
| `NAME` | `VARCHAR(128)` | The name of the module. |
| `STATE` | `VARCHAR(16)` | One of the following:<br />*COMPLETE* - The build is complete, rows included in searches. <br />*BUILDING* - The build is in progress.<br />*FAILED* - The build failed.<br />*NONE* -The module was not added to the vector index. |
| `FAILURE_REASON` | `VARCHAR(128)` | In case the state is *FAILED*, provides information about the failure. |


# Closing remarks
Source: https://docs.regatta.dev/tuning-performance/closing-remarks



Sometimes things don’t work as expected. Sometimes it’s as simple as a syntax error. Sometimes it’s a little more complex like an index that should have been used but instead a full scan is done. Perhaps a sub-query with an `IN` needs to replace a join. Or a statement is taking a lot longer than it should.

Finding out what is going on can be as simple as prefixing the statement with `EXPLAIN VERBOSE`.

In any event, please feel free to contact Regatta support.


# Distributing Indexes
Source: https://docs.regatta.dev/tuning-performance/distributing-indexes



### Index creation with default data distribution

When a column is denoted as having an index on it, by default, only one index segment is created. This segment is placed on a device chosen in a random manner. An example command that creates a table with an index with default data distribution:

```sql theme={null}
CREATE TABLE table_w_index (col1 int INDEX, col2 dec(5,4));
```

As can be seen using `SHOW TABLES`, Regatta adds a device and empty range separators:

```sql theme={null}
CREATE TABLE "table_w_index" (
	"col1" int DEFAULT NULL INDEX WITH (devices = (m4d2),range_separators = ()), …)
```

### Overriding the default index creation parameters

While creating a default index is good for a quick start, it won’t necessarily provide optimal performance. The entire index will be stored in the one index segment. All index queries and scans run on the same segment, potentially making it a performance bottleneck.

In order to optimize index layouts, you can specify a list of devices on which to place the index segments and the range separators that divide the key range between the different index segments.

The index may be given segments on multiple devices and distributed to multiple nodes to get more parallelism and performance. If the index segments all contain roughly the same number of entries, this will also spread the load evenly, parallelizing scans optimally and making key lookups quickest on average. On the other hand, having too many small index segments can lead to excess operators.

On a particular device, experience with the current version has shown that 3 index segments is optimal in terms of maximizing IOs to the device and CPU usage.

Once the number of index segments has been decided, it is necessary to figure out the separators between them. If it is possible to gain insight into the distribution of values in the indexed column, this information can be used to find separators that divide that distribution roughly equally. Total precision is not necessary. If the distribution is unknown, use your best guess.

Reusing the earlier example of the person table with columns name and age, with a non-unique index on age with range separators (20, 40, 55, 70) and 5 data segments, this is what its `CREATE TABLE` might look like:

```sql theme={null}
CREATE TABLE index_seps (
	name VARCHAR(20),
	age int INDEX WITH (
		DEVICES = (m3d0, m4d0, m5d0, m3d1, m4d1),
		RANGE_SEPARATORS = (20, 40, 55, 70)))
WITH (DEVICES = (m5d1, m3d2, m4d2, m5d2, m3d0));
```

When specifiying the index structure in this way, both the `RANGE_SEPARATORS` and `DEVICES` clauses must be specified. If the `WITH DEVICES` clause is not specified for the table, it will still receive the default layout.

<Note>
  Note: distribution helps parallelization of operations. However, in the case
  of a small table, you should consider placing the data and index segments of
  the table on one and the same device.
</Note>


# Distributing Tables
Source: https://docs.regatta.dev/tuning-performance/distributing-tables



### Table creation with default data distribution

There is a default placement of the data segments of new tables on the devices in a cluster. The default is that new tables are given 3 data segments on every device.

As an example, this is a `CREATE TABLE` statement with default data segment placement:

```sql theme={null}
CREATE TABLE default_table (col1 int, col2 dec(5,4));
```

The resulting layout can be displayed using a `SHOW TABLES` statement. The `--output-file` option of the `client_cli` command can be used to get untruncated output. The `TABLE_METADATA` field shows the equivalent `CREATE TABLE` statement that would explicitly define the table layout. In the example cluster that has 3 nodes each with 3 devices, the above `CREATE TABLE` command is equivalent to the following command that specifies the segments and their locations explicitly:

```sql theme={null}
CREATE TABLE "default_table" ("col1" int DEFAULT NULL, "col2" numeric(5,4) DEFAULT NULL)
	WITH (devices =
		(m3d0,m3d0,m3d0,m3d1,m3d1,m3d1,m3d2,m3d2,m3d2,
		 m4d0,m4d0,m4d0,m4d1,m4d1,m4d1,m4d2,m4d2,m4d2,
		 m5d0,m5d0,m5d0,m5d1,m5d1,m5d1,m5d2,m5d2,m5d2));
```

As you can see, each device is specified 3 times, thus creating 3 segments on each device.

### Overriding the default table creation parameters

You can override those defaults. You can decide to place more or fewer segments on a device, or place segments only on a subset of the devices. For example, this may be done in order to avoid using a device which is already nearly full. As another example, you may know that a table will always remain small, in which case the wide distribution of data across many nodes/devices creates more overhead that outweighs the parallel execution in terms of performance.

To take control of the distribution of segments to devices, a `WITH DEVICES` clause is added to the `CREATE TABLE`, as shown in the output of `SHOW TABLES` above. Below is an example of a `CREATE TABLE` command with a `WITH DEVICES` clause specifying 3 data segments on 2 storage devices:

```sql theme={null}
CREATE TABLE placed_table (col1 int, col2 dec(5, 4))
	WITH (DEVICES = (m5d0, m5d0, m5d2));
```

A large table will get higher performance when its data segments are spread on multiple nodes and on multiple devices. On the other hand, a small table would do better on just one device. For the purpose of this discussion, small is up to a few thousand rows.

As described in [Data distribution of a table](/table-index-best-practices/introduction/data-distribution-table) above, parallel processing on a single segment is maximized when it reaches a few 10s of millions of rows. If the data distribution scheme of a table does not reach that scale, consider creating 3 segments on each device (by specifying the same device 3 times in the command). Note that any number beyond 3 segments per device won’t increase performance and should be avoided.


# Data distribution of an index
Source: https://docs.regatta.dev/tuning-performance/introduction/data-distribution-index



Regatta implements indexes using a high-performance proprietary B-tree variant.  This means that the keys are maintained in order, facilitating fast and efficient range scans.

Indexes are stored in **index segments** which are distributed across storage devices.  Each index segment resides on a specific device and stores a sub-range of the overall key range in its own independent B-tree.  The overall index layout can be thought of as a forest of B-trees.  This allows Regatta to distribute the operations on the index across multiple modules and devices.  The boundaries between the index segment ranges are called **range separators**.  The first index segment indexes all the rows whose values in the indexed column are strictly less than the first range separator.  Each range separator in turn is then the lower bound for the next index segment.  This means that the number of segments is one more than the number of range separators.

There are many implications of this index distribution.  An index lookup (also known as a “point query”) needs to be sent only to one index segment.  A range scan executes in parallel in all the index segments whose sub-ranges overlap that of the scan.

In the current release, the boundaries between index segments must be specified manually during index creation.  It is the responsibility of the user to choose the range separators in such a way that the index segments will be roughly the same size.  The number of index segments is also important as this determines the parallelism of range scans and the total throughput of multiple queries and scans.  More segments across more nodes/devices lead to higher parallel processing, which is important with big tables and/or high workloads (many small transactions and/or large queries).  Both lookups (queries) and inserts (when rows are inserted) are affected by the choice of the number of index segments and their key ranges.  Imbalanced index segment sizes lead to an imbalance of the workload during scans, which could impact performance.  Also, the larger an index segment, the higher the latency of index lookup.


# Data distribution of a table
Source: https://docs.regatta.dev/tuning-performance/introduction/data-distribution-table



The rows of a table are stored on devices in structures called data segments.  A data segment resides on a specific device and contains a subset of the table’s rows.  It is the basic unit of table storage and has dynamic, variable size.

When Regatta runs an operation on the rows of a table, it sends an operator to the relevant data segments of that table.  This makes the number of data segments pivotal in the overall parallelism that the operations will achieve across the cluster.

On insert, new rows are distributed approximately evenly between all the data segments of a table, keeping them all roughly the same size.  When a row is updated, the update takes place in the data segment that contains the row.

In addition to running big queries and inserts in a distributed and parallel manner across the data segments of a table, Regatta also applies parallel processing of transactions on each data segment.  As the number of rows in a data segment increases, Regatta increases the parallelism of operators that operate on that data segment.  The per-segment throughput reaches its maximum when a data segment reaches 10s of millions of rows.


# Introduction
Source: https://docs.regatta.dev/tuning-performance/introduction/introduction



Regatta is a scale-out distributed database that is designed for elasticity, including the dynamic distribution and location of table and index data. Regatta also provides optional manual parameters to further optimize data distribution of tables and indexes. This section aims to provide insights and information about this. Most of the manual configuration options described in this document will become obsolete with the release of enhanced automation and dynamic adaptation features in future Regatta versions.

The rest of this introduction provides a brief outline of Regatta’s components and processes. For more details about Regatta’s architecture, please refer to the documentation.


# How a SQL statement executes
Source: https://docs.regatta.dev/tuning-performance/introduction/sql-statement



This section will take the briefest of looks at a range query to give a quick understanding of what is going on under the hood.  The purpose is to give an understanding of the effect of distribution.

Say there is a `person` table with a string column name and an integer column age, with a non-unique index on age.  Suppose that the table has row segments on devices 1 through 5, and that the index has range separators (20, 40, 55, 70), with index segments on devices 6 through 10.  This means that the index segment on device 6 indexes all the ages from 0 (technically, from the negative infinity value of the integral type) up to 19, the index segment on device 7 indexes all the ages from 20 to 39 and so on.  The last segment starts at 70 and continues up to the positive infinity value.

Consider the execution of the following query:

```sql theme={null}
SELECT name FROM person WHERE age BETWEEN 30 AND 49;
```

The range \[30, 49] overlaps with only 2 sub-ranges, those of the index segments on devices 7 and 8.  A range scan would be performed on only those 2 index segments.  Index scans execute in parallel on all the involved index segments.  The range scan would retrieve the row identifiers of rows in its range and each row identifier would be sent to the relevant data segment.  In each data segment, further operators would retrieve the rows and project the result onto the requested field, which would then be sent back to the client.

Only 2 index segments handled the query.  If the range separators had been, say, (…, 30, 35, 40, 45, 50, …), then the query would have been handled in parallel by 4 index segments.  The index scan part of the query could run up to twice as fast.

In addition, the more data segments, the more parallelism is applied in the data retrieval phase.


# Structure of a Regatta cluster
Source: https://docs.regatta.dev/tuning-performance/introduction/structure-regatta-cluster



A Regatta cluster runs on one or more nodes.  A node may be a bare-metal server or a virtual machine.

Within the nodes, a cluster of software modules runs the database operations. One or more modules may be placed in each node. Regatta has several different module types performing different functionalities. The *RDB* module holds tables and indexes and runs transactions. For best performance, we recommend using symmetric nodes for RDB modules, ensuring they match in CPU, RAM, disk capacity, and network specifications. There are several other modules dedicated to other cluster-wide tasks but for the sake of this document we only care about the RDB modules. Each RDB module runs on a separate Regatta node.

The storage devices on the nodes running the RDB modules are used for storing table data (rows) and indexes.  In the example cluster below, devices are named by their module number and then the device number within that module.  For example, m3d2 is a device attached to the node running module number 3.

### Finding information on nodes, modules and devices

The example output below shows a cluster with 3 RDB modules on 3 nodes.  The RDB modules have IDs 3, 4 and 5, running on nodes 0, 1 and 2 respectively.

```sql theme={null}
rdb> show modules;
statement executed successfully
| MODULE_ROLE | MODULE_ID | NODE_NAME | MODULE_VERSION |
--------------------------------------------------------
| DCM         |         2 | node_0    | 0.0.0.0        |
| GDD         |         1 | node_0    | 0.0.0.0        |
| RDB         |         3 | node_0    | 0.0.0.0        |
| RDB         |         4 | node_1    | 0.0.0.0        |
| RDB         |         5 | node_2    | 0.0.0.0        |
| Sequencer   |         0 | node_0    | 0.0.0.0        |
rdb>
```

In this cluster, each RDB module has 3 devices, each 64TB, as can be seen in the following query:

```sql theme={null}
rdb> show devices;
statement executed successfully
| DEVICE_ID | MODULE_ID | CAPACITY    | TYPE         |
------------------------------------------------------
| m3d0      |         3 | 64424509440 | fast_devices |
| m3d1      |         3 | 64424509440 | fast_devices |
| m3d2      |         3 | 64424509440 | fast_devices |
| m4d0      |         4 | 64424509440 | fast_devices |
| m4d1      |         4 | 64424509440 | fast_devices |
| m4d2      |         4 | 64424509440 | fast_devices |
| m5d0      |         5 | 64424509440 | fast_devices |
| m5d1      |         5 | 64424509440 | fast_devices |
| m5d2      |         5 | 64424509440 | fast_devices |
rdb>
```

The following query shows the current metrics for device m3d1.  The values for both its “metadata consumption percentage” and “row data consumption percentage” are 0, meaning the device is currently empty.  The device would be full when these two metrics sum to 100.  As shown in the other fields, the device is currently performing 342 writes per second with 1,274 KB/sec throughput, and no reads.

```sql theme={null}
rdb> show device metrics in device m3d1;
statement executed successfully
| METRIC_NAME                            | METRIC_ID | MODULE_ID | DEVICE_ID | VALUE | …
-------------------------------------------------------------------------------------- …
| Device metadata consumption percentage |      1001 |         3 |         1 |     0 | …
| Device read rate                       |      1002 |         3 |         1 |     0 | …
| Device read throughput                 |      1004 |         3 |         1 |     0 | …
| Device row data consumption percentage |      1000 |         3 |         1 |     0 | …
| Device write rate                      |      1003 |         3 |         1 |   342 | …
| Device write throughput                |      1005 |         3 |         1 |  1274 | …
rdb>
```

(Output truncated to make the lines presentable here.)


# Other Index Consideration
Source: https://docs.regatta.dev/tuning-performance/other-index



### Indexing nullable columns

When a nullable column is indexed, the `NULL` value is considered to be lower than any value of the type of the column. This means that it is possible to have an index segment with only the NULL values by specifying a first range separator that is smaller than any expected value of that column. (Note: In the case of a string type, the minimal possible value is the empty string `''`.)

### Indexing high frequency values

Sometimes, in the case of a non-unique index, the indexed column has a few values that appear a large number of times. It is possible, using range separators, to index each such value in an index segment of their own. This has an advantage that values that collate close to those values will not be in large index segments.

As an (artificial) example, consider an `orders` table that has an `order_status` column.\
Suppose that there is a large number of possible values that `order_status` could have.\
Also, there is a large number of rows with status `delivered` and `returned`.\
There are also an unknown number of `orders` that don’t have a status, that is, their status is `NULL`. Without getting into too much business logic in this artificial example, suppose that scans are likely over `order_status` values that are not `delivered` or `returned`. For example, periodically the application may want to send reminders for orders that are `unpaid`. The following definition of the range separators would put the index for rows with `order_status` of `NULL`, `delivered` and `returned` into separate index segments that contain only those values:

```sql theme={null}
CREATE TABLE orders (
	…,
	order_status VARCHAR(11) INDEX WITH (
		DEVICES = (m3d0, m3d1, m3d2, m4d0, m4d1, m4d2),
		RANGE_SEPARATORS = ('', 'delivered', 'delivered ', 'returned', 'returned ')),
	…
);
```

Note that this example has 6 devices for the 5 range separators, as required. The index segment on the first device holds the index for all the values strictly less than the first range separator. In this example, the first range separator is the empty string, `''`. As explained in above, all the rows that have a `NULL order_status` will be indexed in this index segment (and only those rows).

There is a subtle difference between the range separators `'delivered'` and `'delivered '`. The difference is the extra space at the end of the second. The only strings that are greater than or equal to the first but less than the second are those that are exactly `'delivered'`, so only rows with this value as their `order_status` will be indexed in this index segment. The same logic holds for `'returned'` and `'returned '`.


# Other Limitations
Source: https://docs.regatta.dev/tuning-performance/other-limitations



### Fully define a new table before using it

The current release of Regatta does not support `ALTER TABLE` operations after the table has been created. It is still possible to split the table creation into multiple statements if the first statement contains the `SET NOT READY` clause:

```sql theme={null}
CREATE TABLE SET NOT READY <table> …
```

It is then possible to use `ALTER TABLE` statements with this table. For example:

```sql theme={null}
ALTER TABLE <table> ADD COLUMN <column> <type> <constraint> …
```

The last statement in the table creation sequence should then be

```sql theme={null}
ALTER TABLE <table> SET READY;
```

Note that the table cannot be used (rows cannot be inserted), until after the completion of the `SET READY` command. That command declares that the table is fully defined and available for use.

### Index on a single column only

The current release of Regatta supports indexes only on a single column. In the case that a combination of columns needs to be indexed, a compound field may be created and maintained, with the index on the compound field.

### PRIMARY KEY INDEX

Note that in the current release, Regatta requires the keyword `INDEX` after the constraint `PRIMARY KEY`.