Getting started

Quickstart

CONTENT

Overview
Prerequisites
Download SQLite starter project & install dependencies
Write your first query with Prisma Client
Write data into the database
Next steps

Overview

This page explains how to get started with Prisma in five minutes. You will learn how to send queries to a SQLite database in a plain TypeScript script using Prisma Client.

This page explains how to get started with Prisma in five minutes. You will learn how to send queries to a SQLite database in a plain Node.js script using Prisma Client.

For demonstration purposes of this guide, you will use a local SQLite database file. This guide does not cover the Prisma setup process.

Expand if you want to set up Prisma with your own database instead of using SQLite

If you're looking to set up Prisma with your own database, you have these options:

Prerequisites

The only requirement for this guide is to have Node.js (version 10 or higher) installed on your machine.

TypeScript will be added as a local dependency to the project, so no need to install it.

The only requirement for this guide is to have Node.js (version 10 or higher) installed on your machine.

Download SQLite starter project & install dependencies

This guide uses a small starter project that has Prisma configured against a SQLite database file.

Open your terminal and download the starter project with the following command:

Unix (Mac OS, Linux)

Windows


curl https://codeload.github.com/prisma/prisma-examples/tar.gz/starter | tar -xz --strip=2 prisma-examples-starter/typescript/starter

Unix (Mac OS, Linux)

Windows


curl https://codeload.github.com/prisma/prisma-examples/tar.gz/starter | tar -xz --strip=2 prisma-examples-starter/javascript/starter

The project is downloaded to directory called starter.

Expand for more info on the starter project

The starter project consists of six files:

package.json: Defines your npm dependencies
prisma/schema.prisma: Prisma schema file defining your models
prisma/.env: Defines your database connection URL as an environment variable
prisma/dev.db: A SQLite database file
script.ts: A plain, executable TypeScript script
tsconfig.json: TypeScript configuration

Note that the dependencies defined in your project are:

@prisma/cli: The Prisma CLI which you can invoke with npx prisma
@prisma/client: Prisma Client library for accessing your database
typescript: TypeScript toolchain
ts-node: Used to execute the TypeScript script

The starter project consists of five files:

package.json: Defines your npm dependencies
prisma/schema.prisma: Prisma schema file defining your models
prisma/.env: Defines your database connection URL as an environment variable
prisma/dev.db: A SQLite database file
script.js: A plain, executable Node.js script

Note that the only two dependencies defined in your project are:

@prisma/cli: The Prisma CLI which you can invoke with npx prisma
@prisma/client: Prisma Client library for accessing your database

The SQLite database file prisma/dev.db contains two tables with dummy data:

User

id	email	name
`1`	`"sarah@prisma.io"`	`"Sarah"`
`2`	`"maria@prisma.io"`	`"Maria"`

Post

id	title	content	published	authorId
`1`	`"Hello World"`	`null`	`false`	`2`

Note: The authorId column references the id column of the User table: the 2 in the authorId column refers to the User record with an id value of 2.

Before you move on, navigate into the starter directory and install the npm dependencies with these commands:


cd starter
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 looks like that your Prisma Client was generated from:

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}
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 script.ts currently looks as follows:

import { PrismaClient } from "@prisma/client"
const prisma = new PrismaClient()
// A `main` function so that you can use async/await
async function main() {
  // ... you will write your Prisma Client queries here
}
main()
  .catch(e => {
    throw e
  })
  .finally(async () => {
    await prisma.disconnect()
  })

The code inside script.js currently looks as follows:

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()
  })

Expand for an explanation of the script

Here's a quick overview of the main parts:

Import the PrismaClient constructor from the @prisma/client node module
Instantiate PrismaClient
Define an async function called main to send queries to the database
Call the main function
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:


async function main() {
  const allUsers = await prisma.user.findMany()
  console.log(allUsers)
}

Now run the code with this command:


npm run dev

This should print following result to output:

[
  { id: 1, email: "sarah@prisma.io", name: "Sarah" },
  { id: 2, email: "maria@prisma.io", name: "Maria" },
]

