From f5088d0924dadbd554049dd55fd52ac582939ce5 Mon Sep 17 00:00:00 2001
From: Jacob M-G Evans <27247160+JacobMGEvans@users.noreply.github.com>
Date: Thu, 9 Oct 2025 17:13:34 -0700
Subject: [PATCH 1/8] test(cloudflare): comprehensive dead letter queue tests
 (#1093)

* test(cloudflare): comprehensive dead letter queue tests

Adds comprehensive test coverage for the dead letter queue feature in
QueueConsumer, which was fixed in PR #1092.

Tests cover:
- DLQ with string reference (queue name)
- DLQ with Queue object reference
- Updating consumer to add DLQ
- Worker eventSources with DLQ settings

Also includes the missing fix for build-worker-options.ts to properly
handle deadLetterQueue in Miniflare local development, and updates
queue-consumer.ts to preserve DLQ settings from props when the API
doesn't return them in the response.

Related: #1092

* test(cloudflare): comprehensive dead letter queue tests

Adds comprehensive test coverage for the dead letter queue feature in
QueueConsumer, which was fixed in PR #1092.

Tests cover:
- DLQ with string reference (queue name)
- DLQ with Queue object reference
- Updating consumer to add DLQ
- Worker eventSources with DLQ settings

Also includes the missing fix for build-worker-options.ts to properly
handle deadLetterQueue in Miniflare local development, and updates
queue-consumer.ts to preserve DLQ settings from props when the API
doesn't return them in the response.

Related: #1092

* Improved the DLQ test and fixed the typings for being root not in settings

* Removed DLQ response, since Cloudflare missed that DX in the API we will callback to the props instead for something to be there for the user

---------

Co-authored-by: Sam Goodwin <sam@alchemy.run>
---
 alchemy/src/cloudflare/queue-consumer.ts      |  35 +-
 .../test/cloudflare/queue-consumer.test.ts    | 656 +++++++++++++++++-
 2 files changed, 673 insertions(+), 18 deletions(-)

diff --git a/alchemy/src/cloudflare/queue-consumer.ts b/alchemy/src/cloudflare/queue-consumer.ts
index 50ac61daf..186afcd9d 100644
--- a/alchemy/src/cloudflare/queue-consumer.ts
+++ b/alchemy/src/cloudflare/queue-consumer.ts
@@ -229,6 +229,12 @@ export const QueueConsumer = Resource(
       );
     }
 
+    const deadLetterQueue = props.settings?.deadLetterQueue
+      ? typeof props.settings.deadLetterQueue === "string"
+        ? props.settings.deadLetterQueue
+        : props.settings.deadLetterQueue.name
+      : undefined;
+
     return {
       id: consumerData.result.consumer_id,
       queueId,
@@ -242,9 +248,14 @@ export const QueueConsumer = Resource(
             maxRetries: consumerData.result.settings.max_retries,
             maxWaitTimeMs: consumerData.result.settings.max_wait_time_ms,
             retryDelay: consumerData.result.settings.retry_delay,
-            deadLetterQueue: consumerData.result.settings.dead_letter_queue,
+            deadLetterQueue,
           }
-        : undefined,
+        : props.settings
+          ? {
+              ...props.settings,
+              deadLetterQueue,
+            }
+          : undefined,
       createdOn: consumerData.result.created_on,
       accountId: api.accountId,
     };
@@ -258,13 +269,13 @@ interface CloudflareQueueConsumerResponse {
   result: {
     consumer_id: string;
     script_name: string;
+    dead_letter_queue?: string;
     settings?: {
       batch_size?: number;
       max_concurrency?: number;
       max_retries?: number;
       max_wait_time_ms?: number;
       retry_delay?: number;
-      dead_letter_queue?: string;
     };
     type: "worker";
     queue_id?: string;
@@ -462,13 +473,13 @@ export async function listQueueConsumers(
       queue_id: string;
       queue_name: string;
       created_on: string;
+      dead_letter_queue?: string;
       settings?: {
         batch_size?: number;
         max_concurrency?: number;
         max_retries?: number;
         max_wait_time_ms?: number;
         retry_delay?: number;
-        dead_letter_queue?: string;
       };
     }>;
   };
@@ -492,7 +503,10 @@ export async function listQueueConsumers(
           maxRetries: consumer.settings.max_retries,
           maxWaitTimeMs: consumer.settings.max_wait_time_ms,
           retryDelay: consumer.settings.retry_delay,
-          deadLetterQueue: consumer.settings.dead_letter_queue,
+          deadLetterQueue:
+            consumer.dead_letter_queue && consumer.dead_letter_queue !== ""
+              ? consumer.dead_letter_queue
+              : undefined,
         }
       : undefined,
   }));
@@ -532,12 +546,12 @@ export async function listQueueConsumersForWorker(
   const data = (await response.json()) as {
     result: Array<{
       script: string;
+      dead_letter_queue?: string;
       settings?: {
         batch_size?: number;
         max_retries?: number;
         max_wait_time_ms?: number;
         retry_delay?: number;
-        dead_letter_queue?: string;
       };
       type: string;
       queue_name: string;
@@ -562,6 +576,13 @@ export async function listQueueConsumersForWorker(
     queueId: consumer.queue_id,
     consumerId: consumer.consumer_id,
     createdOn: consumer.created_on,
-    settings: consumer.settings,
+    settings: consumer.settings
+      ? {
+          ...consumer.settings,
+          deadLetterQueue: consumer.dead_letter_queue,
+        }
+      : consumer.dead_letter_queue
+        ? { deadLetterQueue: consumer.dead_letter_queue }
+        : undefined,
   }));
 }
diff --git a/alchemy/test/cloudflare/queue-consumer.test.ts b/alchemy/test/cloudflare/queue-consumer.test.ts
index 125e4dbeb..d25221871 100644
--- a/alchemy/test/cloudflare/queue-consumer.test.ts
+++ b/alchemy/test/cloudflare/queue-consumer.test.ts
@@ -2,6 +2,7 @@ import { describe, expect } from "vitest";
 import { alchemy } from "../../src/alchemy.ts";
 import { CloudflareApiError } from "../../src/cloudflare/api-error.ts";
 import { createCloudflareApi } from "../../src/cloudflare/api.ts";
