> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tablepro.app/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

# libSQL / Turso Connections

TablePro supports libSQL in two modes: remote over the Hrana HTTP protocol (Turso cloud and self-hosted sqld) and local libSQL database files opened directly from disk. The driver is a downloadable plugin; TablePro offers to install it when you select **libSQL / Turso** in the connection form. See [Plugins](/features/plugins).

## Connection Settings

Pick a mode with the **Connection Mode** dropdown:

| Mode               | Description                                                                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Remote (Turso)** | Connects over HTTP using the Hrana protocol. For Turso cloud and self-hosted sqld.                                                            |
| **Local File**     | Opens a libSQL database file directly from disk using the system SQLite engine. Unencrypted libSQL files use the standard SQLite file format. |

### Remote fields

| Field            | Description                                                                                                                                                             |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Database URL** | Full URL to your database, e.g. `https://your-db-name.turso.io` or `http://localhost:8080`. `libsql://` URLs are rewritten to `https://` automatically.                 |
| **API Token**    | Bearer token, entered in the built-in password field (labeled **API Token** for this driver). Optional for self-hosted sqld without auth. Stored in the macOS Keychain. |

### Local File fields

| Field             | Description                                                                       |
| ----------------- | --------------------------------------------------------------------------------- |
| **Database File** | Path to the file. Use **Browse...** to pick it, or type a path (`~` is expanded). |

In Local File mode the API Token field is hidden; local files need no authentication.

<Frame caption="The libSQL connection form with the Connection Mode dropdown">
  <img className="block dark:hidden" src="https://mintcdn.com/ngquct/tXWaltqW4Zqkau0T/images/libsql-connection-mode.png?fit=max&auto=format&n=tXWaltqW4Zqkau0T&q=85&s=91d59305a61e531392396322aab2d6d7" 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/tXWaltqW4Zqkau0T/images/libsql-connection-mode-dark.png?fit=max&auto=format&n=tXWaltqW4Zqkau0T&q=85&s=d6d289e58477626fdfd5e841d7822e73" alt="libSQL connection form showing Remote (Turso) and Local File modes" width="1560" height="960" data-path="images/libsql-connection-mode-dark.png" />
</Frame>

Click **Test Connection** to verify, then **Save & Connect**.

## Getting Your Credentials

### Turso Cloud

Find the database URL on the [Turso dashboard](https://turso.tech/app) or with the CLI:

```bash theme={null}
turso db show <database-name> --url
turso db tokens create <database-name>
```

### Self-hosted sqld

The default sqld HTTP endpoint is `http://localhost:8080`. If you started sqld without `--auth-jwt-key-file`, leave the token empty. With JWT authentication enabled, generate a token matching your configured key.

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

## SQL Dialect

libSQL uses SQLite syntax; browsing, structure, EXPLAIN QUERY PLAN, data editing, and export work as they do for SQLite. See [SQLite](/databases/sqlite).

## Troubleshooting

**Authentication failed (HTTP 401)**: The token is wrong or expired. Generate a new one with `turso db tokens create <name>`; for sqld, check the JWT matches the configured key. Watch for stray whitespace in the pasted token.

**Invalid URL**: Use `https://your-db.turso.io` for Turso or `http://localhost:8080` for sqld, without a trailing slash or path. `libsql://` URLs are accepted. Verify the database exists with `turso db list`.

**File not found (local mode)**: Re-pick the file with **Browse...** if it was moved or renamed. Encrypted libSQL files cannot be opened in local mode.

## Known Limitations

Remote mode:

* No persistent connections: each query is an independent HTTP request via the Hrana protocol
* No multi-statement transactions: each SQL statement auto-commits independently
* No custom SSL/SSH tunnels: connections use HTTPS (Turso Cloud) or HTTP (local sqld)

Local mode:

* No embedded replica sync: local files open standalone, without syncing to a remote Turso database
* No encrypted database files
* libSQL-only SQL extensions (e.g. `ALTER TABLE ALTER COLUMN`) are unavailable; local mode uses the system SQLite engine

Both modes:

* No database creation or switching from TablePro; a connection targets a single database
* No bulk import through the plugin: use the Turso CLI or direct sqld import