Merge branch 'main' into jharrell/issue5407

cSpell.json

@@ -55,7 +55,8 @@
     "backoff",
     "Replibyte",
     "Snaplet",
-    "Kysely"
+    "Kysely",
+    "Turso"
   ],
   "ignoreWords": [
     "Ania",

content/200-concepts/100-components/database-drivers.mdx

@@ -0,0 +1,54 @@
+---
+title: 'Database drivers'
+metaTitle: 'Database drivers'
+metaDescription: 'Learn how Prisma connects to your database using the built-in drivers and how you can use Prisma along with other JavaScript database drivers using driver adapters (Preview)'
+tocDepth: 4
+---
+
+## Default built-in drivers
+
+One of Prisma Client's components is the [Query Engine](./prisma-engines/query-engine) <span class="concept"></span>. The Query Engine is responsible for transforming Prisma Client queries to SQL statements. The Query Engine connects to your database using the included drivers that don't require additional setup. The built-in drivers use TCP connections to connect to the database.
+
+![Query flow from the user application to the database with Prisma Client](./images/drivers/qe-query-execution-flow.png)
+
+## Driver adapters
+
+Prisma Client can connect and run queries against your database using JavaScript database drivers using **driver adapters**. Adapters act as _translators_ between Prisma Client and the JavaScript database driver.
+
+Prisma will use the Query Engine to transform the Prisma Client query to SQL and run the generated SQL queries via the JavaScript database driver.
+
+![Query flow from the user application to the database using Prisma Client and driver adapters](./images//drivers/qe-query-engine-adapter.png)
+
+### Serverless driver adapters
+
+- [Neon](/guides/database/neon#how-to-use-the-neon-serverless-driver-with-prisma-preview)
+- [PlanetScale](/guides/database/planetscale#how-to-use-the-planetscale-serverless-driver-with-prisma-preview)
+
+### Database driver adapters
+
+- [Turso](/guides/database/turso#connect-and-query-your-primary-database)
+
+### How to use driver adapters
+
+To use this feature:
+
+1. Update the `previewFeatures` block in your schema to include the the `driverAdapters` preview feature:
+
+   ```prisma
+   generator client {
+     provider        = "prisma-client-js"
+     previewFeatures = ["driverAdapters"]
+   }
+   ```
+
+2. Generate Prisma Client:
+
+   ```sh
+   npx prisma generate
+   ```
+
+3. Refer to the following pages to learn more how to use the specific driver adapters with the specific database providers:
+
+   - [Neon](/guides/database/neon#how-to-use-the-neon-serverless-driver-with-prisma-preview)
+   - [PlanetScale](/guides/database/planetscale#how-to-use-the-planetscale-serverless-driver-with-prisma-preview)
+   - [Turso](/guides/database/turso#connect-and-query-your-primary-database)

content/300-guides/050-database/850-planetscale.mdx

@@ -225,6 +225,74 @@ model User {
 
 For a more detailed example, see the [Getting Started guide for PlanetScale](/getting-started/setup-prisma/add-to-existing-project/relational-databases/introspection-typescript-planetscale).
 
+## How to use the PlanetScale serverless driver with Prisma (Preview)
+
+The [PlanetScale serverless driver](https://planetscale.com/docs/tutorials/planetscale-serverless-driver) provides a way of communicating with your database and executing queries over HTTP.
+
+You can use Prisma along with the PlanetScale serverless driver using the [`@prisma/adapter-planetscale`](https://www.npmjs.com/package/@prisma/adapter-planetscale) driver adapter. The driver adapter allows you to communicate with your database over HTTP.
+
+<Admonition>
+
+This feature is available in Preview from Prisma versions 5.4.2 and later.
+
+</Admonition>
+
+To get started, enable the `driverAdapters` Preview feature flag:
+
+```prisma
+generator client {
+  provider        = "prisma-client-js"
+  previewFeatures = ["driverAdapters"]
+}
+```
+
+Generate Prisma Client:
+
+```sh
+npx prisma generate
+```
+
+<Admonition>
+
+Ensure you update the host value in your connection string to `aws.connect.psdb.cloud`. You can learn more about this [here](https://planetscale.com/docs/tutorials/planetscale-serverless-driver#add-and-use-the-planetscale-serverless-driver-for-javascript-to-your-project).
+
+```bash
+DATABASE_URL='mysql://johndoe:[email protected]/clear_nightsky?sslaccept=strict'
+```
+
+</Admonition>
+
+Install the Prisma adapter for PlanetScale, PlanetScale serverless driver and `undici` packages:
+
+```sh
+npm install @prisma/adapter-planetscale @planetscale/database undici
+```
+
+<Admonition>
+
+When using a Node.js version below 18, you must provide a custom fetch function implementation. We recommend the `undici` package on which Node's built-in fetch is based. Node.js versions 18 and later include a built-in global `fetch` function, so you don't have to install an extra package.
+
+</Admonition>
+
+Update your Prisma Client instance to use the PlanetScale serverless driver:
+
+```ts
+import { connect } from '@planetscale/database'
+import { PrismaPlanetScale } from '@prisma/adapter-planetscale'
+import { PrismaClient } from '@prisma/client'
+import dotenv from 'dotenv'
+import { fetch as undiciFetch } from 'undici'
+
+dotenv.config()
+const connectionString = `${process.env.DATABASE_URL}`
+
+const connection = connect({ url: connectionString, fetch: undiciFetch })
+const adapter = new PrismaPlanetScale(connection)
+const prisma = new PrismaClient({ adapter })
+```
+
+You can then use Prisma Client as you normally would with full type-safety. Prisma Migrate, introspection, and Prisma Studio will continue working as before using the connection string defined in the Prisma schema.
+
 ## More on using PlanetScale with Prisma
 
 The fastest way to start using PlanetScale with Prisma is to refer to our Getting Started documentation:

content/300-guides/050-database/890-neon.mdx

@@ -0,0 +1,174 @@
+---
+title: 'Using Prisma with Neon'
+metaTitle: 'Using Prisma with Neon'
+metaDescription: 'Guide to using Prisma with Neon'
+tocDepth: 2
+toc: true
+---
+
+<TopBlock>
+
+This guide explains how to:
+
+- [Connect Prisma using Neon's connection pooling feature](#how-to-use-neons-connection-pooling)
+- [Resolve connection timeout issues](#resolving-connection-timeouts)
+- [Use Neon's serverless driver with Prisma](#how-to-use-neons-serverless-driver-with-prisma-preview)
+
+</TopBlock>
+
+## What is Neon?
+
+<img
+  src="https://avatars.githubusercontent.com/u/77690634?s=200&v=4"
+  style="margin:auto; width: 25%; padding-left: 20px; css-float:right;@media (max-width: 641px){display: none;}"
+  alt="Neon's logo"
+/>
+
+[Neon](https://neon.tech/) is a fully managed serverless PostgreSQL with a generous free tier. Neon separates storage and compute, and offers modern developer features such as serverless, branching, bottomless storage, and more. Neon is open source and written in Rust.
+
+Learn more about Neon [here](https://neon.tech/docs).
+
+## Commonalities with other database providers
+
+Many aspects of using Prisma with Neon are just like using Prisma with any other PostgreSQL database. You can:
+
+- model your database with the [Prisma Schema Language](/concepts/components/prisma-schema)
+- use Prisma's [`postgresql` database connector](/concepts/database-connectors/postgresql) in your schema, along with the [connection string Neon provides you](https://neon.tech/docs/connect/connect-from-any-app)
+- use [Introspection](/concepts/components/introspection) for existing projects if you already have a database schema on Neon
+- use [`prisma migrate dev`](/concepts/components/prisma-migrate/migrate-development-production) to track schema migrations in your Neon database
+- use [`prisma db push`](/concepts/components/prisma-migrate/db-push) to push changes in your schema to Neon
+- use [Prisma Client](/concepts/components/prisma-client) in your application to communicate with the database hosted by Neon
+
+## Differences to consider
+
+There are a few differences between Neon and PostgreSQL you should be aware of the following when deciding to use Neon with Prisma:
+
+- **Neon's serverless model** — By default, Neon scales a [compute](https://neon.tech/docs/introduction/compute-lifecycle) to zero after 5 minutes of inactivity. During this state, a compute instance is in _idle_ state. A characteristic of this feature is the concept of a "cold start". Activating a compute from an idle state takes from 500ms to a few seconds. Depending on how long it takes to connect to your database, your application may timeout. To learn more, see: [Connection latency and timeouts](https://neon.tech/docs/guides/prisma#connection-timeouts).
+- **Neon's connection pooler** — Neon offers connection pooling using PgBouncer, enabling up to 10,000 concurrent connections. To learn more, see: [Connection pooling](https://neon.tech/docs/connect/connection-pooling).
+
+## How to use Neon's connection pooling
+
+If you'd like to use the [connection pooling](https://neon.tech/blog/prisma-dx-improvements#providing-pooled-and-direct-connections-to-the-database) available in Neon, you will
+need to add `pgbouncer=true` to the end of the `DATABASE_URL` environment variable used in the `url` property of the `datasource` block of your Prisma schema:
+
+```env file=.env
+# Connect to Neon with PgBouncer.
+DATABASE_URL=postgres://daniel:<password>@ep-mute-rain-952417-pooler.us-east-2.aws.neon.tech:5432/neondb?pgbouncer=true
+```
+
+If you would like to use Prisma CLI in order to perform other actions on your database (e.g. for migrations) you will need to add a `DIRECT_URL` environment variable to use in the `directUrl` property of the `datasource` block of your Prisma schema so that the CLI will use a direct connection string (without PgBouncer):
+
+```env file=.env highlight=4-5;add
+# Connect to Neon with PgBouncer.
+DATABASE_URL=postgres://daniel:<password>@ep-mute-rain-952417-pooler.us-east-2.aws.neon.tech/neondb?pgbouncer=true
+
+# Direct connection to the database used by Prisma CLI for e.g. migrations.
+DIRECT_URL="postgres://daniel:<password>@ep-mute-rain-952417.us-east-2.aws.neon.tech/neondb"
+```
+
+You can then update your `schema.prisma` to use the new direct URL:
+
+```prisma file=schema.prisma highlight=4;add
+datasource db {
+  provider  = "postgresql"
+  url       = env("DATABASE_URL")
+  directUrl = env("DIRECT_URL")
+}
+```
+
+More information about the `directUrl` field can be found [here](/reference/api-reference/prisma-schema-reference#fields).
+
+<Admonition type="info">
+
+We strongly recommend using the pooled connection string in your `DATABASE_URL` environment variable. You will gain the great developer experience of the Prisma CLI while also allowing for connections to be pooled regardless of deployment strategy. While this is not strictly necessary for every app, serverless solutions will inevitably require connection pooling.
+
+</Admonition>
+
+## Resolving connection timeouts
+
+A connection timeout that occurs when connecting from Prisma to Neon causes an error similar to the following:
+
+```text no-copy
+Error: P1001: Can't reach database server at `ep-white-thunder-826300.us-east-2.aws.neon.tech`:`5432`
+Please make sure your database server is running at `ep-white-thunder-826300.us-east-2.aws.neon.tech`:`5432`.
+```
+
+This error most likely means that the connection created by Prisma Client timed out before the Neon compute was activated.
+
+A Neon compute has two main states: _Active_ and _Idle_. Active means that the compute is currently running. If there is no query activity for 5 minutes, Neon places a compute into an idle state by default. Refer to Neon's docs to [learn more](https://neon.tech/docs/introduction/compute-lifecycle).
+
+When you connect to an idle compute from Prisma, Neon automatically activates it. Activation typically happens within a few seconds but added latency can result in a connection timeout. To address this issue, your can adjust your Neon connection string by adding a `connect_timeout` parameter. This parameter defines the maximum number of seconds to wait for a new connection to be opened. The default value is 5 seconds. A higher setting should provide the time required to avoid connection timeout issues. For example:
+
+```text wrap
+DATABASE_URL=postgres://daniel:<password>@ep-mute-rain-952417.us-east-2.aws.neon.tech/neondb?connect_timeout=10
+```
+
+<Admonition>
+
+A `connect_timeout` setting of 0 means no timeout.
+
+</Admonition>
+
+Another possible cause of connection timeouts is [Prisma's connection pool](https://www.prisma.io/docs/concepts/components/prisma-client/working-with-prismaclient/), which has a default timeout of 10 seconds. This is typically enough time for Neon, but if you are still experiencing connection timeouts, you can try increasing this limit (in addition to the `connect_timeout` setting described above) by setting the `pool_timeout` parameter to a higher value. For example:
+
+```text wrap
+DATABASE_URL=postgres://daniel:<password>@ep-mute-rain-952417.us-east-2.aws.neon.tech/neondb?connect_timeout=15&pool_timeout=15
+```
+
+## How to use Neon's serverless driver with Prisma (Preview)
+
+The [Neon serverless driver](https://github.com/neondatabase/serverless) is a low-latency Postgres driver for JavaScript and TypeScript that allows you to query data from serverless and edge environments over HTTP or WebSockets in place of TCP.
+
+You can use Prisma along with the Neon serverless driver using a [driver adapter](/concepts/components/database-drivers#driver-adapters) <span class="concept"></span>. A driver adapter allows you to use a different database driver from the default Prisma provides to communicate with your database.
+
+<Admonition>
+
+This feature is available in Preview from Prisma versions 5.4.2 and later.
+
+</Admonition>
+
+To get started, enable the `driverAdapters` Preview feature flag:
+
+```prisma
+generator client {
+  provider        = "prisma-client-js"
+  previewFeatures = ["driverAdapters"]
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+```
+
+Generate Prisma Client:
+
+```sh
+npx prisma generate
+```
+
+Install the Prisma adapter for Neon, Neon serverless driver and `ws` packages:
+
+```sh
+npm install @prisma/adapter-neon @neondatabase/serverless ws
+```
+
+Update your Prisma Client instance:
+
+```ts
+import { Pool, neonConfig } from '@neondatabase/serverless'
+import { PrismaNeon } from '@prisma/adapter-neon'
+import { PrismaClient } from '@prisma/client'
+import dotenv from 'dotenv'
+import ws from 'ws'
+
+dotenv.config()
+neonConfig.webSocketConstructor = ws
+const connectionString = `${process.env.DATABASE_URL}`
+
+const pool = new Pool({ connectionString })
+const adapter = new PrismaNeon(pool)
+const prisma = new PrismaClient({ adapter })
+```
+
+You can then use Prisma Client as you normally would with full-type-safety. Prisma Migrate, introspection, and Prisma Studio will continue working as before, using the connection string defined in the Prisma schema.