Skip to main content

Quickstart

Prisma Postgres

In this Quickstart guide, you'll learn how to get started from scratch with Prisma ORM and a Prisma Postgres database in a plain TypeScript project. It covers the following workflows:

Prerequisites​

To successfully complete this tutorial, you need:

1. Set up a Prisma Postgres database in the Platform Console​

Follow these steps to create your Prisma Postgres database:

  1. Log in to .
  2. In a workspace of your choice, click the New project button.
  3. Type a name for your project in the Name field, e.g. hello-ppg.
  4. In the Prisma Postgres section, click the Get started button.
  5. In the Region dropdown, select the region that's closest to your current location, e.g. US East (N. Virginia).
  6. Click the Create project button.

At this point, you'll be redirected to the Database page where you will need to wait for a few seconds while the status of your database changes from PROVISIONING, to ACTIVATING to CONNECTED.

Once the green CONNECTED label appears, your database is ready to use!

2. Download example and install dependencies​

Copy the try-prisma command that's shown in the Console, paste it into your terminal and execute it.

For reference, this is what the command looks like:

npx try-prisma@latest \
  --template databases/prisma-postgres \
  --name hello-prisma \
  --install npm

Once the try-prisma command has terminated, navigate into the project directory:

cd hello-prisma

3. Set database connection and Pulse API key​

The connection to your database and the Pulse API key are configured via environment variables in a .env file.

First, rename the existing .env.example file to just .env:

mv .env.example .env

Next, navigate back into the Console and click the Generate database credentials button.

Then, copy the resulting DATABASE_URL and PULSE_API_KEY environment variables and paste it into the .env file.

For reference, the file should now look similar to this:

DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=ey...."
PULSE_API_KEY="ey...."

4. Create database tables (with a schema migration)​

Next, you need to create the tables in your database. You can do this by creating and executing a schema migration with the following command of the Prisma CLI:

npx prisma migrate dev --name init

This will map the User and Post models that are defined in your Prisma schema to your database. You can also review the SQL migration that was executed and created the tables in the newly created prisma/migrations directory.

5. Execute queries with Prisma ORM​

The src/queries.ts script contains a number of CRUD queries that will write and read data in your database. You can execute it by running the following command in your terminal:

npm run queries

Once the script has completed, you can inspect the logs in your terminal or use Prisma Studio to explore what records have been created in the database:

npx prisma studio

6. Explore caching with Prisma Accelerate​

The src/caching.ts script contains a sample query that uses Stale-While-Revalidate (SWR) and Time-To-Live (TTL) to cache a database query using Prisma Accelerate. You can execute it as follows:

npm run caching

Take note of the time that it took to execute the query, e.g.:

The query took 2009.2467149999998ms.

Now, run the script again:

npm run caching

You'll notice that the time the query took will be a lot shorter this time, e.g.:

The query took 300.5655280000001ms.

7. Observe real-time events in your database​

The src/realtime.ts script contains a demo for receiving real-time change events from your database. You can start the script as follows:

npm run realtime

The script now created a stream that will receive database events and print them to the console whenever a write-operation (i.e. create, update or delete) happens on the User table.

To test the stream, you can open Prisma Studio:

npx prisma studio

... and make a change to the User table, e.g. create a new record. Once you've saved the change, you should see an output in the terminal that looks similar to this:

Received an event: {
  action: 'create',
  created: { id: 3, email: 'burk@prisma.io', name: 'Nikolas' },
  id: '01JAFNSZHQRDTW773BCAA9G7FJ',
  modelName: 'User'
}

8. Next steps​

In this Quickstart guide, you have learned how to get started with Prisma ORM in a plain TypeScript project. Feel free to explore the Prisma Client API a bit more on your own, e.g. by including filtering, sorting, and pagination options in the findMany query or exploring more operations like update and delete queries.

Explore the data in Prisma Studio​

Prisma ORM comes with a built-in GUI to view and edit the data in your database. You can open it using the following command:

npx prisma studio

Explore ready-to-run Prisma ORM examples​

Check out the prisma-examples repository on GitHub to see how Prisma ORM can be used with your favorite library. The repo contains examples with Express, NestJS, GraphQL as well as fullstack examples with Next.js and Vue.js, and a lot more.

Build real-time apps with Prisma Pulse​

Prisma Pulse enables you to create applications that instantly react to changes in your database, allowing you to build type-safe real-time features and applications easily:

DemoDescription
starterA Prisma Pulse starter app
email-with-resendAn example app to send emails to new users using Prisma Pulse and Resend
fullstack-leaderboardA live leaderboard (built with Next.js)
fullstack-simple-chatA simple chat app (built with Next.js & Express)
product-search-with-typesenseA cron job that syncs data into Typesense (built with Hono.js)
data-sync-with-bigqueryA script that automatically syncs data into Google BigQuery

Speed up your database queries with Prisma Accelerate​

Prisma Accelerate is a connection pooler and global database cache that can drastically speed up your database queries. Check out the Speed Test or try Accelerate with your favorite framework:

DemoDescription
nextjs-starterA Next.js project using Prisma Accelerate's caching and connection pooling
svelte-starterA SvelteKit project using Prisma Accelerate's caching and connection pooling
solidstart-starterA Solidstart project using Prisma Accelerate's caching and connection pooling
remix-starterA Remix project using Prisma Accelerate's caching and connection pooling
nuxt-starterA Nuxt.js project using Prisma Accelerate's caching and connection pooling
astro-starterAn Astro project using Prisma Accelerate's caching and connection pooling

Build an app with Prisma ORM​

The Prisma blog features comprehensive tutorials about Prisma ORM, check out our latest ones:

Join the Prisma community 💚​

Prisma has a huge community of developers. Join us on Discord or ask questions using GitHub Discussions.