Alpha

These pages are built from main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

Getting Started

Connecting with the Turborel client

With a server running (Running the Server), connect to it with turborel, as a user of the database. A password is proved only over a Unix socket, a named pipe or TLS, never over plain TCP, so a server of this machine is best reached at its socket. Start it with one, here a database kept in memory and owned by ANN:

$ turboreld --memory --owner ann --set SERVER.SOCKET=/run/turborel/socket
password:
turboreld: listening at 127.0.0.1:7422, /run/turborel/socket

Then connect at that socket:

$ turborel --socket /run/turborel/socket -U ann -W
password:
turborel 0.0.0 (alpha), the command-line client
Copyright 2026, Turborel Inc.
Distributed under the BSD-2-Clause Plus Patent License.

Connected to turborel 0.0.0 (alpha) at the socket /run/turborel/socket, as ANN.
End each statement with a semicolon; end of input (Ctrl-D) quits.

turborel>

On Windows the socket is a named pipe, as \\.\pipe\turborel. A server of another machine is reached over TLS, with --tls (The turborel Command, Connections). Connecting with a password over plain TCP is refused before the password is asked for.

-W asks for the password. Each statement runs once a semicolon ends it; it may go over many lines. The examples of this guide show a null value as NULL, as the client shows it run with --null NULL; by default it shows nothing there.

A first schema

A user's tables are kept in a schema, named as the user:

CREATE SCHEMA AUTHORIZATION ANN;
CREATE TABLE DEPARTMENTS (CODE CHAR(3) PRIMARY KEY, NAME VARCHAR(30) NOT NULL);
CREATE TABLE EMPLOYEES (
    ID     INTEGER PRIMARY KEY,
    NAME   VARCHAR(30) NOT NULL,
    DEPT   CHAR(3) REFERENCES DEPARTMENTS,
    SALARY DECIMAL(9,2) CHECK (SALARY > 0));
INSERT INTO DEPARTMENTS VALUES ('ENG', 'Engineering'), ('OPS', 'Operations');
INSERT INTO EMPLOYEES VALUES (1, 'Ada', 'ENG', 7200), (2, 'Grace', 'ENG', 8100), (3, 'Edsger', 'OPS', 5400);
COMMIT;
OK
OK
OK
OK
OK
OK

The tables say what they hold, and what they refuse: each employee has an ID of its own, a name, a department that exists, and a salary above 0. COMMIT makes the changes lasting.

A first query

SELECT NAME, SALARY FROM EMPLOYEES WHERE DEPT = 'ENG' ORDER BY SALARY DESC;
SELECT D.NAME, COUNT(*) AS STAFF, AVG(E.SALARY) AS AVERAGE
  FROM DEPARTMENTS D JOIN EMPLOYEES E ON E.DEPT = D.CODE
 GROUP BY D.NAME ORDER BY D.NAME;
 NAME                           |      SALARY
--------------------------------+-------------
 Grace                          |     8100.00
 Ada                            |     7200.00
(2 rows)
 NAME                           |                STAFF |              AVERAGE
--------------------------------+----------------------+----------------------
 Engineering                    |                    2 |            7650.0000
 Operations                     |                    1 |            5400.0000
(2 rows)

A column the query names, by a column of a table or by AS, is headed by that name. One it does not name, as COUNT(*) written without AS, has an empty heading. An exact number is shown to its type's scale. AVG of DECIMAL(9,2) has four places after the point, so AVERAGE above shows four, and a digit past them is dropped, not rounded. An approximate number, REAL or DOUBLE PRECISION, is shown in E notation, 11 as 1.1E1 (Data Types).

And what the tables refuse:

INSERT INTO EMPLOYEES VALUES (4, 'Barbara', 'XYZ', 6000);
turborel: SQLCODE -201 (SQLSTATE 23000): a row of ANN.EMPLOYEES references no row of ANN.DEPARTMENTS: FOREIGN KEY ANN.EMPLOYEES_FOREIGN1 [ISO/IEC 9075:1992 §11.8 GR2]

There is no department XYZ. An error gives its SQLCODE and SQLSTATE, what is wrong, and the rule of the standard that says so (Errors and Diagnostics).

Ending a session

The end of input, Ctrl-D, ends the session. A transaction left open is committed as the session ends, unless the setting SESSION.COMMIT_AT_END is OFF; end it with COMMIT or ROLLBACK to be sure. A commit that fails as the session ends is told, as any statement's failure is.