CRUD

This page describes how to perform CRUD operations with your generated Prisma Client API. CRUD is an acronym that stands for:

Create
Read
Update
Delete

Refer to the Prisma Client API reference documentation for detailed explanations of each method.

Example schema

All examples are based on the following schema:

<details> <summary>Expand for sample schema</summary>

prisma

datasource db {
  provider = "postgresql"
}

generator client {
  provider = "prisma-client"
  output   = "./generated"
}

model ExtendedProfile {
  id        Int    @id @default(autoincrement())
  biography String
  user      User   @relation(fields: [userId], references: [id])
  userId    Int    @unique
}

model User {
  id           Int              @id @default(autoincrement())
  name         String?
  email        String           @unique
  profileViews Int              @default(0)
  role         Role             @default(USER)
  coinflips    Boolean[]
  posts        Post[]
  profile      ExtendedProfile?
}

model Post {
  id         Int        @id @default(autoincrement())
  title      String
  published  Boolean    @default(true)
  author     User       @relation(fields: [authorId], references: [id])
  authorId   Int
  comments   Json?
  views      Int        @default(0)
  likes      Int        @default(0)
  categories Category[]
}

model Category {
  id    Int    @id @default(autoincrement())
  name  String @unique
  posts Post[]
}

enum Role {
  USER
  ADMIN
}

prisma

