prisma/prisma

prisma/prisma

README

Prisma


Quickstart •  Website •  Docs •  Examples •  Blog •  Slack •  Twitter •  Prisma 1

What is Prisma?


Prisma is a next-generation ORMthat consists of these tools:

Prisma Client : Auto-generated and type-safe query builder for Node.js & TypeScript
Prisma Migrate : Declarative data modeling & migration system
Prisma Studio : GUI to view and edit data in your database

Prisma Client can be used in anyNode.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.

Are you looking for Prisma 1? The Prisma 1 repository has been renamed to prisma/prisma1.


Getting started


The fastest way to get started with Prisma is by following the Quickstart (5 min).

The Quickstart is based on a preconfigured SQLite database. You can also get started with your own database (PostgreSQL and MySQL) by following one of these guides:

Add Prisma to an existing project
Set up a new project with Prisma from scratch

How does Prisma work


This section provides a high-level overview of how Prisma works and its most important technical components. For a more thorough introduction, visit the Prisma documentation.

The Prisma schema


Every project that uses a tool from the Prisma toolkit starts with a Prisma schema file. The Prisma schema allows developers to define their application modelsin an intuitive data modeling language. It also contains the connection to a database and defines a generator:

  1. ``` prisma
  2. // Data source
  3. datasource db {
  4.   provider = "postgresql"
  5.   url      = env("DATABASE_URL")
  6. }

  8. // Generator
  9. generator client {
  10.   provider = "prisma-client-js"
  11. }

  13. // Data model
  14. model Post {
  15.   id        Int     @id @default(autoincrement())
  16.   title     String
  17.   content   String?
  18.   published Boolean @default(false)
  19.   author    User?   @relation(fields:  [authorId], references: [id])
  20.   authorId  Int?
  21. }

  23. model User {
  24.   id    Int     @id @default(autoincrement())
  25.   email String  @unique
  26.   name  String?
  27.   posts Post[]
  28. }
  29. ```

In this schema, you configure three things:

Data source: Specifies your database connection (via an environment variable)
Generator: Indicates that you want to generate Prisma Client
Data model: Defines your application models

The Prisma data model


On this page, the focus is on the data model. You can learn more about Data sources and Generators on the respective docs pages.

Functions of Prisma models


The data model is a collection of models. A model has two major functions:

Represent a table in the underlying database
Provide the foundation for the queries in the Prisma Client API

Getting a data model


There are two major workflows for "getting" a data model into your Prisma schema:

Generate the data model from introspecting a database
Manually writing the data model and mapping it to the database with Prisma Migrate

Once the data model is defined, you can generate Prisma Client which will expose CRUD and more queries for the defined models. If you're using TypeScript, you'll get full type-safety for all queries (even when only retrieving the subsets of a model's fields).

Accessing your database with Prisma Client


Generating Prisma Client


The first step when using Prisma Client is installing its npm package:

  1. ``` sh
  2. npm install @prisma/client

  4. ```

Note that the installation of this package invokes the prisma generate command which reads your Prisma schema and generatesthe Prisma Client code. The code will be located in node_modules/.prisma/client, which is exported by node_modules/@prisma/client/index.d.ts.

After you change your data model, you'll need to manually re-generate Prisma Client to ensure the code inside node_modules/.prisma/client get updated:

  1. ``` sh
  2. npx prisma generate

  4. ```

Refer to the documentation for more information about "generating the Prisma client".

Using Prisma Client to send queries to your database


Once the Prisma Client is generated, you can import it in your code and send queries to your database. This is what the setup code looks like.

Import and instantiate Prisma Client

You can import and instantiate Prisma Client as follows:

  1. ``` ts
  2. import { PrismaClient } from '@prisma/client'

  4. const prisma = new PrismaClient()
  5. ```

or

  1. ``` js
  2. const { PrismaClient } = require('@prisma/client')

  4. const prisma = new PrismaClient()
  5. ```

Now you can start sending queries via the generated Prisma Client API, here are few sample queries. Note that all Prisma Client queries return plain old JavaScript objects.

Learn more about the available operations in the Prisma Client docs or watch this demo video (2 min).

Retrieve all User records from the database

  1. ``` ts
  2. // Run inside `async` function
  3. const allUsers = await prisma.user.findMany()
  4. ```

Include the posts relation on each returned User object

  1. ``` ts
  2. // Run inside `async` function
  3. const allUsers = await prisma.user.findMany({
  4.   include: { posts: true },
  5. })
  6. ```

Filter all Post records that contain "prisma"

  1. ``` ts
  2. // Run inside `async` function
  3. const filteredPosts = await prisma.post.findMany({
  4.   where: {
  5.     OR: [{ title: { contains: 'prisma' } }, { content: { contains: 'prisma' } }],
  6.   },
  7. })
  8. ```

Create a new User and a new Post record in the same query

  1. ``` ts
  2. // Run inside `async` function
  3. const user = await prisma.user.create({
  4.   data: {
  5.     name: 'Alice',
  6.     email: 'alice@prisma.io',
  7.     posts: {
  8.       create: { title: 'Join us for Prisma Day 2021' },
  9.     },
  10.   },
  11. })
  12. ```

Update an existing Post record

  1. ``` ts
  2. // Run inside `async` function
  3. const post = await prisma.post.update({
  4.   where: { id: 42 },
  5.   data: { published: true },
  6. })
  7. ```

Usage with TypeScript


Note that when using TypeScript, the result of this query will be statically typedso that you can't accidentally access a property that doesn't exist (and any typos are caught at compile-time). Learn more about leveraging Prisma Client's generated types on the Advanced usage of generated types page in the docs.

Community


Prisma has a large and supportive community of enthusiastic application developers. You can join us on Slack and here on GitHub.

Security


If you have a security issue to report, please contact us at security@prisma.io.

Support


Ask a question about Prisma


You can ask questions and initiate discussions about Prisma-related topics in the prisma repository on GitHub.

👉Ask a question

Create a bug report for Prisma


If you see an error message or run into an issue, please make sure to create a bug report! You can find best practices for creating bug reports (like including additional debugging output) in the docs.

👉Create bug report

Submit a feature request


If Prisma currently doesn't have a certain feature, be sure to check out the roadmap to see if this is already planned for the future.

If the feature on the roadmap is linked to a GitHub issue, please make sure to leave a +1 on the issue and ideally a comment with your thoughts about the feature!

👉Submit feature request

Contributing


Refer to our contribution guidelines and Code of Conduct for contributors.

Build Status


Prisma Tests Status:
Ecosystem Tests Status:Actions Status