diff --git a/content/800-guides/400-deno-integration.mdx b/content/800-guides/400-deno-integration.mdx new file mode 100644 index 0000000000..b0b10fe407 --- /dev/null +++ b/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://:@db.prisma.io:5432/-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..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) \ No newline at end of file diff --git a/sidebars.ts b/sidebars.ts index be26f75369..e38be5d27a 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -474,6 +474,7 @@ const sidebars: SidebarsConfig = { "guides/management-api-basic", "guides/management-api", "guides/vercel-app-deployment", + "guides/deno-integration", ].sort(), }, { diff --git a/static/img/guides/prisma-deno-integration-cover.png b/static/img/guides/prisma-deno-integration-cover.png new file mode 100644 index 0000000000..0580ac2072 Binary files /dev/null and b/static/img/guides/prisma-deno-integration-cover.png differ