diff --git a/content/01-getting-started/01-quickstart.mdx b/content/01-getting-started/01-quickstart.mdx index ef28cca0ea..1a50ffd4f5 100644 --- a/content/01-getting-started/01-quickstart.mdx +++ b/content/01-getting-started/01-quickstart.mdx @@ -51,7 +51,7 @@ Open your terminal and download the starter project with the following command: ```copy -curl https://codeload.github.com/prisma/prisma-examples/tar.gz/starter | tar -xz --strip=2 prisma-examples-starter/javascript/starter +curl https://codeload.github.com/prisma/prisma-examples/tar.gz/starter | tar -xz --strip=2 prisma-examples-starter/typescript/starter ``` @@ -94,7 +94,7 @@ Note that the dependencies defined in your project are: The starter project consists of five files: - `package.json`: Defines your npm dependencies -- `prisma/schema.prisma`: [Prisma schema file](../reference/tools-and-interfaces/prisma-schema/ +- `prisma/schema.prisma`: [Prisma schema file](../reference/tools-and-interfaces/prisma-schema/) defining your models - `prisma/.env`: Defines your database connection URL as an environment variable - `prisma/dev.db`: A SQLite database file - `scr/index.js`: A plain, executable Node.js script @@ -134,6 +134,35 @@ npm install ## Write your first query with Prisma Client +In this section, you will write your first query with Prisma Client. For reference, this is what the [Prisma schema](../reference/tools-and-interfaces/prisma-schema/prisma-schema-file) for which your Prisma Client was generated looks like: + +```prisma +datasource db { + provider = "sqlite" + url = "file:./dev.db" +} + +generator client { + provider = "prisma-client-js" +} + +model Post { + id Int @id @default(autoincrement()) + title String + content String? + published Boolean @default(false) + author User? @relation(fields: [authorId], references: [id]) + authorId Int? +} + +model User { + id Int @id @default(autoincrement()) + email String @unique + name String? + posts Post[] +} +``` + The code inside `src/index.ts` currently looks as follows: @@ -475,8 +504,19 @@ const deletedUser = await prisma.user.delete({ To learn how to connect Prisma to your own database, you can follow the respective setup guide: -- [Setup a new project with Prisma from scratch](./setup-prisma/start-from-scratch-sql) -- [Add Prisma to an existing project](./setup-prisma/add-to-an-existing-project) + + Setup a new project from scratch + + +
+
+ + + Add Prisma to an existing project + + + --- @@ -558,7 +598,6 @@ Now you can run the migration against the database `npx prisma migrate up --expe - Finally, re-generate Prisma Client with this command: ``` copy @@ -579,17 +618,17 @@ The [`prisma-examples`](https://github.com/prisma/prisma-examples/) repository c | Demo | Stack | Description | | :----------------------------------------------------------------------------------------------------------------- | :----------- | --------------------------------------------------------------------------------------------------- | -| [`rest-nextjs`](https://github.com/prisma/prisma-examples/typescript/rest-nextjs) | Fullstack | Simple [Next.js](https://nextjs.org/) app (React) with a REST API | -| [`graphql-nextjs`](https://github.com/prisma/prisma-examples/typescript/graphql-nextjs) | Fullstack | Simple [Next.js](https://nextjs.org/) app (React) with a GraphQL API | -| [`graphql-apollo-server`](https://github.com/prisma/prisma-examples/typescript/graphql-apollo-server) | Backend only | Simple GraphQL server based on [`apollo-server`](https://www.apollographql.com/docs/apollo-server/) | -| [`rest-express`](https://github.com/prisma/prisma-examples/typescript/rest-express) | Backend only | Simple REST API with Express.JS | -| [`grpc`](https://github.com/prisma/prisma-examples/typescript/grpc) | Backend only | Simple gRPC API | +| [`rest-nextjs`](https://github.com/prisma/prisma-examples/tree/prisma2/typescript/rest-nextjs) | Fullstack | Simple [Next.js](https://nextjs.org/) app (React) with a REST API | +| [`graphql-nextjs`](https://github.com/prisma/prisma-examples/tree/prisma2/typescript/graphql-nextjs) | Fullstack | Simple [Next.js](https://nextjs.org/) app (React) with a GraphQL API | +| [`graphql-apollo-server`](https://github.com/prisma/prisma-examples/tree/prisma2/typescript/graphql-apollo-server) | Backend only | Simple GraphQL server based on [`apollo-server`](https://www.apollographql.com/docs/apollo-server/) | +| [`rest-express`](https://github.com/prisma/prisma-examples/tree/prisma2/typescript/rest-express) | Backend only | Simple REST API with Express.JS | +| [`grpc`](https://github.com/prisma/prisma-examples/tree/prisma2/typescript/grpc) | Backend only | Simple gRPC API | **JavaScript (Node.js)** | Demo | Stack | Description | | :----------------------------------------------------------------------------------------------------------------- | :----------- | :-------------------------------------------------------------------------------------------------- | -| [`rest-nextjs`](https://github.com/prisma/prisma-examples/javascript/rest-nextjs) | Fullstack | Simple [Next.js](https://nextjs.org/) app (React) with a REST API | -| [`graphql-apollo-server`](https://github.com/prisma/prisma-examples/javascript/graphql-apollo-server) | Backend only | Simple GraphQL server based on [`apollo-server`](https://www.apollographql.com/docs/apollo-server/) | -| [`rest-express`](https://github.com/prisma/prisma-examples/javascript/rest-express) | Backend only | Simple REST API with Express.JS | -| [`grpc`](https://github.com/prisma/prisma-examples/javascript/grpc) | Backend only | Simple gRPC API | +| [`rest-nextjs`](https://github.com/prisma/prisma-examples/tree/prisma2/javascript/rest-nextjs) | Fullstack | Simple [Next.js](https://nextjs.org/) app (React) with a REST API | +| [`graphql-apollo-server`](https://github.com/prisma/prisma-examples/tree/prisma2/javascript/graphql-apollo-server) | Backend only | Simple GraphQL server based on [`apollo-server`](https://www.apollographql.com/docs/apollo-server/) | +| [`rest-express`](https://github.com/prisma/prisma-examples/tree/prisma2/javascript/rest-express) | Backend only | Simple REST API with Express.JS | +| [`grpc`](https://github.com/prisma/prisma-examples/tree/prisma2/javascript/grpc) | Backend only | Simple gRPC API | diff --git a/content/01-getting-started/02-setup-prisma/01-add-to-an-existing-project.mdx b/content/01-getting-started/02-setup-prisma/01-add-to-an-existing-project.mdx index be4c26ae62..a98e4f2dda 100644 --- a/content/01-getting-started/02-setup-prisma/01-add-to-an-existing-project.mdx +++ b/content/01-getting-started/02-setup-prisma/01-add-to-an-existing-project.mdx @@ -20,6 +20,8 @@ This page walks you through the process of adding Prisma to a **Node.js** projec +You can also watch this short [video series](https://www.youtube.com/playlist?list=PLn2e1F9Rfr6k9PnR_figWOcSHgc_erDr5) that shows the Prisma setup process with an existing database. + ## Prerequisites In order to successfully complete this guide, you need: diff --git a/content/01-getting-started/02-setup-prisma/02-start-from-scratch-sql.mdx b/content/01-getting-started/02-setup-prisma/02-start-from-scratch-sql.mdx index fc4216b4a8..3e95edc0c5 100644 --- a/content/01-getting-started/02-setup-prisma/02-start-from-scratch-sql.mdx +++ b/content/01-getting-started/02-setup-prisma/02-start-from-scratch-sql.mdx @@ -1,6 +1,6 @@ --- title: 'Start from scratch' -metaTitle: 'Setup a new projecct with Prisma from scratch (15 min)' +metaTitle: 'Setup a new project with Prisma from scratch (SQL)' metaDescription: 'Learn how to create a new Node.js or TypeScript project from scratch by connecting Prisma to your database and generating Prisma Client for database access.' dbSwitcher: true langSwitcher: true diff --git a/content/01-getting-started/02-setup-prisma/03-start-from-scratch-prisma-migrate.mdx b/content/01-getting-started/02-setup-prisma/03-start-from-scratch-prisma-migrate.mdx new file mode 100644 index 0000000000..64ffc558cc --- /dev/null +++ b/content/01-getting-started/02-setup-prisma/03-start-from-scratch-prisma-migrate.mdx @@ -0,0 +1,764 @@ +--- +title: 'Start from scratch (Prisma Migrate)' +metaTitle: 'Setup a new project with Prisma from scratch (Prisma Migrate)' +metaDescription: 'Learn how to create a new Node.js or TypeScript project from scratch by connecting Prisma to your database and generating Prisma Client for database access.' +dbSwitcher: true +langSwitcher: true +--- + +## Overview + +This page walks you through the process of setting up Prisma from scratch with your own database. It uses [Prisma Migrate](../../../reference/tools-and-interfaces/prisma-migrate) to create tables in your database. + +> **Note**: Prisma Migrate is currently considered experimental. + +## Prerequisites + +In order to successfully complete this guide, you need: + + + +- [Node.js](https://nodejs.org/en/) installed on your machine +- a [PostgreSQL](https://www.postgresql.org/) database server running + + + + + +- [Node.js](https://nodejs.org/en/) installed on your machine +- a [MySQL](https://www.mysql.com/) database server running + + + +Make sure your have your database [connection URL](../../reference/tools-and-interfaces/database-connectors/connection-urls) (includes your authentication credentials) at hand! + +If you don't have a database server running and only want to explore Prisma, check out the [Quickstart](../quickstart). Alternatively you can [setup a free PostgreSQL database on Heroku](https://dev.to/prisma/how-to-setup-a-free-postgresql-database-on-heroku-1dc1) and use it in this guide. + +## Create project setup + +As a first step, create a project directory and navigate into it: + +``` +mkdir hello-prisma +cd hello-prisma +``` + + + +Next, initialize a TypeScript project and add the Prisma CLI as a development dependency to it: + +``` +npm init -y +npm install @prisma/cli typescript ts-node @types/node --save-dev +``` + +This creates a `package.json` with an initial setup for your TypeScript app. + +Next, create a `tsconfig.json` file and add the following configuration to it: + +```json +{ + "compilerOptions": { + "sourceMap": true, + "outDir": "dist", + "strict": true, + "lib": ["esnext"], + "esModuleInterop": true + } +} +``` + + + + + +Next, initialize a Node.js project and add the Prisma CLI as a development dependency to it: + +``` +npm init -y +npm install @prisma/cli --save-dev +``` + +This creates a `package.json` with an initial setup for a Node.js app. + + + +You can now invoke the Prisma CLI by prefixing it with `npx`: + +``` +npx prisma +``` + +Next, set up your Prisma project by creating your [Prisma schema](../../reference/tools-and-interfaces/prisma-schema/prisma-schema-file) file with the following command: + +``` +npx prisma init +``` + +This command created a new directory called `prisma` with the following contents: + +- `schema.prisma`: The Prisma schema with your database connection and the Prisma Client generator +- `.env`: A [dotenv](https://github.com/motdotla/dotenv) file for defining environment variables (used for your database connection) + +## Connect your database + +To connect your database, you need to set the `url` field of the `datasource` block in your Prisma schema to your database [connection URL](../../reference/tools-and-interfaces/database-connectors/connection-urls): + + + +```prisma +datasource postgresql { + provider = "postgresql" + url = env("DATABASE_URL") +} +``` + +In this case, the `url` is [set via an environment variable](../../reference/tools-and-interfaces/prisma-schema/prisma-schema-file#using-environment-variables) which is defined in `prisma/.env`: + +``` +DATABASE_URL="postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public" +``` + +You now need to adjust the connection URL to point to your own database. + +The format of the connection URL for your database typically depends on the database you use. For PostgreSQL, it looks as follows (the parts spelled all-uppercased are _placeholders_ for your specific connection details): + +``` +postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA +``` + +Here's a short explanation of each component: + +- `USER`: The name of your database user +- `PASSWORD`: The password your database user +- `PORT`: The port where your database server is running (typically `5432` for PostgreSQL) +- `DATABASE`: The name of the [database](https://www.postgresql.org/docs/12/manage-ag-overview.html) +- `SCHEMA`: The name of the [schema](https://www.postgresql.org/docs/12/ddl-schemas.html) inside the database + +If you're unsure what to provide for the `schema` parameter for a PostgreSQL connection URL, you can probably omit it. In that case, the default schema name `public` will be used. + +As an example, for a PostgreSQL database hosted on Heroku, the [connection URL](../../reference/tools-and-interfaces/database-connectors/connection-urls) might look similar to this: + +``` +DATABASE_URL="postgresql://opnmyfngbknppm:XXX@ec2-46-137-91-216.eu-west-1.compute.amazonaws.com:5432/d50rgmkqi2ipus?schema=hello-prisma" +``` + +When running PostgreSQL locally, your user and password as well as the database name _typically_ correspond to the current _user_ of your OS, e.g. assuming the user is called `janedoe`: + +``` +DATABASE_URL="postgresql://janedoe:janedoe@localhost:5432/janedoe?schema=hello-prisma" +``` + + + + + +```prisma +datasource postgresql { + provider = "postgresql" + url = env("DATABASE_URL") +} +``` + +Note that the default schema created by `prisma init` uses PostgreSQL, so you first need to switch the `provider` to `mysql`: + +```prisma +datasource mysql { + provider = "mysql" + url = env("DATABASE_URL") +} +``` + +In this case, the `url` is [set via an environment variable](../../reference/tools-and-interfaces/prisma-schema/prisma-schema-file#using-environment-variables) which is defined in `prisma/.env`: + +``` +DATABASE_URL="mysql://johndoe:randompassword@localhost:3306/mydb" +``` + +You now need to adjust the connection URL to point to your own database. + +The format of the connection URL for your database typically depends on the database you use. For MySQL, it looks as follows (the parts spelled all-uppercased are _placeholders_ for your specific connection details): + +``` +mysql://USER:PASSWORD@HOST:PORT/DATABASE +``` + +Here's a short explanation of each component: + +- `USER`: The name of your database user +- `PASSWORD`: The password your database user +- `PORT`: The port where your database server is running (typically `3306` for MySQL) +- `DATABASE`: The name of the [database](https://dev.mysql.com/doc/refman/8.0/en/creating-database.html) + +As an example, for a MySQL database hosted on AWS RDS, the [connection URL](../../reference/tools-and-interfaces/database-connectors/connection-urls) might look similar to this: + +``` +DATABASE_URL="mysql://johndoe:XXX@mysql–instance1.123456789012.us-east-1.rds.amazonaws.com:3306/mydb +``` + +When running MySQL locally, your connection URL typically looks similar to this: + +``` +DATABASE_URL="mysql://root:randompassword@localhost:3306/mydb" +``` + + + +## Create database tables with Prisma Migrate + + + +In this guide, you'll use [Prisma Migrate](../../../reference/tools-and-interfaces/prisma-migrate) to create the tables in your database. Add the following Prisma data model to your Prisma schema in `prisma/schema.prisma`: + + + +```prisma +model Post { + id Int @default(autoincrement()) @id + createdAt DateTime @default(now()) + title String + content String? + published Boolean @default(false) + author User @relation(fields: [authorId], references: [id]) + authorId Int + + @@index([authorId], name: "authorId") +} + +model Profile { + id Int @default(autoincrement()) @id + bio String? + user User @relation(fields: [userId], references: [id]) + userId Int @unique +} + +model User { + id Int @default(autoincrement()) @id + email String @unique + name String? + Post Post[] + Profile Profile? +} +``` + +```sql +CREATE TABLE "public"."User" ( + id SERIAL PRIMARY KEY NOT NULL, + name VARCHAR(255), + email VARCHAR(255) UNIQUE NOT NULL +); + +CREATE TABLE "public"."Post" ( + id SERIAL PRIMARY KEY NOT NULL, + title VARCHAR(255) NOT NULL, + "createdAt" TIMESTAMP NOT NULL DEFAULT now(), + content TEXT, + published BOOLEAN NOT NULL DEFAULT false, + author INTEGER NOT NULL, + FOREIGN KEY (author) REFERENCES "public"."User"(id) +); + +CREATE TABLE "public"."Profile" ( + id SERIAL PRIMARY KEY NOT NULL, + bio TEXT, + "user" INTEGER UNIQUE NOT NULL, + FOREIGN KEY ("user") REFERENCES "public"."User"(id) +); +``` + + + + + + + +```prisma +model Post { + id Int @default(autoincrement()) @id + createdAt DateTime @default(now()) + title String + content String? + published Boolean @default(false) + author User @relation(fields: [authorId], references: [id]) + authorId Int + + @@index([authorId], name: "authorId") +} + +model Profile { + id Int @default(autoincrement()) @id + bio String? + user User @relation(fields: [userId], references: [id]) + userId Int @unique +} + +model User { + id Int @default(autoincrement()) @id + email String @unique + name String? + Post Post[] + Profile Profile? +} +``` + +```sql +CREATE TABLE User ( + id INTEGER PRIMARY KEY AUTO_INCREMENT NOT NULL, + name VARCHAR(255), + email VARCHAR(255) UNIQUE NOT NULL +); + +CREATE TABLE Post ( + id INTEGER PRIMARY KEY AUTO_INCREMENT NOT NULL, + title VARCHAR(255) NOT NULL, + createdAt TIMESTAMP NOT NULL DEFAULT now(), + content TEXT, + published BOOLEAN NOT NULL DEFAULT false, + authorId INTEGER NOT NULL, + FOREIGN KEY (authorId) REFERENCES User(id) +); + +CREATE TABLE Profile ( + id INTEGER PRIMARY KEY AUTO_INCREMENT NOT NULL, + bio TEXT, + userId INTEGER UNIQUE NOT NULL, + FOREIGN KEY (userId) REFERENCES User(id) +); +``` + + + +To map your data model to the databse schema, you need to use the `prisma migrate` CLI commands: + +``` +npx prisma migrate save --name init --experimental +npx prisma migrate up --experimental +``` + +The `save` command creates a new directory called `migrations` where it will store your migration history, it does not yet create any tables in the database. The tables are created when `up` is invoked! + +Great, you now created three tables in your database with Prisma Migrate 🚀 + +
Expand for a graphical overview of the tables + +**User** + +| Column name | Type | Primary key | Foreign key | Required | Default | +| :---------- | :------------- | :---------- | :---------- | :------- | :----------------- | +| `id` | `INTEGER` | **✔️** | No | No | _autoincrementing_ | +| `name` | `VARCHAR(255)` | No | No | No | - | +| `email` | `VARCHAR(255)` | No | No | **✔️** | - | + +**Post** + +| Column name | Type | Primary key | Foreign key | Required | Default | +| :---------- | :------------- | :---------- | :---------- | :------- | :----------------- | +| `id` | `INTEGER` | **✔️** | No | No | _autoincrementing_ | +| `createdAt` | `TIMESTAMP` | No | No | **✔️** | `now()` | +| `title` | `VARCHAR(255)` | No | No | **✔️** | - | +| `content` | `TEXT` | No | No | No | - | +| `published` | `BOOLEAN` | No | No | **✔️** | `false` | +| `authorId` | `INTEGER` | No | **✔️** | **✔️** | `false` | + +**Profile** + +| Column name | Type | Primary key | Foreign key | Required | Default | +| :---------- | :-------- | :---------- | :---------- | :------- | :----------------- | +| `id` | `INTEGER` | **✔️** | No | No | _autoincrementing_ | +| `bio` | `TEXT` | No | No | **✔️** | - | +| `userId` | `INTEGER` | No | **✔️** | **✔️** | - | + +
+ +## Install and generate Prisma Client + +To get started with Prisma Client, you need to install it as a node module: + +``` +npm install @prisma/client +``` + +Notice that the [`@prisma/client` node module](../../reference/tools-and-interfaces/prisma-client/configuring-the-prisma-client-api#the-prisma-client-npm-module) is a bit different from "conventional" node modules (e.g. a library like [`lodash`](https://lodash.com/)). When installing the module with `npm install @prisma/client`, npm only downloads an empty package into the `node_modules/@prisma/client` directory. The package is then "filled" with the actual library with the following command of the Prisma CLI: + +``` +npx prisma generate +``` + +This commands reads your Prisma schema and generates your Prisma Client library into `node_modules/@prisma/client`. + +![](https://imgur.com/FensWfo.png) + +Because the `@prisma/client` node module actually is customized to your project, it is sometimes referred to as a "smart node module": + +![](https://i.imgur.com/83djlkl.png) + +## Write your first query with Prisma Client + +Now that you generated your Prisma Client library, you can start writing queries to read and write data in your database. For the purpose of this guide, you'll use a plain Node.js script to explore some basic features of Prisma Client. + + + +Create a new file called `index.ts` and add the following code to it: + +```js +import { PrismaClient } from "@prisma/client" + +const prisma = new PrismaClient() + +async function main() { + // ... you will write your Prisma Client queries here +} + +main() + .catch(e => { + throw e + }) + .finally(async () => { + await prisma.disconnect() + }) +``` + + + + + +Create a new file called `index.js` and add the following code to it: + +```js +const { PrismaClient } = require("@prisma/client") + +const prisma = new PrismaClient() + +async function main() { + // ... you will write your Prisma Client queries here +} + +main() + .catch(e => { + throw e + }) + .finally(async () => { + await prisma.disconnect() + }) +``` + + + +Here's a quick overview of the different parts of the code snippet: + +1. Import the `PrismaClient` constructor from the `@prisma/client` node module +1. Instantiate `PrismaClient` +1. Define an `async` function called `main` to send queries to the database +1. Call the `main` function +1. Close the database connections when the script terminates + +Inside the `main` function, add the folowing query to read all `User` records from the database and print the result: + +```js +async function main() { + const allUsers = await prisma.user.findMany() + console.log(allUsers) +} +``` + +Now run the code with this command: + +``` +node index.js +``` + +This should print an empty arrays because there are no `User` records in the database yet: + +```js +[] +``` + +## Write data into the database + +The `findMany` query you used in the previous section only _reads_ data from the database (although it was still empty). In this section, you'll learn how to write a query to _write_ new records into the `Post` and `User` tables. + +Adjust the `main` function to send a `create` query to the database: + +```js +async function main() { + + await prisma.user.create({ + data: { + name: "Alice", + email: "alice@prisma.io", + author: { + create: { title: "Hello World" }, + }, + profile: { + create: { bio: "I like turtles" } + } + } + }) + + const allUsers = await prisma.user.findMany({ + include: { + posts: true, + profile: true + }, + }) + console.dir(allUsers, { depth: null }) +} +``` + +This code creates a new `User` record together with new `Post` and `Profile` records using a [nested write](#nested-writes) query. The `User` record is connected to the two other ones via the `Post.author` ↔ `User.posts` and `Profile.user` ↔ `User.profile` [relation fields](../../reference/tools-and-interfaces/prisma-schema/relations#relation-fields) respectively. + +Notice that you're passing the [`include`](../../reference/tools-and-interfaces/prisma-client/field-selection#include) option to `findMany` which tells Prisma Client to include the `posts` and `profile` relations on the returned `User` objects. + + + +Run the code with this command: + +``` +npx ts-node index.ts +``` + + + + + +Run the code with this command: + +``` +npx ts-node index.ts +``` + + + + + +Run the code with this command: + +``` +node index.js +``` + + + +The output should look similar to this: + +```js +[ + { + email: 'alice@prisma.io', + id: 1, + name: 'Alice', + posts: [ + { + content: null, + createdAt: 2020-03-21T16:45:01.246Z, + id: 1, + published: false, + title: 'Hello World', + authorId: 1, + } + ], + profile: { + bio: 'I like turtles', + userId: 1, + } + } +] +``` + + + +Also note that `allUsers` is _statically typed_ thanks to [Prisma Client's generated types](../../reference/tools-and-interfaces/prisma-client/advanced-usage-of-generated-types). You can observe the type by hovering over the `allUsers` variable in your editor. It should be typed as follows: + +```ts +const allUsers: (User & { + posts: Post[]; +})[] + +export type Post = { + id: number + title: string + content: string | null + published: boolean + authorId: number | null +} +``` + + + +The query added new records to the `User` and the `Post` tables: + +**User** + +| **id** | **email** | **name** | +| :----- | :------------------ | :-------- | +| `1` | `"alice@prisma.io"` | `"Alice"` | + +**Post** + +| **id** | **createdAt** | **title** | **content** | **published** | **authorId** | +| :----- | :------------------------- | :-------------- | :---------- | :------------ | :--------- | +| `1` | `2020-03-21T16:45:01.246Z` | `"Hello World"` | `null` | `false` | `1` | + +**Profile** + +| **id** | **bio** | **userId** | +| :----- | :------------------ | :-------- | +| `1` | `"I like turtles"` | `1` | + +> **Note**: The numbers in the `authorId` column on `Post` and `userId` column on `Profile` both reference the `id` column of the `User` table: the `id` value `1` column therefore refers to the first (and only) `User` record in the database. + +Before moving on to the next section, you'll "publish" the `Post` record you just created using an `update` query. Adjust the `main` function as follows: + +```js +async function main() { + const post = await prisma.post.update({ + where: { id: 1 }, + data: { published: true }, + }) + console.log(post) +} +``` + + + +Now run the code using the same command as before: + +``` +npx ts-node index.ts +``` + + + + + +Now run the code using the same command as before: + +``` +node index.js +``` + + + +You will see the following output: + +```js +{ + id: 1, + title: 'Hello World', + content: null, + published: true, + authorId: 1 +} +``` + +The `Post` record with an `id` of `1` now got updated in the database: + +**Post** + +| **id** | **title** | **content** | **published** | **authorId** | +| :----- | :------------------------------ | :---------- | :------------ | :--------- | +| `1` | `"Hello World"` | `null` | `true` | `1` | + +Fantastic, you just wrote new data into your database for the first time using Prisma Client 🚀 + +## Next steps + +This section lists a number of potential next steps you can now take from here. Feel free to explore those or read the [Introduction](../../understand-prisma/introduction) page to get a high-level overview of Prisma. + +### Continue exploring the Prisma Client API + +You can send a variety of different queries with the Prisma Client API. Check out the [API reference](../../reference/tools-and-interfaces/prisma-client/api) and use your existing database setup from this guide to try them out. + +**Tip**: You can use your editor's auto-completion feature to learn about the different API calls and the arguments it takes. Auto-completion is commonly invoked by hitting CTRL+SPACE on your keyboard. + +
Expand for more Prisma Client API examples + +Here are a few suggestions for a number of more queries you can send with Prisma Client: + +**Filter all `Post` records that contain `"hello"`** + +```js +const filteredPosts = await prisma.post.findMany({ + where: { + OR: [ + { title: { contains: "hello" }, + { content: { contains: "hello" }, + ], + }, +}) +``` + +**Create a new `Post` record and connect it to an existing `User` record** + +```js +const post = await prisma.post.create({ + data: { + title: "Join us for Prisma Day 2020", + posts: { + connect: { email: "alice@prisma.io" }, + }, + }, +}) +``` + +**Use the fluent relations API to retrieve the `Post` records of a `User` by traversing the relations** + +```js +const posts = await prisma.profile + .findOne({ + where: { id: 1 }, + }) + .user() + .posts() +``` + +**Delete a `User` record** + +```js +const deletedUser = await prisma.user.delete({ + where: { email: "sarah@prisma.io" }, +}) +``` + +
+ +--- + +### Explore the data in Prisma Studio (experimental) + +Prisma Studio is a visual editor for the data in your database. You can use it by running the following command: + +``` +npx prisma studio --experimental +``` + +--- + +### Try a Prisma example + +The [`prisma-examples`](https://github.com/prisma/prisma-examples/) repository contains a number of ready-to-run examples: + +**TypeScript** + +| Demo | Stack | Description | +| :----------------------------------------------------------------------------------------------------------------- | :----------- | --------------------------------------------------------------------------------------------------- | +| [`rest-nextjs`](https://github.com/prisma/prisma-examples/tree/prisma2/typescript/rest-nextjs) | Fullstack | Simple [Next.js](https://nextjs.org/) app (React) with a REST API | +| [`graphql-nextjs`](https://github.com/prisma/prisma-examples/tree/prisma2/typescript/graphql-nextjs) | Fullstack | Simple [Next.js](https://nextjs.org/) app (React) with a GraphQL API | +| [`graphql-apollo-server`](https://github.com/prisma/prisma-examples/tree/prisma2/typescript/graphql-apollo-server) | Backend only | Simple GraphQL server based on [`apollo-server`](https://www.apollographql.com/docs/apollo-server/) | +| [`rest-express`](https://github.com/prisma/prisma-examples/tree/prisma2/typescript/rest-express) | Backend only | Simple REST API with Express.JS | +| [`grpc`](https://github.com/prisma/prisma-examples/tree/prisma2/typescript/grpc) | Backend only | Simple gRPC API | + +**JavaScript (Node.js)** + +| Demo | Stack | Description | +| :----------------------------------------------------------------------------------------------------------------- | :----------- | :-------------------------------------------------------------------------------------------------- | +| [`rest-nextjs`](https://github.com/prisma/prisma-examples/tree/prisma2/javascript/rest-nextjs) | Fullstack | Simple [Next.js](https://nextjs.org/) app (React) with a REST API | +| [`graphql-apollo-server`](https://github.com/prisma/prisma-examples/tree/prisma2/javascript/graphql-apollo-server) | Backend only | Simple GraphQL server based on [`apollo-server`](https://www.apollographql.com/docs/apollo-server/) | +| [`rest-express`](https://github.com/prisma/prisma-examples/tree/prisma2/javascript/rest-express) | Backend only | Simple REST API with Express.JS | +| [`grpc`](https://github.com/prisma/prisma-examples/tree/prisma2/javascript/grpc) | Backend only | Simple gRPC API | + + + + + + diff --git a/content/02-understand-prisma/05-under-the-hood.mdx b/content/02-understand-prisma/05-under-the-hood.mdx index 6199cbea29..4eb83f0009 100644 --- a/content/02-understand-prisma/05-under-the-hood.mdx +++ b/content/02-understand-prisma/05-under-the-hood.mdx @@ -21,7 +21,7 @@ The tools in the Prisma toolkit are built with respect to two dimensions: The following illustration gives an overview of the tools that exist (or are planned) in the Prisma toolkit: -![](https://imgur.com/NoTXRqT.png) +![](https://i.imgur.com/mxJTGOu.png) ### Modules diff --git a/content/03-reference/01-tools-and-interfaces/02-prisma-client/01-api.mdx b/content/03-reference/01-tools-and-interfaces/02-prisma-client/01-api.mdx index 9a590271bf..a1fd19fe4f 100644 --- a/content/03-reference/01-tools-and-interfaces/02-prisma-client/01-api.mdx +++ b/content/03-reference/01-tools-and-interfaces/02-prisma-client/01-api.mdx @@ -8,10 +8,23 @@ metaDescription: "This page gives an overview of the Prisma Client API and links Prisma Client is an auto-generated and type-safe query builder that's _tailored_ to your data. The easiest way to get started with Prisma Client is by following the **[Quickstart](../../../getting-started/quickstart)**. + + + Quickstart (5 min) + + The setup instruction below provide a high-level overview of the steps needed to set up Prisma Client. If you want to get started using Prisma Client with your own database, follow one of these guides: -- [Setup a new project with Prisma from scratch](../../../setup-prisma/start-from-scratch-sql) -- [Add Prisma to an existing project](../../../setup-prisma/add-to-an-existing-project) + + Setup a new project from scratch + + +
+
+ + + Add Prisma to an existing project + ## Setup diff --git a/content/03-reference/01-tools-and-interfaces/02-prisma-client/06-field-selection.mdx b/content/03-reference/01-tools-and-interfaces/02-prisma-client/06-field-selection.mdx index cd1c078cbf..10761d10a1 100644 --- a/content/03-reference/01-tools-and-interfaces/02-prisma-client/06-field-selection.mdx +++ b/content/03-reference/01-tools-and-interfaces/02-prisma-client/06-field-selection.mdx @@ -1,7 +1,7 @@ --- title: 'Field selection' metaTitle: 'Field selection (Reference)' -metaDescription: 'This page explains how to select only a subset of a model''s fields and/or include relations ("eager loading") in a Prisma Client query.' +metaDescription: "This page explains how to select only a subset of a model's fields and/or include relations (\"eager loading\") in a Prisma Client query." --- ## Overview diff --git a/content/index.mdx b/content/index.mdx index 7cd13b0337..f3eb440cde 100644 --- a/content/index.mdx +++ b/content/index.mdx @@ -10,6 +10,20 @@ Welcome to the Prisma documentation! You can find an overview of the available c > **If you're using Prisma 1, please refer to the [Prisma 1 documentation](https://www.prisma.io/docs/1.34).** +## Explore + + + Quickstart (5 min) + + +
+
+ + + Read Prisma introduction + + + ## Table of contents ---