diff --git a/content/200-orm/200-prisma-client/000-setup-and-configuration/050-databases-connections/200-pgbouncer.mdx b/content/200-orm/200-prisma-client/000-setup-and-configuration/050-databases-connections/200-pgbouncer.mdx index 2a59b1b447..ec68d67ff1 100644 --- a/content/200-orm/200-prisma-client/000-setup-and-configuration/050-databases-connections/200-pgbouncer.mdx +++ b/content/200-orm/200-prisma-client/000-setup-and-configuration/050-databases-connections/200-pgbouncer.mdx @@ -1,16 +1,18 @@ --- title: Configure Prisma Client with PgBouncer metaTitle: Configure Prisma Client with PgBouncer -toc_max_heading_level: 2 --- - - An external connection pooler like PgBouncer holds a connection pool to the database, and proxies incoming client connections by sitting between Prisma Client and the database. This reduces the number of processes a database has to handle at any given time. Usually, this works transparently, but some connection poolers only support a limited set of functionality. One common feature that external connection poolers do not support are named prepared statements, which Prisma ORM uses. For these cases, Prisma ORM can be configured to behave differently. - +:::info + +Looking for an easy, infrastructure-free solution? Try [Prisma Accelerate](https://www.prisma.io/accelerate?utm_source=docs&utm_campaign=pgbouncer-help)! It requires little to no setup and works seamlessly with all databases supported by Prisma ORM. + +Ready to begin? Get started with Prisma Accelerate by clicking [here](https://console.prisma.io?utm_source=docs&utm_campaign=pgbouncer-help). +::: ## PgBouncer diff --git a/content/200-orm/200-prisma-client/100-queries/100-query-optimization-performance.mdx b/content/200-orm/200-prisma-client/100-queries/100-query-optimization-performance.mdx index f8278a4aac..5650052a69 100644 --- a/content/200-orm/200-prisma-client/100-queries/100-query-optimization-performance.mdx +++ b/content/200-orm/200-prisma-client/100-queries/100-query-optimization-performance.mdx @@ -93,7 +93,7 @@ async function getUsers() { } ``` -For serverless development environments with frameworks that use HMR (Hot Module Replacement), ensure you properly handle a [single instance of Prisma in development](/orm/more/help-and-troubleshooting/help-articles/nextjs-prisma-client-dev-practices). +For serverless development environments with frameworks that use HMR (Hot Module Replacement), ensure you properly handle a [single instance of Prisma in development](/orm/more/help-and-troubleshooting/nextjs-help#best-practices-for-using-prisma-client-in-development). ## Solving the n+1 problem diff --git a/content/200-orm/200-prisma-client/500-deployment/400-module-bundlers.mdx b/content/200-orm/200-prisma-client/500-deployment/400-module-bundlers.mdx index 509843fd10..dc471a85bb 100644 --- a/content/200-orm/200-prisma-client/500-deployment/400-module-bundlers.mdx +++ b/content/200-orm/200-prisma-client/500-deployment/400-module-bundlers.mdx @@ -15,5 +15,5 @@ To do so, you can use plugins that let you copy over static assets: | Bundler | Plugin | | :---------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | | Webpack | [`copy-webpack-plugin`](https://github.com/webpack-contrib/copy-webpack-plugin#copy-webpack-plugin) | -| Webpack (with [Next.js monorepo](/orm/more/help-and-troubleshooting/help-articles/nextjs-prisma-client-monorepo)) | [`nextjs-monorepo-workaround-plugin`](https://www.npmjs.com/package/@prisma/nextjs-monorepo-workaround-plugin) | +| Webpack (with [Next.js monorepo](/orm/more/help-and-troubleshooting/nextjs-help#setting-up-prisma-orm-in-a-monorepo)) | [`nextjs-monorepo-workaround-plugin`](https://www.npmjs.com/package/@prisma/nextjs-monorepo-workaround-plugin) | | Parcel | [`parcel-plugin-static-files-copy`](https://github.com/elwin013/parcel-plugin-static-files-copy#readme) | diff --git a/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/600-legacy-migrate.mdx b/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/600-legacy-migrate.mdx index 89b299e25b..272a15e8ad 100644 --- a/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/600-legacy-migrate.mdx +++ b/content/200-orm/300-prisma-migrate/200-understanding-prisma-migrate/600-legacy-migrate.mdx @@ -197,7 +197,7 @@ The following table shows which SQL operations are currently supported by legacy | Create indexes | `CREATE INDEX` | ✔️ | | Cascading deletes | `ON DELETE` | No (workaround: manually add in SQL and introspect) | | Cascading updates | `ON UPDATE` | No | -| Data validation | `CHECK` | No ([workaround](/orm/more/help-and-troubleshooting/help-articles/check-constraints)) | +| Data validation | `CHECK` | No ([workaround](/orm/more/help-and-troubleshooting/check-constraints)) | Note that this table assumes that the operation is also supported by the underlying database. For example, `ENUM` is not supported in SQLite. This means that you also can't use `enum` when using legacy Prisma Migrate. diff --git a/content/200-orm/500-reference/050-prisma-client-reference.mdx b/content/200-orm/500-reference/050-prisma-client-reference.mdx index cd804ec218..9c3755e365 100644 --- a/content/200-orm/500-reference/050-prisma-client-reference.mdx +++ b/content/200-orm/500-reference/050-prisma-client-reference.mdx @@ -3502,7 +3502,7 @@ const result = await prisma.user.update({ - From version 4.3.0, you can also use these operators to compare _fields_ in the same model [with the `.fields` property](#compare-columns-in-the-same-table). -- In versions before 4.3.0, you can compare fields in the same model [with raw queries](/orm/more/help-and-troubleshooting/help-articles/comparing-columns-through-raw-queries). +- In versions before 4.3.0, you can compare fields in the same model [with raw queries](/orm/more/help-and-troubleshooting/comparing-columns-through-raw-queries). @@ -5525,7 +5525,7 @@ This feature was moved to general availability in version 5.0.0 and was availabl -In the following situations, you must [use raw queries to compare columns in the same table](/orm/more/help-and-troubleshooting/help-articles/comparing-columns-through-raw-queries): +In the following situations, you must [use raw queries to compare columns in the same table](/orm/more/help-and-troubleshooting/comparing-columns-through-raw-queries): - If you use a version earlier than 4.3.0 - If you want to use a unique filter, such as [`findUnique`](#findunique) or [`findUniqueOrThrow`](#finduniqueorthrow) diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/050-creating-bug-reports.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/050-creating-bug-reports.mdx deleted file mode 100644 index f36c2329b1..0000000000 --- a/content/200-orm/800-more/600-help-and-troubleshooting/050-creating-bug-reports.mdx +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: 'Creating bug reports' -metaTitle: 'Creating bug reports for Prisma ORM' -metaDescription: 'This page explains best practices for creating bug reports for Prisma ORM, including sharing additional debugging output and other recommendations.' -toc_max_heading_level: 2 ---- - -## Overview - -You can help us improve Prisma ORM by creating **bug reports**. When creating a bug report, it's important that you include as much information as possible about your issue. That way, it's easier to reproduce. - -Note that you can also create **feature requests** or ask a **question** via the issue templates on GitHub. - -## Where to open the bug report on GitHub? - -Prisma ORM's tools are spread across different repositories in the [`prisma`](https://github.com/prisma/) organization on GitHub. You can open a new issue in the repo of the respective tool. - -If you're unsure where to open the GitHub issue, you can use the main [`prisma/prisma`](https://github.com/prisma/prisma) repo as a default. Our engineering team is regularly triaging new issues and will move the issue to another repo if necessary. - -## Ideal scenario: Share standalone repository with reproduction - -In an ideal scenario, you're able to reproduce the bug in an isolated environment and put it into a GitHub repository that you can share in your report. That way, we already have a reproduction and the problem can be tackled without further triaging. - -This [StackOverflow guide](https://stackoverflow.com/help/minimal-reproducible-example) has a lot of helpful information for creating minimal, reproducible examples. - -## Best practices for writing a bug report - -If you don't have the time to create a full reproduction of the issue, please include as much information as possible about the problem. The [bug report template](https://pris.ly/prisma-prisma-bug-report) helps you with that. - -### Include logging and debugging output - -Please make sure to include _any_ [logging](/orm/prisma-client/observability-and-logging/logging) and [debugging](/orm/prisma-client/debugging-and-troubleshooting/debugging) output in the issue that may help to identify the problem. - -**Setting the `DEBUG` env var** - -To get additional output from Prisma ORM, you can set `DEBUG` to `*`: - -```terminal -export DEBUG="*" -``` - -**Print logs of Prisma Client** - -You can enable additional logs in Prisma Client by instantiating it with the `log` option: - -```ts -const prisma = new PrismaClient({ log: ['query', 'info', 'warn'] }) -``` - -### Include a bug description, reproduction and expected behavior - -When describing the bug, it's helpful to include the following information: - -- A clear and concise description of what the bug is -- Steps to reproduce the bug -- A clear and concise description of what you expected to happen -- Screenshots (if applicable) - -
- -Expand for an example for a hypothetical bug report - -**Example** - -**Describe the bug** - -`@unique` attribute on `email` field doesn't work on my model. I can create duplicate records with the same `email`. - -**To reproduce**: - -I have this Prisma schema (removed all unnecessary models and fields): - -```prisma -model User { - id Int @id @default(autoincrement()) - email String @unique -} -``` - -I then run `prisma generate` to generate Prisma Client. - -I then have a Node.js script that creates two `User` records with the same `email`: - -```ts -import { PrismaClient } from '@prisma/client' - -const prisma = new PrismaClient() - -// A `main` function so that we can use async/await -async function main() { - const user1 = await prisma.create({ - data: { email: 'alice@prisma.io' }, - }) - const user2 = await prisma.create({ - data: { email: 'alice@prisma.io' }, - }) - console.log(user1, user2) -} - -main() - .then(async () => { - await prisma.$disconnect() - }) - .catch(async (e) => { - console.error(e) - await prisma.$disconnect() - process.exit(1) - }) -``` - -**Expected behavior** - -I expected an exception when trying to create `user2` with the same `email` as `user1` because this violates the `@unique` constraint defined in the Prisma schema. - -
- -### Include environment and setup information - -Please include any information about your environment and setup. Specifically it's important to include: - -- Which **operating system** you use (e.g. macOS, Windows, Debian, CentOS, ...) -- Which **database** you use with Prisma ORM (PostgreSQL, MySQL, MariaDB, SQLite or Microsoft SQL Server) -- Which **version of Prisma ORM** you use (run `prisma -v` to see your Prisma ORM version) -- Which **version of Node.js** you use (run `node -v` to see your Node.js version) - -Here's an example of what this could look like in your bug report: - -- OS: macOS Catalina 10.15.7 -- Database: PostgreSQL v11 -- Node.js version: `v14.16.1` -- Prisma ORM version: - -``` -prisma : 2.22.0 -@prisma/client : Not found -Current platform : darwin -Query Engine : query-engine 60cc71d884972ab4e897f0277c4b84383dddaf6c (at ../../../../../.npm/_npx/31227/lib/node_modules/prisma/node_modules/@prisma/engines/query-engine-darwin) -Migration Engine : migration-engine-cli 60cc71d884972ab4e897f0277c4b84383dddaf6c (at ../../../../../.npm/_npx/31227/lib/node_modules/prisma/node_modules/@prisma/engines/migration-engine-darwin) -Format Binary : prisma-fmt 60cc71d884972ab4e897f0277c4b84383dddaf6c (at ../../../../../.npm/_npx/31227/lib/node_modules/prisma/node_modules/@prisma/engines/prisma-fmt-darwin) -Default Engines Hash : 60cc71d884972ab4e897f0277c4b84383dddaf6c -Studio : 0.379.0 -``` - -Additionally, you can use the [`prisma debug`](/orm/reference/prisma-cli-reference#debug) command to retrieve debugging information. The `prisma debug` command provides debugging information that compliments the output of the `prisma -v` command. The information includes [environment variables](/orm/reference/environment-variables-reference) used for Prisma Client, Prisma Migrate, Prisma CLI, and Prisma Studio. - - - -The `prisma debug` command is available from version 5.6.0 and newer. If you're using an older version of Prisma ORM, you can use this command by running: - -```terminal -npx prisma@latest debug -``` - - - -### Include relevant Prisma ORM info (e.g. the Prisma schema, Prisma Client queries, ...) - -To help us reproduce your problem, it is helpful to include your Prisma schema in the bug report. **Please remove any database credentials before sharing your Prisma schema in a bug report**. If you're sure about which parts of the schema is causing the issue, please strip out the irrelevant parts of it and only show the parts that are related to the problem. If you're not sure, please include your entire schema. - -If you have an issue with Prisma Client, please also include which Prisma Client query is causing the issue. diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/100-autocompletion-in-graphql-resolvers-with-js.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/100-autocompletion-in-graphql-resolvers-with-js.mdx similarity index 97% rename from content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/100-autocompletion-in-graphql-resolvers-with-js.mdx rename to content/200-orm/800-more/600-help-and-troubleshooting/100-autocompletion-in-graphql-resolvers-with-js.mdx index b0fcd231c4..912ecb7d92 100644 --- a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/100-autocompletion-in-graphql-resolvers-with-js.mdx +++ b/content/200-orm/800-more/600-help-and-troubleshooting/100-autocompletion-in-graphql-resolvers-with-js.mdx @@ -27,7 +27,7 @@ filterPosts: (parent, args, ctx) => { Now whenever you type `ctx.` VS Code will provide unnecessary options in the autocomplete which is undesirable. -![Unwanted autocomplete values by VSCode](./unwanted-autocomplete-values-in-vscode.png) +![Unwanted autocomplete values by VSCode](/img/orm/unwanted-autocomplete-values-in-vscode.png) VS Code doesn't know the _type_ of the `context` object so it can't provide any intellisense for it, which is why unwanted suggestions are displayed. @@ -69,7 +69,7 @@ This will tell VS Code that the `context` has a property named `prisma` and the And voilà, autocompletion in plain JavaScript. -![The correct parameters for context are obtained](./prisma-autocompletion-in-js.png) +![The correct parameters for context are obtained](/img/orm/prisma-autocompletion-in-js.png) The final file should look something like: diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/400-nextjs-prisma-client-dev-practices.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/400-nextjs-prisma-client-dev-practices.mdx deleted file mode 100644 index 7d2a926348..0000000000 --- a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/400-nextjs-prisma-client-dev-practices.mdx +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: 'Best practice for instantiating Prisma Client with Next.js' -metaTitle: 'Best practice for instantiating Prisma Client with Next.js' -metaDescription: 'Best practice for instantiating Prisma Client with Next.js' ---- - - - -:::tip - -If you want to learn how to build an app with Next.js and Prisma ORM, check out this comprehensive [video tutorial](https://www.youtube.com/watch?v=QXxy8Uv1LnQ&ab_channel=ByteGrad). - -::: - -## Problem - -Many users have come across this warning while working with [Next.js](https://nextjs.org/) in development: - -``` -warn(prisma-client) There are already 10 instances of Prisma Client actively running. -``` - -There's a related [discussion](https://github.com/prisma/prisma/discussions/4399) and [issue](https://github.com/prisma/prisma/issues/5103) for the same. - -In development, the command `next dev` clears Node.js cache on run. This in turn initializes a new `PrismaClient` instance each time due to hot reloading that creates a connection to the database. This can quickly exhaust the database connections as each `PrismaClient` instance holds its own connection pool. - -## Solution - -The solution in this case is to instantiate a single instance `PrismaClient` and save it on the [`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) object. Then we keep a check to only instantiate `PrismaClient` if it's not on the `globalThis` object otherwise use the same instance again if already present to prevent instantiating extra `PrismaClient` instances. - -```ts file=db.ts -import { PrismaClient } from '@prisma/client' - -const prismaClientSingleton = () => { - return new PrismaClient() -} - -declare const globalThis: { - prismaGlobal: ReturnType; -} & typeof global; - -const prisma = globalThis.prismaGlobal ?? prismaClientSingleton() - -export default prisma - -if (process.env.NODE_ENV !== 'production') globalThis.prismaGlobal = prisma -``` - -You can extend Prisma Client using a Prisma Client extension by appending the `$extends` client method when instantiating Prisma Client as follows: - -```ts -import { PrismaClient } from '@prisma/client' - -const prismaClientSingleton = () => { - return new PrismaClient().$extends({ - result: { - user: { - fullName: { - needs: { firstName: true, lastName: true }, - compute(user) { - return `${user.firstName} ${user.lastName}` - }, - }, - }, - }, - }) -} -``` - -After creating this file, you can now import the extended `PrismaClient` instance anywhere in your Next.js `pages` as follows: - -```ts -// e.g. in `pages/index.tsx` -import prisma from './db' - -export const getServerSideProps = async () => { - const posts = await prisma.post.findMany() - - return { props: { posts } } -} -``` diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/425-nextjs-prisma-client-monorepo.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/425-nextjs-prisma-client-monorepo.mdx deleted file mode 100644 index 04208caf71..0000000000 --- a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/425-nextjs-prisma-client-monorepo.mdx +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: 'Using Prisma Client in a Next.js project in a monorepo setup' -metaTitle: 'Using Prisma Client in a Next.js project in a monorepo setup' -metaDescription: 'Using Prisma Client in a Next.js project in a monorepo setup' ---- - - - -:::tip - -If you want to learn how to build an app with Next.js and Prisma ORM, check out this comprehensive [video tutorial](https://www.youtube.com/watch?v=QXxy8Uv1LnQ&ab_channel=ByteGrad). - -::: - - -## Problem - -If you use Prisma Client in a [Next.js](https://nextjs.org/) application within a monorepo, you may run into an error that looks similar to: - -```terminal no-copy wrap -Prisma Client could not locate the Query Engine for runtime "debian-openssl-3.0.x". - -We detected that you are using Next.js, learn how to fix this: https://pris.ly/d/engine-not-found-nextjs. - -This is likely caused by tooling that has not copied "libquery_engine-debian-openssl-3.0.x.so.node" to the deployment folder. -Ensure that you ran \`prisma generate\` and that "libquery_engine-debian-openssl-3.0.x.so.node" has been copied to "generated/client". - -We would appreciate if you could take the time to share some information with us. -Please help us by answering a few questions: https://pris.ly/engine-not-found-tooling-investigation -``` - -or: - -```terminal no-copy wrap -Prisma Client could not locate the Query Engine for runtime "debian-openssl-3.0.x". - -We detected that you are using Next.js, learn how to fix this: https://pris.ly/d/engine-not-found-nextjs. - -This is likely caused by a bundler that has not copied "libquery_engine-debian-openssl-3.0.x.so.node" next to the resulting bundle. -Ensure that "libquery_engine-debian-openssl-3.0.x.so.node" has been copied next to the bundle or in "generated/client". - -We would appreciate if you could take the time to share some information with us. -Please help us by answering a few questions: https://pris.ly/engine-not-found-bundler-investigation -``` - -Assume you have a monorepo with the following structure: - -``` -. -├── packages -│ ├── db -│ │ ├── index.ts -│ │ ├── node_modules -│ │ ├── package.json -│ │ └── prisma -│ │ ├── client // <-- Custom output location for the generated Prisma Client -│ │ │ ├── index.js -│ │ │ ├── libquery_engine-debian-openssl-1.1.x.so.node // engine to be copied -│ │ │ └── schema.prisma // schema to be copied -│ │ └── schema.prisma -│ └── service/ -│ ├── pages/ -│ │ └── api/ -│ │ └── test.js -│ ├── next.config.js -│ └── package.json -├── pnpm-workspace.yaml -├── package.json -└── vercel.json -``` - -The file tree above shows a monorepo contained in a `packages` folder. Inside, there are two packages: - -- `db`: Contains the generated Prisma Client in a custom output location named `client`. `index.ts` at the root of this package exports the instantiated Prisma Client. -- `service`: Contains a Next.js application. The `test.js` API route uses the Prisma Client instance provided by the `db` package. - -The errors mentioned above occur as a result of a bundling problem during Next.js's bundling process. The Query Engine file(s) is expected to be found next to the generated Prisma Client. The bundling process, however, does not copy over those files to the output location of the bundle. - - - -For a more detailed explanation of exactly what is going wrong during the bundling process, please refer to [this issue](https://github.com/vercel/next.js/issues/46070) we opened in the Next.js GitHub repository. - - - -## Solution - -To work around this issue, you can use a custom Webpack plugin we created that correctly copies the files Prisma Client needs to their correct location. - -To use this plugin, first install the package: - -```terminal copy -npm install -D @prisma/nextjs-monorepo-workaround-plugin -``` - -You can then import the plugin into your `next.config.js` file and use it in `config.plugins`. For example: - -```js copy -const { PrismaPlugin } = require('@prisma/nextjs-monorepo-workaround-plugin') - -module.exports = { - webpack: (config, { isServer }) => { - if (isServer) { - config.plugins = [...config.plugins, new PrismaPlugin()] - } - - return config - }, -} -``` - -Alternatively, if you are using `next.config.mjs`, you may alter the file as such: - -```js file=next.config.mjs -import { PrismaPlugin } from '@prisma/nextjs-monorepo-workaround-plugin' - -const nextConfig = { - webpack: (config, { isServer }) => { - if (isServer) { - config.plugins = [...config.plugins, new PrismaPlugin()] - } - - return config - } -} - -export default nextConfig -``` diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/430-nextjs-prisma-client-dynamic.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/430-nextjs-prisma-client-dynamic.mdx deleted file mode 100644 index 820b00a96c..0000000000 --- a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/430-nextjs-prisma-client-dynamic.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: 'Best practices for using Prisma Client with Next.js and Next.js Data Cache' -metaTitle: 'Best practices for using Prisma Client with Next.js and Next.js Data Cache' -metaDescription: 'Learn best practices to avoid issues with route caching in Next.js' ---- - -## Problem - -When deploying a Next.js app, you may run into an issue where your queries are not updating or displaying the correct content. Or, you may find that it takes a long time for newly created objects to show up in your queries. - -In these cases, you are most likely seeing data persisted in the [Next.js Data Cache](https://nextjs.org/docs/app/building-your-application/caching#data-cache). Any `fetch` request has its result cached by default, leading to possibly unwanted results as Prisma uses `fetch` internally. - -## Solution - -To opt-out of the Next.js Data Cache, you can [disable caching for a specific route](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamic) using the `"force-dynamic"` config option so that up to date data is always returned and no caching happens. - -You can add `"force-dynamic"` like this: - -```ts -import { NextRequest, NextResponse } from 'next/server' -import prisma from './db' - -export const dynamic = 'force-dynamic' - -export async function GET(request: NextRequest, response: NextResponse) { - // your code would go here -} -``` diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/index.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/index.mdx deleted file mode 100644 index ff81c33f50..0000000000 --- a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/index.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 'Help articles' -metaTitle: 'Help articles' -metaDescription: 'Common problems and how to solve them.' -hidePage: false -hide_table_of_contents: true ---- - - - -This section provides a number of common problems that developers might encounter when using Prisma ORM and provides short, practical solutions to resolve them. - - - -## Help articles - - diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/200-working-with-many-to-many-relations.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/200-working-with-many-to-many-relations.mdx similarity index 100% rename from content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/200-working-with-many-to-many-relations.mdx rename to content/200-orm/800-more/600-help-and-troubleshooting/200-working-with-many-to-many-relations.mdx diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/300-implicit-to-explicit-conversion.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/300-implicit-to-explicit-conversion.mdx similarity index 100% rename from content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/300-implicit-to-explicit-conversion.mdx rename to content/200-orm/800-more/600-help-and-troubleshooting/300-implicit-to-explicit-conversion.mdx diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/400-nextjs-help.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/400-nextjs-help.mdx new file mode 100644 index 0000000000..678ca28249 --- /dev/null +++ b/content/200-orm/800-more/600-help-and-troubleshooting/400-nextjs-help.mdx @@ -0,0 +1,111 @@ +--- +title: "Comprehensive Guide to Using Prisma ORM with Next.js" +sidebar_label: "Using Prisma ORM with Next.js" +description: "Learn best practices, monorepo strategies, and dynamic usage techniques for Prisma ORM in Next.js applications." +tags: + - Prisma + - Next.js + - ORM + - Monorepo + - Dynamic Usage + - Best Practices +--- + +Prisma ORM and Next.js form a powerful combination for building modern, server-side rendered, and API-driven web applications. This guide consolidates various tips and strategies to help you maximize their potential. Whether you’re looking for best practices, monorepo setup guidance, or strategies for dynamic usage, we’ve got you covered. + +--- + +## Best practices for using Prisma Client in development + +### Avoid multiple Prisma Client instances + +When developing a Next.js application, one common issue is accidentally creating multiple instances of the Prisma Client. This often occurs due to Next.js’s hot-reloading feature in development. + +#### Why this happens + +Next.js’s hot-reloading feature reloads modules frequently to reflect code changes instantly. However, this can lead to multiple instances of Prisma Client being created, which consumes resources and might cause unexpected behavior. + +#### Recommended solution + +To avoid this, create a single Prisma Client instance by using a global variable: + +```typescript +// lib/prisma.ts +import { PrismaClient } from "@prisma/client"; + +const globalForPrisma = global as unknown as { prisma: PrismaClient }; + +export const prisma = + globalForPrisma.prisma || new PrismaClient(); + +if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma; +``` + +Using this approach ensures that only one instance of Prisma Client exists, even during hot-reloading in development. + +--- + +## Setting Up Prisma ORM in a Monorepo + +### Challenges of using Prisma ORM in monorepos + +Monorepos allow multiple projects to share code and dependencies, making them a popular choice for modern development. However, using Prisma ORM in a monorepo can present challenges related to dependency resolution and schema management. + +#### Key issues + +1. **Dependency Resolution**: Multiple packages in a monorepo might lead to conflicts if they use different version of Prisma ORM. +2. **Schema Centralization**: Managing a single Prisma Schema across multiple projects can be complex. + +#### Best practices for monorepo integration + +- **Centralize the Prisma Schema**: Place the `schema.prisma` file in a shared package, such as `@myorg/db`, to ensure consistency. +- **Install Dependencies in the Root**: Avoid version conflicts by installing Prisma ORM as a dependency at the root of the monorepo. +- **Use NPM Scripts for Generation**: + +```json +{ + "scripts": { + "prisma:generate": "prisma generate --schema=./packages/db/schema.prisma" + } +} +``` + +This approach keeps your Prisma Schema and generated client in sync across all projects in the monorepo. + +--- + +## Dynamic usage of Prisma Client in Next.js + +### Handling dynamic scenarios + +Dynamic use cases, such as working with tenant-specific databases, require additional consideration when using Prisma ORM with Next.js. + +#### Problem + +Each tenant might have its own database, necessitating the creation of separate Prisma Clients at runtime. This can be complex in Next.js due to its hybrid rendering model. + +#### Solution + +Use a factory function to dynamically create Prisma Clients based on tenant-specific configurations: + +```typescript +// lib/prismaDynamic.ts +import { PrismaClient } from "@prisma/client"; + +type TenantConfig = { + databaseUrl: string; +}; + +export function createPrismaClient(config: TenantConfig): PrismaClient { + return new PrismaClient({ + datasources: { + db: { + url: config.databaseUrl, + }, + }, + }); +} +``` + +Ensure that you manage the lifecycle of dynamically created Prisma Clients to avoid resource exhaustion. + diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/450-pkg-issue.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/450-pkg-issue.mdx similarity index 100% rename from content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/450-pkg-issue.mdx rename to content/200-orm/800-more/600-help-and-troubleshooting/450-pkg-issue.mdx diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/500-comparing-columns-through-raw-queries.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/500-comparing-columns-through-raw-queries.mdx similarity index 100% rename from content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/500-comparing-columns-through-raw-queries.mdx rename to content/200-orm/800-more/600-help-and-troubleshooting/500-comparing-columns-through-raw-queries.mdx diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/600-vercel-caching-issue.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/600-vercel-caching-issue.mdx similarity index 94% rename from content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/600-vercel-caching-issue.mdx rename to content/200-orm/800-more/600-help-and-troubleshooting/600-vercel-caching-issue.mdx index f74a73fbde..5061c15778 100644 --- a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/600-vercel-caching-issue.mdx +++ b/content/200-orm/800-more/600-help-and-troubleshooting/600-vercel-caching-issue.mdx @@ -96,8 +96,8 @@ Another way to configure `prisma generate` to be run on every deployment is to a Within your project's dashboard, go to the **Settings** tab and find the **General** section. In that section you will find a box labeled **Build & Development Settings** that contains an input field named **Build Command**: -![Vercel project dashboard's Build Command setting](./vercel-ui-build-command.png) +![Vercel project dashboard's Build Command setting](/img/orm/vercel-ui-build-command.png) Within that field, prepend `prisma generate` to the existing script: -![Vercel project dashboard's Build Command setting filled](./vercel-ui-build-command-filled.png) +![Vercel project dashboard's Build Command setting filled](/img/orm/vercel-ui-build-command-filled.png) diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/700-netlify-caching-issue.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/700-netlify-caching-issue.mdx similarity index 95% rename from content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/700-netlify-caching-issue.mdx rename to content/200-orm/800-more/600-help-and-troubleshooting/700-netlify-caching-issue.mdx index 41971278c9..663610ef68 100644 --- a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/700-netlify-caching-issue.mdx +++ b/content/200-orm/800-more/600-help-and-troubleshooting/700-netlify-caching-issue.mdx @@ -98,8 +98,8 @@ Within your project's dashboard, go to the **Site Settings** tab and find the ** Find the box in that section labeled **Build settings** and click the **Edit settings** button: -![Netlify project dashboard's Build settings button](./netlify-edit-settings.png) +![Netlify project dashboard's Build settings button](/img/orm/netlify-edit-settings.png) Clicking that button will open a form with various fields. Find the **Build command** field and prepend `prisma generate` to the existing script: -![Netlify project dashboard's Build command setting filled](./netlify-build-command-filled.png) +![Netlify project dashboard's Build command setting filled](/img/orm/netlify-build-command-filled.png) diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/800-check-constraints.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/800-check-constraints.mdx similarity index 100% rename from content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/800-check-constraints.mdx rename to content/200-orm/800-more/600-help-and-troubleshooting/800-check-constraints.mdx diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/900-prisma-nuxt-module.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/900-prisma-nuxt-module.mdx similarity index 98% rename from content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/900-prisma-nuxt-module.mdx rename to content/200-orm/800-more/600-help-and-troubleshooting/900-prisma-nuxt-module.mdx index 11ab0e2c89..8b4dcf23f9 100644 --- a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/900-prisma-nuxt-module.mdx +++ b/content/200-orm/800-more/600-help-and-troubleshooting/900-prisma-nuxt-module.mdx @@ -32,7 +32,7 @@ This module provides several features to streamline the setup and usage of Prism
:::warning - If you're using `pnpm`, make sure to hoist Prisma dependencies. Follow the steps [here](/orm/more/help-and-troubleshooting/help-articles/prisma-nuxt-module#prisma-studio-not-opening-with-pnpm) for detailed instructions. + If you're using `pnpm`, make sure to hoist Prisma dependencies. Follow the [Prisma studio steps](#prisma-studio-not-opening-with-pnpm) for detailed instructions. ::: diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/index.mdx b/content/200-orm/800-more/600-help-and-troubleshooting/index.mdx index edba629f3b..c97a1142a9 100644 --- a/content/200-orm/800-more/600-help-and-troubleshooting/index.mdx +++ b/content/200-orm/800-more/600-help-and-troubleshooting/index.mdx @@ -1,10 +1,13 @@ --- -title: 'Help & troubleshooting' -metaTitle: 'Help & troubleshooting' -metaDescription: 'Help & troubleshooting in Prisma ORM projects.' +title: 'Help articles' +metaTitle: 'Help articles' +metaDescription: 'Common problems and how to solve them.' +hidePage: false hide_table_of_contents: true --- -## In this section +This section provides a number of common problems that developers might encounter when using Prisma ORM and provides short, practical solutions to resolve them. + +## Help articles diff --git a/static/_redirects b/static/_redirects index f41444b72c..d14688faf3 100644 --- a/static/_redirects +++ b/static/_redirects @@ -538,6 +538,23 @@ /accelerate/what-is-accelerate /docs/accelerate/ /pulse/what-is-pulse /docs/pulse/ /accelerate/limitations /docs/accelerate/known-limitations +/getting-started/quickstart /docs/getting-started/quickstart-sqlite + +# move help articles up a level +/orm/more/help-and-troubleshooting/creating-bug-reports https://github.com/prisma/prisma/issues/new?assignees=&labels=kind/bug&projects=&template=bug_report.yml +/orm/more/help-and-troubleshooting/help-articles/autocompletion-in-graphql-resolvers-with-js /docs/orm/more/help-and-troubleshooting/autocompletion-in-graphql-resolvers-with-js +/orm/more/help-and-troubleshooting/help-articles/nextjs-prisma-client-dev-practices /docs/orm/more/help-and-troubleshooting/nextjs-help +/orm/more/help-and-troubleshooting/help-articles/nextjs-prisma-client-monorepo /docs/orm/more/help-and-troubleshooting/nextjs-help +/orm/more/help-and-troubleshooting/help-articles/nextjs-prisma-client-dynamic /docs/orm/more/help-and-troubleshooting/nextjs-help +/orm/more/help-and-troubleshooting/help-articles /docs/orm/more/help-and-troubleshooting +/orm/more/help-and-troubleshooting/help-articles/working-with-many-to-many-relations /docs/orm/more/help-and-troubleshooting/working-with-many-to-many-relations +/orm/more/help-and-troubleshooting/help-articles/implicit-to-explicit-conversion /docs/orm/more/help-and-troubleshooting/implicit-to-explicit-conversion +/orm/more/help-and-troubleshooting/help-articles/pkg-issue /docs/orm/more/help-and-troubleshooting/pkg-issue +/orm/more/help-and-troubleshooting/help-articles/comparing-columns-through-raw-queries /docs/orm/more/help-and-troubleshooting/comparing-columns-through-raw-queries +/orm/more/help-and-troubleshooting/help-articles/vercel-caching-issue /docs/orm/more/help-and-troubleshooting/vercel-caching-issue +/orm/more/help-and-troubleshooting/help-articles/netlify-caching-issue /docs/orm/more/help-and-troubleshooting/netlify-caching-issue +/orm/more/help-and-troubleshooting/help-articles/check-constraints /docs/orm/more/help-and-troubleshooting/check-constraints +/orm/more/help-and-troubleshooting/help-articles/prisma-nuxt-module /docs/orm/more/help-and-troubleshooting/prisma-nuxt-module ### Dynamic redirects ### /faq/* https://v1.prisma.io/docs/1.34/faq/:splat @@ -583,5 +600,3 @@ /getting-started/setup-prisma/start-from-scratch/mongodb/next-steps-* /docs/getting-started/setup-prisma/start-from-scratch/mongodb/next-steps /getting-started/setup-prisma/add-to-existing-project/relational-databases/next-steps-* /docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/next-steps /getting-started/setup-prisma/add-to-existing-project/mongodb/next-steps-* /docs/getting-started/setup-prisma/add-to-existing-project/mongodb/next-steps - -/getting-started/quickstart /docs/getting-started/quickstart-sqlite diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/netlify-build-command-filled.png b/static/img/orm/netlify-build-command-filled.png similarity index 100% rename from content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/netlify-build-command-filled.png rename to static/img/orm/netlify-build-command-filled.png diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/netlify-edit-settings.png b/static/img/orm/netlify-edit-settings.png similarity index 100% rename from content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/netlify-edit-settings.png rename to static/img/orm/netlify-edit-settings.png diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/prisma-autocompletion-in-js.png b/static/img/orm/prisma-autocompletion-in-js.png similarity index 100% rename from content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/prisma-autocompletion-in-js.png rename to static/img/orm/prisma-autocompletion-in-js.png diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/unwanted-autocomplete-values-in-vscode.png b/static/img/orm/unwanted-autocomplete-values-in-vscode.png similarity index 100% rename from content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/unwanted-autocomplete-values-in-vscode.png rename to static/img/orm/unwanted-autocomplete-values-in-vscode.png diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/vercel-ui-build-command-filled.png b/static/img/orm/vercel-ui-build-command-filled.png similarity index 100% rename from content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/vercel-ui-build-command-filled.png rename to static/img/orm/vercel-ui-build-command-filled.png diff --git a/content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/vercel-ui-build-command.png b/static/img/orm/vercel-ui-build-command.png similarity index 100% rename from content/200-orm/800-more/600-help-and-troubleshooting/100-help-articles/vercel-ui-build-command.png rename to static/img/orm/vercel-ui-build-command.png