← Cloudflare D1 / d1 / best-practices

Локальная разработка

D1 полноценно поддерживает локальную разработку и запускает ту же версию D1, что использует Cloudflare в глобальном масштабе. Локальная разработка использует Wrangler, интерфейс командной строки для Workers, предназначенный для управления сессиями локальной разработки и их состоянием.

Сессии локальной разработки создают автономную, полностью локальную среду, воспроизводящую продакшен-окружение, в котором работает D1, чтобы вы могли тестировать Worker и D1 до вы развернёте в продакшене.

Существующий привязка D1 DB будет доступна вашему Worker при локальном запуске.

Чтобы начать локальную сессию разработки:

1. Убедитесь, что вы используете wrangler v3.0+.

   wrangler --version

   ⛅️ wrangler 3.0.0

2. Запуск локальной сессии разработки

   wrangler dev

   ------------------
   wrangler dev now uses local mode by default, powered by 🔥 Miniflare and 👷 workerd.
   To run an edge preview session for your Worker, use wrangler dev --remote
   Your worker has access to the following bindings:
   - D1 Databases:
   	- DB: test-db (c020574a-5623-407b-be0c-cd192bab9545)
   ⎔ Starting local server...
   
   [mf:inf] Ready on http://127.0.0.1:8787/
   [b] open a browser, [d] open Devtools, [l] turn off local mode, [c] clear console, [x] to exit

В этом примере Worker имеет доступ только к локальной базе данных D1. Соответствующая привязка D1 в вашем конфигурационный файл Wrangler будет выглядеть следующим образом:

{
	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "test-db",
			"database_id": "c020574a-5623-407b-be0c-cd192bab9545"
		}
	]
}

[[d1_databases]]
binding = "DB"
database_name = "test-db"
database_id = "c020574a-5623-407b-be0c-cd192bab9545"

Обратите внимание, что wrangler dev разделяет локальные и продакшен (удалённые) данные. Локальная сессия по умолчанию не имеет доступа к вашим продакшен-данным. Чтобы получить доступ к продакшен (удалённой) базе данных, задайте "remote" : true в конфигурации привязки D1. См. документация по remote bindings с дополнительной информацией. Все изменения, внесённые при работе с удалённой базой данных, отменить нельзя.

См. wrangler dev документация чтобы узнать больше о настройке локальной сессии разработки.

Разработку можно вести только с использованием локальный базы данных D1 при использовании Cloudflare Pages путём создания минимального конфигурационный файл Wrangler в корне вашего проекта Pages. Это может быть полезно при создании схем, заполнении данными или ином прямом управлении базой данных D1, не затрагивая логику приложения.

Ваш конфигурационный файл Wrangler должен выглядеть примерно так:

{
	// If you are only using Pages + D1, you only need the below in your Wrangler config file to interact with D1 locally.
	"d1_databases": [
		{
			"binding": "DB", // Should match preview_database_id
			"database_name": "YOUR_DATABASE_NAME",
			"database_id": "the-id-of-your-D1-database-goes-here", // wrangler d1 info YOUR_DATABASE_NAME
			"preview_database_id": "DB" // Required for Pages local development
		}
	]
}

[[d1_databases]]
binding = "DB"
database_name = "YOUR_DATABASE_NAME"
database_id = "the-id-of-your-D1-database-goes-here"
preview_database_id = "DB"

После этого в рамках локальной разработки можно выполнять запросы и/или миграции к локальной базе данных, передав --local флаг для wrangler:

wrangler d1 execute YOUR_DATABASE_NAME \
  --local --command "CREATE TABLE IF NOT EXISTS users ( user_id INTEGER PRIMARY KEY, email_address TEXT, created_at INTEGER, deleted INTEGER, settings TEXT);"

Приведённая выше команда выполнила бы запросы, которые только локально версия вашей базы данных D1. Без --local флага, команды выполняются для удалённой версии вашей базы данных D1, работающей в сети Cloudflare.

