You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/100-getting-started/02-prisma-orm/100-quickstart/800-mongodb.mdx
+35-17Lines changed: 35 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,18 +12,17 @@ import NextSteps from '../../_components/_next-steps.mdx'
12
12
13
13
[MongoDB](https://www.mongodb.com) is a popular NoSQL document database. In this guide, you will learn how to set up a new TypeScript project from scratch, connect it to MongoDB using Prisma ORM, and generate a Prisma Client for easy, type-safe access to your database.
14
14
15
-
:::warning[Do not upgrade to Prisma ORM v7 if you are using MongoDB]
15
+
:::warning[MongoDB support for Prisma ORM v7]
16
16
17
-
Prisma ORM v7 is not yet compatible with MongoDB. Please use Prisma ORM v6 instead. Support for MongoDB is coming in a future release.
17
+
**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.
18
+
19
+
This guide uses Prisma ORM v6.19 to ensure full compatibility with MongoDB.
18
20
19
21
:::
20
22
21
23
## Prerequisites
22
24
23
-
<Prerequisites />
24
-
25
-
You also need:
26
-
25
+
- Node.js installed in your system [with the supported version](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-6#minimum-supported-nodejs-versions)
27
26
- A [MongoDB](https://www.mongodb.com/) database accessible via connection string
28
27
29
28
## 1. Create a new project
@@ -35,10 +34,18 @@ You also need:
35
34
Install the packages needed for this quickstart:
36
35
37
36
```terminal
38
-
npm install prisma @types/node --save-dev
39
-
npm install @prisma/client dotenv
37
+
npm install prisma@6.19 @types/node --save-dev
38
+
npm install @prisma/client@6.19 dotenv
40
39
```
41
40
41
+
:::info[Why Prisma v6.19?]
42
+
43
+
This is the latest stable version of Prisma ORM v6 that fully supports MongoDB. MongoDB support for Prisma ORM v7 is coming soon.
44
+
45
+
You can also install `prisma@6` and `@prisma/client@6` to automatically get the latest v6 release.
46
+
47
+
:::
48
+
42
49
Here's what each package does:
43
50
44
51
-**`prisma`** - The Prisma CLI for running commands like `prisma init`, `prisma db push`, and `prisma generate`
Replace with your actual MongoDB connection string.
171
+
:::tip
172
+
173
+
Replace `username`, `password`, `cluster`, and `mydb` with your actual MongoDB credentials and database name. You can get your connection string from [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) or your MongoDB deployment.
174
+
175
+
:::
160
176
161
177
## 5. Define your data model
162
178
@@ -194,19 +210,21 @@ model Post {
194
210
195
211
## 6. Push your schema to MongoDB
196
212
197
-
Since MongoDB doesn't use migrations, pushyour schema directly:
213
+
MongoDB doesn't support migrations like relational databases. Instead, use `db push` to sync your schema:
198
214
199
215
```terminal
200
216
npx prisma db push
201
217
```
202
218
203
-
This command creates the collections based on your schema.
219
+
This command:
220
+
- Creates the collections in MongoDB based on your schema
221
+
- Automatically generates Prisma Client
204
222
205
-
Now run the following command to generate the Prisma Client:
223
+
:::info
206
224
207
-
```terminal
208
-
npx prisma generate
209
-
```
225
+
Unlike relational databases, MongoDB uses a flexible schema. The `db push` command ensures your Prisma schema is reflected in your database without creating migration files.
Copy file name to clipboardExpand all lines: content/100-getting-started/02-prisma-orm/200-add-to-existing-project/800-mongodb.mdx
+41-25Lines changed: 41 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,6 +11,14 @@ import NextSteps from '../../_components/_next-steps.mdx'
11
11
12
12
[MongoDB](https://www.mongodb.com/) 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.
13
13
14
+
:::warning[MongoDB support for Prisma ORM v7]
15
+
16
+
**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.
17
+
18
+
This guide uses Prisma ORM v6.19 to ensure full compatibility with MongoDB.
19
+
20
+
:::
21
+
14
22
:::tip
15
23
16
24
If you're migrating to Prisma ORM from Mongoose, see our [Migrate from Mongoose guide](/guides/migrate-from-mongoose).
@@ -21,7 +29,7 @@ If you're migrating to Prisma ORM from Mongoose, see our [Migrate from Mongoose
21
29
22
30
In order to successfully complete this guide, you need:
23
31
24
-
-[Node.js](https://nodejs.org/en/) installed on your machine (see [system requirements](/orm/reference/system-requirements) for officially supported versions)
32
+
-[Node.js](https://nodejs.org/en/) installed on your machine (see [system requirements](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-6#minimum-supported-nodejs-versions) for officially supported versions)
25
33
- An existing TypeScript project with a `package.json` file
26
34
- Access to a MongoDB 4.2+ server with a replica set deployment. We recommend using [MongoDB Atlas](https://www.mongodb.com/cloud/atlas).
27
35
@@ -44,8 +52,8 @@ If your project contains multiple directories with `package.json` files (e.g., `
44
52
Navigate to your existing project directory and install the required dependencies:
45
53
46
54
```terminal
47
-
npm install prisma @types/node --save-dev
48
-
npm install @prisma/client dotenv
55
+
npm install prisma@6.19 @types/node --save-dev
56
+
npm install @prisma/client@6.19 dotenv
49
57
```
50
58
51
59
Here's what each package does:
@@ -54,9 +62,11 @@ Here's what each package does:
54
62
-**`@prisma/client`** - The Prisma Client library for querying your database
55
63
-**`dotenv`** - Loads environment variables from your `.env` file
56
64
57
-
:::info
65
+
:::info[Why Prisma v6.19?]
66
+
67
+
This is the latest stable version of Prisma ORM v6 that fully supports MongoDB. MongoDB support for Prisma ORM v7 is coming soon.
58
68
59
-
MongoDB does not require a driver adapter like relational databases. Prisma Client connects directly to MongoDB.
69
+
You can also install `prisma@6` and `@prisma/client@6` to automatically get the latest v6 release.
60
70
61
71
:::
62
72
@@ -121,6 +131,7 @@ generator client {
121
131
122
132
datasource db {
123
133
provider = "mongodb"
134
+
url = env("DATABASE_URL")
124
135
}
125
136
```
126
137
@@ -138,23 +149,23 @@ For MongoDB Atlas, the connection URL format is:
The [format of the connection URL](/orm/reference/connection-urls) for MongoDB looks as follows (the parts spelled all-uppercased are _placeholders_ for your specific connection details):
152
+
Self-hosted MongoDB connection URL format:
142
153
143
154
```
144
155
mongodb://USERNAME:PASSWORD@HOST:PORT/DATABASE
145
156
```
146
157
147
-
Here's a short explanation of each component:
158
+
Connection URL components:
148
159
149
-
-**`USERNAME`**: The name of your database user
150
-
-**`PASSWORD`**: The password for your database user
151
-
-**`HOST`**: The host where a [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod/#mongodb-binary-bin.mongod)(or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos/#mongodb-binary-bin.mongos)) instance is running
152
-
-**`PORT`**: The port where your database server is running (typically `27017` for MongoDB)
153
-
-**`DATABASE`**: The name of the database
160
+
-**`USERNAME`**: Your database user name
161
+
-**`PASSWORD`**: Your database user password
162
+
-**`HOST`**: The host where [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod/#mongodb-binary-bin.mongod) or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos/#mongodb-binary-bin.mongos) is running
163
+
-**`PORT`**: The port where your database server is running (typically `27017`)
164
+
-**`DATABASE`**: The name of your database
154
165
155
166
:::tip
156
167
157
-
If you're using MongoDB Atlas, you need to manually append the database name to the connection URL because the environment link from MongoDB Atlas doesn't contain it.
168
+
For MongoDB Atlas, you can manually append the database name to the connection URL, as Atlas doesn't include it by default.
158
169
159
170
:::
160
171
@@ -176,15 +187,20 @@ Run the following command to introspect your existing database:
176
187
npx prisma db pull
177
188
```
178
189
179
-
This command reads the `DATABASE_URL` environment variable, connects to your database, and introspects the database schema. Prisma ORM introspects a MongoDB schema by sampling the data stored in the database and inferring the schema.
190
+
This command:
191
+
- Reads the `DATABASE_URL` from your `.env` file
192
+
- Connects to your MongoDB database
193
+
- Samples documents in your collections to infer the schema
194
+
- Generates Prisma models in your `schema.prisma` file
180
195
181
196

182
197
183
-
After introspection, your Prisma schema will contain models that represent your existing MongoDB collections.
184
-
185
198
:::info
186
199
187
-
MongoDB introspection works by sampling documents in your collections. You may need to manually add relation fields using the `@relation` attribute to enable relational queries.
200
+
**MongoDB introspection limitations:** Prisma introspects MongoDB by sampling documents. You may need to manually:
201
+
- Add relation fields using the `@relation` attribute
202
+
- Adjust field types if the sampling didn't capture all variations
203
+
- Add indexes and constraints not detected during introspection
188
204
189
205
:::
190
206
@@ -244,11 +260,11 @@ npx tsx script.ts
244
260
245
261
## 8. Evolve your schema
246
262
247
-
MongoDB does not use migrations. To make changes to your database schema:
263
+
MongoDB doesn't support migrations like relational databases. Instead, use `db push`to sync schema changes:
248
264
249
265
### 8.1. Update your Prisma schema file
250
266
251
-
Update your Prisma schema file to reflect the changes you want to make to your database schema. For example, add a new model:
267
+
Modify your Prisma schema file with the changes you want. For example, add a new model:
252
268
253
269
```prisma file=prisma/schema.prisma
254
270
// add-start
@@ -276,19 +292,19 @@ In MongoDB, the `id` field is mapped to `_id` and uses `@db.ObjectId` type. Rela
276
292
277
293
:::
278
294
279
-
### 8.2. Push the changes to your database:
295
+
### 8.2. Push the changes to your database
280
296
281
297
```terminal
282
298
npx prisma db push
283
299
```
284
300
285
-
This command will:
286
-
-Apply the schema changes to your MongoDB database
287
-
-Regenerate Prisma Client
301
+
This command:
302
+
-Applies schema changes to your MongoDB database
303
+
-Automatically regenerates Prisma Client
288
304
289
-
:::info
305
+
:::info[Why `db push` instead of migrations?]
290
306
291
-
Prisma Migrate is not supported for MongoDB. Use`prisma db push` to sync your schema changes.
307
+
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.
-**`prisma`** - The Prisma CLI for running commands like `prisma migrate` and `prisma generate`
182
182
-**`@prisma/client`** - The Prisma Client library for querying your database
183
183
-**`@prisma/adapter-pg`** - The [`node-postgres` driver adapter](/orm/overview/databases/postgresql#using-the-node-postgres-driver) that connects Prisma Client to your database
184
+
-**`pg`** - The node-postgres database driver
185
+
-**`@types/pg`** - TypeScript type definitions for node-postgres
184
186
-**`dotenv`** - Loads environment variables from your `.env` file
0 commit comments