+import { KVNamespace } from "../../src/cloudflare/kv-namespace.ts";
 import {
   listQueueConsumers,
   QueueConsumer,
@@ -45,7 +46,10 @@ describe("QueueConsumer Resource", () => {
               return new Response("Hello World");
             },
             async queue(batch, env, ctx) {
-              return batch.messages.map(() => ({ status: "ack" }));
+              // Acknowledge all messages successfully
+              for (const message of batch.messages) {
+                message.ack();
+              }
             }
           }
         `,
@@ -68,19 +72,20 @@ describe("QueueConsumer Resource", () => {
       }
       expect(thisConsumer).toBeTruthy();
     } finally {
-      // Always clean up, even if test assertions fail
       await destroy(scope);
 
-      // Verify consumers were deleted
       try {
         if (queue?.id) {
           await listQueueConsumers(api, queue.id);
         }
       } catch (err) {
         if (err instanceof CloudflareApiError && err.status === 404) {
-          // expected
+          // This is expected when queue is deleted
         } else {
-          throw err;
+          console.error(
+            "Unexpected error checking queue consumer deletion:",
+            err,
+          );
         }
       }
     }
@@ -91,7 +96,6 @@ describe("QueueConsumer Resource", () => {
     let worker: Worker | undefined;
 
     try {
-      // Create a queue
       queue = await Queue(`${testId}-adopt-queue`, {
         name: `${testId}-adopt-queue`,
         adopt: true,
@@ -99,7 +103,6 @@ describe("QueueConsumer Resource", () => {
 
       expect(queue.id).toBeTruthy();
 
-      // Create a worker that consumes the queue (this creates a consumer)
       worker = await Worker(`${testId}-adopt-worker`, {
         name: `${testId}-adopt-worker`,
         script: `
@@ -109,7 +112,10 @@ describe("QueueConsumer Resource", () => {
             },
             async queue(batch, env, ctx) {
               console.log("Processing", batch.messages.length, "messages");
-              return batch.messages.map(() => ({ status: "ack" }));
+              // Acknowledge all messages successfully
+              for (const message of batch.messages) {
+                message.ack();
+              }
             }
           }
         `,
@@ -117,8 +123,7 @@ describe("QueueConsumer Resource", () => {
         adopt: true,
       });
 
-      // Now try to adopt the existing consumer using QueueConsumer resource
-      await QueueConsumer(`${testId}-adopted`, {
+      const consumer = await QueueConsumer(`${testId}-adopted`, {
         queue: queue.id,
         scriptName: worker.name,
         adopt: true,
@@ -128,9 +133,638 @@ describe("QueueConsumer Resource", () => {
           maxWaitTimeMs: 1000,
         },
       });
+
+      expect(consumer.id).toBeTruthy();
+    } catch (err) {
+      console.error("Adopt test error:", err);
+      throw err;
+    } finally {
+      await destroy(scope);
+
+      try {
+        if (queue?.id) {
+          await listQueueConsumers(api, queue.id);
+        }
+      } catch (err) {
+        if (err instanceof CloudflareApiError && err.status === 404) {
+          // This is expected when queue is deleted
+        } else {
+          console.error(
+            "Unexpected error checking queue consumer deletion:",
+            err,
+          );
+        }
+      }
+    }
+  });
+
+  test("create queue consumer with dead letter queue (string)", async (scope) => {
+    let queue: Queue | undefined;
+    let dlq: Queue | undefined;
+    let worker: Worker | undefined;
+    let consumer: QueueConsumer | undefined;
+
+    try {
+      queue = await Queue(`${testId}-dlq-main`, {
+        name: `${testId}-dlq-main`,
+        adopt: true,
+      });
+
+      dlq = await Queue(`${testId}-dlq-dead`, {
+        name: `${testId}-dlq-dead`,
+        adopt: true,
+      });
+
+      expect(queue.id).toBeTruthy();
+      expect(dlq.id).toBeTruthy();
+
+      worker = await Worker(`${testId}-dlq-worker`, {
+        name: `${testId}-dlq-worker`,
+        script: `
+          export default {
+            async fetch(request, env, ctx) {
+              return new Response("Hello DLQ");
+            },
+            async queue(batch, env, ctx) {
+              // Simulate failures to test DLQ - retry all messages
+              for (const message of batch.messages) {
+                message.retry();
+              }
+            }
+          }
+        `,
+        adopt: true,
+      });
+
+      consumer = await QueueConsumer(`${testId}-dlq-consumer`, {
+        queue: queue.id,
+        scriptName: worker.name,
+        settings: {
+          batchSize: 10,
+          maxRetries: 3,
+          maxWaitTimeMs: 500,
+          retryDelay: 10,
+          deadLetterQueue: dlq.name,
+        },
+        adopt: true,
+      });
+
+      expect(consumer.id).toBeTruthy();
+      expect(consumer.settings?.deadLetterQueue).toEqual(dlq.name);
+      expect(worker).toBeTruthy();
+
+      const consumers = await listQueueConsumers(api, queue.id);
+      const foundConsumer = consumers.find(
+        (c) => c.scriptName === worker!.name,
+      );
+      expect(foundConsumer).toBeTruthy();
+
+      const consumerResponse = await api.get(
+        `/accounts/${api.accountId}/queues/${queue.id}/consumers/${consumer.id}`,
+      );
+      expect(consumerResponse.ok).toBe(true);
+      const consumerData: any = await consumerResponse.json();
+
+      expect(consumerData.result.dead_letter_queue).toEqual(dlq.name);
+      expect(consumerData.result.script).toEqual(worker.name);
+      expect(foundConsumer?.settings?.deadLetterQueue).toEqual(dlq.name);
+      expect(foundConsumer?.settings?.batchSize).toEqual(10);
+      expect(foundConsumer?.settings?.maxRetries).toEqual(3);
+
+      const queueResponse = await api.get(
+        `/accounts/${api.accountId}/queues/${queue.id}`,
+      );
+      expect(queueResponse.ok).toBe(true);
+      const queueData: any = await queueResponse.json();
+      expect(queueData.result.consumers).toBeDefined();
+      const queueConsumer = queueData.result.consumers?.find(
+        (c: any) => c.script === worker!.name,
+      );
+      expect(queueConsumer).toBeDefined();
+      expect(queueConsumer?.dead_letter_queue).toEqual(dlq.name);
+    } catch (err) {
+      console.error("DLQ test error:", err);
+    } finally {
+      await destroy(scope);
+
+      try {
+        if (queue?.id && consumer?.id) {
+          const response = await api.get(
+            `/accounts/${api.accountId}/queues/${queue.id}/consumers/${consumer.id}`,
+          );
+          if (response.status !== 404) {
+            throw new Error(
+              `Queue consumer ${consumer.id} was not deleted as expected`,
+            );
+          }
+        }
+      } catch (err) {
+        if (err instanceof CloudflareApiError && err.status === 404) {
+          // This is expected for this test case but dont need to log or throw
+        } else {
+          console.error(
+            "Unexpected error checking queue consumer deletion:",
+            err,
+          );
+        }
+      }
+    }
+  });
+
+  test("create queue consumer with dead letter queue (Queue object)", async (scope) => {
+    let queue: Queue | undefined;
+    let dlq: Queue | undefined;
+    let worker: Worker | undefined;
+    let consumer: QueueConsumer | undefined;
+
+    try {
+      queue = await Queue(`${testId}-dlq-obj-main`, {
+        name: `${testId}-dlq-obj-main`,
+        adopt: true,
+      });
+
+      dlq = await Queue(`${testId}-dlq-obj-dead`, {
+        name: `${testId}-dlq-obj-dead`,
+        adopt: true,
+      });
+
+      expect(queue.id).toBeTruthy();
+      expect(dlq.id).toBeTruthy();
+
+      worker = await Worker(`${testId}-dlq-obj-worker`, {
+        name: `${testId}-dlq-obj-worker`,
+        script: `
+          export default {
+            async fetch(request, env, ctx) {
+              return new Response("Hello DLQ Object");
+            },
+            async queue(batch, env, ctx) {
+              // Simulate failures to test DLQ - retry all messages
+              for (const message of batch.messages) {
+                message.retry();
+              }
+            }
+          }
+        `,
+        adopt: true,
+      });
+
+      consumer = await QueueConsumer(`${testId}-dlq-obj-consumer`, {
+        queue: queue.id,
+        scriptName: worker.name,
+        settings: {
+          batchSize: 10,
+          maxRetries: 3,
+          maxWaitTimeMs: 500,
+          retryDelay: 10,
+          deadLetterQueue: dlq,
+        },
+        adopt: true,
+      });
+
+      expect(consumer.id).toBeTruthy();
+      expect(consumer.settings?.deadLetterQueue).toEqual(dlq.name);
+      expect(worker).toBeTruthy();
+
+      const consumers = await listQueueConsumers(api, queue.id);
+      const foundConsumer = consumers.find(
+        (c) => c.scriptName === worker!.name,
+      );
+      expect(foundConsumer).toBeTruthy();
+      expect(foundConsumer?.settings?.deadLetterQueue).toEqual(dlq.name);
+      expect(foundConsumer?.settings?.batchSize).toEqual(10);
+      expect(foundConsumer?.settings?.maxRetries).toEqual(3);
+
+      const consumerResponse = await api.get(
+        `/accounts/${api.accountId}/queues/${queue.id}/consumers/${consumer.id}`,
+      );
+      expect(consumerResponse.ok).toBe(true);
+      const consumerData: any = await consumerResponse.json();
+
+      expect(consumerData.result.dead_letter_queue).toEqual(dlq.name);
+
+      const dlqResponse = await api.get(
+        `/accounts/${api.accountId}/queues/${dlq.id}`,
+      );
+      expect(dlqResponse.ok).toBe(true);
+      const dlqData: any = await dlqResponse.json();
+      expect(dlqData.result.queue_name).toEqual(dlq.name);
+    } catch (err) {
+      console.error("DLQ Queue object test error:", err);
+      throw err;
     } finally {
-      // Clean up
       await destroy(scope);
+
+      try {
+        if (queue?.id && consumer?.id) {
+          const response = await api.get(
+            `/accounts/${api.accountId}/queues/${queue.id}/consumers/${consumer.id}`,
+          );
+          if (response.status !== 404) {
+            throw new Error(
+              `Queue consumer ${consumer.id} was not deleted as expected`,
+            );
+          }
+        }
+      } catch (err) {
+        if (err instanceof CloudflareApiError && err.status === 404) {
+          // expected for this test case but dont need to log or throw
+        } else {
+          throw err;
+        }
+      }
     }
   });
+
+  test("update queue consumer to add dead letter queue", async (scope) => {
+    let queue: Queue | undefined;
+    let dlq: Queue | undefined;
+    let worker: Worker | undefined;
+    let consumer: QueueConsumer | undefined;
+
+    try {
+      queue = await Queue(`${testId}-dlq-update-main`, {
+        name: `${testId}-dlq-update-main`,
+        adopt: true,
+      });
+
+      dlq = await Queue(`${testId}-dlq-update-dead`, {
+        name: `${testId}-dlq-update-dead`,
+        adopt: true,
+      });
+
+      worker = await Worker(`${testId}-dlq-update-worker`, {
+        name: `${testId}-dlq-update-worker`,
+        script: `
+          export default {
+            async fetch(request, env, ctx) {
+              return new Response("Hello DLQ Update");
+            },
+            async queue(batch, env, ctx) {
+              // Acknowledge all messages successfully
+              for (const message of batch.messages) {
+                message.ack();
+              }
+            }
+          }
+        `,
+        adopt: true,
+      });
+
+      consumer = await QueueConsumer(`${testId}-dlq-update-consumer`, {
+        queue: queue.id,
+        scriptName: worker.name,
+        settings: {
+          batchSize: 10,
+          maxRetries: 2,
+        },
+        adopt: true,
+      });
+
+      expect(consumer.id).toBeTruthy();
+      expect(consumer.settings?.deadLetterQueue).toBeUndefined();
+
+      let consumerResponse = await api.get(
+        `/accounts/${api.accountId}/queues/${queue.id}/consumers/${consumer.id}`,
+      );
+      expect(consumerResponse.ok).toBe(true);
+
+      let consumerData: any = await consumerResponse.json();
+      expect(consumerData.result.dead_letter_queue).toBeUndefined();
+
+      consumer = await QueueConsumer(`${testId}-dlq-update-consumer`, {
+        queue: queue.id,
+        scriptName: worker.name,
+        settings: {
+          batchSize: 10,
+          maxRetries: 3,
+          deadLetterQueue: dlq.name,
+        },
+        adopt: true,
+      });
+
+      expect(consumer.settings?.deadLetterQueue).toEqual(dlq.name);
+
+      consumerResponse = await api.get(
+        `/accounts/${api.accountId}/queues/${queue.id}/consumers/${consumer.id}`,
+      );
+      expect(consumerResponse.ok).toBe(true);
+      consumerData = await consumerResponse.json();
+      expect(consumerData.result.dead_letter_queue).toEqual(dlq.name);
+      expect(consumerData.result.settings?.max_retries).toEqual(3);
+
+      const consumers = await listQueueConsumers(api, queue.id);
+      const foundConsumer = consumers.find(
+        (c) => c.scriptName === worker!.name,
+      );
+      expect(foundConsumer).toBeTruthy();
+      expect(foundConsumer?.settings?.deadLetterQueue).toEqual(dlq.name);
+      expect(foundConsumer?.settings?.maxRetries).toEqual(3);
+    } catch (err) {
+      console.error("DLQ update test error:", err);
+      throw err;
+    } finally {
+      await destroy(scope);
+
+      try {
+        if (queue?.id && consumer?.id) {
+          const response = await api.get(
+            `/accounts/${api.accountId}/queues/${queue.id}/consumers/${consumer.id}`,
+          );
+          if (response.status !== 404) {
+            throw new Error(
+              `Queue consumer ${consumer.id} was not deleted as expected`,
+            );
+          }
+        }
+      } catch (err) {
+        if (err instanceof CloudflareApiError && err.status === 404) {
+          // expected
+        } else {
+          throw err;
+        }
+      }
+    }
+  });
+
+  test("worker with queue event source including dead letter queue", async (scope) => {
+    let queue: Queue | undefined;
+    let dlq: Queue | undefined;
+    let worker: Worker | undefined;
+
+    try {
+      queue = await Queue(`${testId}-worker-dlq-main`, {
+        name: `${testId}-worker-dlq-main`,
+        adopt: true,
+      });
+
+      dlq = await Queue(`${testId}-worker-dlq-dead`, {
+        name: `${testId}-worker-dlq-dead`,
+        adopt: true,
+      });
+
+      worker = await Worker(`${testId}-worker-dlq`, {
+        name: `${testId}-worker-dlq`,
+        script: `
+          export default {
+            async fetch(request, env, ctx) {
+              return new Response("Hello Worker DLQ");
+            },
+            async queue(batch, env, ctx) {
+              // Simulate failures to test DLQ - retry all messages
+              for (const message of batch.messages) {
+                message.retry();
+              }
+            }
+          }
+        `,
+        eventSources: [
+          {
+            queue,
+            settings: {
+              batchSize: 25,
+              maxRetries: 5,
+              maxWaitTimeMs: 1000,
+              retryDelay: 30,
+              deadLetterQueue: dlq,
+            },
+          },
+        ],
+        adopt: true,
+      });
+
+      expect(worker.id).toBeTruthy();
+      expect(worker.name).toBeTruthy();
+
+      const consumers = await listQueueConsumers(api, queue.id);
+      const foundConsumer = consumers.find(
+        (c) => c.scriptName === worker!.name,
+      );
+      expect(foundConsumer).toBeTruthy();
+      expect(foundConsumer?.settings?.maxRetries).toEqual(5);
+      expect(foundConsumer?.settings?.batchSize).toEqual(25);
+      expect(foundConsumer?.settings?.deadLetterQueue).toEqual(dlq.name);
+      expect(foundConsumer?.settings?.retryDelay).toEqual(30);
+      expect(foundConsumer?.settings?.maxWaitTimeMs).toEqual(1000);
+
+      if (foundConsumer) {
+        const consumerResponse = await api.get(
+          `/accounts/${api.accountId}/queues/${queue.id}/consumers/${foundConsumer.id}`,
+        );
+        expect(consumerResponse.ok).toBe(true);
+        const consumerData: any = await consumerResponse.json();
+
+        expect(consumerData.result.dead_letter_queue).toEqual(dlq.name);
+        expect(consumerData.result.settings?.max_retries).toEqual(5);
+        expect(consumerData.result.settings?.batch_size).toEqual(25);
+
+        const queueResponse = await api.get(
+          `/accounts/${api.accountId}/queues/${queue.id}`,
+        );
+        expect(queueResponse.ok).toBe(true);
+        const queueData: any = await queueResponse.json();
+        const queueConsumer = queueData.result.consumers?.find(
+          (c: any) => c.script === worker!.name,
+        );
+
+        expect(queueConsumer?.dead_letter_queue).toEqual(dlq.name);
+      }
+    } catch (err) {
+      console.error("Worker DLQ test error:", err);
+      throw err;
+    } finally {
+      await destroy(scope);
+
+      try {
+        if (queue?.id) {
+          await listQueueConsumers(api, queue.id);
+        }
+      } catch (err) {
+        if (err instanceof CloudflareApiError && err.status === 404) {
+          // This is expected when queue is deleted
+        } else {
+          console.error(
+            "Unexpected error checking queue consumer deletion:",
+            err,
+          );
+        }
+      }
+    }
+  });
+
+  test("end-to-end DLQ message flow - verify messages reach DLQ after max retries", async (scope) => {
+    let queue: Queue | undefined;
+    let dlq: Queue | undefined;
+    let producerWorker: Worker | undefined;
+    let consumerWorker: Worker | undefined;
+    let dlqConsumer: Worker | undefined;
+
+    try {
+      queue = await Queue(`${testId}-e2e-main`, {
+        name: `${testId}-e2e-main`,
+        adopt: true,
+      });
+
+      dlq = await Queue(`${testId}-e2e-dlq`, {
+        name: `${testId}-e2e-dlq`,
+        adopt: true,
+      });
+
+      consumerWorker = await Worker(`${testId}-e2e-consumer`, {
+        name: `${testId}-e2e-consumer`,
+        script: `
+          export default {
+            async fetch(request, env, ctx) {
+              return new Response("OK");
+            },
+            async queue(batch, env, ctx) {
+              // Always retry to simulate persistent failures
+              for (const message of batch.messages) {
+                console.log("Main consumer retrying message:", message.id);
+                message.retry();
+              }
+            }
+          }
+        `,
+        eventSources: [
+          {
+            queue,
+            settings: {
+              batchSize: 1,
+              maxRetries: 2,
+              retryDelay: 1,
+              maxWaitTimeMs: 100,
+              deadLetterQueue: dlq,
+            },
+          },
+        ],
+        adopt: true,
+      });
+
+      dlqConsumer = await Worker(`${testId}-e2e-dlq-consumer`, {
+        name: `${testId}-e2e-dlq-consumer`,
+        script: `
+          export default {
+            async fetch(request, env, ctx) {
+              const url = new URL(request.url);
+              if (url.pathname === "/dlq-count") {
+                const count = await env.DLQ_TRACKING.get("count") || "0";
+                return new Response(count);
+              }
+              return new Response("DLQ Consumer OK");
+            },
+            async queue(batch, env, ctx) {
+              // Track messages that reached the DLQ
+              for (const message of batch.messages) {
+                console.log("DLQ received message:", message.id, "attempts:", message.attempts);
+                const currentCount = parseInt(await env.DLQ_TRACKING.get("count") || "0");
+                await env.DLQ_TRACKING.put("count", String(currentCount + 1));
+                await env.DLQ_TRACKING.put(\`msg-\${message.id}\`, JSON.stringify({
+                  body: message.body,
+                  attempts: message.attempts,
+                  timestamp: message.timestamp
+                }));
+                message.ack();
+              }
+            }
+          }
+        `,
+        eventSources: [dlq],
+        bindings: {
+          DLQ_TRACKING: await KVNamespace(`${testId}-e2e-dlq-kv`, {
+            title: `${testId}-e2e-dlq-tracking`,
+            adopt: true,
+          }),
+        },
+        adopt: true,
+        url: true,
+      });
+
+      producerWorker = await Worker(`${testId}-e2e-producer`, {
+        name: `${testId}-e2e-producer`,
+        script: `
+          export default {
+            async fetch(request, env, ctx) {
+              const messageId = crypto.randomUUID();
+              await env.MAIN_QUEUE.send({
+                test: "dlq-e2e-flow",
+                timestamp: Date.now(),
+                id: messageId
+              });
+              return new Response(JSON.stringify({ sent: messageId }), {
+                headers: { "Content-Type": "application/json" }
+              });
+            }
+          }
+        `,
+        bindings: {
+          MAIN_QUEUE: queue,
+        },
+        adopt: true,
+        url: true,
+      });
+
+      expect(consumerWorker.id).toBeTruthy();
+      expect(dlqConsumer.id).toBeTruthy();
+      expect(producerWorker.url).toBeTruthy();
+      expect(dlqConsumer.url).toBeTruthy();
+
+      const mainConsumers = await listQueueConsumers(api, queue.id);
+      const mainConsumer = mainConsumers.find(
+        (c) => c.scriptName === consumerWorker!.name,
+      );
+      expect(mainConsumer).toBeTruthy();
+      expect(mainConsumer?.settings?.deadLetterQueue).toEqual(dlq.name);
+      expect(mainConsumer?.settings?.maxRetries).toEqual(2);
+
+      const dlqConsumers = await listQueueConsumers(api, dlq.id);
+      expect(dlqConsumers.length).toBeGreaterThan(0);
+      const dlqConsumerFound = dlqConsumers.find(
+        (c) => c.scriptName === dlqConsumer!.name,
+      );
+      expect(dlqConsumerFound).toBeDefined();
+
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+
+      const sendResponse = await fetch(producerWorker.url!);
+      if (!sendResponse.ok) {
+        const errorText = await sendResponse.text();
+        console.error("Send failed:", sendResponse.status, errorText);
+      }
+      expect(sendResponse.ok).toBe(true);
+      const sendData = await sendResponse.json();
+      console.log("Sent message:", sendData);
+
+      console.log("Waiting 25 seconds for retries and DLQ delivery...");
+      await new Promise((resolve) => setTimeout(resolve, 25000));
+
+      const dlqCountResponse = await fetch(`${dlqConsumer.url}/dlq-count`);
+      const dlqCount = await dlqCountResponse.text();
+      console.log("DLQ message count:", dlqCount);
+      expect(Number.parseInt(dlqCount, 10)).toBeGreaterThan(0);
+    } catch (err) {
+      console.error("End-to-end DLQ flow test error:", err);
+      throw err;
+    } finally {
+      await destroy(scope);
+
+      try {
+        if (queue?.id) {
+          await listQueueConsumers(api, queue.id);
+        }
+        if (dlq?.id) {
+          await listQueueConsumers(api, dlq.id);
+        }
+      } catch (err) {
+        if (err instanceof CloudflareApiError && err.status === 404) {
+          // This is expected when queue is deleted
+        } else {
+          console.error(
+            "Unexpected error checking queue consumer deletion:",
+            err,
+          );
+        }
+      }
+    }
+  }, 60000);
 });

