Turso
Reylo on Turso Cloud and Turso's own engine
Turso Cloud runs libSQL, a fork of SQLite, so everything on the SQLite page holds for it.
| Dialect | SQLite |
| The type check reads | A local SQLite file with your schema, never a libsql:// URL |
| Turso Cloud | @libsql/client, with .run() |
| Turso's own engine | @tursodatabase/database, with .run(), and .runSync() on its compat Database |
| Migrations | reylo migrate, on Turso Cloud through its libsql:// URL |
| SQLite versions | Reylo's 3.53, and the SQLite of each driver your package.json lists: 3.45.1 for @libsql/client |
| libSQL's own SQL | Vector columns and indexes, the vector functions, vector_top_k and alter table … alter column (Vectors) |
View the schema behind the examples
create table users (
id integer primary key,
name text not null,
email text,
settings text not null default '{}'
) strict;
create table docs (
id integer primary key,
title text not null,
emb F32_BLOB(3)
);
create index docs_emb on docs (libsql_vector_idx(emb));Turso Cloud
Pass an @libsql/client client, made with your database's URL and an auth token, or a transaction taken from it:
import { } from "@libsql/client";
import from "./add_user.sql";
import from "./find_user.sql";
const = ({
: ..!, // libsql://…
: ..,
});
const = await .(, { : 1 });
// both inserts land, or neither
const = await .("write");
await .(, { : "Ada" });
await .(, { : "Grace" });
await .();select id, name, email from users where id = :idinsert into users (name) values (:name)- The client answers through a promise, so use
.run(), not.runSync(). - With the default
intMode, libSQL throws aRangeErroron an integer past 2^53. SetintMode: "bigint"to get it exact. - A Drizzle database over
@libsql/clientworks too (Drizzle).
Local database
Make a local SQLite file from a dump of your Turso database:
turso db shell app .dump > dump.sql
sqlite3 dev.db < dump.sqlOr run your migrations into a new file:
for file in migrations/*.sql; do sqlite3 dev.db < "$file"; donePoint direct_url at it:
# the path starts at package.json
direct_url: file:./dev.db- A
DATABASE_URLthat holds yourlibsql://URL fails the type check, which reads onlyfile:andsqlite:URLs for SQLite. Adirect_urlwins over it. - In development, your app can open the same file:
createClient({ url: "file:dev.db" })needs no auth token. - In CI, run your migrations into the file before the type check (Deployment). The job needs no Turso token.
Migrations
Run Reylo Migrate on Turso Cloud with your database's URL, its auth token in authToken:
npx reylo migrate deploy --url "libsql://app-acme.turso.io?authToken=$TURSO_AUTH_TOKEN"To make a token, run turso db tokens create app. Keep direct_url on your local file, so the type check and reylo migrate dev stay on it, and pass --url to reach Turso Cloud:
steps:
# ...
- run: npx reylo migrate deploy --url "$TURSO_DATABASE_URL?authToken=$TURSO_AUTH_TOKEN"
env:
TURSO_DATABASE_URL: ${{ secrets.TURSO_DATABASE_URL }}
TURSO_AUTH_TOKEN: ${{ secrets.TURSO_AUTH_TOKEN }}- Every
reylo migrateandreylo dbcommand runs on Turso Cloud, and on any libSQL server: alibsql://,https://orhttp://URL, as@libsql/clienttakes it. Add?tls=0to alibsql://URL for a server without TLS. - From code, pass the same URL:
migrate({ url })(API). - Shadow databases are in memory, on libSQL's own engine as Turso Cloud runs it: SQLite 3.47.0, libSQL's SQL, and the functions Turso Cloud adds, such as
floor,percentile,uuid4andregexp_like. - Migrations can use libSQL's own SQL, such as a vector index (
libsql_vector_idx) oralter table … alter column. When your migrations orschema.sqldo,reylo migrate devand every other command open your local file on libSQL's engine too. - Each migration runs in one transaction with its history row. Two deploys on one machine take turns; two on different machines at once don't, and one of them fails, changing nothing.
SQLite version
The SQLite in @libsql/client is 3.45.1, older than Reylo's 3.53. With @libsql/client in your package.json, the type check also runs each query on it:
{
"dependencies": {
"@libsql/client": "^0.18.0"
}
}A query it refuses is a type error, with its own message:
queries/user_settings.sql(1,12): error reylo6: @libsql/client runs SQLite 3.45.1, which refuses this statement: no such function: json_prettyIt refuses json_pretty, which came in SQLite 3.46, and iif with two arguments, which came in 3.48. Functions has the rest.
Vectors
Reylo types libSQL's vector SQL. Declare a column as a vector, such as F32_BLOB(3), index it with libsql_vector_idx, and search it with vector_top_k:
import { } from "@libsql/client";
import from "./add_doc.sql";
import from "./nearest_docs.sql";
const = ({ : "file:dev.db" });
await .(, { : "Ada", : "[0.1,0.2,0.3]" });
const = await .(, { : "[0.1,0.2,0.3]" });select docs.id, docs.title
from vector_top_k('docs_emb', vector32(:q), 5) as top
join docs on docs.id = top.idinsert into docs (title, emb) values (:title, vector32(:embedding))- A vector parameter takes the vector's text, as
'[0.1,0.2,0.3]'. The count ofvector_top_ktakes an integer. - Each row of
vector_top_kis theidof a row of the indexed table: its rowid, or the primary key of aWITHOUT ROWIDtable. - A distance, from
vector_distance_cosorvector_distance_l2, isnumber | null, since it'sNULLwhere it can't be computed, as for a vector of zeros. - A vector function fails on a
NULLvector, where most SQLite functions returnNULL. Leave rows without one out withwhere emb is not null. - A vector column is typed as a
BLOBcolumn outside aSTRICTtable, since libSQL refuses vector types in aSTRICTtable..run()returns a vector as aUint8Array, andvector_extract(emb)returns its text. - A driver whose SQLite has no vectors, such as
better-sqlite3, refuses these queries in the type check. Turso's own engine can't open a schema with a vector index, so the type check doesn't run queries on it then. alter table … alter columntype-checks as a statement that returns nothing.
Turso's own engine
Turso's own engine, @tursodatabase/database, runs in your process on a database file. Pass the database connect() resolves to, or the transaction .transactionAsync() hands its callback:
import { } from "@tursodatabase/database";
import { } from "@tursodatabase/database/compat";
import from "./add_user.sql";
import from "./find_user.sql";
const = await ("dev.db");
const = await .(, { : 1 });
// both inserts land, or neither
await .(async () => {
await .(, { : "Ada" });
await .(, { : "Grace" });
})();
// synchronous
const = new ("dev.db");
const = .(, { : 1 });- The
Databaseof@tursodatabase/database/compatis synchronous, so.runSync()works on it, inside itsdb.transaction(fn)as well. - The type check reads the same file, through
direct_urlas above. - With
@tursodatabase/databasein yourpackage.json, the type check also runs each query on Turso's engine, unless your schema has an FTS5 table or a vector index, which the engine can't open. - From 0.8 on, its errors carry no code. With
.try(),codeisundefinedand onlymessagenames the failure. - An integer past 2^53 comes back exact.