Co-authored by
Hayden Bleaselnext-forge
Jamie BartonTurso

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 next-forge project.

​
1. Sign up to Turso

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>;
Switch to SupabaseSwitch to Fumadocs