One of the main features of Prisma Client is the ease of working with relations. You can retrieve the posts of each user by using the include option. Adjust your code to look as follows:


async function main() {
  const allUsers = await prisma.user.findMany({
    include: { posts: true },
  })
  // use `console.dir` to print nested objects
  console.dir(allUsers, { depth: null })
}

Run the code again with:


npm run dev

Each object inside allUsers now includes a posts field that represents data retrieved by following the relation between the User and Post tables:

[
  { id: 1, email: 'sarah@prisma.io', name: 'Sarah', posts: [] },
  {
    id: 2,
    email: 'maria@prisma.io',
    name: 'Maria',
    posts: [
      {
        id: 1,
        title: 'Hello World',
        content: null,
        published: false,
        authorId: 2
      }
    ]
  }
]

Also note that allUsers is statically typed thanks to Prisma Client's generated types. You can observe the type by hovering over the allUsers variable in your editor. It should be typed as follows:

const allUsers: (User & {
    posts: Post[];
})[]
export type Post = {
  id: number
  title: string
  content: string | null
  published: boolean
  authorId: number | null
}

Congratulations, you just wrote your first query with Prisma Client 🎉

Write data into the database

The findMany query you used in the previous section only reads data from the database. 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:


async function main() {
  const post = await prisma.post.create({
    data: {
      title: "Prisma makes databases easy",
      author: {
        connect: { email: "sarah@prisma.io" },
      },
    },
  })
  console.log(post)
  const allUsers = await prisma.user.findMany({
    include: { posts: true },
  })
  console.dir(allUsers, { depth: null })
}

This code creates a new Post record and connects it in a nested write to an existing User record.

Run the code with this command:


npm run dev

The output should look similar to this:

{
  id: 2,
  title: 'Prisma makes databases easy',
  content: null,
  published: false,
  authorId: 1
}
[
  {
    id: 1,
    email: 'sarah@prisma.io',
    name: 'Sarah',
    posts: [
      {
        id: 2,
        title: 'Prisma makes databases easy',
        content: null,
        published: false,
        authorId: 1
      }
    ]
  },
  {
    id: 2,
    email: 'maria@prisma.io',
    name: 'Maria',
    posts: [
      {
        id: 1,
        title: 'Hello World',
        content: null,
        published: false,
        authorId: 2
      }
    ]
  }
]

The query added a new record to the Post table:

Post

id	title	content	published	authorId
`1`	`"Hello World"`	`null`	`false`	`2`
`2`	`"Prisma makes databases easy"`	`null`	`false`	`1`

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:


async function main() {
  const post = await prisma.post.update({
    where: { id: 2 },
    data: { published: true },
  })
  console.log(post)
}

Now run the code using the same command as before:


npm run dev

You will see the following output:

{
  id: 2,
  title: 'Prisma makes databases easy',
  content: null,
  published: true,
  authorId: 1
}

The Post record with an id of 2 has been updated in the database:

Post

id	title	content	published	authorId
`1`	`"Hello World"`	`null`	`false`	`2`
`2`	`"Prisma makes databases easy"`	`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 these or read the Introduction page to get a high-level overview of Prisma.

Continue exploring the Prisma Client API

You can send a variety of queries with the Prisma Client API. Check out the API reference and use your existing SQLite-based 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 "prisma"


const filteredPosts = await prisma.post.findMany({
  where: {
    OR: [
      { title: { contains: "prisma" } },
      { content: { contains: "prisma" } },
    ],
  },
})

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


const user = await prisma.user.create({
  data: {
    name: "Nancy",
    email: "nancy@prisma.io",
    posts: {
      create: { title: "Join us for Prisma Day 2020" },
    },
  },
})

Use the fluent relations API to retrieve the Post records of a User


const posts = await prisma.user
  .findOne({
    where: { email: "sarah@prisma.io" },
  })
  .posts()

Delete a User record


const deletedUser = await prisma.user.delete({
  where: { email: "sarah@prisma.io" },
})

Set up Prisma with your own database

To learn how to connect Prisma to your own database, you can follow the respective setup guide.

Set up a new project from scratch

The following guides both explain how you can set up a new project from scratch using your own database as well as how to send queries with Prisma Client. The first one uses SQL migrations and introspection while the second one uses Prisma Migrate as the main Prisma workflow.

SQL migrations Prisma Migrate

Add Prisma to an existing npm project

When adding Prisma to an already existing npm project, you can obtain your initial data model through introspection.

Add Prisma to existing project

Explore the data in Prisma Studio (experimental)

Prisma Studio is a visual editor for the data in your database. You can run it with the following command:


npx prisma studio --experimental

Change the database schema (e.g. create more tables)

Changing your database schema using SQL typically happens with the following steps.

First, create a new table in your database, e.g. with this command in your terminal:

Unix (Mac OS, Linux)

Windows


sqlite3 ./prisma/dev.db \
'CREATE TABLE "Profile" (
  "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, 
  "bio" TEXT,
  "userId" INTEGER NOT NULL UNIQUE REFERENCES "User"(id) ON DELETE SET NULL
)'

Then, introspect your database with this command from the Prisma CLI:


npx prisma introspect

This updates your Prisma schema in prisma/schema.prisma.

Note that after the introspection, you might want to configure your Prisma Client API.

Alternative: Use Prisma Migrate (experimental)

Changing your database schema using Prisma Migrate typically happens with the following steps.

First, adjust the data model in your Prisma schema, e.g. by adding a new model:


model Profile {
  id     Int     @id @default(autoincrement())
  bio    String
  user   User    @relation(fields: [userId], references: [id])
  userId Int
}
model User {
  id      Int      @id @default(autoincrement())
  email   String   @unique
  name    String?
  posts   Post[]
  profile Profile?
}
model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  author    User?    @relation(fields: [authorId], references: [id])
  authorId  Int?
}

Next, create a new migration by running the following command:


npx prisma migrate save --name "add-profile" --experimental
npx prisma migrate up --experimental

Now you can run the migration against the database npx prisma migrate up --experimental.

Finally, re-generate Prisma Client with this command:


npx prisma generate

This updates the generated Prisma Client library in node_modules/@prisma/client.

You can now run queries against the new Profile table, e.g. using prisma.profile.findMany().

Try a Prisma example

The prisma-examples repository contains a number of ready-to-run examples:

TypeScript

Demo	Stack	Description
`rest-nextjs`	Fullstack	Simple Next.js app (React) with a REST API
`graphql-nextjs`	Fullstack	Simple Next.js app (React) with a GraphQL API
`graphql-apollo-server`	Backend only	Simple GraphQL server based on `apollo-server`
`rest-express`	Backend only	Simple REST API with Express.JS
`grpc`	Backend only	Simple gRPC API

JavaScript (Node.js)

Demo	Stack	Description
`rest-nextjs`	Fullstack	Simple Next.js app (React) with a REST API
`graphql-apollo-server`	Backend only	Simple GraphQL server based on `apollo-server`
`rest-express`	Backend only	Simple REST API with Express.JS
`grpc`	Backend only	Simple gRPC API

Was this helpful?

Edit this page on Github

Getting started

Quickstart

CONTENT

Overview

Prerequisites

Download SQLite starter project & install dependencies

Write your first query with Prisma Client

Write data into the database

Next steps

Continue exploring the Prisma Client API

Set up Prisma with your own database

Explore the data in Prisma Studio (experimental)

Change the database schema (e.g. create more tables)

Try a Prisma example

Was this helpful?

PRODUCTS

RESOURCES

COMMUNITY

COMPANY

NEWSLETTER

Getting started

Quickstart

CONTENT

Overview

Prerequisites

Download SQLite starter project & install dependencies

Write your first query with Prisma Client

Write data into the database

Next steps

Continue exploring the Prisma Client API

Set up Prisma with your own database

Explore the data in Prisma Studio (experimental)

Change the database schema (e.g. create more tables)

Try a Prisma example

Was this helpful?

PRODUCTS

RESOURCES

COMMUNITY

COMPANY

NEWSLETTER

FIND US