Используйте wrangler dev --persist-to=/path/to/file чтобы сохранять данные в определённом месте. Это может быть полезно при работе в команде (позволяя использовать одну и ту же копию), при развёртывании через CI/CD (для обеспечения одинакового начального состояния) или как способ сохранить данные при переносе между машинами.

Пользователям wrangler 2.x должен использовать --persist флаг: предыдущие версии wrangler по умолчанию не сохраняли данные.

Miniflare ↗ позволяет моделировать Workers и ресурсы, такие как D1, используя ту же среду выполнения и код, что и в продакшене.

Можно использовать возможности Miniflare поддержка D1 ↗ чтобы создать базы данных D1, которые можно использовать для тестирования:

{
	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "test-db",
			"database_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
		}
	]
}

[[d1_databases]]
binding = "DB"
database_name = "test-db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

const mf = new Miniflare({
	d1Databases: {
		DB: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	},
});

После этого можно использовать getD1Database() метод, чтобы получить смоделированную базу данных и выполнять к ней запросы так, как если бы это была ваша настоящая рабочая база данных D1:

const db = await mf.getD1Database("DB");

const stmt = db.prepare("SELECT name, age FROM users LIMIT 3");
const { results } = await stmt.run();

console.log(results);

Wrangler предоставляет unstable_dev() который позволяет запускать локальный HTTP-сервер для тестирования Workers и D1. Выполните миграции к локальной базе данных, задав preview_database_id в конфигурации Wrangler.

При следующей конфигурации Wrangler:

{
	"d1_databases": [
		{
			"binding": "DB", // i.e. if you set this to "DB", it will be available in your Worker at `env.DB`
			"database_name": "your-database", // the name of your D1 database, set when created
			"database_id": "<UUID>", // The unique ID of your D1 database, returned when you create your database or run `
			"preview_database_id": "local-test-db" // A user-defined ID for your local test database.
		}
	]
}

[[d1_databases]]
binding = "DB"
database_name = "your-database"
database_id = "<UUID>"
preview_database_id = "local-test-db"

Миграции можно выполнять локально как часть настройки CI/CD, передав --local флаг для wrangler:

wrangler d1 migrations apply your-database --local

В следующем примере показано, как использовать Wrangler unstable_dev() API, чтобы:

• Выполните миграции на локальной тестовой базе данных, заданной в preview_database_id.
• Отправьте запрос к конечной точке, определённой в вашем Worker. В этом примере используется /api/users/?limit=2.
• Убедитесь, что возвращаемые результаты совпадают, включая Response.status и JSON, который возвращает наш API.

import { unstable_dev } from "wrangler";
import type { UnstableDevWorker } from "wrangler";

describe("Test D1 Worker endpoint", () => {
	let worker: UnstableDevWorker;

	beforeAll(async () => {
		// Optional: Run any migrations to set up your `--local` database
		// By default, this will default to the preview_database_id
		execSync(`NO_D1_WARNING=true wrangler d1 migrations apply db --local`);

		worker = await unstable_dev("src/index.ts", {
			experimental: { disableExperimentalWarning: true },
		});
	});

	afterAll(async () => {
		await worker.stop();
	});

	it("should return an array of users", async () => {
		// Our expected results
		const expectedResults = `{"results": [{"user_id": 1234, "email": "[email protected]"},{"user_id": 6789, "email": "[email protected]"}]}`;
		// Pass an optional URL to fetch to trigger any routing within your Worker
		const resp = await worker.fetch("/api/users/?limit=2");
		if (resp) {
			// https://jestjs.io/docs/expect#tobevalue
			expect(resp.status).toBe(200);
			const data = await resp.json();
			// https://jestjs.io/docs/expect#tomatchobjectobject
			expect(data).toMatchObject(expectedResults);
		}
	});
});

Просмотрите unstable_dev() документацию, чтобы узнать больше об использовании API в тестах.

• Используйте wrangler dev чтобы запустить Worker и D1 локально и устранить проблемы перед развёртыванием.
• Узнайте как отлаживать D1.
• Узнайте, как журналы доступа сгенерированный вашим Worker и D1.