From 58e338a9c0cc13dee397444a92edef60309ba391 Mon Sep 17 00:00:00 2001
From: Alex <alex@gogl.io>
Date: Sat, 18 Oct 2025 11:47:35 +0200
Subject: [PATCH 2/8] feat(neon): add Role resource with comprehensive docs and
 tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add NeonRole resource for managing Postgres database roles (users) in Neon branches:

- Resource implementation with automatic password generation
- Support for protected (no-login) roles
- Secret encryption for passwords
- Full lifecycle management (create, update, delete)
- Comprehensive test suite (4 test cases, all passing)
- User-facing documentation with examples
- Provider overview docs with Role included

All tests passing with 100% success rate.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../src/content/docs/providers/neon/branch.md | 266 +++++++++++++++
 .../src/content/docs/providers/neon/index.md  | 314 ++++++++++++++++++
 .../src/content/docs/providers/neon/role.md   | 285 ++++++++++++++++
 alchemy/src/neon/role.ts                      | 204 ++++++++++++
 alchemy/test/neon/role.test.ts                | 162 +++++++++
 5 files changed, 1231 insertions(+)
 create mode 100644 alchemy-web/src/content/docs/providers/neon/branch.md
 create mode 100644 alchemy-web/src/content/docs/providers/neon/index.md
 create mode 100644 alchemy-web/src/content/docs/providers/neon/role.md
 create mode 100644 alchemy/src/neon/role.ts
 create mode 100644 alchemy/test/neon/role.test.ts

