The Turborel Documentation Set
Turborel is a relational database system: a library a program embeds, a
server, turboreld, that serves its databases over a network, and a
command-line client, turborel. This set of manuals describes them for
those who use, run and connect to them.
Turborel speaks the SQL of the international standards, ANSI X3.135-1986 ("SQL-86"), ISO/IEC 9075:1992 ("SQL-92") and ISO/IEC 9075-2:2023 ("SQL:2023"), read as one language, the newer prevailing where they differ. SQL-86 is implemented in full and SQL-92 nearly so, and SQL:2023's features are added to the same language as they are implemented. What is implemented, clause by clause and feature by feature, is in CONFORMANCE.md.
Turborel is in alpha: what these manuals describe may change in any release until 1.0.0 (Versions). Each change updates the pages it touches, so the manuals describe the release they come with.
The volumes
| Volume | For | |
|---|---|---|
| I. User's Guide | Anyone who writes SQL against Turborel | Concepts, and how to use them, chapter by chapter |
| II. SQL Reference Manual | The same, looking something up | The language element by element; each statement on a page of its own |
| III. Operator's Guide | Whoever installs and runs a server | Installing, running turboreld, databases, settings, users, connections |
| IV. Client Reference | Users of the client, and programs that connect or embed | The turborel command, the client library, and the embedded library |
| V. Specialized Data | SQL users working with full-text, spatial, JSON, vector, XML and graph data | Data models, practical queries, interchange and indexing, a guide each |
| Appendices | Everyone | SQLSTATEs, key words, settings, limits, implementation-defined choices, versions, table options, a glossary |
Read the User's Guide from the start to learn Turborel; turn to the Reference Manual and the appendices to look a thing up.
Conventions
Syntax is written in the notation of the SQL standard:
| Notation | Means |
|---|---|
<name> |
A syntactic element, defined elsewhere in the syntax |
::= |
Is defined as |
[ x ] |
x may be written, or left out |
{ x } |
x, grouped |
x | y |
Either x or y |
x... |
x, once or more |
KEY WORD |
Written as shown, in any case |
Examples of SQL are set in a fixed-width font. Key words are in upper case, names in upper case unless delimited, as the standard folds them:
SELECT NAME, SALARY FROM STAFF WHERE SALARY > 50000;
Results of examples follow them, as the command-line client,
turborel, shows them, run with --null NULL: a null value is shown as
NULL, where by default the client shows nothing
(The turborel Command).
Citations name the clause of a standard a rule comes from: [ISO/IEC 9075-2:2023 §7.17] is clause 7.17 of SQL:2023; [ISO/IEC 9075:1992 §11.3] is clause 11.3 of SQL-92; [X3.135-1986 §8.7] is clause 8.7 of SQL-86. A rule is cited further as Syntax Rule (SR), General Rule (GR) or Access Rule (AR) and its number: §11.9 AR1 is Access Rule 1 of clause 11.9. Turborel's own error messages cite rules the same way, so a message can be looked up.
Extensions, facilities the standards do not define, are marked (extension) where they are described.
Errors are given by SQLSTATE, the code the standard defines, and SQLCODE, the older number; Appendix A lists every one.
Pages of reference
A statement's reference page has these sections, in this order:
- NAME: the statement, and what it does in a line.
- SYNOPSIS: its syntax.
- DESCRIPTION: what it does.
- RULES: what must hold for it to run, and what it does in each case.
- PRIVILEGES: what its user must hold.
- ERRORS: each way it fails, by SQLSTATE.
- EXAMPLES: statements, and what they give.
- STANDARD: the clauses it is defined by, and what is an extension.
- SEE ALSO: related pages.