Switch to Turso

Turso is multi-tenant database platform built for all types of apps, including AI apps with on-device RAG, local-first vector search, offline writes, and privacy-focused data access with low latency. Here’s how to switch from Neon to Turso for your ShipThing project. You can use the Dashboard, or the CLI to manage your account, database, and auth tokens. We’ll be using the CLI throughout this guide.

2. Create a Database

Create a new database and give it a name using the Turso CLI:

Terminal

turso db create <database-name>

You can now fetch the URL to the database:

Terminal

turso db show <database-name> --url

It will look something like this:

libsql://<database-name>-<account-or-org-slug>.turso.io

3. Create a Database Auth Token

You will need to create an auth token to connect to your Turso database:

Terminal

turso db tokens create <database-name>

4. Update your environment variables

Update your environment variables to use the new Turso connection string:

apps/database/.env

DATABASE_URL="libsql://<database-name>-<account-or-org-slug>.turso.io"
DATABASE_AUTH_TOKEN="..."

apps/app/.env.local

DATABASE_URL="libsql://<database-name>-<account-or-org-slug>.turso.io"
DATABASE_AUTH_TOKEN="..."

Etcetera. Now inside packages/env/index.ts, add DATABASE_AUTH_TOKEN to the server and runtimeEnv objects:

const server: Parameters<typeof createEnv>[0]["server"] = {
  // ...
  DATABASE_AUTH_TOKEN: z.string(),
  // ...
};

export const env = createEnv({
  client,
  server,
  runtimeEnv: {
    // ...
    DATABASE_AUTH_TOKEN: process.env.DATABASE_AUTH_TOKEN,
    // ...
  },
});

5. Install @libsql/client

The @libsql/client is used to connect to the hosted Turso database. Uninstall the existing dependencies for Neon…

Terminal

pnpm remove @neondatabase/serverless @prisma/adapter-neon ws @types/ws --filter @repo/database

… and install the new dependencies for Turso & libSQL:

Terminal

pnpm add @libsql/client --filter @repo/database

6. Update Webpack configuration

Open packages/next-config/index.ts and add @libsql/client to the list of externals:

packages/next-config/index.ts

let nextConfig: NextConfig = {
  ...config,
  webpack: (config, { isServer }) => {
    if (isServer) {
      config.externals = [...(config.externals || []), "@libsql/client"];
    }

    // ...
  },
};

7. Update the database connection code

Open packages/database/index.ts and make the following changes:

packages/database/index.ts

import "server-only";

import { createClient } from "@libsql/client";
import { env } from "@repo/env";

const libsql = createClient({
  url: env.DATABASE_URL,
  authToken: env.DATABASE_AUTH_TOKEN,
});

export const database = libsql;

8. Apply schema changes

Now connect to the Turso database using the CLI:

Terminal

turso db shell <database-name>

And apply the schema to the database:

CREATE TABLE pages (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  email TEXT UNIQUE NOT NULL,
  name TEXT
);

9. Update application code

Now wherever you would usually call Prisma, use the libsql client instead:

packages/app/app/(authenticated)/page.tsx

import { database } from "@repo/database";

type PageType = {
  id: number;
  email: string;
  name?: string;
};

// ...

const { rows } = await database.execute(`SELECT * FROM pages`);

const pages = rows as unknown as Array<PageType>;

Authentication

Database

Feature flags

Formatting

2. Create a Database

3. Create a Database Auth Token

4. Update your environment variables

5. Install @libsql/client

6. Update Webpack configuration

7. Update the database connection code

8. Apply schema changes

9. Update application code

​1. Sign up to Turso

​2. Create a Database

​3. Create a Database Auth Token

​4. Update your environment variables

​5. Install @libsql/client

​6. Update Webpack configuration

​7. Update the database connection code

​8. Apply schema changes

​9. Update application code

1. Sign up to Turso

2. Create a Database

3. Create a Database Auth Token

4. Update your environment variables

5. Install @libsql/client

6. Update Webpack configuration

7. Update the database connection code

8. Apply schema changes

9. Update application code