|
1 | | -# Prisma Postgres Example: Queries, Connection Pooling & Caching |
| 1 | +# Prisma Postgres |
2 | 2 |
|
3 | | -This project contains a sample application demonstrating various capabilities and workflows of [Prisma Postgres](https://prisma.io/data-platform/postgres): |
| 3 | +This example shows how to use [Prisma ORM](https://www.prisma.io/orm) with [Prisma Postgres](https://prisma.io/postgres). |
4 | 4 |
|
5 | | -- Schema migrations and queries (via [Prisma ORM](https://www.prisma.io/orm)) |
6 | | -- Connection pooling and caching (via [Prisma Accelerate](https://prisma.io/data-platform/accelerate)) |
| 5 | +## Getting Started |
7 | 6 |
|
8 | | -## Getting started |
| 7 | +### 1. Download the example & install dependencies |
9 | 8 |
|
10 | | -### 1. Set up a Prisma Postgres database in Prisma Data Platform |
11 | | - |
12 | | -Follow these steps to create your Prisma Postgres database: |
13 | | - |
14 | | -1. Log in to [Prisma Data Platform](https://console.prisma.io/). |
15 | | -1. In a [workspace](https://www.prisma.io/docs/platform/about#workspace) of your choice, click the **New project** button. |
16 | | -1. Type a name for your project in the **Name** field, e.g. **hello-ppg**. |
17 | | -1. In the **Prisma Postgres** section, click the **Get started** button. |
18 | | -1. In the **Region** dropdown, select the region that's closest to your current location, e.g. **US East (N. Virginia)**. |
19 | | -1. Click the **Create project** button. |
20 | | - |
21 | | -At this point, you'll be redirected to the **Database** page where you will need to wait a few seconds while the status of your database changes from **`PROVISIONING`**, to **`ACTIVATING`** to **`CONNECTED`**. |
22 | | - |
23 | | -Once the green **`CONNECTED`** label appears, your database is ready to use! |
24 | | - |
25 | | -Then, find your database credentials in the **Set up database access** section, copy the `DATABASE_URL` environment variable and store it securely. |
26 | | - |
27 | | -```bash no-copy |
28 | | -DATABASE_URL=<your-database-url> |
29 | | -``` |
30 | | - |
31 | | -> These `DATABASE_URL` environment variable will be required in the next steps. |
32 | | -
|
33 | | -Once that setup process has finished, move to the next step. |
34 | | - |
35 | | -### 2. Download example and install dependencies |
36 | | - |
37 | | -Copy the `try-prisma` command that', paste it into your terminal, and execute it: |
38 | | - |
39 | | -```terminal |
40 | | -npx try-prisma@latest \ |
41 | | - --template databases/prisma-postgres \ |
42 | | - --name hello-prisma \ |
43 | | - --install npm |
44 | | -``` |
45 | | - |
46 | | -<!-- 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): |
47 | | -
|
48 | | -``` |
49 | | -npx try-prisma@latest |
50 | | - --template databases/prisma-postgres |
51 | | - --connection-string __YOUR_DATABASE_CONNECTION_STRING__ |
52 | | - --name hello-prisma |
53 | | - --install npm |
54 | | -``` |
55 | | -
|
56 | | -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...` |
57 | | ---> |
58 | | - |
59 | | -Navigate into the project directory and (if you haven't done so via the CLI wizard) install dependencies: |
60 | | - |
61 | | -```terminal |
62 | | -cd hello-prisma |
63 | | -npm install |
64 | | -``` |
65 | | - |
66 | | -### 3. Set database connection |
67 | | - |
68 | | -The connection to your database is configured via environment variables in a `.env` file. |
69 | | - |
70 | | -First, rename the existing `.env.example` file to just `.env`: |
71 | | - |
72 | | -```terminal |
73 | | -mv .env.example .env |
74 | | -``` |
75 | | - |
76 | | -Then, find your database credentials in the **Set up database access** section, copy the `DATABASE_URL` environment variable and paste them into the `.env` file. |
77 | | - |
78 | | -For reference, the file should now look similar to this: |
| 9 | +Clone this repository and install dependencies: |
79 | 10 |
|
80 | 11 | ```bash |
81 | | -DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=ey...." |
| 12 | +npx try-prisma@latest --template databases/prisma-postgres |
82 | 13 | ``` |
83 | 14 |
|
84 | | -### 4. Create database tables (with a schema migration) |
| 15 | +Then navigate into the project directory and install dependencies: |
85 | 16 |
|
86 | | -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: |
87 | | - |
88 | | -```terminal |
89 | | -npx prisma migrate dev --name init |
| 17 | +```bash |
| 18 | +cd prisma-postgres |
| 19 | +bun install |
90 | 20 | ``` |
91 | 21 |
|
92 | | -This will map the `User` and `Post` models that are defined in your [Prisma schema](./prisma/schema.prisma) to your database. You can also review the SQL migration that was executed and created the tables in the newly created `prisma/migrations` directory. |
| 22 | +### 2. Create a Prisma Postgres database |
93 | 23 |
|
94 | | -### 5. Execute queries with Prisma ORM |
| 24 | +Run the following command to create a Prisma Postgres database: |
95 | 25 |
|
96 | | -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: |
97 | | - |
98 | | -```terminal |
99 | | -npm run queries |
100 | | -``` |
101 | | - |
102 | | -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: |
103 | | - |
104 | | -```terminal |
105 | | -npx prisma studio |
| 26 | +```bash |
| 27 | +npx create-db@latest |
106 | 28 | ``` |
107 | 29 |
|
108 | | -### 6. Explore caching with Prisma Accelerate |
| 30 | +Copy the `DATABASE_URL` from the output and add it to a `.env` file: |
109 | 31 |
|
110 | | -The [`src/caching.ts`](./src/caching.ts) script contains a sample query that uses [Stale-While-Revalidate](https://www.prisma.io/docs/accelerate/caching#stale-while-revalidate-swr) (SWR) and [Time-To-Live](https://www.prisma.io/docs/accelerate/caching#time-to-live-ttl) (TTL) to cache a database query using Prisma Accelerate. You can execute it as follows: |
111 | | - |
112 | | -```terminal |
113 | | -npm run caching |
| 32 | +```bash |
| 33 | +DATABASE_URL="postgresql://..." |
114 | 34 | ``` |
115 | 35 |
|
116 | | -Take note of the time that it took to execute the query, e.g.: |
| 36 | +> **Tip:** Claim your database at the provided URL to keep it permanently. |
117 | 37 |
|
118 | | -```terminal |
119 | | -The query took 2009.2467149999998ms. |
120 | | -``` |
| 38 | +### 3. Push the schema & generate Prisma Client |
121 | 39 |
|
122 | | -Now, run the script again: |
| 40 | +Push the schema to the database and generate Prisma Client: |
123 | 41 |
|
124 | | -```terminal |
125 | | -npm run caching |
| 42 | +```bash |
| 43 | +npx prisma db push |
| 44 | +npx prisma generate |
126 | 45 | ``` |
127 | 46 |
|
128 | | -You'll notice that the time the query took will be a lot shorter this time, e.g.: |
| 47 | +### 4. Run the example |
129 | 48 |
|
130 | | -```terminal |
131 | | -The query took 300.5655280000001ms. |
| 49 | +```bash |
| 50 | +bun run dev |
132 | 51 | ``` |
133 | 52 |
|
134 | 53 | ## Next steps |
135 | 54 |
|
136 | | -- Check out the [Prisma docs](https://www.prisma.io/docs) |
137 | | -- [Join our community on Discord](https://pris.ly/discord?utm_source=github&utm_medium=prisma_examples&utm_content=next_steps_section) to share feedback and interact with other users. |
138 | | -- [Subscribe to our YouTube channel](https://pris.ly/youtube?utm_source=github&utm_medium=prisma_examples&utm_content=next_steps_section) for live demos and video tutorials. |
139 | | -- [Follow us on X](https://pris.ly/x?utm_source=github&utm_medium=prisma_examples&utm_content=next_steps_section) for the latest updates. |
140 | | -- Report issues or ask [questions on GitHub](https://pris.ly/github?utm_source=github&utm_medium=prisma_examples&utm_content=next_steps_section). |
| 55 | +- [Prisma Postgres documentation](https://www.prisma.io/docs/postgres) |
| 56 | +- [Prisma ORM documentation](https://www.prisma.io/docs/orm) |
| 57 | +- [Join the Prisma Discord](https://pris.ly/discord) |
0 commit comments