DC-5560 Deno Deploy Integration Guide

content/800-guides/400-deno-integration.mdx

@@ -0,0 +1,277 @@
+---
+title: 'Integrate Prisma Postgres with Deno Deploy'
+metaTitle: 'Integrate Prisma Postgres with Deno Deploy'
+metaDescription: 'Learn how to integrate Prisma Postgres in a Deno Deploy project using a simple Deno application.'
+sidebar_label: 'Prisma Postgres on Deno'
+image: '/img/guides/prisma-deno-integration-cover.png'
+completion_time: '15 min'
+community_section: true
+---
+
+[Deno Deploy](https://deno.com/deploy) includes a feature that allows you to provision a Prisma Postgres database directly within the platform. This guide demonstrates how to integrate Prisma Postgres in a Deno Deploy project using a minimal Deno application that logs HTTP requests to the database.
+
+By the end of this guide, you will have a deployed Deno app that writes to and reads from a Prisma Postgres database provisioned in Deno Deploy, using Prisma Client with `runtime = "deno"`.
+
+## Prerequisites
+
+- A [Deno Deploy](https://deno.com/deploy) account
+- Deno runtime installed ([installation guide](https://docs.deno.com/runtime/#install-deno))
+- [Deno extension for VS Code](https://docs.deno.com/runtime/reference/vscode/)
+
+## 1. Create and set up a new Deno project
+
+Create a new Deno project using the `deno init` command, which generates a basic project structure with a main entry file and configuration.
+
+```terminal
+deno init prisma-postgres-deno-deploy
+cd prisma-postgres-deno-deploy
+```
+
+### 1.1 Configure VS Code for Deno
+
+To ensure VS Code recognizes this as a Deno project and provides proper TypeScript validation, you need to initialize the workspace. Without this, VS Code will show errors when using Deno-specific APIs like `Deno.serve`.
+
+Install the [Deno extension for VS Code](https://docs.deno.com/runtime/reference/vscode/), then:
+1. Select **View** > **Command Palette** _(or press `Cmd+Shift+P` on macOS or `Ctrl+Shift+P` on Windows)_
+2. Run the command **Deno: Initialize Workspace Configuration**
+
+### 1.2 Create a basic HTTP server
+
+Update the `main.ts` file to create a simple HTTP server that responds with "Hello, World!", establishing the foundation for your application before adding database functionality.
+
+```tsx file=main.ts
+function handler(_req: Request): Response {
+  return new Response("Hello, World!");
+}
+
+Deno.serve(handler);
+```
+
+You can test the server locally by running:
+
+```terminal
+deno run dev
+```
+
+Visit `localhost:8000` in your browser to see the application running.
+
+### 1.3 Push initial project to GitHub
+
+To connect your project to Deno Deploy and get a database connection string, you need to have a successful deployment. Set up a GitHub repository and push your project to it.
+
+## 2. Deploy the project to Deno Deploy
+
+Deploy your repository to Deno Deploy. Any subsequent commits will trigger automatic redeployments. You need to deploy now, as the database string requires a successful deployment to generate.
+
+1. Navigate to the [Deno Deploy dashboard](https://dash.deno.com/) and select **New App**
+2. Configure GitHub app permissions by following GitHub's prompts
+3. Choose your GitHub repository in the Deno Deploy interface
+4. Click **Create App** to complete the deployment
+
+The application will deploy automatically.
+
+## 3. Provision a Prisma Postgres database
+
+Provision a Prisma Postgres database in Deno Deploy, and link it to your application:
+
+1. Go to the **Databases** section in the Deno Deploy dashboard
+2. Select **Provision Database** and choose **Prisma Postgres**
+3. Complete the database configuration and confirm provisioning
+4. Click **Assign** and select your application
+5. Copy the **Production connection string**
+6. Add the connection string to your `.env` file:
+
+```env
+DATABASE_URL="postgresql://<username>:<password>@db.prisma.io:5432/<database_name>-production"
+```
+
+## 4. Configure Prisma ORM
+
+### 4.1 Enable environment variables
+
+To access the database connection string during local development, configure Deno to load environment variables from your `.env` file using the `--env-file` flag.
+
+Update the `dev` task in `deno.json`:
+
+```json file=deno.json
+{
+  "tasks": {
+    // edit-next-line
+    "dev": "deno run --watch --env-file main.ts"
+  }
+}
+```
+
+### 4.2 Initialize Prisma and create schema
+
+Install the Prisma Client:
+
+```terminal
+deno install npm:@prisma/client
+```
+
+Initialize Prisma in your project, which creates the necessary configuration files and folder structure for defining your database models.
+
+```terminal
+npx prisma init
+```
+
+Update the Prisma schema with these changes:
+1. Change the client output from `prisma-client-js` to `prisma-client`.
+2. Add the Deno runtime configuration. *(This is required for Deno to run properly)*
+3. Add the Log model for storing request information.
+
+```prisma file=prisma/schema.prisma
+generator client {
+  // edit-next-line
+  provider = "prisma-client"
+  output   = "../generated/prisma"
+  // add-next-line
+  runtime  = "deno"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+// add-start
+model Log {
+  id      Int    @id @default(autoincrement())
+  level   Level
+  message String
+  meta    Json
+}
+
+enum Level {
+  Info
+  Warn
+  Error
+}
+// add-end
+```
+
+### 4.3 Generate and apply migrations
+
+Migrations create the actual database tables based on your Prisma schema. This command generates SQL migration files and executes them against your database, creating the `Log` table with the specified fields.
+
+```terminal
+deno run -A npm:prisma migrate dev --name init
+```
+
+## 5. Update the application to use Prisma
+
+Now that the database is configured, update your application to interact with it. This implementation creates a logging system that captures every HTTP request, stores it in the database, and returns the logged entry as JSON.
+
+```tsx file=main.ts
+import { PrismaClient } from "./generated/prisma/client.ts";
+import process from "node:process";
+
+const prisma = new PrismaClient({
+  datasources: {
+    db: {
+      url: process.env.DATABASE_URL,
+    },
+  },
+});
+
+async function handler(request: Request) {
+  const url = new URL(request.url);
+  if (url.pathname === "/favicon.ico") {
+    return new Response(null, { status: 204 });
+  }
+
+  const log = await prisma.log.create({
+    data: {
+      level: "Info",
+      message: `${request.method} ${request.url}`,
+      meta: {
+        headers: JSON.stringify(request.headers),
+      },
+    },
+  });
+  const body = JSON.stringify(log, null, 2);
+  return new Response(body, {
+    headers: { "content-type": "application/json; charset=utf-8" },
+  });
+}
+
+Deno.serve(handler);
+```
+
+Test the application locally by running:
+
+```terminal
+deno run dev
+```
+
+:::note
+
+It may ask you for access to your environment variables. Select **Allow** to grant access.
+
+:::
+
+Visit `localhost:8000` in your browser to see the application running. You should see a JSON response containing the log entry:
+
+```json
+{
+  "id": 1,
+  "level": "Info",
+  "message": "GET http://localhost:8000/",
+  "meta": {
+    "headers": "..."
+  }
+}
+```
+
+## 6. Deploy the application
+
+The build command must generate the Prisma Client code to ensure it is available in production.
+
+### 6.1 Update build command in Deno Deploy
+
+1. Go to the application in Deno Deploy and click **Settings**
+2. Under **Build configuration**, hit **Edit** and add `deno run -A npm:prisma generate` to the build command
+3. Click **Save**
+
+### 6.2 Push changes to GitHub
+
+Commit and push your changes to trigger an automatic deployment:
+
+```terminal
+git add .
+git commit -m "added prisma"
+git push
+```
+
+Navigate back to Deno Deploy and you should see a successful build. Once deployed, click the deployment URL at the top right of the dashboard.
+
+### 6.3 Verify the deployment
+
+When you visit your deployed application, you should see a response that looks like this:
+
+```json
+{
+  "id": 1,
+  "level": "Info",
+  "message": "GET https://prisma-postgres-deno-deploy.<org-name>.deno.net/",
+  "meta": {
+    "headers": "{}"
+  }
+}
+```
+
+You're done! Each time you refresh the page, a new log entry is created in your database.
+
+## Next Steps
+
+Now that you have a working Deno app connected to a Prisma Postgres database, you can:
+
+- **Enhance your data model** - Add relationships, validations, and indexes to your Prisma schema
+- **Secure your API** - Implement authentication, rate limiting, and proper error handling
+- **Improve deployment** - Set up CI/CD, monitoring, and database backups for production
+
+## More info
+
+- [Prisma ORM Documentation](/orm/overview/introduction)
+- [Deno Deploy Documentation](https://docs.deno.com/deploy)

sidebars.ts

@@ -474,6 +474,7 @@ const sidebars: SidebarsConfig = {
             "guides/management-api-basic",
             "guides/management-api",
             "guides/vercel-app-deployment",
+            "guides/deno-integration",
           ].sort(),
         },
         {