diff --git a/alchemy-web/src/content/docs/providers/neon/branch.md b/alchemy-web/src/content/docs/providers/neon/branch.md
new file mode 100644
index 000000000..e6f9773a6
--- /dev/null
+++ b/alchemy-web/src/content/docs/providers/neon/branch.md
@@ -0,0 +1,266 @@
+---
+title: NeonBranch
+description: Learn how to create and manage Neon database branches for instant development environments and preview deployments using Alchemy.
+---
+
+The NeonBranch resource lets you create and manage database branches within a [Neon serverless PostgreSQL](https://neon.tech) project. Branches are instant, copy-on-write clones of your database that enable Git-like workflows for your data.
+
+## Minimal Example
+
+Create a basic development branch with a read-write endpoint:
+
+```ts
+import { NeonProject, NeonBranch } from "alchemy/neon";
+
+const project = await NeonProject("db", {
+  name: "My Database",
+});
+
+const dev = await NeonBranch("dev", {
+  project,
+  endpoints: [{ type: "read_write" }],
+});
+
+console.log("Connection URI:", dev.connectionUris[0].connection_uri);
+```
+
+## Multiple Endpoints
+
+Create a branch with both read-write and read-only endpoints:
+
+```ts
+import { NeonProject, NeonBranch } from "alchemy/neon";
+
+const project = await NeonProject("db", {
+  name: "My Database",
+});
+
+const prod = await NeonBranch("prod", {
+  project,
+  name: "production",
+  protected: true, // Prevent accidental deletion
+  endpoints: [
+    { type: "read_write" },
+    { type: "read_only" },
+  ],
+});
+
+// Read-write connection for application
+console.log("Write endpoint:", prod.endpoints[0].host);
+
+// Read-only connection for analytics
+console.log("Read endpoint:", prod.endpoints[1].host);
+```
+
+## Feature Branch from Parent
+
+Create a feature branch based on another branch:
+
+```ts
+import { NeonProject, NeonBranch } from "alchemy/neon";
+
+const project = await NeonProject("db", {
+  name: "My Database",
+});
+
+const main = await NeonBranch("main", {
+  project,
+  endpoints: [{ type: "read_write" }],
+});
+
+const feature = await NeonBranch("feature", {
+  project,
+  name: "feature-new-schema",
+  parentBranch: main,
+  endpoints: [{ type: "read_write" }],
+});
+```
+
+## Point-in-Time Branch
+
+Create a branch from a specific point in time on the parent:
+
+```ts
+import { NeonProject, NeonBranch } from "alchemy/neon";
+
+const project = await NeonProject("db", {
+  name: "My Database",
+});
+
+const restore = await NeonBranch("restore", {
+  project,
+  name: "restore-before-incident",
+  parentTimestamp: "2024-10-17T12:00:00Z",
+  endpoints: [{ type: "read_write" }],
+});
+```
+
+## Schema-Only Branch
+
+Create a branch with only the schema (no data):
+
+```ts
+import { NeonProject, NeonBranch } from "alchemy/neon";
+
+const project = await NeonProject("db", {
+  name: "My Database",
+});
+
+const schema = await NeonBranch("schema", {
+  project,
+  name: "schema-only",
+  initSource: "schema-only",
+  endpoints: [{ type: "read_write" }],
+});
+```
+
+## Temporary Preview Branch
+
+Create a branch that automatically expires:
+
+```ts
+import { NeonProject, NeonBranch } from "alchemy/neon";
+
+const project = await NeonProject("db", {
+  name: "My Database",
+});
+
+// Expires in 7 days
+const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);
+
+const preview = await NeonBranch("preview", {
+  project,
+  name: "preview-pr-123",
+  expiresAt: expiresAt.toISOString(),
+  endpoints: [{ type: "read_write" }],
+});
+```
+
+## Using Connection Parameters
+
+Access individual connection parameters for manual connection setup:
+
+```ts
+import { NeonProject, NeonBranch } from "alchemy/neon";
+
+const project = await NeonProject("db", {
+  name: "My Database",
+});
+
+const branch = await NeonBranch("app", {
+  project,
+  endpoints: [{ type: "read_write" }],
+});
+
+const conn = branch.connectionUris[0].connection_parameters;
+
+console.log(`Host: ${conn.host}`);
+console.log(`Port: ${conn.port}`);
+console.log(`Database: ${conn.database}`);
+console.log(`User: ${conn.user}`);
+// Password is encrypted in alchemy state
+```
+
+## Integration with External Branch
+
+Reference an existing branch by its ID:
+
+```ts
+import { NeonProject, NeonBranch } from "alchemy/neon";
+
+const project = await NeonProject("db", {
+  name: "My Database",
+});
+
+const feature = await NeonBranch("feature", {
+  project,
+  parentBranch: "br-aged-wind-12345678", // Existing branch ID
+  endpoints: [{ type: "read_write" }],
+});
+```
+
+## Resource Properties
+
+### Input Properties (NeonBranchProps)
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `project` | `string \| NeonProject` | Yes | The project to create the branch in |
+| `endpoints` | `BranchCreateRequestEndpointOptions[]` | Yes | Endpoints to create for the branch |
+| `name` | `string` | No | Branch name (default: `${app}-${stage}-${id}`) |
+| `protected` | `boolean` | No | Protect against accidental deletion (default: `false`) |
+| `parentBranch` | `string \| NeonBranch \| Branch` | No | Parent branch to branch from (default: project's default branch) |
+| `parentLsn` | `string` | No | Log Sequence Number on parent branch to branch from |
+| `parentTimestamp` | `string` | No | ISO 8601 timestamp on parent branch to branch from |
+| `initSource` | `"schema-only" \| "parent-data"` | No | Initialize with schema only or full data (default: `"parent-data"`) |
+| `expiresAt` | `string` | No | When the branch should auto-delete (RFC 3339 format) |
+| `apiKey` | `Secret` | No | Neon API key (overrides `NEON_API_KEY` env var) |
+
+### Output Properties (NeonBranch)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | Branch ID (e.g., `br-small-term-683261`) |
+| `name` | `string` | Branch name |
+| `projectId` | `string` | Project ID this branch belongs to |
+| `parentBranchId` | `string \| undefined` | ID of the parent branch |
+| `parentLsn` | `string \| undefined` | LSN the branch was created from |
+| `parentTimestamp` | `string \| undefined` | Timestamp the branch was created from |
+| `initSource` | `"schema-only" \| "parent-data" \| undefined` | How the branch was initialized |
+| `protected` | `boolean` | Whether the branch is protected |
+| `default` | `boolean` | Whether this is the project's default branch |
+| `createdAt` | `Date` | When the branch was created |
+| `updatedAt` | `Date` | When the branch was last updated |
+| `expiresAt` | `Date \| undefined` | When the branch will auto-delete |
+| `endpoints` | `Endpoint[]` | Compute endpoints for the branch |
+| `databases` | `Database[]` | Databases on the branch |
+| `roles` | `NeonRole[]` | Database roles (passwords are encrypted) |
+| `connectionUris` | `NeonConnectionUri[]` | Connection URIs (passwords are encrypted) |
+
+## Important Notes
+
+### Endpoints Required
+
+You must configure at least one endpoint when creating a branch, otherwise you won't be able to connect to it:
+
+```ts
+// ✅ Correct
+const branch = await NeonBranch("app", {
+  project,
+  endpoints: [{ type: "read_write" }],
+});
+
+// ❌ Will fail - no endpoints
+const branch = await NeonBranch("app", {
+  project,
+  endpoints: [],
+});
+```
+
+### Secret Encryption
+
+All sensitive data (passwords, connection strings) is automatically encrypted when stored in Alchemy state files using the `Secret` type.
+
+### Immutable Properties
+
+These properties cannot be changed after creation (they trigger replacement):
+- `project` / `projectId`
+- `parentBranch` / `parentBranchId`
+- `parentLsn`
+- `parentTimestamp`
+- `initSource`
+
+### Branch Workflows
+
+Branches are perfect for:
+- **Development**: Create a dev branch for local development
+- **Feature branches**: Mirror your Git workflow with database branches
+- **Preview deployments**: Automatically create and destroy branches for PRs
+- **Testing**: Create isolated test environments
+- **Migrations**: Test schema changes before applying to production
+- **Point-in-time restore**: Recover from accidents
+
+## Related Resources
+
+- [NeonProject](./project) - Create a Neon serverless PostgreSQL project
+- [Neon Branching Guide](https://neon.tech/docs/guides/branching) - Learn more about database branching
diff --git a/alchemy-web/src/content/docs/providers/neon/index.md b/alchemy-web/src/content/docs/providers/neon/index.md
new file mode 100644
index 000000000..62c829a72
--- /dev/null
+++ b/alchemy-web/src/content/docs/providers/neon/index.md
@@ -0,0 +1,314 @@
+---
+title: Neon
+description: Learn how to manage Neon serverless PostgreSQL projects and database branches using Alchemy.
+---
+
+Neon is a serverless PostgreSQL database platform that separates compute and storage, enabling instant scaling, database branching, and point-in-time restore capabilities. Alchemy provides resources to manage Neon projects and branches programmatically.
+
+[Official Neon Documentation](https://neon.tech/docs) | [Neon API Reference](https://api-docs.neon.tech/)
+
+## Resources
+
+- [Project](/providers/neon/project) - Create and manage Neon serverless PostgreSQL projects with multiple regions and PostgreSQL versions
+- [Branch](/providers/neon/branch) - Create and manage database branches for development, testing, and preview environments
+- [Role](/providers/neon/role) - Create and manage Postgres database roles (users) with encrypted passwords
+
+## Authentication
+
+Neon authentication uses API keys that can be generated in the [Neon Console](https://console.neon.tech/app/settings/api-keys).
+
+### Using Environment Variables
+
+The recommended approach is to use the `NEON_API_KEY` environment variable:
+
+```bash
+export NEON_API_KEY="your-api-key-here"
+```
+
+Alchemy will automatically use this environment variable for all Neon resources.
+
+### Using Encrypted Secrets
+
+For better security, use Alchemy's secret encryption:
+
+```ts
+import { alchemy } from "alchemy";
+import { NeonProject } from "alchemy/neon";
+
+const app = await alchemy("my-app");
+
+const project = await NeonProject("db", {
+  name: "My Database",
+  apiKey: alchemy.secret.env.NEON_API_KEY, // Encrypted in state
+});
+
+await app.finalize();
+```
+
+### Overriding Per Resource
+
+You can override authentication for individual resources to support multiple Neon accounts:
+
+```ts
+const project1 = await NeonProject("db1", {
+  name: "Project 1",
+  apiKey: alchemy.secret.env.NEON_API_KEY_ACCOUNT_1,
+});
+
+const project2 = await NeonProject("db2", {
+  name: "Project 2",
+  apiKey: alchemy.secret.env.NEON_API_KEY_ACCOUNT_2,
+});
+```
+
+## Example Usage
+
+### Basic Project and Branch
+
+```ts
+import { alchemy } from "alchemy";
+import { NeonProject, NeonBranch } from "alchemy/neon";
+
+const app = await alchemy("my-app");
+
+// Create a Neon project
+const project = await NeonProject("db", {
+  name: "My Database",
+  region_id: "aws-us-east-1",
+  pg_version: 16,
+});
+
+// Create a development branch
+const dev = await NeonBranch("dev", {
+  project,
+  name: "development",
+  endpoints: [
+    { type: "read_write" }
+  ],
+});
+
+console.log("Connection URI:", dev.connectionUris[0].connection_uri);
+
+await app.finalize();
+```
+
+### Git-Style Database Workflow
+
+```ts
+import { alchemy } from "alchemy";
+import { NeonProject, NeonBranch } from "alchemy/neon";
+
+const app = await alchemy("my-app");
+
+// Create project
+const project = await NeonProject("db", {
+  name: "My App Database",
+});
+
+// Main production branch (created automatically with project)
+const mainBranchId = project.branch.id;
+
+// Development branch from main
+const dev = await NeonBranch("dev", {
+  project,
+  name: "development",
+  parentBranch: mainBranchId,
+  endpoints: [
+    { type: "read_write" }
+  ],
+});
+
+// Feature branch from dev
+const feature = await NeonBranch("feature", {
+  project,
+  name: "feature-new-auth",
+  parentBranch: dev,
+  endpoints: [
+    { type: "read_write" }
+  ],
+});
+
+console.log("Feature branch connection:", feature.connectionUris[0].connection_uri);
+
+await app.finalize();
+```
+
+### Preview Deployments
+
+```ts
+import { alchemy } from "alchemy";
+import { NeonProject, NeonBranch } from "alchemy/neon";
+
+const app = await alchemy("my-app");
+
+const project = await NeonProject("db", {
+  name: "My App Database",
+});
+
+// Get PR number from environment (e.g., GitHub Actions)
+const prNumber = process.env.PR_NUMBER;
+
+// Create temporary preview branch that expires in 7 days
+const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);
+
+const preview = await NeonBranch(`preview-${prNumber}`, {
+  project,
+  name: `preview-pr-${prNumber}`,
+  parentBranch: project.branch.id,
+  expiresAt: expiresAt.toISOString(),
+  endpoints: [
+    { type: "read_write" }
+  ],
+});
+
+console.log(`Preview environment for PR #${prNumber}:`, preview.connectionUris[0].connection_uri);
+
+await app.finalize();
+```
+
+### Production with Read Replicas
+
+```ts
+import { alchemy } from "alchemy";
+import { NeonProject, NeonBranch } from "alchemy/neon";
+
+const app = await alchemy("my-app");
+
+const project = await NeonProject("prod-db", {
+  name: "Production Database",
+  region_id: "aws-us-east-1",
+  pg_version: 16,
+  history_retention_seconds: 604800, // 7 days
+});
+
+// Production branch with read-write and read-only endpoints
+const prod = await NeonBranch("prod", {
+  project,
+  name: "production",
+  protected: true, // Prevent accidental deletion
+  endpoints: [
+    { type: "read_write" },  // For application writes
+    { type: "read_only" },   // For analytics/reporting
+  ],
+});
+
+console.log("Application (read-write):", prod.connectionUris[0].connection_uri);
+console.log("Analytics (read-only):", prod.connectionUris[1].connection_uri);
+
+await app.finalize();
+```
+
+### Point-in-Time Recovery
+
+```ts
+import { alchemy } from "alchemy";
+import { NeonProject, NeonBranch } from "alchemy/neon";
+
+const app = await alchemy("my-app");
+
+const project = await NeonProject("db", {
+  name: "My Database",
+});
+
+// Create a branch from 2 hours ago to recover from an incident
+const twoHoursAgo = new Date(Date.now() - 2 * 60 * 60 * 1000);
+
+const recovery = await NeonBranch("recovery", {
+  project,
+  name: "recovery-branch",
+  parentTimestamp: twoHoursAgo.toISOString(),
+  endpoints: [
+    { type: "read_write" }
+  ],
+});
+
+console.log("Recovery branch:", recovery.connectionUris[0].connection_uri);
+
+await app.finalize();
+```
+
+## Key Features
+
+### Instant Database Branching
+
+Create isolated database copies in seconds without duplicating storage. Perfect for:
+- Development and testing environments
+- Feature branches that mirror your Git workflow
+- Preview deployments for pull requests
+- Safe schema migration testing
+
+### Point-in-Time Restore
+
+Branch from any point in your database's history (within retention period):
+- Recover from accidental data changes
+- Test with production data at specific timestamps
+- Debug issues by recreating the exact database state
+
+### Automatic Secret Encryption
+
+All sensitive data is automatically encrypted in Alchemy state files:
+- Database passwords
+- Connection strings
+- API keys
+
+### Multiple PostgreSQL Versions
+
+Support for PostgreSQL 14, 15, 16, 17, and 18 with easy version selection.
+
+### Global Region Support
+
+Deploy your database close to your users with regions in:
+- AWS (US, EU, APAC, South America)
+- Azure (US, Europe)
+
+## Common Patterns
+
+### Branch Per Environment
+
+```ts
+const envs = ["dev", "staging", "prod"];
+
+for (const env of envs) {
+  await NeonBranch(env, {
+    project,
+    name: env,
+    protected: env === "prod",
+    endpoints: [{ type: "read_write" }],
+  });
+}
+```
+
+### Schema-Only Test Branch
+
+```ts
+const test = await NeonBranch("test", {
+  project,
+  name: "test-schema-only",
+  initSource: "schema-only", // No data, just schema
+  endpoints: [{ type: "read_write" }],
+});
+```
+
+### Temporary CI Branch
+
+```ts
+const ci = await NeonBranch("ci", {
+  project,
+  name: "ci-test-branch",
+  expiresAt: new Date(Date.now() + 60 * 60 * 1000).toISOString(), // 1 hour
+  endpoints: [{ type: "read_write" }],
+});
+```
+
+## Best Practices
+
+1. **Use Secret Encryption**: Always use `alchemy.secret.env.X` for API keys
+2. **Protect Production**: Set `protected: true` on production branches
+3. **Set Expiration**: Use `expiresAt` for temporary preview/test branches
+4. **Name Branches Clearly**: Use descriptive names that match your workflow
+5. **Use Read Replicas**: Create read-only endpoints for analytics/reporting
+6. **Leverage History Retention**: Configure appropriate retention for point-in-time recovery
+
+## Migration from Other Platforms
+
+Neon branches make it easy to adopt a database-per-environment workflow without the cost and complexity of managing multiple database servers. If you're migrating from platforms like Heroku, AWS RDS, or other PostgreSQL providers, Neon branches provide instant environment isolation at a fraction of the cost.
diff --git a/alchemy-web/src/content/docs/providers/neon/role.md b/alchemy-web/src/content/docs/providers/neon/role.md
new file mode 100644
index 000000000..386c9992c
--- /dev/null
+++ b/alchemy-web/src/content/docs/providers/neon/role.md
@@ -0,0 +1,285 @@
+---
+title: NeonRole
+description: Learn how to create and manage Postgres database roles (users) in Neon branches using Alchemy.
+---
+
+The NeonRole resource lets you create and manage Postgres roles (database users) within a [Neon serverless PostgreSQL](https://neon.tech) branch. In Neon, the terms "role" and "user" are synonymous - a role is a database user with login credentials.
+
+## Minimal Example
+
+Create a basic database role in a branch:
+
+```ts
+import { NeonProject, NeonBranch, NeonRole } from "alchemy/neon";
+
+const project = await NeonProject("db", {
+  name: "My Database",
+});
+
+const branch = await NeonBranch("main", {
+  project,
+  endpoints: [{ type: "read_write" }],
+});
+
+const role = await NeonRole("app-user", {
+  project,
+  branch,
+});
+
+console.log("Username:", role.name);
+console.log("Password:", role.password.unencrypted);
+```
+
+## Using Role with External IDs
+
+Create a role using project and branch IDs instead of resources:
+
+```ts
+import { NeonRole } from "alchemy/neon";
+
+const role = await NeonRole("api-user", {
+  project: "sunny-meadow-12345678",
+  branch: "br-aged-wind-87654321",
+});
+
+console.log("Connection ready for:", role.name);
+```
+
+## Protected Role
+
+Create a protected role that cannot be used for login (useful for ownership and permissions):
+
+```ts
+import { NeonProject, NeonBranch, NeonRole } from "alchemy/neon";
+
+const project = await NeonProject("db", {
+  name: "My Database",
+});
+
+const branch = await NeonBranch("main", {
+  project,
+  endpoints: [{ type: "read_write" }],
+});
+
+const owner = await NeonRole("owner", {
+  project,
+  branch,
+  protected: true, // Cannot be used for login
+});
+
+console.log("Owner role created:", owner.name);
+```
+
+## Custom Role Name
+
+Create a role with a specific name:
+
+```ts
+import { NeonProject, NeonBranch, NeonRole } from "alchemy/neon";
+
+const project = await NeonProject("db", {
+  name: "My Database",
+});
+
+const branch = await NeonBranch("main", {
+  project,
+  endpoints: [{ type: "read_write" }],
+});
+
+const role = await NeonRole("app", {
+  project,
+  branch,
+  name: "myapp_user",
+});
+
+console.log("Role name:", role.name); // "myapp_user"
+```
+
+## Multiple Roles for Different Services
+
+Create different roles for different parts of your application:
+
+```ts
+import { NeonProject, NeonBranch, NeonRole } from "alchemy/neon";
+
+const project = await NeonProject("db", {
+  name: "My Database",
+});
+
+const branch = await NeonBranch("prod", {
+  project,
+  endpoints: [{ type: "read_write" }],
+});
+
+// API service role
+const apiRole = await NeonRole("api", {
+  project,
+  branch,
+  name: "api_service",
+});
+
+// Worker service role
+const workerRole = await NeonRole("worker", {
+  project,
+  branch,
+  name: "worker_service",
+});
+
+// Read-only analytics role
+const analyticsRole = await NeonRole("analytics", {
+  project,
+  branch,
+  name: "analytics_readonly",
+});
+
+console.log("API credentials:", apiRole.password.unencrypted);
+console.log("Worker credentials:", workerRole.password.unencrypted);
+console.log("Analytics credentials:", analyticsRole.password.unencrypted);
+```
+
+## Using with Connection String
+
+Access the role password securely for connection strings:
+
+```ts
+import { NeonProject, NeonBranch, NeonRole } from "alchemy/neon";
+
+const project = await NeonProject("db", {
+  name: "My Database",
+});
+
+const branch = await NeonBranch("main", {
+  project,
+  endpoints: [{ type: "read_write" }],
+});
+
+const role = await NeonRole("app", {
+  project,
+  branch,
+});
+
+// Password is encrypted in state but accessible at runtime
+const connectionString = `postgresql://${role.name}:${role.password.unencrypted}@${branch.endpoints[0].host}:5432/neondb`;
+
+console.log("Connection string:", connectionString);
+```
+
+## Encrypting Role Password
+
+Store the password securely using alchemy.secret:
+
+```ts
+import { NeonProject, NeonBranch, NeonRole } from "alchemy/neon";
+
+const project = await NeonProject("db", {
+  name: "My Database",
+});
+
+const branch = await NeonBranch("main", {
+  project,
+  endpoints: [{ type: "read_write" }],
+});
+
+const role = await NeonRole("app", {
+  project,
+  branch,
+});
+
+// The password is automatically wrapped in a Secret and encrypted in state
+console.log("Password (encrypted in state):", role.password);
+console.log("Password (decrypted at runtime):", role.password.unencrypted);
+```
+
+## Resource Properties
+
+### Input Properties (NeonRoleProps)
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `project` | `string \| NeonProject` | Yes | The project containing the branch |
+| `branch` | `string \| NeonBranch` | Yes | The branch to create the role in |
+| `name` | `string` | No | Role name (max 63 bytes, default: `${app}-${stage}-${id}`) |
+| `protected` | `boolean` | No | Whether to create a role that cannot login (default: `false`) |
+| `apiKey` | `Secret` | No | Neon API key (overrides `NEON_API_KEY` env var) |
+
+### Output Properties (NeonRole)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | The role name |
+| `projectId` | `string` | The project ID |
+| `branchId` | `string` | The branch ID this role belongs to |
+| `branch` | `string \| NeonBranch` | The branch reference from input |
+| `password` | `Secret` | The role password (encrypted in state) |
+| `protected` | `boolean` | Whether the role is system-protected |
+| `createdAt` | `Date` | When the role was created |
+| `updatedAt` | `Date` | When the role was last updated |
+
+## Important Notes
+
+### Secret Encryption
+
+Role passwords are automatically wrapped in Alchemy's `Secret` type and encrypted when stored in state files. To access the password at runtime:
+
+```ts
+const role = await NeonRole("app", {
+  project: "project-id",
+  branch: "branch-id",
+});
+
+// Encrypted in state, decrypted at runtime
+const plainPassword = role.password.unencrypted;
+```
+
+### Immutable Properties
+
+These properties cannot be changed after creation (they trigger replacement):
+- `project` / `projectId`
+- `branch` / `branchId`
+- `name`
+- `protected`
+
+Roles do not have an update endpoint in the Neon API, so attempting to update a role will either keep the existing state or trigger a replacement.
+
+### Role Names
+
+Role names:
+- Cannot exceed 63 bytes in length
+- Must be unique within the branch
+- Cannot be changed after creation
+
+### Protected Roles
+
+Protected roles (`protected: true`) cannot be used to log into the database. They are useful for:
+- Ownership of database objects
+- Role hierarchies and permission inheritance
+- System roles that shouldn't have direct login access
+
+### Using Branch References
+
+You can pass either a Branch resource or a branch ID string:
+
+```ts
+// Using Branch resource (recommended)
+const branch = await NeonBranch("main", { project, endpoints: [...] });
+const role = await NeonRole("app", {
+  project,
+  branch, // Pass the resource
+});
+
+// Using branch ID string
+const role = await NeonRole("app", {
+  project: "sunny-meadow-12345678",
+  branch: "br-aged-wind-87654321", // Pass the ID
+});
+```
+
+### Default Role
+
+Every branch automatically gets a default role with the same name as the database. You don't need to create an additional role unless you want multiple users or specific permissions.
+
+## Related Resources
+
+- [NeonProject](./index) - Create a Neon serverless PostgreSQL project
+- [NeonBranch](./branch) - Create and manage database branches
+- [Neon Roles Documentation](https://neon.tech/docs/manage/roles) - Learn more about managing roles
diff --git a/alchemy/src/neon/role.ts b/alchemy/src/neon/role.ts
new file mode 100644
index 000000000..6ccfedc80
--- /dev/null
+++ b/alchemy/src/neon/role.ts
@@ -0,0 +1,204 @@
+import { Secret } from "../secret.ts";
+import type { Context } from "../context.ts";
+import { Resource } from "../resource.ts";
+import { createNeonApi, type NeonApiOptions } from "./api.ts";
+import type { NeonBranch } from "./branch.ts";
+import type { NeonProject } from "./project.ts";
+import { waitForOperations } from "./utils.ts";
+
+export interface NeonRoleProps extends NeonApiOptions {
+  /**
+   * The project containing the branch.
+   * This can be a Project object or an ID string.
+   */
+  project: string | NeonProject;
+  /**
+   * The branch to create the role in.
+   * This can be a Branch object or an ID string beginning with `br-`.
+   */
+  branch: string | NeonBranch;
+  /**
+   * The role name. Cannot exceed 63 bytes in length.
+   * @default `${app}-${stage}-${id}`
+   */
+  name?: string;
+  /**
+   * Whether to create a role that cannot login.
+   * @default false
+   */
+  protected?: boolean;
+}
+
+export type NeonRole = Omit<NeonRoleProps, "project"> & {
+  /**
+   * The role name
+   */
+  name: string;
+  /**
+   * The ID of the branch to which the role belongs
+   */
+  branchId: string;
+  /**
+   * The ID of the project to which the role belongs
+   */
+  projectId: string;
+  /**
+   * The role password
+   */
+  password: Secret;
+  /**
+   * Whether the role cannot login (no_login flag)
+   */
+  protected: boolean;
+  /**
+   * A timestamp indicating when the role was created
+   */
+  createdAt: Date;
+  /**
+   * A timestamp indicating when the role was last updated
+   */
+  updatedAt: Date;
+};
+
+/**
+ * Creates a Postgres role in a Neon branch.
+ *
+ * In Neon, the terms "role" and "user" are synonymous. A role is a database user
+ * with login credentials that can be used to connect to the database.
+ *
+ * @example
+ * ## Basic Role
+ *
+ * Create a role in a branch:
+ *
+ * ```ts
+ * const role = await NeonRole("app-role", {
+ *   project: "project-id",
+ *   branch: "branch-id",
+ * });
+ *
+ * console.log(`Password: ${role.password.value}`);
+ * ```
+ *
+ * @example
+ * ## Protected Role
+ *
+ * Create a role that cannot login (useful for ownership):
+ *
+ * ```ts
+ * const role = await NeonRole("owner", {
+ *   project: "project-id",
+ *   branch: "branch-id",
+ *   protected: true,
+ * });
+ * ```
+ *
+ * @example
+ * ## Using with Branch
+ *
+ * Create a role using a Branch resource:
+ *
+ * ```ts
+ * const branch = await NeonBranch("dev", {
+ *   project: "project-id",
+ *   endpoints: [{ type: "read-write" }],
+ * });
+ *
+ * const role = await NeonRole("app-user", {
+ *   project: branch.projectId,
+ *   branch: branch,
+ * });
+ * ```
+ */
+export const NeonRole = Resource(
+  "neon::Role",
+  async function (
+    this: Context<NeonRole>,
+    id: string,
+    props: NeonRoleProps,
+  ): Promise<NeonRole> {
+    const api = createNeonApi(props);
+    const name =
+      props.name ?? this.output?.name ?? this.scope.createPhysicalName(id);
+    const projectId =
+      typeof props.project === "string" ? props.project : props.project.id;
+    const branchId =
+      typeof props.branch === "string" ? props.branch : props.branch.id;
+
+    switch (this.phase) {
+      case "delete": {
+        if (this.output) {
+          const res = await api.deleteProjectBranchRole({
+            path: {
+              project_id: this.output.projectId,
+              branch_id: this.output.branchId,
+              role_name: this.output.name,
+            },
+            throwOnError: false,
+          });
+          if (res.error && res.response.status !== 404) {
+            throw new Error(`Failed to delete role: ${res.error.message}`, {
+              cause: res.error,
+            });
+          }
+        }
+        return this.destroy();
+      }
+      case "create": {
+        const { data } = await api.createProjectBranchRole({
+          path: {
+            project_id: projectId,
+            branch_id: branchId,
+          },
+          body: {
+            role: {
+              name,
+              no_login: props.protected,
+            },
+          },
+        });
+
+        // Wait for operations to complete
+        await waitForOperations(api, data.operations);
+
+        // Fetch the role password
+        const passwordRes = await api.getProjectBranchRolePassword({
+          path: {
+            project_id: projectId,
+            branch_id: branchId,
+            role_name: data.role.name,
+          },
+        });
+
+        return {
+          name: data.role.name,
+          projectId,
+          branchId,
+          branch: props.branch,
+          password: new Secret(passwordRes.data.password),
+          protected: props.protected ?? false,
+          createdAt: new Date(data.role.created_at),
+          updatedAt: new Date(data.role.updated_at),
+        };
+      }
+      case "update": {
+        if (
+          this.output.projectId !== projectId ||
+          this.output.branchId !== branchId
+        ) {
+          this.replace();
+        }
+
+        if (this.output.name !== name) {
+          throw new Error(
+            `Cannot change role name from '${this.output.name}' to '${name}'. Role name is immutable after creation.`,
+          );
+        }
+
+        // Roles don't have an update endpoint, so we return the current state
+        // The protected flag is immutable after creation
+        return this.output;
+      }
+    }
+  },
+);
diff --git a/alchemy/test/neon/role.test.ts b/alchemy/test/neon/role.test.ts
new file mode 100644
index 000000000..f238a724f
--- /dev/null
+++ b/alchemy/test/neon/role.test.ts
@@ -0,0 +1,162 @@
+import "../../src/test/vitest.ts";
+
+import { describe, expect } from "vitest";
+import { alchemy } from "../../src/alchemy.ts";
+import { destroy } from "../../src/destroy.ts";
+import { createNeonApi } from "../../src/neon/api.ts";
+import { NeonBranch } from "../../src/neon/branch.ts";
+import { NeonProject } from "../../src/neon/project.ts";
+import { NeonRole } from "../../src/neon/role.ts";
+import { BRANCH_PREFIX } from "../util.ts";
+
+const test = alchemy.test(import.meta, {
+  prefix: BRANCH_PREFIX,
+});
+
+describe("NeonRole Resource", () => {
+  const api = createNeonApi();
+
+  test("create and delete neon role", async (scope) => {
+    let project: NeonProject | undefined;
+    let branch: NeonBranch | undefined;
+    let role: NeonRole | undefined;
+
+    try {
+      // Create project and branch for testing
+      project = await NeonProject("project", {});
+      branch = await NeonBranch("branch", {
+        project,
+        endpoints: [{ type: "read_write" }],
+      });
+
+      // Create role
+      role = await NeonRole("role", {
+        project: project.id,
+        branch: branch.id,
+      });
+
+      expect(role).toMatchObject({
+        name: expect.any(String),
+        projectId: project.id,
+        branchId: branch.id,
+        password: expect.any(Object),
+        protected: false,
+        createdAt: expect.any(Date),
+        updatedAt: expect.any(Date),
+      });
+      expect(role.password.unencrypted).toBeDefined();
+      expect(typeof role.password.unencrypted).toBe("string");
+
+      // Update should return the same state
+      const updatedRole = await NeonRole("role", {
+        project: project.id,
+        branch: branch.id,
+      });
+      expect(updatedRole.name).toBe(role.name);
+    } finally {
+      await destroy(scope);
+
+      // Verify role was deleted
+      if (role && project && branch) {
+        const { response } = await api.getProjectBranchRole({
+          path: {
+            project_id: project.id,
+            branch_id: branch.id,
+            role_name: role.name,
+          },
+          throwOnError: false,
+        });
+        expect(response.status).toEqual(404);
+      }
+    }
+  });
+
+  test("create protected role", async (scope) => {
+    let project: NeonProject | undefined;
+    let branch: NeonBranch | undefined;
+    let role: NeonRole | undefined;
+
+    try {
+      // Create project and branch for testing
+      project = await NeonProject("project", {});
+      branch = await NeonBranch("branch", {
+        project,
+        endpoints: [{ type: "read_write" }],
+      });
+
+      // Create protected role
+      role = await NeonRole("protected-role", {
+        project: project.id,
+        branch: branch.id,
+        protected: true,
+      });
+
+      expect(role).toMatchObject({
+        name: expect.any(String),
+        projectId: project.id,
+        branchId: branch.id,
+        protected: true,
+        createdAt: expect.any(Date),
+        updatedAt: expect.any(Date),
+      });
+    } finally {
+      await destroy(scope);
+    }
+  });
+
+  test("role with custom name", async (scope) => {
+    let project: NeonProject | undefined;
+    let branch: NeonBranch | undefined;
+    let role: NeonRole | undefined;
+
+    try {
+      // Create project and branch for testing
+      project = await NeonProject("project", {});
+      branch = await NeonBranch("branch", {
+        project,
+        endpoints: [{ type: "read_write" }],
+      });
+
+      const customName = `${BRANCH_PREFIX}-custom-role`;
+
+      // Create role with custom name
+      role = await NeonRole("custom", {
+        project: project.id,
+        branch: branch.id,
+        name: customName,
+      });
+
+      expect(role.name).toBe(customName);
+    } finally {
+      await destroy(scope);
+    }
+  });
+
+  test("role with branch resource", async (scope) => {
+    let project: NeonProject | undefined;
+    let branch: NeonBranch | undefined;
+    let role: NeonRole | undefined;
+
+    try {
+      // Create project and branch
+      project = await NeonProject("project", {});
+      branch = await NeonBranch("branch", {
+        project,
+        endpoints: [{ type: "read_write" }],
+      });
+
+      // Create role using branch resource
+      role = await NeonRole("role", {
+        project: project,
+        branch: branch,
+      });
+
+      expect(role).toMatchObject({
+        projectId: project.id,
+        branchId: branch.id,
+      });
+    } finally {
+      await destroy(scope);
+    }
+  });
+});

From 3db7713a41d5ac0faef8f5cd7b05cab476fda99e Mon Sep 17 00:00:00 2001
From: Alex <alex@gogl.io>
Date: Sat, 18 Oct 2025 12:27:34 +0200
Subject: [PATCH 3/8] refactor(neon): rename Role.protected to noLogin for
 clarity
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address reviewer feedback about confusing naming:
- Renamed `protected` property to `noLogin` in NeonRole
- Updated all tests to use `noLogin` instead of `protected`
- Updated documentation to reflect the change
- All 4 tests still passing

The `protected` name was confusing because:
- In NeonBranch, `protected` means "prevent deletion"
- In NeonRole, it was being used for "cannot login"

Now `noLogin` clearly indicates the role cannot be used for login,
which maps directly to the Neon API's `no_login` parameter.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../src/content/docs/providers/neon/role.md      | 16 ++++++++--------
 alchemy/src/neon/role.ts                         | 14 +++++++-------
 alchemy/test/neon/role.test.ts                   | 12 ++++++------
 3 files changed, 21 insertions(+), 21 deletions(-)

diff --git a/alchemy-web/src/content/docs/providers/neon/role.md b/alchemy-web/src/content/docs/providers/neon/role.md
index 386c9992c..29a6d756e 100644
--- a/alchemy-web/src/content/docs/providers/neon/role.md
+++ b/alchemy-web/src/content/docs/providers/neon/role.md
@@ -45,9 +45,9 @@ const role = await NeonRole("api-user", {
 console.log("Connection ready for:", role.name);
 ```
 
-## Protected Role
+## No-Login Role
 
-Create a protected role that cannot be used for login (useful for ownership and permissions):
+Create a role that cannot be used for login (useful for ownership and permissions):
 
 ```ts
 import { NeonProject, NeonBranch, NeonRole } from "alchemy/neon";
@@ -64,7 +64,7 @@ const branch = await NeonBranch("main", {
 const owner = await NeonRole("owner", {
   project,
   branch,
-  protected: true, // Cannot be used for login
+  noLogin: true, // Cannot be used for login
 });
 
 console.log("Owner role created:", owner.name);
@@ -199,7 +199,7 @@ console.log("Password (decrypted at runtime):", role.password.unencrypted);
 | `project` | `string \| NeonProject` | Yes | The project containing the branch |
 | `branch` | `string \| NeonBranch` | Yes | The branch to create the role in |
 | `name` | `string` | No | Role name (max 63 bytes, default: `${app}-${stage}-${id}`) |
-| `protected` | `boolean` | No | Whether to create a role that cannot login (default: `false`) |
+| `noLogin` | `boolean` | No | Whether to create a role that cannot login (default: `false`) |
 | `apiKey` | `Secret` | No | Neon API key (overrides `NEON_API_KEY` env var) |
 
 ### Output Properties (NeonRole)
@@ -211,7 +211,7 @@ console.log("Password (decrypted at runtime):", role.password.unencrypted);
 | `branchId` | `string` | The branch ID this role belongs to |
 | `branch` | `string \| NeonBranch` | The branch reference from input |
 | `password` | `Secret` | The role password (encrypted in state) |
-| `protected` | `boolean` | Whether the role is system-protected |
+| `noLogin` | `boolean` | Whether the role cannot login |
 | `createdAt` | `Date` | When the role was created |
 | `updatedAt` | `Date` | When the role was last updated |
 
@@ -237,7 +237,7 @@ These properties cannot be changed after creation (they trigger replacement):
 - `project` / `projectId`
 - `branch` / `branchId`
 - `name`
-- `protected`
+- `noLogin`
 
 Roles do not have an update endpoint in the Neon API, so attempting to update a role will either keep the existing state or trigger a replacement.
 
@@ -248,9 +248,9 @@ Role names:
 - Must be unique within the branch
 - Cannot be changed after creation
 
-### Protected Roles
+### No-Login Roles
 
-Protected roles (`protected: true`) cannot be used to log into the database. They are useful for:
+No-login roles (`noLogin: true`) cannot be used to log into the database. They are useful for:
 - Ownership of database objects
 - Role hierarchies and permission inheritance
 - System roles that shouldn't have direct login access
diff --git a/alchemy/src/neon/role.ts b/alchemy/src/neon/role.ts
index 6ccfedc80..dd466513f 100644
--- a/alchemy/src/neon/role.ts
+++ b/alchemy/src/neon/role.ts
@@ -26,7 +26,7 @@ export interface NeonRoleProps extends NeonApiOptions {
    * Whether to create a role that cannot login.
    * @default false
    */
-  protected?: boolean;
+  noLogin?: boolean;
 }
 
 export type NeonRole = Omit<NeonRoleProps, "project"> & {
@@ -49,7 +49,7 @@ export type NeonRole = Omit<NeonRoleProps, "project"> & {
   /**
    * Whether the role cannot login (no_login flag)
    */
-  protected: boolean;
+  noLogin: boolean;
   /**
    * A timestamp indicating when the role was created
    */
@@ -77,11 +77,11 @@ export type NeonRole = Omit<NeonRoleProps, "project"> & {
  *   branch: "branch-id",
  * });
  *
- * console.log(`Password: ${role.password.value}`);
+ * console.log(`Password: ${role.password.unencrypted}`);
  * ```
  *
  * @example
- * ## Protected Role
+ * ## No-Login Role
  *
  * Create a role that cannot login (useful for ownership):
  *
@@ -89,7 +89,7 @@ export type NeonRole = Omit<NeonRoleProps, "project"> & {
  * const role = await NeonRole("owner", {
  *   project: "project-id",
  *   branch: "branch-id",
- *   protected: true,
+ *   noLogin: true,
  * });
  * ```
  *
@@ -153,7 +153,7 @@ export const NeonRole = Resource(
           body: {
             role: {
               name,
-              no_login: props.protected,
+              no_login: props.noLogin,
             },
           },
         });
@@ -176,7 +176,7 @@ export const NeonRole = Resource(
           branchId,
           branch: props.branch,
           password: new Secret(passwordRes.data.password),
-          protected: props.protected ?? false,
+          noLogin: props.noLogin ?? false,
           createdAt: new Date(data.role.created_at),
           updatedAt: new Date(data.role.updated_at),
         };
diff --git a/alchemy/test/neon/role.test.ts b/alchemy/test/neon/role.test.ts
index f238a724f..e432d998d 100644
--- a/alchemy/test/neon/role.test.ts
+++ b/alchemy/test/neon/role.test.ts
@@ -40,7 +40,7 @@ describe("NeonRole Resource", () => {
         projectId: project.id,
         branchId: branch.id,
         password: expect.any(Object),
-        protected: false,
+        noLogin: false,
         createdAt: expect.any(Date),
         updatedAt: expect.any(Date),
       });
@@ -71,7 +71,7 @@ describe("NeonRole Resource", () => {
     }
   });
 
-  test("create protected role", async (scope) => {
+  test("create no-login role", async (scope) => {
     let project: NeonProject | undefined;
     let branch: NeonBranch | undefined;
     let role: NeonRole | undefined;
@@ -84,18 +84,18 @@ describe("NeonRole Resource", () => {
         endpoints: [{ type: "read_write" }],
       });
 
-      // Create protected role
-      role = await NeonRole("protected-role", {
+      // Create no-login role
+      role = await NeonRole("no-login-role", {
         project: project.id,
         branch: branch.id,
-        protected: true,
+        noLogin: true,
       });
 
       expect(role).toMatchObject({
         name: expect.any(String),
         projectId: project.id,
         branchId: branch.id,
-        protected: true,
+        noLogin: true,
         createdAt: expect.any(Date),
         updatedAt: expect.any(Date),
       });

From dd6a8b9704a42966a5a1e3dab9027df142cc6551 Mon Sep 17 00:00:00 2001
From: Alex <alex@gogl.io>
Date: Sat, 18 Oct 2025 12:30:47 +0200
Subject: [PATCH 4/8] docs(neon): fix outdated comment referencing protected
 flag

Update comment to reference noLogin instead of protected
---
 alchemy/src/neon/role.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/alchemy/src/neon/role.ts b/alchemy/src/neon/role.ts
index dd466513f..a94baddba 100644
--- a/alchemy/src/neon/role.ts
+++ b/alchemy/src/neon/role.ts
@@ -196,7 +196,7 @@ export const NeonRole = Resource(
         }
 
         // Roles don't have an update endpoint, so we return the current state
-        // The protected flag is immutable after creation
+        // The noLogin flag is immutable after creation
         return this.output;
       }
     }

From 38034e9459c46da4563f821de767bacd8d0d088c Mon Sep 17 00:00:00 2001
From: Alex <alex@gogl.io>
Date: Sat, 18 Oct 2025 20:43:08 +0200
Subject: [PATCH 5/8] fix(neon): trigger replacement instead of error on Role
 name change
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address code review feedback from @Mkassabov and @sam-goodwin:
- Changed from throwing an error to calling this.replace() when role name changes
- Consistent with how project/branch immutable properties are handled
- Allows Alchemy to properly replace the resource instead of failing

All tests passing (4/4).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 alchemy/src/neon/role.ts | 9 ++-------
 1 file changed, 2 insertions(+), 7 deletions(-)

diff --git a/alchemy/src/neon/role.ts b/alchemy/src/neon/role.ts
index a94baddba..82bfe7173 100644
--- a/alchemy/src/neon/role.ts
+++ b/alchemy/src/neon/role.ts
@@ -184,17 +184,12 @@ export const NeonRole = Resource(
       case "update": {
         if (
           this.output.projectId !== projectId ||
-          this.output.branchId !== branchId
+          this.output.branchId !== branchId ||
+          this.output.name !== name
         ) {
           this.replace();
         }
 
-        if (this.output.name !== name) {
-          throw new Error(
-            `Cannot change role name from '${this.output.name}' to '${name}'. Role name is immutable after creation.`,
-          );
-        }
-
         // Roles don't have an update endpoint, so we return the current state
         // The noLogin flag is immutable after creation
         return this.output;

From daa79a3d5f5e6e2e516df3b12bce644671779bdc Mon Sep 17 00:00:00 2001
From: Alex <alex@gogl.io>
Date: Sat, 18 Oct 2025 20:50:11 +0200
Subject: [PATCH 6/8] refactor(neon): clean up Role JSDoc per code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address code review feedback from @Mkassabov:
- Change password type from Secret to Secret<string>
- Remove markdown headings from @example blocks
- Keep only the TypeScript code in examples

All tests passing (4/4).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 alchemy/src/neon/role.ts | 14 +-------------
 1 file changed, 1 insertion(+), 13 deletions(-)

diff --git a/alchemy/src/neon/role.ts b/alchemy/src/neon/role.ts
index 82bfe7173..77829ff69 100644
--- a/alchemy/src/neon/role.ts
+++ b/alchemy/src/neon/role.ts
@@ -45,7 +45,7 @@ export type NeonRole = Omit<NeonRoleProps, "project"> & {
   /**
    * The role password
    */
-  password: Secret;
+  password: Secret<string>;
   /**
    * Whether the role cannot login (no_login flag)
    */
@@ -67,10 +67,6 @@ export type NeonRole = Omit<NeonRoleProps, "project"> & {
  * with login credentials that can be used to connect to the database.
  *
  * @example
- * ## Basic Role
- *
- * Create a role in a branch:
- *
  * ```ts
  * const role = await NeonRole("app-role", {
  *   project: "project-id",
@@ -81,10 +77,6 @@ export type NeonRole = Omit<NeonRoleProps, "project"> & {
  * ```
  *
  * @example
- * ## No-Login Role
- *
- * Create a role that cannot login (useful for ownership):
- *
  * ```ts
  * const role = await NeonRole("owner", {
  *   project: "project-id",
@@ -94,10 +86,6 @@ export type NeonRole = Omit<NeonRoleProps, "project"> & {
  * ```
  *
  * @example
- * ## Using with Branch
- *
- * Create a role using a Branch resource:
- *
  * ```ts
  * const branch = await NeonBranch("dev", {
  *   project: "project-id",

From a17f97c581789c693078dad1a77d22ee87559a95 Mon Sep 17 00:00:00 2001
From: Alex <alex@gogl.io>
Date: Sun, 19 Oct 2025 17:21:16 +0200
Subject: [PATCH 7/8] export role resources from index

---
 alchemy/src/neon/index.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/alchemy/src/neon/index.ts b/alchemy/src/neon/index.ts
index 9c18c0682..41377203c 100644
--- a/alchemy/src/neon/index.ts
+++ b/alchemy/src/neon/index.ts
@@ -1,3 +1,5 @@
 export * from "./api.ts";
 export * from "./branch.ts";
 export * from "./project.ts";
+export * from "./role.ts";
+

From dbcaa286e98aa9b1dfedcce6d352b262ed61faaf Mon Sep 17 00:00:00 2001
From: Alex <alex@gogl.io>
Date: Mon, 20 Oct 2025 16:39:30 +0200
Subject: [PATCH 8/8] feat(neon): add connectionUris to NeonRole for
 consistency
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add connectionUris property to NeonRole output type
- Rename RoleData → NeonRoleData for consistent naming with NeonConnectionUri
- Create createConnectionUri helper to build connection URIs from components
- Generate connection URIs during role creation from branch endpoints/databases
- Update NeonRole tests to verify connectionUris structure

This makes NeonRole consistent with NeonBranch and NeonProject, which both
provide connection URIs. The URIs are generated at creation time and persisted
in state, matching the pattern used by other Neon resources.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 alchemy/src/neon/branch.ts     |  4 +--
 alchemy/src/neon/index.ts      |  1 -
 alchemy/src/neon/project.ts    |  9 ++++--
 alchemy/src/neon/role.ts       | 55 ++++++++++++++++++++++++++++++----
 alchemy/src/neon/utils.ts      | 27 +++++++++++++++--
 alchemy/test/neon/role.test.ts |  7 +++++
 6 files changed, 89 insertions(+), 14 deletions(-)

diff --git a/alchemy/src/neon/branch.ts b/alchemy/src/neon/branch.ts
index e8e145034..1298e180c 100644
--- a/alchemy/src/neon/branch.ts
+++ b/alchemy/src/neon/branch.ts
@@ -8,7 +8,7 @@ import {
   formatRole,
   waitForOperations,
   type NeonConnectionUri,
-  type NeonRole,
+  type NeonRoleData,
 } from "./utils.ts";
 
 export interface NeonBranchProps extends NeonApiOptions {
@@ -139,7 +139,7 @@ export interface NeonBranch {
   /**
    * The roles for the branch.
    */
-  roles: NeonRole[];
+  roles: NeonRoleData[];
   /**
    * The connection URIs for the branch.
    */
diff --git a/alchemy/src/neon/index.ts b/alchemy/src/neon/index.ts
index 41377203c..4aae4bf9d 100644
--- a/alchemy/src/neon/index.ts
+++ b/alchemy/src/neon/index.ts
@@ -2,4 +2,3 @@ export * from "./api.ts";
 export * from "./branch.ts";
 export * from "./project.ts";
 export * from "./role.ts";
-
diff --git a/alchemy/src/neon/project.ts b/alchemy/src/neon/project.ts
index 8b03ceb0a..dc4a15868 100644
--- a/alchemy/src/neon/project.ts
+++ b/alchemy/src/neon/project.ts
@@ -7,7 +7,7 @@ import {
   formatRole,
   waitForOperations,
   type NeonConnectionUri,
-  type NeonRole,
+  type NeonRoleData,
 } from "./utils.ts";
 
 /**
@@ -137,7 +137,7 @@ export interface NeonProject {
   /**
    * Database roles created with the project
    */
-  roles: [NeonRole, ...NeonRole[]];
+  roles: [NeonRoleData, ...NeonRoleData[]];
 
   /**
    * Databases created with the project
@@ -244,7 +244,10 @@ export const NeonProject = Resource(
             NeonConnectionUri,
             ...NeonConnectionUri[],
           ],
-          roles: data.roles.map(formatRole) as [NeonRole, ...NeonRole[]],
+          roles: data.roles.map(formatRole) as [
+            NeonRoleData,
+            ...NeonRoleData[],
+          ],
           databases: data.databases as [neon.Database, ...neon.Database[]],
           branch,
           endpoints: endpoints as [neon.Endpoint, ...neon.Endpoint[]],
diff --git a/alchemy/src/neon/role.ts b/alchemy/src/neon/role.ts
index 77829ff69..29a345249 100644
--- a/alchemy/src/neon/role.ts
+++ b/alchemy/src/neon/role.ts
@@ -4,7 +4,11 @@ import { Resource } from "../resource.ts";
 import { createNeonApi, type NeonApiOptions } from "./api.ts";
 import type { NeonBranch } from "./branch.ts";
 import type { NeonProject } from "./project.ts";
-import { waitForOperations } from "./utils.ts";
+import {
+  createConnectionUri,
+  waitForOperations,
+  type NeonConnectionUri,
+} from "./utils.ts";
 
 export interface NeonRoleProps extends NeonApiOptions {
   /**
@@ -29,7 +33,7 @@ export interface NeonRoleProps extends NeonApiOptions {
   noLogin?: boolean;
 }
 
-export type NeonRole = Omit<NeonRoleProps, "project"> & {
+export type NeonRole = Omit<NeonRoleProps, "project" | "branch"> & {
   /**
    * The role name
    */
@@ -58,6 +62,11 @@ export type NeonRole = Omit<NeonRoleProps, "project"> & {
    * A timestamp indicating when the role was last updated
    */
   updatedAt: Date;
+  /**
+   * The connection URIs for the role.
+   * Generated from the branch's endpoints and databases.
+   */
+  connectionUris: NeonConnectionUri[];
 };
 
 /**
@@ -158,15 +167,49 @@ export const NeonRole = Resource(
           },
         });
 
+        // Fetch endpoints and databases for the branch to generate connection URIs
+        const [endpointsRes, databasesRes] = await Promise.all([
+          api.listProjectBranchEndpoints({
+            path: {
+              project_id: projectId,
+              branch_id: branchId,
+            },
+          }),
+          api.listProjectBranchDatabases({
+            path: {
+              project_id: projectId,
+              branch_id: branchId,
+            },
+          }),
+        ]);
+
+        // Generate connection URIs for each endpoint × database combination
+        const connectionUris: NeonConnectionUri[] = [];
+        const password = passwordRes.data.password;
+        for (const endpoint of endpointsRes.data.endpoints) {
+          if (endpoint.host) {
+            for (const database of databasesRes.data.databases) {
+              connectionUris.push(
+                createConnectionUri(
+                  endpoint.host,
+                  database.name,
+                  data.role.name,
+                  password,
+                ),
+              );
+            }
+          }
+        }
+
         return {
           name: data.role.name,
           projectId,
           branchId,
-          branch: props.branch,
-          password: new Secret(passwordRes.data.password),
+          password: new Secret(password),
           noLogin: props.noLogin ?? false,
           createdAt: new Date(data.role.created_at),
           updatedAt: new Date(data.role.updated_at),
+          connectionUris,
         };
       }
       case "update": {
@@ -178,8 +221,8 @@ export const NeonRole = Resource(
           this.replace();
         }
 
-        // Roles don't have an update endpoint, so we return the current state
-        // The noLogin flag is immutable after creation
+        // Roles don't have an update endpoint, so return current state
+        // The connectionUris are already in this.output from creation
         return this.output;
       }
     }
diff --git a/alchemy/src/neon/utils.ts b/alchemy/src/neon/utils.ts
index d9ad26d63..75f705a76 100644
--- a/alchemy/src/neon/utils.ts
+++ b/alchemy/src/neon/utils.ts
@@ -36,7 +36,7 @@ export function formatConnectionUri(
   };
 }
 
-export interface NeonRole {
+export interface NeonRoleData {
   /**
    * The ID of the branch to which the role belongs
    */
@@ -63,13 +63,36 @@ export interface NeonRole {
   updated_at: string;
 }
 
-export function formatRole(role: neon.Role): NeonRole {
+export function formatRole(role: neon.Role): NeonRoleData {
   return {
     ...role,
     password: role.password ? new Secret(role.password) : undefined,
   };
 }
 
+/**
+ * Creates a connection URI from individual components.
+ * Used when constructing connection URIs for a specific role.
+ */
+export function createConnectionUri(
+  host: string,
+  database: string,
+  roleName: string,
+  password: string,
+): NeonConnectionUri {
+  const connectionString = `postgresql://${roleName}:${password}@${host}/${database}?sslmode=require`;
+  return {
+    connection_uri: new Secret(connectionString),
+    connection_parameters: {
+      database,
+      host,
+      port: 5432,
+      user: roleName,
+      password: new Secret(password),
+    },
+  };
+}
+
 export async function waitForOperations(
   api: NeonClient,
   operations: neon.Operation[],
diff --git a/alchemy/test/neon/role.test.ts b/alchemy/test/neon/role.test.ts
index e432d998d..20faa5f02 100644
--- a/alchemy/test/neon/role.test.ts
+++ b/alchemy/test/neon/role.test.ts
@@ -43,9 +43,16 @@ describe("NeonRole Resource", () => {
         noLogin: false,
         createdAt: expect.any(Date),
         updatedAt: expect.any(Date),
+        connectionUris: expect.any(Array),
       });
       expect(role.password.unencrypted).toBeDefined();
       expect(typeof role.password.unencrypted).toBe("string");
+      expect(role.connectionUris.length).toBeGreaterThan(0);
+      expect(role.connectionUris[0].connection_uri.unencrypted).toContain(
+        "postgresql://",
+      );
+      expect(role.connectionUris[0].connection_parameters.user).toBe(role.name);
+      expect(role.connectionUris[0].connection_parameters.port).toBe(5432);
 
       // Update should return the same state
       const updatedRole = await NeonRole("role", {