Draft: Workflow example

Author: JoaquinGimenez1

src/content/docs/workflows/examples/backup-d1.mdx

@@ -0,0 +1,138 @@
+---
+type: example
+summary: Backup D1 using export API and save it on R2
+tags:
+  - Workflows
+  - D1
+  - R2
+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 for an e-commerce website that is triggered every time a shopping cart is created.
+
+Once a Workflow instance is triggered, it starts polling a [D1](/d1) database for the cart ID until it has been checked out. Once the shopping cart is checked out, we proceed to process the payment with an external provider doing a fetch POST. Finally, assuming everything goes well, we try to send an email using [Email Workers](/email-routing/email-workers/) with the invoice to the customer.
+
+As you can see, Workflows handles all the different service responses and failures; it will retry D1 until the cart is checked out, retry the payment processor if it fails for some reason, and retry sending the email with the invoice if it can't. The developer doesn't have to care about any of that logic, and the workflow can run for hours, handling all the possible conditions until it is completed.
+
+This is a simplified example of processing a shopping cart. We would assume more steps and additional logic in a real-life scenario, 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.
+      // 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);
+      // We 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>