> ## Documentation Index
> Fetch the complete documentation index at: https://ngquct-docs-fix-500-query-results.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# libSQL / Turso

> Connect to Turso cloud databases, self-hosted sqld, or local libSQL files

export const name_0 = "libSQL / Turso"

export const plugin_0 = "libSQL / Turso Driver"

**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 {name_0} driver is not in the app. Picking {name_0} in the **Choose a Database** sheet offers the
download before the form opens, and opening a saved {name_0} connection installs it without asking.
**Settings > Plugins > Browse > {plugin_0}** installs it up front. See [Plugins](/features/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**.

<Frame caption="The libSQL connection form with the Connection Mode dropdown">
  <img className="block dark:hidden" src="https://mintcdn.com/ngquct-docs-fix-500-query-results/HJY892UtvXUv1PFn/images/libsql-connection-mode.png?fit=max&auto=format&n=HJY892UtvXUv1PFn&q=85&s=8e49ba564d096854dc57b32fb65a31e9" alt="libSQL connection form showing Remote (Turso) and Local File modes" width="1560" height="960" data-path="images/libsql-connection-mode.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/ngquct-docs-fix-500-query-results/HJY892UtvXUv1PFn/images/libsql-connection-mode-dark.png?fit=max&auto=format&n=HJY892UtvXUv1PFn&q=85&s=f73303bb1cc52543511e75b8eb9c868f" alt="libSQL connection form showing Remote (Turso) and Local File modes" width="1560" height="960" data-path="images/libsql-connection-mode-dark.png" />
</Frame>

## 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 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.

<Danger>
  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.
</Danger>

## Connection URL

```text theme={null}
libsql://your-db-name.turso.io
https://your-db-name.turso.io
```

Importing either creates a Remote connection. See [Connection URL Reference](/connections/urls).

## Getting a token

Take the URL and a fresh token from the Turso [dashboard](https://turso.tech/app) or the CLI:

```bash theme={null}
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](/databases/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](/connections/ssl).

## 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.

## Related

* [SQLite](/databases/sqlite)
* [Import & Export](/features/import-export)