Alpha

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

The turborel-py Documentation Set

turborel-py is the Python driver for Turborel, a relational database system. It connects a Python program to a Turborel server, turboreld, over Turborel's native protocol, version 1, which it speaks itself, in pure Python on the standard library, with nothing to compile. Its standard interface is DB-API 2.0 (PEP 249), with ? parameters, and an asyncio interface beside it, turborel.aio, over a low-level client built to do all that Turborel's own client library does. This set of manuals describes it for those who write programs with it. The SQL a program sends, and the server, are described in Turborel's own manuals, The Turborel Documentation Set.

turborel-py 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 a Python program against Turborel Installing, connecting, queries, prepared statements, transactions, large objects, copying, pipelines and pools, settings and errors, chapter by chapter
II. API Reference The same, looking something up The standard API, then the low-level client, a page for each main interface or module
Appendices Everyone Types, errors, settings and versions

Read the User's Guide from the start to learn the driver; turn to the API Reference and the appendices to look a thing up.

Conventions

Examples of Python and of SQL are set in a fixed-width font. SQL key words are in upper case, names in upper case unless delimited, as the standard folds them, and a dynamic parameter is ?:

SELECT NAME, SALARY FROM STAFF WHERE SALARY > ?

Results of examples follow them, as the program prints them.

Citations name the section of Turborel's documents a behaviour comes from: [PROTOCOL Frames] is the section "Frames" of The Native Protocol; [CLIENT Pipelines] is the section "Pipelines" of Turborel's client library chapters, The Client Library and Settings, Pipelines and Pools. The rows each page fulfils are those of the driver's parity matrix, CONFORMANCE.md.

Errors are given by SQLSTATE, the code the SQL standard defines, and SQLCODE, the older number, as Turborel gives them; Appendix B maps them to the driver's error.

Pages of reference

A page of the API Reference has these sections, in this order:

  • NAME: the interface, class, module or function, and what it does in a line.
  • SYNOPSIS: its declaration, in Python.
  • DESCRIPTION: what it does.
  • ERRORS: each way it fails, by SQLSTATE.
  • EXAMPLES: programs, and what they print.
  • STANDARD: the sections of Turborel's documents it follows, and, for the standard API, the specification of the interface.
  • SEE ALSO: related pages.