Skip to main content
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 through the system SQLite engine. The driver is not in the app. Picking in the Choose a Database sheet offers the download before the form opens, and opening a saved connection installs it without asking. Settings > Plugins > Browse > installs it up front. See Plugins.

​
Quick setup

Click Create 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

The libSQL connection form with the Connection Mode dropdown

​
Connection settings

​
Remote (Turso)

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

The API Token field is hidden here; a local file needs no authentication.
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

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:
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/TLS pane. 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 system SQLite engine gets the statement and rejects it. Rewrite it as standard SQLite DDL.
  • 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.