apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/mongodb.mdx
MongoDB is a popular document-based NoSQL database known for its flexibility, scalability, and developer-friendly features. In this guide, you will learn how to add Prisma ORM to an existing TypeScript project, connect it to MongoDB, introspect your existing database schema, and start querying with type-safe Prisma Client.
:::warning[MongoDB support for Prisma ORM v7]
MongoDB support for Prisma ORM v7 is coming in the near future. In the meantime, please use Prisma ORM v6.19 (the latest v6 release) when working with MongoDB.
This guide uses Prisma ORM v6.19 to ensure full compatibility with MongoDB.
:::
:::tip
If you're migrating to Prisma ORM from Mongoose, see our Migrate from Mongoose guide.
:::
In order to successfully complete this guide, you need:
package.json file:::warning
The MongoDB database connector uses transactions to support nested writes. Transactions require a replica set deployment. The easiest way to deploy a replica set is with Atlas. It's free to get started.
:::
Make sure you have your database connection URL (that includes your authentication credentials) at hand!
:::note
If your project contains multiple directories with package.json files (e.g., frontend, backend, etc.), note that Prisma ORM is specifically designed for use in the API/backend layer. To set up Prisma, navigate to the appropriate backend directory containing the relevant package.json file and configure Prisma there.
:::
Navigate to your existing project directory and install the required dependencies:
npm install [email protected] @types/node --save-dev
npm install @prisma/[email protected] dotenv
Here's what each package does:
prisma - The Prisma CLI for running commands like prisma init, prisma db pull, and prisma generate@prisma/client - The Prisma Client library for querying your databasedotenv - Loads environment variables from your .env file:::info[Why Prisma v6.19?]
This is the latest stable version of Prisma ORM v6 that fully supports MongoDB. MongoDB support for Prisma ORM v7 is coming soon.
You can also install prisma@6 and @prisma/client@6 to automatically get the latest v6 release.
:::
Set up your Prisma ORM project by creating your Prisma Schema file with the following command:
npx prisma init --datasource-provider mongodb --output ../generated/prisma
This command does a few things:
prisma/ directory with a schema.prisma file containing your database connection configuration.env file in the root directory for environment variablesprisma.config.ts file for Prisma configurationThe generated prisma.config.ts file looks like this:
import { defineConfig, env } from "prisma/config";
export default defineConfig({
schema: "prisma/schema.prisma",
migrations: {
path: "prisma/migrations",
},
engine: "classic",
datasource: {
url: env("DATABASE_URL"),
},
});
Add dotenv to prisma.config.ts so that Prisma can load environment variables from your .env file:
import "dotenv/config"; // [!code ++]
import { defineConfig, env } from "prisma/config";
export default defineConfig({
schema: "prisma/schema.prisma",
migrations: {
path: "prisma/migrations",
},
engine: "classic",
datasource: {
url: env("DATABASE_URL"),
},
});
The generated schema uses the ESM-first prisma-client generator with a custom output path:
generator client {
provider = "prisma-client"
output = "../generated/prisma"
}
datasource db {
provider = "mongodb"
url = env("DATABASE_URL")
}
Update the .env file with your MongoDB connection URL:
DATABASE_URL="mongodb+srv://username:[email protected]/mydb"
For MongoDB Atlas, the connection URL format is:
mongodb+srv://USERNAME:[email protected]/DATABASE
Self-hosted MongoDB connection URL format:
mongodb://USERNAME:PASSWORD@HOST:PORT/DATABASE
Connection URL components:
USERNAME: Your database user namePASSWORD: Your database user passwordHOST: The host where mongod or mongos is runningPORT: The port where your database server is running (typically 27017)DATABASE: The name of your database:::tip
For MongoDB Atlas, you can manually append the database name to the connection URL, as Atlas doesn't include it by default.
:::
SCRAM failure: Authentication failed error, add ?authSource=admin to the end of your connection string.Error code 8000 (AtlasError): empty database name not allowed error, append the database name to your connection URL. See this GitHub issue for details.Run the following command to introspect your existing database:
npx prisma db pull
This command:
DATABASE_URL from your .env fileschema.prisma file:::info
MongoDB introspection limitations: Prisma introspects MongoDB by sampling documents. You may need to manually:
@relation attribute:::
Generate Prisma Client based on your introspected schema:
npx prisma generate
This creates a type-safe Prisma Client tailored to your database schema in the generated/prisma directory.
Create a utility file to instantiate Prisma Client:
import "dotenv/config";
import { PrismaClient } from "../generated/prisma/client";
const prisma = new PrismaClient();
export { prisma };
Now you can use Prisma Client to query your database. Create a script.ts file:
import { prisma } from "./lib/prisma";
async function main() {
// Example: Fetch all records from a collection
// Replace 'user' with your actual model name
const allUsers = await prisma.user.findMany();
console.log("All users:", JSON.stringify(allUsers, null, 2));
}
main()
.then(async () => {
await prisma.$disconnect();
})
.catch(async (e) => {
console.error(e);
await prisma.$disconnect();
process.exit(1);
});
Run the script:
npx tsx script.ts
MongoDB doesn't support migrations like relational databases. Instead, use db push to sync schema changes:
Modify your Prisma schema file with the changes you want. For example, add a new model:
model Post { // [!code ++]
id String @id @default(auto()) @map("_id") @db.ObjectId // [!code ++]
title String // [!code ++]
content String? // [!code ++]
published Boolean @default(false) // [!code ++]
authorId String @db.ObjectId // [!code ++]
author User @relation(fields: [authorId], references: [id]) // [!code ++]
} // [!code ++]
model User { // [!code ++]
id String @id @default(auto()) @map("_id") @db.ObjectId // [!code ++]
email String @unique // [!code ++]
name String? // [!code ++]
posts Post[] // [!code ++]
} // [!code ++]
:::info
In MongoDB, the id field is mapped to _id and uses @db.ObjectId type. Relations use String type with @db.ObjectId annotation.
:::
npx prisma db push
This command:
:::info[Why db push instead of migrations?]
MongoDB uses a flexible schema model. Prisma Migrate (which creates migration files) is not supported for MongoDB. Always use prisma db push to sync your schema changes.
:::
You can use MongoDB Atlas, the MongoDB shell, or MongoDB Compass to view and manage your data.
:::warning
Prisma Studio does not currently support MongoDB. Support may be added in a future release. See Databases supported by Prisma Studio for more information.
:::
You've successfully set up Prisma ORM. Here's what you can explore next: