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.

Packages and Registries

An extension is distributed as a package, one file that holds its manifest, its executable for each platform, its documents and any data files. Each file in it carries its SHA-256 digest, and the package may be signed with Ed25519. A registry is a directory of packages and a signed index of them, served over HTTPS. turborel extension installs packages from files and registries into a server's plug-in directory, keeps a lock of exactly what it installed, and upgrades and removes them. CREATE EXTENSION then loads an installed package by its name.

This chapter is for two readers. An author packs and signs a plug-in and publishes it. An operator chooses the registries and keys a server trusts, and installs, upgrades and checks packages.

Versions and ranges

A package's VERSION is a semantic version, MAJOR.MINOR.PATCH, with an optional prerelease after -, as 2.1.0-beta.1. Build metadata after + is allowed and passed over. Versions are ordered as semantic versioning orders them, so 1.0.0-rc.1 comes before 1.0.0.

A range says which versions a requirement accepts.

Range Accepts
1.2.3 or =1.2.3 exactly 1.2.3
>1.2.3, >=1.2.3, <2.0.0, <=1.4 the versions above, from, below or up to the one written
^1.2.3 1.2.3 up to but not including 2.0.0; ^0.2.3 stops before 0.3.0 and ^0.0.3 before 0.0.4
~1.2.3 1.2.3 up to but not including 1.3.0; ~1 is any 1.x
1.x, 1.2.x, 1, 1.2 any version of the parts written
*, x or nothing any version
1.2.3 - 2.0.0 from the first to the second, both included
>=1.2.0 <2.0.0 or >=1.2.0, <2.0.0 the versions that meet every comparator
^1.0.0 || ^3.0.0 the versions of either

A prerelease is taken only when asked for. It meets a range only if a comparator of that range names a prerelease of the same MAJOR.MINOR.PATCH, so ^1.0.0 never takes 1.1.0-beta.1, and >=1.1.0-beta.1 takes 1.1.0-beta.2 but not 1.2.0-beta.1.

For authors

The manifest of a package

A package's manifest is the plug-in's manifest (Plug-ins) with three more items, each ended by a semicolon.

Item Says
REQUIRES name 'range' the package needs another package, of a version in the range
TURBOREL 'range' the releases of turborel it runs on
UPGRADE FROM 'range' SCRIPT 'path' the SQL script ALTER EXTENSION ... UPDATE runs when it upgrades from a version in the range

A package's name is an SQL identifier, upper case unless quoted, and turborel extension takes it in any case.

NAME geo_tools;
VERSION '1.4.0';
PROTOCOL 1;
EXECUTABLE FOR 'linux' 'bin/geo-tools';
EXECUTABLE FOR 'windows' 'bin/geo-tools.exe';
EXECUTABLE FOR 'macos' 'bin/geo-tools-macos';
REQUIRES UNITS '^2.0.0';
TURBOREL '>=0.0.0';
UPGRADE FROM '>=1.0.0 <1.4.0' SCRIPT 'upgrade/1.4.sql';
FUNCTION AREA_KM2(DOUBLE PRECISION, DOUBLE PRECISION) RETURNS DOUBLE PRECISION DETERMINISTIC;

The upgrade scripts that apply are run in the order of the lowest version each range names.

A signing key

turborel extension keygen writes a new Ed25519 signing key, and its public key beside it with .pub after the name. It never writes over a file. Keep the key file private, as the command writes it with the permissions a new file gets, and give operators the public key.

$ turborel extension keygen --output author.key
wrote the key author.key and its public key 3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29

Packing

turborel extension pack DIR builds the package of the plug-in in DIR. It takes every file under DIR but those whose names begin with .. The manifest, the executables and upgrade scripts it names, and the files under doc/ are told apart in the package. With --key the package is signed. The signature covers the manifest and every file's path and digest, so no file can be changed or added without breaking it.

$ turborel extension pack geo_tools --key author.key
packed GEO_TOOLS 1.4.0 into geo_tools-1.4.0.tbpkg, signed by 3b6a27bc...9da29, sha256 0d5c...

Publishing to a registry

turborel extension publish DIR --registry-dir REG --key KEY packs and signs DIR, writes the package into the registry directory REG, adds it to REG's index, and signs the index again with the same key. The index is trusted for 30 days unless --expires-days says otherwise. Publish again before it expires, even with no new package, so clients never see an index that expired.

$ turborel extension publish geo_tools --registry-dir /srv/registry --key author.key
published GEO_TOOLS 1.4.0 as geo_tools-1.4.0.tbpkg
signed the index of /srv/registry, trusted until 2026-12-19T09:00:00Z

Hosting a registry

A registry is a static directory, so any web server that serves files over HTTPS hosts one. No registry is operated for turborel, so there is no default, and each organization runs its own or uses a third party's. The directory holds three kinds of file.

File Holds
index the packages, one package line each, with their requirements, and when the index expires
index.sig the public key that signed the index and its Ed25519 signature, in hexadecimal
*.tbpkg the package files

