cx-platform-db

Why reach for it

A database is a URL, and the rows come back as a document. cx-platform-db is external database access: $sql-open, $sql-exec, $sql-query and $sql-close, $redis-open, $redis-cmd and $redis-close — builtins of the language, nothing to import — with the engine chosen by the URL's scheme: sqlite in the default build, redis, postgres and mysql as packs.

A query answers [rows [row …]], a statement answers its change count and last row id, and every refusal is a value with a place in the order: an operand of the wrong kind is refused before any engine is consulted, an unknown handle is one uniform runtime error, closing a handle twice is null rather than a fault, and a constraint violation is an error carrying the backend's own state code — never an empty success. A refused multi-row statement leaves nothing behind.

Opening a connection is an effect, so it needs the write grant, and a connection URL that carries a credential is consumed at open — it never reaches a log line or an error message afterwards. Parameters bind by position as strings, and [param null=true] binds the backend's own NULL, which is what a keyset walk needs for the page before the first cursor. This is database access, not the CX store: sqlite:// as a store substrate belongs to the store platform — two sqlites, one name.

What it gives you

No module namespace: the surface is the seven builtins named above, specified in the repository's db_access page and graded by one corpus that covers every engine the default build carries. The registry names the repository through three rows — the suite and its two backends, sql and redis — none of them a module a program imports, so the table the generator draws for a module-shipping repository is the note below instead.

This repository ships no bundled module of its own; what it gives you is above, and its links are below.

Try it

A whole lifecycle against an in-memory sqlite: open, create, insert, sum, close — the rows as a document, the grant on the command line because opening a database is an effect.

        [?let [= $c [$sql-open "sqlite://:memory:"]] [= $create [$sql-exec $c "CREATE TABLE t (x INTEGER)"]] [= $insert [$sql-exec $c "INSERT INTO t VALUES (40), (2)"]] [= $r [$sql-query $c "SELECT SUM(x) AS total FROM t"]] [= $closed [$sql-close $c]] $r]
      

        $ cx --allow-write prog.cx
[rows [row [total '42']]]
      

Status

The drivers build on the language and are built on by the application host, their only in-tree consumer; the front door compiles the V module from the pin with the default engines, and a build without them answers that sql-open is not callable — a missing flag, not a defect.

Links

• github.com/cx-home/cx-platform-db — the repository
• README — what it is, how to install it, what it pins
• spec/03-approved — the specification, the only truth
• conformance — the conformance corpus, the executable truth