From Cloudflare Workers + D1
This is the full path for a Next.js app running on Cloudflare Workers/Pages (typically via OpenNext) with a D1 database. You will move the runtime to brrrd, the database to Louhi (libSQL), and your data from D1 to Louhi. It is written as a runbook a coding agent can execute.
In practice the Cloudflare coupling is small and usually lives in one file (your database client). The steps below are the validated path used to migrate real apps onto the platform.
If the application also stores files in Cloudflare R2, treat that as a
separate object migration: complete this runtime/database guide, then follow
From S3, R2, or compatible storage. Do not put
an R2 API token or access key into the deployed app; the destination uses a
project-scoped cwp_ token through the Comwit S3 endpoint.
1. Switch the runtime to brrrd
Section titled “1. Switch the runtime to brrrd”Do the runtime work from the Next.js guide first:
pnpm add @brrrd/adapter; setadapterPath: require.resolve("@brrrd/adapter")innext.config.- Remove the OpenNext /
@opennextjs/cloudflaresetup (the init call,wranglerdeploy wiring,open-next.config.ts). - Upgrade to Next ^16.2 / React 19 if you are not there yet.
- Apply the runtime checklist (native image dependencies, request duration, public assets, etc.).
- Build with
next build --webpack→dist/brrrd.
2. Swap the database client (D1 → libSQL)
Section titled “2. Swap the database client (D1 → libSQL)”Find your D1 client — usually src/server/db/index.ts — and replace the
Cloudflare/D1 wiring with a libSQL client. Keep the same exported names so
the rest of your app doesn’t change.
import { drizzle } from "drizzle-orm/d1";import { getCloudflareContext } from "@opennextjs/cloudflare";
export const getDb = async () => { const { env } = await getCloudflareContext({ async: true }); return drizzle(env.DB, { schema });};import "server-only";import { type Client as LibsqlClient } from "@libsql/client/web";import { createClient } from "@tursodatabase/serverless/compat";import { drizzle } from "drizzle-orm/libsql/web";import * as schema from "./schema";
export const getDb = async () => { const client = createClient({ url: process.env.DATABASE_URL!, authToken: process.env.DATABASE_AUTH_TOKEN!, }); // Create a fresh client per request: the serverless compat client serializes // work internally, so one long-lived instance can stall unrelated requests. return drizzle({ client: client as unknown as LibsqlClient, schema });};pnpm add @tursodatabase/serverless @libsql/client drizzle-ormpnpm remove @opennextjs/cloudflare # and any wrangler-only D1 depsYour Drizzle schema is portable as-is — only the client changes.
3. Move D1 data into a new Louhi database
Section titled “3. Move D1 data into a new Louhi database”There are two paths. For anything beyond a few megabytes, convert the D1 export to a SQLite file locally and upload the file; Comwit creates the database from it server-side in upload time plus a short validation. Replaying the SQL dump statement by statement works for small databases but takes minutes for large ones.
Recommended: upload a SQLite file
Section titled “Recommended: upload a SQLite file”wrangler d1 export <DB_NAME> --remote --output d1-dump.sqlcomwit databases create \ --project <projectId> \ --name app-db \ --from-dump ./d1-dump.sql \ --token-out ./app-db.tokenThe CLI converts the dump into a single SQLite file locally (no sqlite3
install needed; add --sqlite-out ./app.sqlite to keep it), checks
integrity_check and foreign_key_check, streams the file, waits until the
database is ready, and prints the database_id, database_url, and one-time
token. If you already have a SQLite file, pass it with --from-file instead
(single file with no -wal/-shm sidecar; use
sqlite3 src.db ".backup out.sqlite" if needed). Generated columns and
extension-backed virtual tables are not supported. Size limit is 2 GiB.
Alternative: replay the SQL dump
Section titled “Alternative: replay the SQL dump”comwit databases import-dump \ --project <projectId> \ --name app-db \ --from-dump d1-dump.sqlThe command prints:
database— the new database idurl— set this asDATABASE_URLtoken— set this asDATABASE_AUTH_TOKEN; it is shown once
import-dump is new database only. It does not import into an existing
database and it does not accept a raw SQLite .db file. If you already have a
local .db, export SQL first with sqlite3 source.db .dump > dump.sql.
The importer handles normal Wrangler/D1, SQLite .dump, and Turso .dump
output. It also skips known fresh-database noise such as
PRAGMA defer_foreign_keys and direct sqlite_sequence maintenance.
Large transaction-wrapped dumps must fit in one CLI replay request. If the CLI reports that the transaction is too large, split the export into smaller transaction-free chunks or wait for a future server-side import workflow.
4. Fresh schema-only option
Section titled “4. Fresh schema-only option”If you have no D1 data to keep, create an empty database and push your final schema directly:
comwit databases create --project <projectId> --name app-dbDATABASE_URL=... DATABASE_AUTH_TOKEN=... pnpm drizzle-kit push --force5. Set environment and deploy
Section titled “5. Set environment and deploy”comwit apps create --project <projectId> --name web
comwit apps env set --project <projectId> --app <appId> DATABASE_URL "$DATABASE_URL"comwit apps env set --project <projectId> --app <appId> DATABASE_AUTH_TOKEN "$DATABASE_AUTH_TOKEN"
comwit deploy \ --project <projectId> \ --app <appId> \ --package ./dist/brrrd \ --host app.example.com6. Verify
Section titled “6. Verify”- App renders on its hostname (test pages in a browser — isolate-only runtime errors pass the build).
comwit apps logs --project <projectId> --app <appId> --tail 100shows no startup or route errors.- Database reads/writes work against Louhi.
- If you moved data, spot-check row counts and a few records.
Common Cloudflare-specific gotchas, recapped
Section titled “Common Cloudflare-specific gotchas, recapped”| Symptom | Cause | Fix |
|---|---|---|
| OG/icon route 500s | Route imports native image code such as sharp or another .node addon | Use next/og’s adapter/runtime WASM fallback, static assets, or an external image service; do not use runtime = "edge" as a blanket fix |
| Import request too large | One oversized transaction-wrapped dump | Split into smaller transaction-free dumps or wait for server-side import |
| Import rejected | SQL feature or provider-specific statement does not translate to Louhi/libSQL | Edit the dump at the statement index printed by the CLI, then rerun into a new database |
.db rejected by import-dump | import-dump accepts SQL dumps only | Use comwit databases create --from-file source.db instead |
Once it’s live, automate redeploys from GitHub Actions.