Skip to main content

​
libSQL / Turso Connections

TablePro supports libSQL and Turso databases in two modes: remote connections via the Hrana HTTP protocol (Turso cloud databases and self-hosted sqld instances) and local libSQL database files opened directly from disk.

​
Install Plugin

The libSQL / Turso driver is available as a downloadable plugin. When you select libSQL / Turso in the connection form, TablePro will prompt you to install it automatically. You can also install it manually:
  1. Open Settings > Plugins > Browse
  2. Find libSQL / Turso Driver and click Install
  3. The plugin downloads and loads immediately - no restart needed

​
Quick Setup

1

Open Connection Form

Click New Connection from the Welcome screen or File > New Connection
2

Select libSQL / Turso

Choose libSQL / Turso from the database type selector
3

Choose Connection Mode

Pick Remote (Turso) for a Turso or sqld server, or Local File to open a database file on disk
4

Enter Connection Details

Remote: fill in your Database URL and Auth Token. Local: pick the database file with Browse…
5

Test and Connect

Click Test Connection, then Create

​
Connection Settings

​
Connection Mode

ModeDescription
Remote (Turso)Connects over HTTP using the Hrana protocol. For Turso cloud and self-hosted sqld.
Local FileOpens a libSQL database file directly from disk. Unencrypted libSQL files use the standard SQLite file format.

​
Remote Fields

FieldDescription
NameConnection identifier
Database URLFull URL to your libSQL database (e.g., https://your-db-name.turso.io or http://localhost:8080)
Auth TokenBearer token for authentication (optional for self-hosted sqld without auth)
The Auth Token field is optional. Self-hosted sqld instances can run without authentication, in which case you can leave this field empty.

​
Local File Fields

FieldDescription
NameConnection identifier
Database FilePath to the database file. Use Browse… to pick it, or type a path (~ is expanded).
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.

​
Getting Your Credentials

​
Turso Cloud

Database URL: Find it on the Turso dashboard or run: 
turso db show <database-name> --url
This returns a URL like libsql://your-db-name-your-org.turso.io. TablePro automatically rewrites libsql:// to https:// for the HTTP connection. Auth Token: Generate a token with the Turso CLI: 
turso db tokens create <database-name>
Store your auth token securely. TablePro saves it in the macOS Keychain, but the token grants full access to your database.

​
Self-hosted sqld

Database URL: The default sqld HTTP endpoint is http://localhost:8080. Adjust the host and port to match your sqld configuration. Auth Token: Depends on your sqld setup. If you started sqld without --auth-jwt-key-file, no token is needed. If JWT authentication is enabled, generate a token matching your configured key.

​
Example Configuration

​
Turso Cloud

Name:          My Turso DB
Database URL:  libsql://my-app-db-myorg.turso.io
Auth Token:    (your Turso auth token)

​
Self-hosted sqld

Name:          Local sqld
Database URL:  http://localhost:8080
Auth Token:    (leave empty if no auth configured)

​
Local File

Name:             My Local libSQL DB
Connection Mode:  Local File
Database File:    ~/Databases/app.db

​
Features

​
Database Browsing

After connecting, the sidebar shows tables and views in the database. libSQL databases have a single “main” schema, similar to SQLite.

​
Table Browsing

For each table, TablePro shows:
  • Structure: Columns with SQLite data types, nullability, default values, and primary key info
  • Indexes: B-tree indexes with column details
  • Foreign Keys: Foreign key constraints with referenced tables
  • DDL: The full CREATE TABLE statement

​
Query Editor

Write and execute SQL queries using SQLite syntax: 
-- Query data
SELECT name, email FROM users WHERE id > 10 ORDER BY name;

-- Create tables
CREATE TABLE posts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER REFERENCES users(id),
    title TEXT NOT NULL,
    content TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Aggregations
SELECT user_id, COUNT(*) as post_count
FROM posts
GROUP BY user_id
HAVING post_count > 5;

​
EXPLAIN Query Plan

Analyze query execution plans using the Explain button in the query editor. TablePro uses EXPLAIN QUERY PLAN to show how SQLite processes your queries.

​
Data Editing

Edit cell values, insert rows, and delete rows directly in the data grid. Changes are submitted as standard INSERT, UPDATE, and DELETE statements, via the Hrana HTTP API in remote mode or directly against the file in local mode.

​
Export

Export query results or table data to CSV, JSON, SQL, and other formats.

​
SQL Dialect

libSQL uses SQLite syntax. See SQLite for details.

​
Troubleshooting

​
Authentication Failed

Symptoms: “Authentication failed” or HTTP 401 response Solutions:
  1. Verify your auth token is correct and has not expired
  2. For Turso Cloud, generate a new token: turso db tokens create <name>
  3. For self-hosted sqld, check that your JWT matches the configured key
  4. Ensure you have not accidentally included extra whitespace in the token

​
Invalid URL

Symptoms: “Invalid database URL” or connection fails immediately Solutions:
  1. Check the URL format: https://your-db.turso.io for Turso, http://localhost:8080 for sqld
  2. Do not include a trailing slash or path components
  3. libsql:// URLs are accepted and automatically rewritten to https://
  4. Verify the database exists: turso db list

​
Connection Timeout

Symptoms: Queries take too long or time out Solutions:
  1. Check your internet connection (for Turso Cloud)
  2. Verify sqld is running (for self-hosted): curl http://localhost:8080/health
  3. Simplify queries that scan large amounts of data

​
Rate Limited

Symptoms: HTTP 429 response or “rate limited” error Solutions:
  1. Wait for the retry period and try again
  2. Reduce query frequency
  3. Use pagination for large result sets instead of fetching all rows
  4. Check your Turso plan limits at Turso Pricing

​
File Not Found

Symptoms: Local file connection fails to open Solutions:
  1. Check the file path is correct and the file still exists at that location
  2. Use Browse… to re-pick the file if it was moved or renamed
  3. Make sure the file is not an encrypted libSQL database; encrypted 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 management via TablePro (use Turso CLI or sqld admin tools)
  • No bulk import through the plugin: use the Turso CLI or direct sqld import
  • No database switching: libSQL connections target a single database