SurrealDB
Use VibORM with SurrealDB, through its own query language
viborm/surrealdb writes SurrealQL, not SQL: a relation is a record link, a
many-to-many is a graph edge, and a filter on a relation walks the graph. Every
query, write, transaction, migration and official extension works the same as on
the other databases, with the differences below.
npm install viborm surrealdb
import { createClient } from "viborm/surrealdb";
import { schema } from "./schema";
const db = createClient({
schema,
url: "ws://127.0.0.1:8000/rpc",
namespace: "app",
database: "main",
authentication: { username: "root", password: "root" },
});
The driver connects at the first query. If that first connection does not open within
10 seconds (nothing answers at url), the query fails with V1001 instead of waiting:
the SDK would otherwise retry for good. Once connected, the SDK reconnects without a limit.
To keep control of the connection, pass a client you connected. The driver never closes it, nor bounds its connection:
import { Surreal } from "surrealdb";
import { SurrealDriver } from "viborm/surrealdb";
import { createClient } from "viborm";
const surreal = new Surreal();
await surreal.connect("ws://127.0.0.1:8000/rpc", {
namespace: "app",
database: "main",
authentication: { username: "root", password: "root" },
});
const db = createClient({ schema, driver: new SurrealDriver({ client: surreal }) });
Migrations
viborm/migrations/surrealdb gives push, generate, apply, verify, down
and reset. Generated files hold SurrealQL. The SurrealDB migration driver
page says what it writes and what it does differently.
import { createMigrationClient } from "viborm/migrations/surrealdb";
const migrations = createMigrationClient(db, { storage });
await migrations.generate({ name: "init" });
await migrations.apply();
Server settings
Permission policies write deep statements. Start the server with
SURREAL_MAX_QUERY_PARSING_DEPTH=128; a statement past the limit refuses by name
and says so.
What differs from SQL
- Transactions are snapshot isolated. There is no savepoint, so going back to
a nested
$transactionand a commit conflict run the statements again. If a concurrent write changed what they read, the transaction fails withV5001and can be retried;rerunsOnConflictretries a$transactioncallback for you, and everything it does outside the database happens again. A raw statement that begins withLET, outside a transaction, runs as one transaction of its own. A migration’s statement of that kind (the rewrite of a table’s rows on a key change) runs again when refused at its commit, since it wrote nothing and answered nothing. Your own$executeRaw/$queryRawstatement never runs again: it may hold its ownCOMMIT, so part of it may have committed, and the conflict is returned to you. - A single write outside
$transactionthat meets a concurrent write at commit has written nothing: it runs again by itself, up to 16 times. Inside your$transactionthe conflict is the transaction’s. - A write that needs no answer between its statements is one request, a transaction of
its own. If that request fails, the write runs again with one statement per request, so
that the error names the statement that failed: a write that fails costs two attempts.
logging.queryreports such a request once, under the model you called; astatementhook still sees each statement. isolationLevel: a transaction reads a snapshot, which gives whatReadUncommitted,ReadCommittedandRepeatableReadask.Serializableis refused: two transactions may each read what the other writes. There are no row locks.- A connection holds 64 open transactions, and the rest wait for one to end;
maxWaitbounds the wait. - A record’s key is its id, and an id never changes. Changing a key copies the
record to its new id, and what holds it follows. A key that is a
dateTimeordecimalis stored as its text. A decimal key, and a link to one, still compare and sort as numbers, but no index holds that order: a read that sorts by one, or filters it by a range, reads every row, and so does a page of the table it keys. - A foreign key to a unique field, rather than to the key, is events, not a record link:
on the referenced table, its actions; on the referencing table, that the row it names
exists, as a
REFERENCEchecks. A row whose reference holds one of its own unique fields is checked when that field is updated, not when the row is created: moving a record to a new key writes a stand-in there until the copy is complete. restricton a many-to-many is the driver’s: a rawDELETEdoes not hold back.- A partial unique index is a computed field. Its predicate may hold comparisons,
IN,IS [NOT] NULL,AND,ORandNOTover columns and values; anything else is refused by name. - A page in an order walks an index on its first field, as on SQL. A descending page first reads, in the same statement, that field’s value at the page’s last row, because the key that breaks ties ascends and no index here holds that order. Without an index on that field the page sorts every row.
- An
includewith atakewalks an index in its order only under a root page of at most 20 rows (or afindUnique), whose children are then read one row at a time, in the same statement, and only if the filters on both hold no subquery. Otherwise each row reads all its children and sorts them, as SurrealDB plans a correlated read without one. - An order through a to-one follows its links and looks up who references the row it reached. A to-one that is no record link (a foreign key in its row’s own key, a compound one, or one to a unique field) can be ordered by only from the row itself; behind another relation it is refused by name.
- A
groupByreads every row it groups. Under atakeof at most 20 groups, ordered by a field an index holds and without ahaving, it first seeks those groups on the index and reads only their rows. - Every index kind is a plain index here: a
spatial,ginorfulltextdeclaration is kept, and a read through it scans as it would without. An HNSW or search index is declared with.rawIndex(), whose comment holds VibORM’s marker. Any other index VibORM did not define (another kind, or a comment of someone else’s) refuses synchronization before effects while its table is managed, and is left as it is; drop it, and declare it. So does a table or field comment that is not VibORM’s JSON. Outside the managed tables both are skipped. A generated junction’s indexes are not read. - A field named
idbeside a key of another name is stored asid_field:idis the record’s. - Renaming a table or a field, and changing a key, copy the rows, statement by statement, since SurrealDB has no rename and a record’s id never changes. They are not atomic.
- A concurrent delete and insert can leave an orphan:
REFERENCEis checked in each transaction’s own snapshot, and neither sees the other. - Raw fragments are SurrealQL, and
$executeRawparameters are named$p1,$p2. - A
$queryRawor a filter fragment cannot hold SQL subqueries.