Manual setup
Manually setting up D1, applying migrations, and seeding your database
Creating and setting up D1
Before you begin, ensure your terminal is created in the root of the application you will be using your databases in. This guide assumes apps/app is the target application.
Create the D1 database
npx wrangler d1 create your-database-nameCopy the database ID
The CLI tool will output the details of your new D1 database. Copy/save your database_id
✅ Successfully created DB 'your-database-name' in region WEUR
Created your new D1 database.
{
"d1_databases": [
{
"binding": "DB",
"database_name": "your-database-name",
"database_id": "DATABASE_ID_HERE"
}
]
}Add your D1 database configuration to wrangler.jsonc
wrangler will default to using a local migrations directory which will result in errors as we are using a centralised database package.
Add the migrations_dir value to the database configuration, ensuring it points to where your migrations are saved (a relative path from where wrangler.jsonc is located):
{
"$schema": "../../node_modules/wrangler/config-schema.json",
"name": "next-cloudflare-turbo",
"main": ".open-next/worker.js",
"compatibility_date": "2025-03-01",
"compatibility_flags": [
"nodejs_compat",
"global_fetch_strictly_public"
],
"assets": {
"binding": "ASSETS",
"directory": ".open-next/assets"
},
"d1_databases": [
{
"binding": "DB",
"database_name": "your-database-name",
"database_id": "DATABASE_ID_HERE",
"migrations_dir": "../../packages/db/drizzle/migrations"
}
]
} Add your database name to package.json
While we're using the full wrangler commands in this guide, they are also in the package.json scripts for convenience. Ensure you change the default database name (next-cloudflare-turbo) to match your database name
"scripts": {
"----- Database Local": "───────────────────────────────────────",
"db:migrate:local": "wrangler d1 migrations apply next-cloudflare-turbo --local",
"db:list:local": "wrangler d1 migrations list next-cloudflare-turbo --local",
"db:seed:local": "wrangler d1 execute next-cloudflare-turbo --local --file=../../packages/db/seed.sql",
"db:validate:local": "wrangler d1 execute next-cloudflare-turbo --local --command=\"SELECT name FROM sqlite_master WHERE type='table';\"",
"----- Database: Production": "───────────────────────────────────────",
"db:migrate:prod": "wrangler d1 migrations apply next-cloudflare-turbo --remote",
"db:info:prod": "wrangler d1 info next-cloudflare-turbo",
"db:seed:prod": "wrangler d1 execute next-cloudflare-turbo --file=../../packages/db/seed.sql --remote",
"db:validate:prod": "wrangler d1 execute next-cloudflare-turbo --remote --command=\"SELECT name FROM sqlite_master WHERE type='table';\""
}Generate types
Run npm run cf-typegen to ensure the new bindings are accessible when using getCloudflareContext()
Migrations
The database configuration, migrations and seed scripts are all part of our monorepo package @nct/db which is located in packages/db. This is where you make changes to the database schema and generate migrations.
In order to apply migrations, you must change over to the target application; in this example apps/app.
Generate migrations
From the packages/db folder run the command:
npm run db:generateApply migrations
npx wrangler d1 migrations apply DATABASE_NAME --localThe --local flag signifies to wrangler that this is being done on the local database, and not the one in your Cloudflare account.
Local D1 databases are stored in your filesystem, in .wrangler/state/v3/d1/miniflare-D1DatabaseObject
There is a convenience script in the package.json called db:migrate:local. You can modify this with your DATABASE_NAME and run npm run db:migrate:local instead of the full wrangler command instead
Seeding the database
Once you have successfully setup your D1 database and applied migrations, you can now seed the local database.
Run the seed script
npx wrangler d1 execute DATABASE_NAME --local --file=../../packages/db/seed.sqlYou can adjust the --file argument to point to your seed script
There is also a convenience script in the app's package.json file which can be run with npm run db:seed:local
Optional: Validate the local database
npx wrangler d1 execute DATABASE_NAME --local --command="SELECT name FROM sqlite_master WHERE type='table';"Applying migrations/seeding the remote database
Once everything is working locally, you can repeat the migration and seed steps to applying migrations/seed your remote database instead.
To do so, just replace the --local command with --remote instead - all commands are the same.
FAQ
How is this guide?
Last updated on