Connect Turso from Workers: @libsql/client/web is the only path

Why there is only one path

Hyperdrive pools the Postgres/MySQL TCP protocols; libSQL is outside its supported scope. Fortunately @libsql/client in HTTP mode fits Workers naturally: every request is a single HTTPS call, with no long-lived connection required.

The free tier covers roughly 100 databases and 5GB of storage — enough for prototypes and small-to-medium applications.

Prepare the database and credentials

turso db create notes
turso db show notes --url        # shaped like libsql://<db>-<user>.turso.io
turso db tokens create notes     # generates an auth token

Store the connection string and the token as separate secrets:

npx wrangler secret put TURSO_DATABASE_URL
npx wrangler secret put TURSO_AUTH_TOKEN

Do not put the token into vars in wrangler.jsonc, and never commit it. If it leaks, regenerate and rotate it on the Turso side.

Worker code

npm i @libsql/client

import { createClient } from '@libsql/client/web';

interface Env {
  TURSO_DATABASE_URL: string;
  TURSO_AUTH_TOKEN: string;
}

export default {
  async fetch(request, env: Env): Promise<Response> {
    const client = createClient({
      url: env.TURSO_DATABASE_URL,
      authToken: env.TURSO_AUTH_TOKEN,
    });
    try {
      const result = await client.execute('SELECT id, title FROM notes LIMIT 10');
      return Response.json({ notes: result.rows });
    } catch (error) {
      return Response.json({ error: String(error) }, { status: 502 });
    }
  },
};

This path needs no Wrangler binding; the only configuration is the two secrets.

Verification and troubleshooting

curl -s https://<worker>.workers.dev/notes

Remote boundary and rollback

Creating the Turso database, generating tokens, writing secrets, and deploying the Worker all change remote state; this tutorial does not run those actions. Rollback: remove the related routes in code and redeploy — Workers holds no long-lived connections, so there is no pool to drain. Then delete the TURSO_DATABASE_URL and TURSO_AUTH_TOKEN secrets in Cloudflare and revoke the token on the Turso side. If you are rolling the whole approach back to D1, export the data first, then import into D1 and rewrite the data layer against the D1 binding — the schema is SQLite dialect, so migration cost is relatively low, but verify table by table.

Next: connect TiDB from Workers. For the selection recap, see the external database integrations overview.

Primary sources

• Connect to Turso using Workers
• Databases and features supported by Hyperdrive