Skip to content

libsql.mdx

Latest commit

 

History

History
100 lines (64 loc) · 5.31 KB

libsql.mdx

File metadata and controls

100 lines (64 loc) · 5.31 KB
Raw
title libSQL / Turso
description Connect to Turso cloud databases, self-hosted sqld, or local libSQL files

import RegistryPlugin from "/snippets/registry-plugin.mdx";

Connection Mode decides every other field on the form. Remote speaks the Hrana HTTP protocol to Turso or a self-hosted sqld; Local File opens a libSQL file with the SQLite engine the driver carries.

Quick setup

Click New Connection…, select libSQL / Turso, pick a Connection Mode, fill in the fields it leaves on screen, then click Test Connection and Save & Connect.

libSQL connection form showing Remote (Turso) and Local File modes

libSQL connection form showing Remote (Turso) and Local File modes

Connection settings

Remote (Turso)

Field Description
Database URL https://your-db-name.turso.io, or http://localhost:8080 for sqld. A libsql:// URL is rewritten to https://, and trailing slashes are dropped
API Token The bearer token, in the password field, labeled API Token for this driver. Leave it empty for a sqld started without --auth-jwt-key-file. Stored in the macOS Keychain

There is no host, no port and no Database field: the URL names one database and the connection stays on it. Any Turso database works, as does any sqld serving the Hrana v2 pipeline endpoint.

Local File

Field Description
Database File Path to the file. Browse… picks one, New… names one that does not exist yet, and ~ expands. A path that does not exist is created, along with any missing folders

The API Token field is hidden here; a local file needs no authentication. Options gains two lists in this mode: Attached Databases, which attaches more files the way it does for SQLite, and Extensions, which loads SQLite extensions the way it does for SQLite.

Do not open a file that is being synced as a Turso embedded replica while the owning app is running. Concurrent access to a syncing replica can corrupt it.

Connection URL

libsql://your-db-name.turso.io
https://your-db-name.turso.io

Importing either creates a Remote connection. See Connection URL Reference.

Getting a token

Take the URL and a fresh token from the Turso dashboard or the CLI:

turso db show <database-name> --url
turso db tokens create <database-name>

A self-hosted sqld answers on http://localhost:8080 by default. With JWT authentication on, generate a token matching the key the server started with.

Schema and SQL

libSQL takes SQLite syntax, so browsing, EXPLAIN QUERY PLAN, data editing and export behave as they do on SQLite. The structure editor creates tables, adds and drops columns, and adds and drops indexes; Triggers in the Structure tab creates, edits and drops those.

SSL/TLS

There is no SSL Mode. A Remote connection is encrypted when its Database URL starts with https:// and is not when it starts with http://, and a local file is not networked at all. See SSL/TLS.

Limitations

  • Remote mode runs no transaction. Each statement is its own HTTP request and auto-commits, and BEGIN fails with Transactions are not supported in this mode. Use Local File mode for transactional work.
  • Local File mode does not sync. The file opens standalone, with no embedded-replica sync to a remote Turso database. Reach the remote copy through Remote mode.
  • libSQL-only SQL such as ALTER TABLE ALTER COLUMN does not run in Local File mode. The SQLite engine gets the statement and rejects it. Rewrite it as standard SQLite DDL.
  • Remote mode loads no extensions. A Turso database runs the extensions its server was built with.
  • Encrypted libSQL files do not open in Local File mode.
  • The structure editor cannot rename a column, change its type, nullability or default, or edit a foreign key. Recreate the table instead.
  • One connection, one database. A switch returns Switching databases is not supported, and there is no create or drop.
  • No bulk import, no SSH tunnel, no custom TLS settings. Load data with the Turso CLI or a direct sqld import.

Troubleshooting

Authentication failed

The full message is Authentication failed. Check your auth token. The server answered 401 or 403. Generate a new token with turso db tokens create <name>; for sqld, check the JWT matches the configured key. Watch for whitespace picked up in the paste.

Server not found

Server not found. Check your database URL. is a 404. The URL wants the bare origin, https://your-db.turso.io or http://localhost:8080, with no path. Confirm the database exists with turso db list.

Rate limited

Rate limited. Retry after … seconds. means Turso is throttling the connection. Wait out the interval it names, then retry.

Related