add ppg quickstart

prisma · Oct 22, 2024 · 8438781 · 8438781
1 parent 6d34cdf
commit 8438781
Show file tree

Hide file tree

Showing 33 changed files with 2,472 additions and 2,645 deletions.
diff --git a/content/100-getting-started/01-quickstart-prisma-postgres.mdx b/content/100-getting-started/01-quickstart-prisma-postgres.mdx
@@ -0,0 +1,195 @@
+---
+title: 'Quickstart'
+metaTitle: 'Quickstart with TypeScript & Prisma Postgres'
+metaDescription: 'Get started with Prisma ORM in 5 minutes. You will learn how to send queries to a SQLite database in a plain TypeScript script using Prisma Client.'
+search: true
+dbSwitcher: ['sqlite', 'prisma-postgres']
+slugSwitch: /getting-started/quickstart-`
+sidebar_custom_props: { badge: '5 min' }
+---
+
+In this Quickstart guide, you'll learn how to get started from scratch with Prisma ORM and a remote **Prisma Postgres** database in a plain **TypeScript** project. It covers the following workflows:
+
+- Creating a [Prisma Postgres](https://prisma.io/data-platform/postgres) database
+- Schema migrations and queries (via [Prisma ORM](https://www.prisma.io/orm))
+- Connection pooling and caching (via [Prisma Accelerate](https://prisma.io/data-platform/accelerate))
+- Real-time database change events (via [Prisma Pulse](https://prisma.io/data-platform/pulse))
+
+
+## Prerequisites
+
+To successfully complete this tutorial, you need:
+- a [Prisma Data Platform](https://console.prisma.io/) (PDP) account
+- Node.js v16.13.0 or higher (learn more about [system requirements](/orm/reference/system-requirements))
+
+
+## 1. Set up a Prisma Postgres database in the PDP Console
+
+Follow these steps to create your Prisma Postgres database:
+
+1. Log in to [Prisma Data Platform](https://console.prisma.io/).
+1. In a [workspace](/platform/about#workspace) of your choice, click the **New project** button.
+1. Type a name for your project in the **Name** field, e.g. **hello-ppg**.
+1. In the **Prisma Postgres** section, click the **Get started** button.
+1. In the **Region** dropdown, select the region that's closest to your current location, e.g. **US East (N. Virginia)**.
+1. Click the **Create project** button.
+
+At this point, you'll be redirected to the **Dashboard** 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 hown in the Console, paste it into your terminal and execute it.
+
+For reference, this is what the command looks like (note that the `__YOUR_DATABASE_CONNECTION_STRING__` placeholder must be replaced with _your_ actual database connection string):
+
+```
+npx try-prisma@latest
+  --template databases/prisma-postgres
+  --connection-string __YOUR_DATABASE_CONNECTION_STRING__
+  --name hello-prisma-postgres
+  --install npm
+  --path .
+```
+
+Your connection string that should replace the `__YOUR_DATABASE_CONNECTION_STRING__` placeholder looks similar to this: `prisma+postgres://accelerate.prisma-data.net/?api_key=ey...`
+
+Once the `try-prisma` command has terminaed, navigate into the project directory and install dependencies:
+
+```
+cd hello-prisma-postgres
+npm install
+```
+
+## 3. 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](/orm/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.
+
+## 4. Execute queries with Prisma ORM
+
+The [`src/queries.ts`](./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 terminated, 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
+```
+
+## 5. Explore caching with Prisma Accelerate
+
+The [`src/caching.ts`](./src/caching.ts) script contains a sample query that uses [Stale-While-Revalidate](/accelerate/caching#stale-while-revalidate-swr) (SWR) and [Time-To-Live](/accelerate/caching#time-to-live-ttl) (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.
+```
+
+## 6. Observe real-time events in your database
+
+The  [`src/realtime.ts`](./src/realtime.ts) script contains a demo for receiving real-time change [events](/pulse/database-events) from your database. You can start the script as follows:
+
+```
+npm run realtime
+```
+
+The script now created a [stream](/pulse/api-reference#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: '[email protected]', name: 'Nikolas' },
+  id: '01JAFNSZHQRDTW773BCAA9G7FJ',
+  modelName: 'User'
+}
+```
+
+## 7. 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:
+
+```terminal
+npx prisma studio
+```
+
+### Explore ready-to-run Prisma ORM examples
+
+Check out the [`prisma-examples`](https://github.com/prisma/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](/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:
+
+| Demo                                                                     | Description                                                              |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| [`starter`](https://github.com/prisma/prisma-examples/tree/latest/pulse/starter)                                             | A Prisma Pulse starter app                                               |
+| [`email-with-resend`](https://github.com/prisma/prisma-examples/tree/latest/pulse/email-with-resend)                         | An example app to send emails to new users using Prisma Pulse and Resend |
+| [`fullstack-leaderboard`](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-leaderboard)                 | A live leaderboard (built with Next.js)                                  |
+| [`fullstack-simple-chat`](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat)                 | A simple chat app (built with Next.js & Express)                         |
+| [`product-search-with-typesense`](https://github.com/prisma/prisma-examples/tree/latest/pulse/product-search-with-typesense) | A cron job that syncs data into Typesense (built with Hono.js)           |
+| [`data-sync-with-bigquery`](https://github.com/prisma/prisma-examples/tree/latest/pulse/data-sync-with-bigquery)             | A script that automatically syncs data into Google BigQuery              |
+
+### Speed up your database queries with Prisma Accelerate
+
+[Prisma Accelerate](/accelerate) is a connection pooler and global database cache that can drastically speed up your database queries. Check out the [Speed Test](https://accelerate-speed-test.prisma.io/) or try Accelerate with your favorite framework:
+
+| Demo                                            | Description                                                                |
+| ----------------------------------------------- | -------------------------------------------------------------------------- |
+| [`nextjs-starter`](https://github.com/prisma/prisma-examples/tree/latest/accelerate/nextjs-starter) | A Next.js project using Prisma Accelerate's caching and connection pooling |
+| [`svelte-starter`](https://github.com/prisma/prisma-examples/tree/latest/accelerate/svelte-starter) | A SvelteKit project using Prisma Accelerate's caching and connection pooling |
+| [`solidstart-starter`](https://github.com/prisma/prisma-examples/tree/latest/accelerate/solidstart-starter) | A Solidstart project using Prisma Accelerate's caching and connection pooling |
+| [`remix-starter`](https://github.com/prisma/prisma-examples/tree/latest/accelerate/remix-starter) | A Remix project using Prisma Accelerate's caching and connection pooling |
+| [`nuxt-starter`](https://github.com/prisma/prisma-examples/tree/latest/accelerate/nuxtjs-starter) | A Nuxt.js project using Prisma Accelerate's caching and connection pooling |
+| [`astro-starter`](https://github.com/prisma/prisma-examples/tree/latest/accelerate/astro-starter) | An 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:
+
+- [Build a fullstack app with Next.js](https://www.youtube.com/watch?v=QXxy8Uv1LnQ&ab_channel=ByteGrad)
+- [Build a fullstack app with Remix](https://www.prisma.io/blog/fullstack-remix-prisma-mongodb-1-7D0BfTXBmB6r) (5 parts, including videos)
+- [Build a REST API with NestJS](https://www.prisma.io/blog/nestjs-prisma-rest-api-7D056s1BmOL0)
+
+### Join the Prisma community 💚
+
+Prisma has a huge [community](https://www.prisma.io/community) of developers. Join us on [Discord](https://discord.gg/KQyTW2H5ca) or ask questions using [GitHub Discussions](https://github.com/prisma/prisma/discussions).
diff --git a/...ent/100-getting-started/01-quickstart.mdx → ...-getting-started/01-quickstart-sqlite.mdx b/...ent/100-getting-started/01-quickstart.mdx → ...-getting-started/01-quickstart-sqlite.mdx
@@ -3,20 +3,18 @@ title: 'Quickstart'
 metaTitle: 'Quickstart with TypeScript & SQLite'
 metaDescription: 'Get started with Prisma ORM in 5 minutes. You will learn how to send queries to a SQLite database in a plain TypeScript script using Prisma Client.'
 search: true
+dbSwitcher: ['sqlite', 'prisma-postgres']
+slugSwitch: /getting-started/quickstart-
 sidebar_custom_props: { badge: '5 min' }
 ---
 
-<TopBlock>
-
 In this Quickstart guide, you'll learn how to get started with Prisma ORM from scratch using a plain **TypeScript** project and a local **SQLite** database file. It covers **data modeling**, **migrations** and **querying** a database.
 
 If you want to use Prisma ORM with your own PostgreSQL, MySQL, MongoDB or any other supported database, go here instead:
 
 - [Start with Prisma ORM from scratch](/getting-started/setup-prisma/start-from-scratch/relational-databases-typescript-postgresql)
 - [Add Prisma ORM to an existing project](/getting-started/setup-prisma/add-to-existing-project/relational-databases-typescript-postgresql)
 
-</TopBlock>
-
 ## Prerequisites
 
 You need Node.js v16.13.0 or higher for this guide (learn more about [system requirements](/orm/reference/system-requirements)).

diff --git a/...tup-prisma/100-start-from-scratch/110-relational-databases-node-cockroachdb.mdx b/...tup-prisma/100-start-from-scratch/110-relational-databases-node-cockroachdb.mdx
@@ -26,7 +26,7 @@ In order to successfully complete this guide, you need:
 
 > See [System requirements](/orm/reference/system-requirements) for exact version requirements.
 
-Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart).
+Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart-sqlite).
 
 ## Create project setup
 

diff --git a/.../02-setup-prisma/100-start-from-scratch/110-relational-databases-node-mysql.mdx b/.../02-setup-prisma/100-start-from-scratch/110-relational-databases-node-mysql.mdx
@@ -26,7 +26,7 @@ In order to successfully complete this guide, you need:
 
 > See [System requirements](/orm/reference/system-requirements) for exact version requirements.
 
-Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart).
+Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart-sqlite).
 
 ## Create project setup
 

diff --git a/...etup-prisma/100-start-from-scratch/110-relational-databases-node-postgresql.mdx b/...etup-prisma/100-start-from-scratch/110-relational-databases-node-postgresql.mdx
@@ -26,7 +26,7 @@ In order to successfully complete this guide, you need:
 
 > See [System requirements](/orm/reference/system-requirements) for exact version requirements.
 
-Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart).
+Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart-sqlite).
 
 ## Create project setup
 

diff --git a/...setup-prisma/100-start-from-scratch/110-relational-databases-node-sqlserver.mdx b/...setup-prisma/100-start-from-scratch/110-relational-databases-node-sqlserver.mdx
@@ -29,7 +29,7 @@ In order to successfully complete this guide, you need:
 
 > See [System requirements](/orm/reference/system-requirements) for exact version requirements.
 
-Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart).
+Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart-sqlite).
 
 ## Create project setup
 

diff --git a/...isma/100-start-from-scratch/110-relational-databases-typescript-cockroachdb.mdx b/...isma/100-start-from-scratch/110-relational-databases-typescript-cockroachdb.mdx
@@ -26,7 +26,7 @@ In order to successfully complete this guide, you need:
 
 > See [System requirements](/orm/reference/system-requirements) for exact version requirements.
 
-Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart).
+Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart-sqlite).
 
 ## Create project setup
 

diff --git a/...tup-prisma/100-start-from-scratch/110-relational-databases-typescript-mysql.mdx b/...tup-prisma/100-start-from-scratch/110-relational-databases-typescript-mysql.mdx
@@ -26,7 +26,7 @@ In order to successfully complete this guide, you need:
 
 > See [System requirements](/orm/reference/system-requirements) for exact version requirements.
 
-Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart).
+Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart-sqlite).
 
 ## Create project setup
 

diff --git a/...isma/100-start-from-scratch/110-relational-databases-typescript-planetscale.mdx b/...isma/100-start-from-scratch/110-relational-databases-typescript-planetscale.mdx
@@ -32,7 +32,7 @@ This tutorial will also assume that you can push to the `main` branch of your da
 
 > See [System requirements](/orm/reference/system-requirements) for exact version requirements.
 
-Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart).
+Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart-sqlite).
 
 ## Create project setup
 

diff --git a/...risma/100-start-from-scratch/110-relational-databases-typescript-postgresql.mdx b/...risma/100-start-from-scratch/110-relational-databases-typescript-postgresql.mdx
@@ -25,7 +25,7 @@ In order to successfully complete this guide, you need:
 
 > See [System requirements](/orm/reference/system-requirements) for exact version requirements.
 
-Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart).
+Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart-sqlite).
 
 ## Create project setup
 

diff --git a/...prisma/100-start-from-scratch/110-relational-databases-typescript-sqlserver.mdx b/...prisma/100-start-from-scratch/110-relational-databases-typescript-sqlserver.mdx
@@ -28,7 +28,7 @@ In order to successfully complete this guide, you need:
 
 > See [System requirements](/orm/reference/system-requirements) for exact version requirements.
 
-Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart).
+Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart-sqlite).
 
 ## Create project setup
 

diff --git a/...ing-started/02-setup-prisma/100-start-from-scratch/120-mongodb-node-mongodb.mdx b/...ing-started/02-setup-prisma/100-start-from-scratch/120-mongodb-node-mongodb.mdx
@@ -30,7 +30,7 @@ In order to successfully complete this guide, you need:
 
   </Admonition>
 
-Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart).
+Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart-sqlite).
 
 > See [System requirements](/orm/reference/system-requirements) for exact version requirements.
 

diff --git a/...arted/02-setup-prisma/100-start-from-scratch/120-mongodb-typescript-mongodb.mdx b/...arted/02-setup-prisma/100-start-from-scratch/120-mongodb-typescript-mongodb.mdx
@@ -29,7 +29,7 @@ In order to successfully complete this guide, you need:
 
   </Admonition>
 
-Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart).
+Make sure you have your database [connection URL](/orm/reference/connection-urls) at hand. If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart-sqlite).
 
 > See [System requirements](/orm/reference/system-requirements) for exact version requirements.
 

diff --git a/...risma/200-add-to-existing-project/110-relational-databases-node-cockroachdb.mdx b/...risma/200-add-to-existing-project/110-relational-databases-node-cockroachdb.mdx
@@ -33,7 +33,7 @@ In order to successfully complete this guide, you need:
 
 > See [System requirements](/orm/reference/system-requirements) for exact version requirements.
 
-Make sure you have your database [connection URL](/orm/reference/connection-urls) (that includes your authentication credentials) at hand! If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart).
+Make sure you have your database [connection URL](/orm/reference/connection-urls) (that includes your authentication credentials) at hand! If you don't have a database server running and just want to explore Prisma ORM, check out the [Quickstart](/getting-started/quickstart-sqlite).
 
 ## Set up Prisma ORM