An index, format 1, reads as follows.

turborel-registry 1
expires 2026-12-19T09:00:00Z
package GEO_TOOLS 1.4.0 geo_tools-1.4.0.tbpkg 0d5c...e1 3b6a...29
requires UNITS ^2.0.0
turborel >=0.0.0
package UNITS 2.1.0 units-2.1.0.tbpkg 9f02...4a 3b6a...29

A client trusts an index only after its signature verifies by a key it trusts, whether or not it requires signed packages, and only before it expires. A stale index, or an old one replayed, is refused. Only then does the client trust the digests the index lists, and a package fetched whose digest differs is refused. Each package still carries its own signature, which the server checks as it installs the package and every time its program starts.

A mirror is a copy of the directory. A directory of the local machine also serves as a registry, named by its path or a file:// URL.

For operators

Settings

turborel extension reads the server's settings, given with --set NAME=VALUE or in the environment as TURBOREL_ and the name with . written _.

Setting Meaning
PLUGINS.DIRECTORIES the plug-in directories; packages are installed into the first, as <name>/<version>/
PLUGINS.REGISTRIES the registries' URLs, separated by ;, the first tried first
PLUGINS.PINS NAME=URL entries separated by ;, each taking a package from that registry alone
PLUGINS.TRUSTED_KEYS the Ed25519 public keys trusted, in hexadecimal, separated by ;, or @ and a file of them, one a line
PLUGINS.REQUIRE_SIGNED ON refuses a package no trusted key signed, and a plug-in directory no package installed

Downloaded packages are kept in a cache, .cache in the plug-in directory unless --cache names another, by their digest, so a package installed again is not fetched again. --tls FILE trusts the registries' certificates of a PEM file instead of the platform's authorities.

Installing

$ turborel extension install geo_tools@^1.0.0 --set PLUGINS.DIRECTORIES=/var/lib/turborel/plugins \
    --set PLUGINS.REGISTRIES=https://plugins.example.com/ --set PLUGINS.TRUSTED_KEYS=3b6a...29
installed UNITS 2.1.0 from https://plugins.example.com/
installed GEO_TOOLS 1.4.0 from https://plugins.example.com/

Install resolves the whole set again. It takes every package asked for by name, with its range, and every package they require, choosing the newest versions that meet every requirement and trying older ones where a newer one leads to a conflict. One version of each package is installed in a set. A dependency cycle, or requirements no versions meet, is refused with SQLSTATE 38T09, naming the requirement. A package file may be named instead of a name, and is installed with what it requires.

A package installed is never changed after. Its files are checked against their digests as it is installed and each time its program starts, so a changed file is refused with SQLSTATE 38T07.

The lock

The plug-in directory keeps a lock, turborel-extensions.lock, of the exact set installed, each package's name, version, the SHA-256 digest of its package file, its registry, and the range it was asked for by name.

turborel-lock 1
GEO_TOOLS 1.4.0 0d5c...e1 https://plugins.example.com/ explicit ^1.0.0
UNITS 2.1.0 9f02...4a https://plugins.example.com/ dependency

install with no package installs exactly what the lock names, from the cache or the registry, each file's digest the one locked. lock export FILE writes the lock to a file, and lock import FILE installs exactly what it names on another server and keeps it as that server's lock, so two servers run the same packages to the byte. Each database records the version of each extension it created, as INFORMATION_SCHEMA.EXTENSIONS shows, and a version stays installed while a database runs it.

Keeping packages current

Command Does
outdated lists each package with a newer version, the newest its range allows and the newest of all
upgrade [NAME]... upgrades to the newest versions the ranges allow
upgrade NAME --latest upgrades beyond the range, and keeps the new version's caret range
why NAME tells which packages required NAME, back to one asked for by name
remove NAME removes a package no installed package requires
autoremove removes packages installed only as dependencies that nothing requires now, and versions the lock no longer names
verify checks every installed file against its digest and the package's signature
clean empties the cache
search WORDS... lists the registries' packages whose names hold a word
info NAME lists a package's versions, what each requires, and its signer
$ turborel extension outdated --set ...
name current wanted latest
GEO_TOOLS 1.4.0 1.5.2 2.0.0
$ turborel extension why units --set ...
UNITS is required by GEO_TOOLS 1.4.0 (^2.0.0)
  GEO_TOOLS 1.4.0 was installed by name

A database moves to a new version with ALTER EXTENSION name UPDATE, which runs the package's upgrade scripts in the statement's transaction. CREATE EXTENSION name with no FROM loads the newest installed version that meets every requirement, and VERSION names a version or range.

Conditions

SQLSTATE Condition
38T07 a package or installed file is not what its digest says, or a lock's digest differs from the registry's
38T08 a package is unsigned or signed by no trusted key where a signature is required, a signature does not verify, or a registry's index is unsigned, untrusted or expired
38T09 no versions meet every requirement, or the requirements form a cycle