apps/blog/content/blog/prisma-2-beta-b7bcl0gd8d8e/index.mdx
We introduced the first Preview version of Prisma 2.0 in June last year. Today, we are excited to launch the first official Beta along with a new website and updated Prisma 2.0 documentation.
Update: Prisma is now ready for production. Read more in the announcement article: The Complete ORM for Node.js & TypeScript.
prisma2 repository to prismaprisma2 CLIprisma/prisma2 repo has been renamed to prisma/prisma (and the former Prisma 1 repo prisma/prisma repo is now called prisma/prisma1).Try the new Prisma Client in 5 minutes by following the Quickstart in the new docs.
The new version of Prisma Client is a modern database access library for Node.js and TypeScript. It can be used as an alternative to traditional ORMs and SQL query builders to read and write data in your database.
To set it up, you need a Prisma schema file and must add Prisma Client as a dependency to your project:
npm install @prisma/client
Prisma Client can be used in any Node.js or TypeScript backend application (including serverless applications and microservices). This can be a REST API, a GraphQL API, a gRPC API, or anything else that needs a database.
The main goal of Prisma Client is to increase the productivity of application developers when working with databases. It achieves this by providing a clean data access API that returns plain JavaScript objects.
This approach enables simpler reasoning about database queries and increases the confidence with predictable (and type-safe) query results. Here are a couple of the major benefits Prisma Client provides:
Learn more about how Prisma makes developers productive in the Introduction or get a taste of the Prisma Client API by checking out the code examples on the website.
The @prisma/client module is different from "conventional" node modules. With conventional node modules (e.g., lodash), the entire package is downloaded into your node_modules directory and only gets updated when you re-install the package.
The @prisma/client node module is different. It is a "facade package" (basically a stub) that doesn't contain any functional code.
While you do need to install it once with npm install @prisma/client, it is likely that the code inside the node_modules/@prisma/client directory changes more often as you're evolving your application. That's because whenever you make changes to the Prisma schema, you need to re-generate Prisma Client, which updates the code in the @prisma/client node module.
Because the node_modules/@prisma/client directory contains some code that is tailored to your project, it is sometimes called a "smart node module":
Auto-completion is an extremely powerful tool for developers. It allows them to explore an API directly in their editor instead of referring to documentation. Prisma Client brings auto-completion to your database queries!
Thanks to Prisma Client's generated types, which are included in the index.d.ts of the @prisma/client module, this feature is available not only to TypeScript developers, but also when developing an application in plain JavaScript.
A major benefit of Prisma Client compared to other ORMs and database tools is that it provides full type safety - even for "partial" database queries (i.e., when you query only the subset of a model's field or include a relation).
As an example, consider this Prisma Client query (you can switch the tab to view the corresponding Prisma models):
const usersWithPartialPosts = await prisma.user.findMany({
include: {
posts: {
select: {
title: true,
published: true,
},
},
},
})
model Post {
id Int @id @default(autoincrement())
title String
content String?
published Boolean @default(false)
author User?
}
model User {
id Int @id @default(autoincrement())
email String @unique
name String?
posts Post[]
}
Note that the resulting usersWithPartialPosts will be statically typed to:
export type User = {
id: number
email: string
name: string | null
}
const usersWithPartialPosts: (User & {
posts: {
title: string
published: boolean
}[]
})[]
This means that TypeScript will catch any errors when you make a typo or accidentally access a property that was not requested from the database!
The best way to get started with Prisma Client is by following the Quickstart in the docs:
Alternatively, you can:
The Prisma 2.0 Beta comes with the following tools:
Try the new Prisma Client in 5 minutes by following the Quickstart in the new docs.
Note: Learn more about the Beta release in the release notes.
prisma2 repository to prismaSince its initial release, the main repository for Prisma 2.0 has been called prisma2.
Because Prisma 2.0 is now the default for developers getting started with Prisma, the Prisma repositories have been renamed as follows:
prisma/prisma2 repository has been renamed to prisma/prismaprisma/prisma repository has been renamed to prisma/prisma1prisma2 CLIDuring the Preview period, the CLI for Prisma 2.0 was invoked using the prisma2 command. With Prisma 2.0 being the default for new developers getting started with Prisma, the command is changed to just prisma. The exist ing prisma command of Prisma 1 is renamed to prisma1.
Also, note that the installation of the npm packages changes:
| Prisma version | Old CLI command | New CLI command | Old npm package name | New npm package name |
|---|---|---|---|---|
| 2.0 | prisma2 | prisma | prisma2 | @prisma/cli |
| 1.X | prisma | prisma1 | prisma | prisma1 |
If you're currently using Prisma 1 with the prisma command, you can keep using it as before. If you want to upgrade to Prisma 2.0, it is recommended to uninstall your current prisma installation and install the new CLI versions locally in the projects where they are needed:
# Remove global installation
npm uninstall -g prisma
# Navigate into Prisma 1 project directory & install locally
cd path/to/prisma-1-project
npm install prisma1 --save-dev
# Invoke `prisma1` by prefixing it with `npx`
npx prisma1
prisma2 npm package is deprecatedThe prisma2 npm package is now deprecated. To prevent confusions during installation, it now outputs the following when you try to install it:
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā
ā The package prisma2 has been renamed to @prisma/cli. ā
ā ā
ā Please uninstall prisma2 from your project or globally. ā
ā Then install @prisma/cli to continue using Prisma 2.0: ā
ā ā
ā # Uninstall old CLI ā
ā npm uninstall prisma2 ā
ā ā
ā # Install new CLI ā
ā npm install @prisma/cli --save-dev ā
ā ā
ā # Invoke via npx ā
ā npx prisma2 --help ā
ā ā
ā Learn more here: https://pris.ly/preview025 ā
ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
First of all, we want to hugely thank all existing Prisma 1 users! š We are deeply grateful for a supportive and active community that has formed on GitHub and Slack!
Prisma 2.0 comes with a number of changes compared to Prisma 1. Here's a high-level overview of the main differences:
prisma deploy).prisma.yml have been merged into the Prisma schema.You can keep accessing specific versions of the Prisma 1 docs by appending the version number to https://www.prisma.io/docs. For example, to view the docs for Prisma version 1.34, you can go to https://v1.prisma.io/docs/1.34/.
The Prisma 1 examples have been moved to the prisma1-examples repository.
Whether or not you should upgrade depends on the context of your project. In general, one major consideration is the fact that Prisma Migrate is still experimental. This means you probably need to make any future adjustments to your database schema using SQL or another migration tool.
Also, note that we will put together an upgrade guide as well as dedicated tooling for the upgrade process over the next weeks. So, if you do want to upgrade despite Prisma Migrate not being ready, it might be worth waiting until these resources are in place.
<Accordions type="single"> <Accordion title="Expand for different upgrade scenarios"> #### I use Prisma 1 with Prisma client and `nexus-prisma`, should I upgrade?It is certainly possible to upgrade a project that's running on Prisma 1 and nexus-prisma to Prisma 2.0.
If you decide to upgrade, be aware that changing your database schema after having upgraded to Prisma 2.0, will require running migrations with SQL or a third-party migration tool. Also, note that the nexus-prisma API changes with Prisma 2.0.
Here is a high-level overview of the steps needed to upgrade:
npm install @prisma/cli --save-devdatasource that points to your Prisma 1 databasenpx prisma introspectnpm install @prisma/clientnpx prisma generatenexus-prisma and adjust your resolvers.Note: You can find your database credentials in the Docker Compose file that you used to deploy the Prisma server. These credentials are needed to compose the connection URL for Prisma 2.0.
nexus-prisma), should I upgrade?It is certainly possible to upgrade a project that's running on Prisma 1.
If you decide to upgrade, be aware that changing your database schema after having upgraded to Prisma 2.0 will require running migrations with SQL or a third-party migration tool. Here is a high-level overview of the steps needed to upgrade:
npm install @prisma/cli --save-devdatasource that points to your Prisma 1 databasenpx prisma introspectnpm install @prisma/clientnpx prisma generateNote: You can find your database credentials in the Docker Compose file that you used to deploy the Prisma server. These credentials are needed to compose the connection URL for Prisma 2.0.
prisma-binding, should I upgrade?It is certainly possible to upgrade a project that's running on Prisma 1 and prisma-binding to Prisma 2.0.
If you decide to upgrade, be aware that changing your database schema after having upgraded to Prisma 2.0 will require running migrations with SQL or a third-party migration tool.
Also, note that the way how your GraphQL resolvers are implemented changes with Prisma 2.0. As Prisma 2.0 doesn't expose a GraphQL API for your database, you can't use the prisma-binding npm package anymore. This is mostly relevant for implementing relations, resolvers for these now need to be implemented on a type level. To learn more about why this is necessary, be sure to read this article about the basics of GraphQL schemas.
Here is a high-level overview of the steps needed to upgrade:
npm install @prisma/cli --save-devdatasource that points to your Prisma 1 databasenpx prisma introspectnpm install @prisma/clientnpx prisma generateprisma-bindingIf you want to switch to a code-first approach, check out GraphQL Nexus.
</Accordions>Note: You can find your database credentials in the Docker Compose file that you used to deploy the Prisma server. These credentials are needed to compose the connection URL for Prisma 2.0.
</Accordion>
We are really excited to finally share the Beta version of Prisma 2.0 and can't wait to see what you all build with it.
If you want to leave feedback, share ideas, create feature requests or submit bug reports, please do so in the (renamed) prisma repository on GitHub and join the (renamed) #prisma2-beta channel on the Prisma Slack!