From 66b24cc271dfe9b41f36c56caceef49a883ddaf4 Mon Sep 17 00:00:00 2001
From: Joaquin Gimenez <jg@joaquingimenez.com>
Date: Mon, 30 Dec 2024 10:17:00 -0300
Subject: [PATCH] Add Workflow example

---
 .../docs/workflows/examples/backup-d1.mdx     | 142 ++++++++++++++++++
 1 file changed, 142 insertions(+)
 create mode 100644 src/content/docs/workflows/examples/backup-d1.mdx

diff --git a/src/content/docs/workflows/examples/backup-d1.mdx b/src/content/docs/workflows/examples/backup-d1.mdx
new file mode 100644
index 00000000000000..e5946297730fac
--- /dev/null
+++ b/src/content/docs/workflows/examples/backup-d1.mdx
@@ -0,0 +1,142 @@
+---
+type: example
+summary: Backup D1 using export API and save it on R2
+tags:
+  - Workflows
+  - D1
+  - R2
+languages:
+  - Typescript
+pcx_content_type: configuration
+title: Backup and save D1 database
+sidebar:
+  order: 3
+description: Send invoice when shopping cart is checked out and paid for
+
+---
+
+import { TabItem, Tabs } from "~/components"
+
+In this example, we implement a Workflow periodically triggered by a [Cron Trigger](/workers/configuration/cron-triggers) to start a backup for a D1 database using the REST API and finally store the SQL dump in an R2 bucket.
+
+Once a Workflow instance is triggered, fetches the REST API to start an export job for a specific database. Then, it fetches the same endpoint to check if the backup job is ready and the SQL dump is available to download.
+
+As you can see, Workflows handles the responses and failures. It will retry the API calls until we get a successful response, retry fetching the backup from the URL provided, and retry saving the file to R2. The developer doesn't have to care about any of that logic. The workflow can run until the backup file is ready, handling all the possible conditions until it is completed.
+
+This is a simplified example of backing up a [D1](/d1) database. For every step, we use the [default](/workflows/build/sleeping-and-retrying) sleeping and retrying configuration. In a real-life scenario, we would assume more steps and additional logic, but this example gives you a good idea of what you can do with Workflows.
+
+```ts
+import {
+  WorkflowEntrypoint,
+  WorkflowStep,
+  WorkflowEvent,
+} from "cloudflare:workers";
+
+
+// We are using R2 to store the D1 backup
+type Env = {
+  BACKUP_WORKFLOW: Workflow;
+  D1_REST_API_TOKEN: string;
+  BACKUP_BUCKET: R2Bucket;
+};
+
+// Workflow parameters: we expect accountId and databaseId
+type Params = {
+  accountId: string;
+  databaseId: string;
+};
+
+// Workflow logic
+export class backupWorkflow extends WorkflowEntrypoint<Env, Params> {
+  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
+    const { accountId, databaseId } = event.payload;
+
+    const url = `https://api.cloudflare.com/client/v4/accounts/${accountId}/d1/database/${databaseId}/export`;
+    const method = "POST";
+    const headers = new Headers();
+    headers.append("Content-Type", "application/json");
+    headers.append("Authorization", `Bearer ${this.env.D1_REST_API_TOKEN}`);
+
+    const bookmark = step.do(`Starting backup for ${databaseId}`, async () => {
+      const payload = { output_format: "polling" };
+
+      const res = await fetch(url, { method, headers, body: JSON.stringify(payload) });
+      const { result } = (await res.json()) as any;
+
+      // If we don't get `at_bookmark` we throw to retry the step
+      if (!result?.at_bookmark) throw new Error("Missing `at_bookmark`");
+
+      return result.at_bookmark;
+    });
+
+    step.do("Check backup status and store it on R2", async () => {
+      const payload = { current_bookmark: bookmark };
+
+      const res = await fetch(url, { method, headers, body: JSON.stringify(payload) });
+      const { result } = (await res.json()) as any;
+
+      // The endpoint sends `signed_url` when the backup is ready to download.
+      // If we don't get `signed_url` we throw to retry the step.
+      if (!result?.signed_url) throw new Error("Missing `signed_url`");
+
+      const dumpResponse = await fetch(result.signed_url);
+      if (!dumpResponse.ok) throw new Error("Failed to fetch dump file");
+
+      // Finally, stream the file directly to R2
+      await this.env.BACKUP_BUCKET.put(result.filename, dumpResponse.body);
+    });
+  }
+}
+
+export default {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    return new Response("Not found", { status: 404 });
+  },
+  async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext) {
+    const params: Params = {
+      accountId: "{accountId}",
+      databaseId: "{databaseId}",
+    };
+    const instance = await env.BACKUP_WORKFLOW.create({ params });
+    console.log(`Started workflow: ${instance.id}`);
+  },
+};
+```
+
+Here's a minimal package.json:
+
+```json
+{
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20241224.0",
+    "wrangler": "^3.99.0"
+  }
+}
+```
+
+And finally wrangler.toml:
+
+import { WranglerConfig } from "~/components";
+
+<WranglerConfig>
+
+```toml
+name = "backup-d1"
+main = "src/index.ts"
+compatibility_date = "2024-12-27"
+compatibility_flags = [ "nodejs_compat" ]
+
+[[workflows]]
+name = "backup-workflow"
+binding = "BACKUP_WORKFLOW"
+class_name = "backupWorkflow"
+
+[[r2_buckets]]
+binding = "BACKUP_BUCKET"
+bucket_name = "d1-backups"
+
+[triggers]
+crons = [ "0 0 * * *" ]
+```
+
+</WranglerConfig>
\ No newline at end of file