← Cloudflare D1 / d1 / best-practices

Lokální vývoj

D1 má plnohodnotnou podporu lokálního vývoje a spouští stejnou verzi D1, jakou Cloudflare provozuje globálně. Lokální vývoj využívá Wrangler, rozhraní příkazového řádku pro Workers, ke správě relací a stavu lokálního vývoje.

Relace lokálního vývoje vytvoří samostatné, čistě lokální prostředí, které odpovídá produkčnímu prostředí, ve kterém běží D1, abyste mohli otestovat svůj Worker a D1 před nasadíte do produkčního prostředí.

Existující D1 binding z DB by byla dostupná vašemu Workeru při lokálním spouštění.

Pro spuštění lokální vývojové relace:

1. Ověřte, že používáte wrangler v3.0 nebo novější.

   wrangler --version

   ⛅️ wrangler 3.0.0

2. Spusťte místní vývojovou relaci

   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

V tomto příkladu má Worker přístup pouze k lokální databázi D1. Odpovídající D1 binding ve vašem Konfigurační soubor Wrangler by vypadala následovně:

{
	"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"

Upozorňujeme, že wrangler dev odděluje lokální data od produkčních (vzdálených). Lokální relace nemá ve výchozím nastavení přístup k vašim produkčním datům. Pro přístup k produkční (vzdálené) databázi nastavte "remote" : true v konfiguraci bindingu D1. Viz dokumentace k remote bindings pro další informace. Jakékoli změny provedené při práci se vzdálenou databází nelze vrátit zpět.

Viz wrangler dev dokumentace a dozvíte se více o konfiguraci relace lokálního vývoje.

Vyvíjet můžete pouze vůči lokální databáze D1 při použití Cloudflare Pages vytvořením minimálního Konfigurační soubor Wrangler v kořenovém adresáři vašeho projektu Pages. To se hodí při vytváření schémat, plnění dat testovacími hodnotami nebo jiné přímé správě databáze D1 bez zásahu do logiky aplikace.

Váš Konfigurační soubor Wrangler by mělo vypadat následovně:

{
	// 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"

Poté můžete spouštět dotazy nebo migrace proti lokální databázi v rámci lokálního vývoje předáním --local příznak nástroji 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);"

Předchozí příkaz by provedl dotazy, které pouze lokální verzi vaší databáze D1. Bez --local příznakem se příkazy spouští proti vzdálené verzi vaší databáze D1, která běží v síti Cloudflare.

Použijte wrangler dev --persist-to=/path/to/file k trvalému uložení dat na konkrétní místo. To se hodí při práci v týmu (umožňuje sdílet) stejnou kopii, při nasazování přes CI/CD (zajišťuje stejný počáteční stav) nebo jako způsob uchování dat při migraci mezi stroji.

Uživatelé wrangler 2.x musí používat --persist příznak: předchozí verze nástroje wrangler standardně data neukládaly trvale.

Miniflare ↗ umožňuje simulovat Workers a prostředky jako D1 pomocí stejného základního runtime a kódu, jaký se používá v produkci.

Můžete použít Miniflare podpora D1 ↗ k vytvoření databází D1, které můžete použít pro testování:

{
	"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",
	},
});

Poté můžete použít getD1Database() metoda pro získání simulované databáze a spouštění dotazů proti ní, jako by šlo o vaši skutečnou produkční databázi 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 poskytuje unstable_dev() který vám umožňuje spustit lokální HTTP server pro testování Workers a D1. Spusťte migrace vůči lokální databázi nastavením preview_database_id ve vaší konfiguraci Wrangler.

Uvažujme následující konfiguraci 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"

Migrace můžete spouštět lokálně jako součást nastavení CI/CD tím, že předáte --local příznak pro wrangler:

wrangler d1 migrations apply your-database --local

Následující příklad ukazuje, jak použít Wranglerův unstable_dev() API k těmto účelům:

• Spusťte migrace na lokální testovací databázi definované v preview_database_id.
• Odešlete požadavek na koncový bod definovaný ve vašem Workeru. Tento příklad používá /api/users/?limit=2.
• Ověřte, že se vrácené výsledky shodují, včetně Response.status a JSON, který naše API vrací.

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);
		}
	});
});

Zkontrolujte unstable_dev() dokumentaci, kde najdete více informací o použití API v testech.

• Použijte wrangler dev ke spuštění Workeru a D1 lokálně a k ladění problémů před nasazením.
• Přečtěte si jak ladit D1.
• Seznamte se s tím, jak protokoly přístupu vygenerovaný z vašeho Workeru a D1.