datasource db {
  provider = "mongodb"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

model ExtendedProfile {
  id        String @id @default(auto()) @map("_id") @db.ObjectId
  biography String
  user      User   @relation(fields: [userId], references: [id])
  userId    String @unique @db.ObjectId
}

model User {
  id           String           @id @default(auto()) @map("_id") @db.ObjectId
  name         String?
  email        String           @unique
  profileViews Int              @default(0)
  role         Role             @default(USER)
  coinflips    Boolean[]
  posts        Post[]
  profile      ExtendedProfile?
}

model Post {
  id         String     @id @default(auto()) @map("_id") @db.ObjectId
  title      String
  published  Boolean    @default(true)
  author     User       @relation(fields: [authorId], references: [id])
  authorId   String     @db.ObjectId
  comments   Json?
  views      Int        @default(0)
  likes      Int        @default(0)
  categories Category[]
}

model Category {
  id    String @id @default(auto()) @map("_id") @db.ObjectId
  name  String @unique
  posts Post[]
}

enum Role {
  USER
  ADMIN
}

</details>

For relational databases, use db push command to push the example schema to your own database

npm

npx prisma db push

For MongoDB, ensure your data is in a uniform shape and matches the model defined in the Prisma schema.

Create

Create a single record

The following query creates (create()) a single user with two fields:

const user = await prisma.user.create({
  data: {
    email: "[email protected]",
    name: "Elsa Prisma",
  },
});

{
  id: 22,
  name: 'Elsa Prisma',
  email: '[email protected]',
  profileViews: 0,
  role: 'USER',
  coinflips: []
}

The user's id is auto-generated, and your schema determines which fields are mandatory.

Create a single record using generated types

The following example produces an identical result, but creates a UserCreateInput variable named user outside the context of the create() query. After completing a simple check ("Should posts be included in this create() query?"), the user variable is passed into the query:

import { PrismaClient, Prisma } from "../prisma/generated/client";

const prisma = new PrismaClient();

async function main() {
  let includePosts: boolean = false;
  let user: Prisma.UserCreateInput;

  // Check if posts should be included in the query
  if (includePosts) {
    user = {
      email: "[email protected]",
      name: "Elsa Prisma",
      posts: {
        create: {
          title: "Include this post!",
        },
      },
    };
  } else {
    user = {
      email: "[email protected]",
      name: "Elsa Prisma",
    };
  }

  // Pass 'user' object into query
  const createUser = await prisma.user.create({ data: user });
}

main();

For more information about working with generated types, see: Generated types.

Create multiple records

Prisma Client supports bulk inserts as a GA feature in 2.20.0 and later.

The following createMany() query creates multiple users and skips any duplicates (email must be unique):

const createMany = await prisma.user.createMany({
  data: [
    { name: "Bob", email: "[email protected]" },
    { name: "Bobo", email: "[email protected]" }, // Duplicate unique key!
    { name: "Yewande", email: "[email protected]" },
    { name: "Angelique", email: "[email protected]" },
  ],
  skipDuplicates: true, // Skip 'Bobo'
});

{
  count: 3;
}

:::warning

Note skipDuplicates is not supported when using MongoDB, SQLServer, or SQLite.

:::

createMany() uses a single INSERT INTO statement with multiple values, which is generally more efficient than a separate INSERT per row:

sql

BEGIN
INSERT INTO "public"."User" ("id","name","email","profileViews","role","coinflips","testing","city","country") VALUES (DEFAULT,$1,$2,$3,$4,DEFAULT,DEFAULT,DEFAULT,$5), (DEFAULT,$6,$7,$8,$9,DEFAULT,DEFAULT,DEFAULT,$10), (DEFAULT,$11,$12,$13,$14,DEFAULT,DEFAULT,DEFAULT,$15), (DEFAULT,$16,$17,$18,$19,DEFAULT,DEFAULT,DEFAULT,$20) ON CONFLICT DO NOTHING
COMMIT
SELECT "public"."User"."country", "public"."User"."city", "public"."User"."email", SUM("public"."User"."profileViews"), COUNT(*) FROM "public"."User" WHERE 1=1 GROUP BY "public"."User"."country", "public"."User"."city", "public"."User"."email" HAVING AVG("public"."User"."profileViews") >= $1 ORDER BY "public"."User"."country" ASC OFFSET $2

Note: Multiple create() statements inside a $transaction results in multiple INSERT statements.

The following video demonstrates how to use createMany() and faker.js to seed a database with sample data:

See Working with relations > Nested writes for information about creating a record and one or more related records at the same time.

Create and return multiple records

:::info

This feature is available in Prisma ORM version 5.14.0 and later for PostgreSQL, CockroachDB and SQLite.

:::

You can use createManyAndReturn() in order to create many records and return the resulting objects.

const users = await prisma.user.createManyAndReturn({
  data: [
    { name: "Alice", email: "[email protected]" },
    { name: "Bob", email: "[email protected]" },
  ],
});

[
  {
    id: 22,
    name: "Alice",
    email: "[email protected]",
    profileViews: 0,
    role: "USER",
    coinflips: [],
  },
  {
    id: 23,
    name: "Bob",
    email: "[email protected]",
    profileViews: 0,
    role: "USER",
    coinflips: [],
  },
];

:::warning

relationLoadStrategy: join is not available when using createManyAndReturn().

:::

Read

Get record by ID or unique identifier

The following queries return a single record (findUnique()) by unique identifier or ID:

// By unique identifier
const user = await prisma.user.findUnique({
  where: {
    email: "[email protected]",
  },
});

// By ID
const user = await prisma.user.findUnique({
  where: {
    id: 99,
  },
});

If you are using the MongoDB connector and your underlying ID type is ObjectId, you can use the string representation of that ObjectId:

// By ID
const user = await prisma.user.findUnique({
  where: {
    id: "60d5922d00581b8f0062e3a8",
  },
});

Get all records

The following findMany() query returns all User records:

const users = await prisma.user.findMany();

You can also paginate your results.

Get the first record that matches a specific criteria

The following findFirst() query returns the most recently created user with at least one post that has more than 100 likes:

Order users by descending ID (largest first) - the largest ID is the most recent
Return the first user in descending order with at least one post that has more than 100 likes

const findUser = await prisma.user.findFirst({
  where: {
    posts: {
      some: {
        likes: {
          gt: 100,
        },
      },
    },
  },
  orderBy: {
    id: "desc",
  },
});

Get a filtered list of records

Prisma Client supports filtering on record fields and related record fields.

Filter by a single field value

The following query returns all User records with an email that ends in "prisma.io":

const users = await prisma.user.findMany({
  where: {
    email: {
      endsWith: "prisma.io",
    },
  },
});

Filter by multiple field values

The following query uses a combination of operators to return users whose name start with E or administrators with at least 1 profile view:

const users = await prisma.user.findMany({
  where: {
    OR: [
      {
        name: {
          startsWith: "E",
        },
      },
      {
        AND: {
          profileViews: {
            gt: 0,
          },
          role: {
            equals: "ADMIN",
          },
        },
      },
    ],
  },
});

Filter by related record field values

The following query returns users with an email that ends with prisma.io and have at least one post (some) that is not published:

const users = await prisma.user.findMany({
  where: {
    email: {
      endsWith: "prisma.io",
    },
    posts: {
      some: {
        published: false,
      },
    },
  },
});

See Working with relations for more examples of filtering on related field values.

Select a subset of fields

The following findUnique() query uses select to return the email and name fields of a specific User record:

const user = await prisma.user.findUnique({
  where: {
    email: "[email protected]",
  },
  select: {
    email: true,
    name: true,
  },
});

{ email: '[email protected]', name: "Emma" }

For more information about including relations, refer to:

Select a subset of related record fields

The following query uses a nested select to return:

The user's email
The likes field of each post

const user = await prisma.user.findUnique({
  where: {
    email: "[email protected]",
  },
  select: {
    email: true,
    posts: {
      select: {
        likes: true,
      },
    },
  },
});

{ email: '[email protected]', posts: [ { likes: 0 }, { likes: 0 } ] }

For more information about including relations, see Select fields and include relations.

Select distinct field values

See Select distinct for information about selecting distinct field values.

The following query returns all ADMIN users and includes each user's posts in the result:

const users = await prisma.user.findMany({
  where: {
    role: "ADMIN",
  },
  include: {
    posts: true,
  },
});

{
    "id": 38,
    "name": "Maria",
    "email": "[email protected]",
    "profileViews": 20,
    "role": "ADMIN",
    "coinflips": [
        true,
        false,
        false
    ],
    "posts": []
},
{
    "id": 39,
    "name": "Oni",
    "email": "[email protected]",
    "profileViews": 20,
    "role": "ADMIN",
    "coinflips": [
        true,
        false,
        false
    ],
    "posts": [
        {
        "id": 25,
        "authorId": 39,
        "title": "My awesome post",
        "published": true,
        "comments": null,
        "views": 0,
        "likes": 0
        }
    ]
}

For more information about including relations, see Select fields and include relations.

Include a filtered list of relations

See Working with relations to find out how to combine include and where for a filtered list of relations - for example, only include a user's published posts.

Update

Update a single record

The following query uses update() to find and update a single User record by email:

const updateUser = await prisma.user.update({
  where: {
    email: "[email protected]",
  },
  data: {
    name: "Viola the Magnificent",
  },
});

{
   "id": 43,
   "name": "Viola the Magnificent",
   "email": "[email protected]",
   "profileViews": 0,
   "role": "USER",
   "coinflips": [],
}

Update multiple records

The following query uses updateMany() to update all User records that contain prisma.io:

const updateUsers = await prisma.user.updateMany({
  where: {
    email: {
      contains: "prisma.io",
    },
  },
  data: {
    role: "ADMIN",
  },
});

{
   "count": 19
}

Update and return multiple records

:::info

This feature is available in Prisma ORM version 6.2.0 and later for PostgreSQL, CockroachDB, and SQLite.

:::

You can use updateManyAndReturn() in order to update many records and return the resulting objects.

const users = await prisma.user.updateManyAndReturn({
  where: {
    email: {
      contains: "prisma.io",
    },
  },
  data: {
    role: "ADMIN",
  },
});

[
  {
    id: 22,
    name: "Alice",
    email: "[email protected]",
    profileViews: 0,
    role: "ADMIN",
    coinflips: [],
  },
  {
    id: 23,
    name: "Bob",
    email: "[email protected]",
    profileViews: 0,
    role: "ADMIN",
    coinflips: [],
  },
];

:::warning

relationLoadStrategy: join is not available when using updateManyAndReturn().

:::

Update or create records

The following query uses upsert() to update a User record with a specific email address, or create that User record if it does not exist:

const upsertUser = await prisma.user.upsert({
  where: {
    email: "[email protected]",
  },
  update: {
    name: "Viola the Magnificent",
  },
  create: {
    email: "[email protected]",
    name: "Viola the Magnificent",
  },
});

{
   "id": 43,
   "name": "Viola the Magnificent",
   "email": "[email protected]",
   "profileViews": 0,
   "role": "ADMIN",
   "coinflips": [],
}

:::info

From version 4.6.0, Prisma Client carries out upserts with database native SQL commands where possible. Learn more.

:::

Prisma Client does not have a findOrCreate() query. You can use upsert() as a workaround. To make upsert() behave like a findOrCreate() method, provide an empty update parameter to upsert().

:::warning

A limitation to using upsert() as a workaround for findOrCreate() is that upsert() will only accept unique model fields in the where condition. So it's not possible to use upsert() to emulate findOrCreate() if the where condition contains non-unique fields.

:::

Update a number field

Use atomic number operations to update a number field based on its current value - for example, increment or multiply. The following query increments the views and likes fields by 1:

const updatePosts = await prisma.post.updateMany({
  data: {
    views: {
      increment: 1,
    },
    likes: {
      increment: 1,
    },
  },
});

Refer to Working with relations for information about disconnecting (disconnect) and connecting (connect) related records.

Delete

Delete a single record

The following query uses delete() to delete a single User record:

const deleteUser = await prisma.user.delete({
  where: {
    email: "[email protected]",
  },
});

Attempting to delete a user with one or more posts result in an error, as every Post requires an author - see cascading deletes.

Delete multiple records

The following query uses deleteMany() to delete all User records where email contains prisma.io:

const deleteUsers = await prisma.user.deleteMany({
  where: {
    email: {
      contains: "prisma.io",
    },
  },
});

Attempting to delete a user with one or more posts result in an error, as every Post requires an author - see cascading deletes.

Delete all records

The following query uses deleteMany() to delete all User records:

const deleteUsers = await prisma.user.deleteMany({});

Be aware that this query will fail if the user has any related records (such as posts). In this case, you need to delete the related records first.

:::warning

In 2.26.0 and later it is possible to do cascading deletes using the preview feature referential actions.

:::

The following query uses delete() to delete a single User record:

const deleteUser = await prisma.user.delete({
  where: {
    email: "[email protected]",
  },
});

However, the example schema includes a required relation between Post and User, which means that you cannot delete a user with posts:

The change you are trying to make would violate the required relation 'PostToUser' between the `Post` and `User` models.

To resolve this error, you can:

Make the relation optional:

prisma

model Post {
  id       Int   @id @default(autoincrement())
  author   User? @relation(fields: [authorId], references: [id]) // [!code ++]
  authorId Int? // [!code ++]
  author   User  @relation(fields: [authorId], references: [id]) // [!code --]
  authorId Int // [!code --]
}

Change the author of the posts to another user before deleting the user.

Delete a user and all their posts with two separate queries in a transaction (all queries must succeed):

const deletePosts = prisma.post.deleteMany({
  where: {
    authorId: 7,
  },
});

const deleteUser = prisma.user.delete({
  where: {
    id: 7,
  },
});

const transaction = await prisma.$transaction([deletePosts, deleteUser]);

Delete all records from all tables

Sometimes you want to remove all data from all tables but keep the actual tables. This can be particularly useful in a development environment and whilst testing.

The following shows how to delete all records from all tables with Prisma Client and with Prisma Migrate.

Deleting all data with `deleteMany()`

When you know the order in which your tables should be deleted, you can use the deleteMany function. This is executed synchronously in a $transaction and can be used with all types of databases.

const deletePosts = prisma.post.deleteMany();
const deleteProfile = prisma.profile.deleteMany();
const deleteUsers = prisma.user.deleteMany();

// The transaction runs synchronously so deleteUsers must run last.
await prisma.$transaction([deleteProfile, deletePosts, deleteUsers]);

✅ Pros:

Works well when you know the structure of your schema ahead of time
Synchronously deletes each tables data

❌ Cons:

When working with relational databases, this function doesn't scale as well as having a more generic solution which looks up and TRUNCATEs your tables regardless of their relational constraints. Note that this scaling issue does not apply when using the MongoDB connector.

Note: The $transaction performs a cascading delete on each models table so they have to be called in order.

Deleting all data with raw SQL / `TRUNCATE`

If you are comfortable working with raw SQL, you can perform a TRUNCATE query on a table using $executeRawUnsafe.

In the following examples, the first tab shows how to perform a TRUNCATE on a Postgres database by using a $queryRaw look up that maps over the table and TRUNCATES all tables in a single query.

The second tab shows performing the same function but with a MySQL database. In this instance the constraints must be removed before the TRUNCATE can be executed, before being reinstated once finished. The whole process is run as a $transaction

const tablenames = await prisma.$queryRaw<
  Array<{ tablename: string }>
>`SELECT tablename FROM pg_tables WHERE schemaname='public'`;

const tables = tablenames
  .map(({ tablename }) => tablename)
  .filter((name) => name !== "_prisma_migrations")
  .map((name) => `"public"."${name}"`)
  .join(", ");

try {
  await prisma.$executeRawUnsafe(`TRUNCATE TABLE ${tables} CASCADE;`);
} catch (error) {
  console.log({ error });
}

const transactions: PrismaPromise<any>[] = [];
transactions.push(prisma.$executeRaw`SET FOREIGN_KEY_CHECKS = 0;`);

const tablenames = await prisma.$queryRaw<
  Array<{ TABLE_NAME: string }>
>`SELECT TABLE_NAME from information_schema.TABLES WHERE TABLE_SCHEMA = 'tests';`;

for (const { TABLE_NAME } of tablenames) {
  if (TABLE_NAME !== "_prisma_migrations") {
    try {
      transactions.push(prisma.$executeRawUnsafe(`TRUNCATE ${TABLE_NAME};`));
    } catch (error) {
      console.log({ error });
    }
  }
}

transactions.push(prisma.$executeRaw`SET FOREIGN_KEY_CHECKS = 1;`);

try {
  await prisma.$transaction(transactions);
} catch (error) {
  console.log({ error });
}

✅ Pros:

Scalable
Very fast

❌ Cons:

Can't undo the operation
Using reserved SQL key words as tables names can cause issues when trying to run a raw query

Deleting all records with Prisma Migrate

If you use Prisma Migrate, you can use migrate reset, this will:

Drop the database
Create a new database
Apply migrations
Seed the database with data

Advanced query examples

Create a deeply nested tree of records

A single User
Two new, related Post records
Connect or create Category per post

const u = await prisma.user.create({
  include: {
    posts: {
      include: {
        categories: true,
      },
    },
  },
  data: {
    email: "[email protected]",
    posts: {
      create: [
        {
          title: "My first post",
          categories: {
            connectOrCreate: [
              {
                create: { name: "Introductions" },
                where: {
                  name: "Introductions",
                },
              },
              {
                create: { name: "Social" },
                where: {
                  name: "Social",
                },
              },
            ],
          },
        },
        {
          title: "How to make cookies",
          categories: {
            connectOrCreate: [
              {
                create: { name: "Social" },
                where: {
                  name: "Social",
                },
              },
              {
                create: { name: "Cooking" },
                where: {
                  name: "Cooking",
                },
              },
            ],
          },
        },
      ],
    },
  },
});

Example schema

Create

Create a single record

Create a single record using generated types

Create multiple records

Create records and connect or create related records

Create and return multiple records

Read

Get record by ID or unique identifier

Get all records

Get the first record that matches a specific criteria

Get a filtered list of records

Filter by a single field value

Filter by multiple field values

Filter by related record field values

Select a subset of fields

Select a subset of related record fields

Select distinct field values

Include related records

Include a filtered list of relations

Update

Update a single record

Update multiple records

Update and return multiple records

Update or create records

Update a number field

Connect and disconnect related records

Delete

Delete a single record

Delete multiple records

Delete all records

Cascading deletes (deleting related records)

Delete all records from all tables

Deleting all data with deleteMany()

Deleting all data with raw SQL / TRUNCATE

Deleting all records with Prisma Migrate

Advanced query examples

Create a deeply nested tree of records

Deleting all data with `deleteMany()`

Deleting all data with raw SQL / `TRUNCATE`