diff --git a/cSpell.json b/cSpell.json index 64e73a0743..13b402dc94 100644 --- a/cSpell.json +++ b/cSpell.json @@ -55,7 +55,8 @@ "backoff", "Replibyte", "Snaplet", - "Kysely" + "Kysely", + "Turso" ], "ignoreWords": [ "Ania", diff --git a/content/200-concepts/100-components/database-drivers.mdx b/content/200-concepts/100-components/database-drivers.mdx new file mode 100644 index 0000000000..6d7a022377 --- /dev/null +++ b/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) . 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) diff --git a/content/200-concepts/100-components/images/drivers/qe-query-engine-adapter.png b/content/200-concepts/100-components/images/drivers/qe-query-engine-adapter.png new file mode 100644 index 0000000000..068f9c76c5 Binary files /dev/null and b/content/200-concepts/100-components/images/drivers/qe-query-engine-adapter.png differ diff --git a/content/200-concepts/100-components/images/drivers/qe-query-execution-flow.png b/content/200-concepts/100-components/images/drivers/qe-query-execution-flow.png new file mode 100644 index 0000000000..aca500b4fe Binary files /dev/null and b/content/200-concepts/100-components/images/drivers/qe-query-execution-flow.png differ diff --git a/content/300-guides/050-database/850-planetscale.mdx b/content/300-guides/050-database/850-planetscale.mdx index d919317118..5706f7c9e3 100644 --- a/content/300-guides/050-database/850-planetscale.mdx +++ b/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. + + + +This feature is available in Preview from Prisma versions 5.4.2 and later. + + + +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 +``` + + + +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:strongpassword@aws.connect.psdb.cloud/clear_nightsky?sslaccept=strict' +``` + + + +Install the Prisma adapter for PlanetScale, PlanetScale serverless driver and `undici` packages: + +```sh +npm install @prisma/adapter-planetscale @planetscale/database undici +``` + + + +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. + + + +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: diff --git a/content/400-reference/200-api-reference/050-prisma-client-reference.mdx b/content/400-reference/200-api-reference/050-prisma-client-reference.mdx index 557a323f1a..8837c1b33e 100644 --- a/content/400-reference/200-api-reference/050-prisma-client-reference.mdx +++ b/content/400-reference/200-api-reference/050-prisma-client-reference.mdx @@ -376,6 +376,36 @@ const prisma = new PrismaClient({ }) ``` +### adapter + +Defines an instance of a [driver adapter](/concepts/components/drivers#driver-adapters). See also [Database drivers](/concepts/components/drivers) . + + + +This is available from version 5.4.0 and newer behind the `driverAdapters` feature flag. + + + +#### Example + +The example below uses the [Neon driver adapter](/guides/database/neon#how-to-use-the-neon-serverless-driver-with-prisma-preview) + +```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 }) +``` + ### rejectOnNotFound