Skip to content

Commit 08d5c2c

Browse files
nikolasburknikolasburk
authored
6.9.0 docs (#6927)
* page for vs code extension * merge pages for vs code extension and agent * fix links * expand orm docs for vs code extension * fix typos * add connection string * add info about tcp connections * add redirects * re-add tcp tunnel page with deprecation warning * fix broken anchors * update getting started docs * update tcp docs * add more tcp docs * update redicts * update limits * minor updates * minor updates * updates to local ppg * minor changes * minor changes * minor changes * minor changes * update import guides to use direct connection instead of tunnel * update faq * update backup docs * update backup docs * update backup docs * update backup docs * update backup docs * fix typo * clarify vs code ui workflows * Update static/_redirects
1 parent 7d0d816 commit 08d5c2c

25 files changed

+535
-515
lines changed

‎cSpell.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,8 @@
125125
"Deepgram",
126126
"PGSSLMODE",
127127
"pgloader",
128-
"unikernel"
128+
"unikernel",
129+
"Mikro"
129130
],
130131
"patterns": [
131132
{

‎content/100-getting-started/01-quickstart-prismaPostgres.mdx

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,12 @@ In this Quickstart guide, you'll learn how to get started from scratch with Pris
1717
- Schema migrations and queries (via [Prisma ORM](https://www.prisma.io/orm))
1818
- Connection pooling and caching (via [Prisma Accelerate](https://www.prisma.io/accelerate))
1919

20+
:::note
21+
22+
If you want to use Prisma Postgres with another ORM or database library (like Drizzle ORM, TypeORM or Kysely), you can follow the instructions [here](/postgres/introduction/getting-started#connect-via-any-database-library--tool).
23+
24+
:::
25+
2026
## Prerequisites
2127

2228
To successfully complete this tutorial, you need:

‎content/100-getting-started/03-prisma-postgres/110-import-from-existing-database-postgresql.mdx

Lines changed: 28 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ You can accomplish this migration in three steps:
1818
1. Export your existing data via `pg_dump`.
1919
1. Import the previously exported data into Prisma Postgres via `pg_restore`.
2020

21-
In the third step, you will be using the [TCP tunnel](/postgres/database/tcp-tunnel) to securely connect to your Prisma Postgres database during to run `pg_restore`.
21+
In the third step, you will be using a [direct connection](/postgres/database/direct-connections) to securely connect to your Prisma Postgres database during to run `pg_restore`.
2222

2323
## Prerequisites
2424

@@ -27,50 +27,6 @@ In the third step, you will be using the [TCP tunnel](/postgres/database/tcp-tun
2727
- Node.js 18+ installed
2828
- PostgreSQL CLI Tools (`pg_dump`, `pg_restore`) for creating and restoring backups
2929

30-
<!-- ### Installing PostgreSQL 16 utilities
31-
32-
To create and restore backups, ensure you have the PostgreSQL 16 command-line tools installed. Run the following commands based on your operating system:
33-
34-
<TabbedContent code>
35-
36-
<TabItem value="macOS">
37-
38-
```terminal
39-
brew install postgresql@16
40-
which pg_dump
41-
which pg_restore
42-
```
43-
44-
</TabItem>
45-
46-
<TabItem value="Windows">
47-
```terminal
48-
# Download from the official PostgreSQL website:
49-
# https://www.postgresql.org/download/windows/
50-
# During installation, select "Command Line Tools".
51-
# Then verify with:
52-
53-
where pg_dump
54-
where pg_restore
55-
```
56-
</TabItem>
57-
58-
<TabItem value="Linux">
59-
```terminal
60-
sudo apt-get update
61-
sudo apt-get install postgresql-client-16
62-
which pg_dump
63-
which pg_restore
64-
```
65-
</TabItem>
66-
67-
</TabbedContent>
68-
69-
:::tip
70-
If you installed PostgreSQL but still see a “command not found” error for pg_dump or pg_restore, ensure your installation directory is in your system’s PATH environment variable.
71-
::: -->
72-
73-
7430
## 1. Create a new Prisma Postgres database
7531

7632
Follow these steps to create a new Prisma Postgres database:
@@ -82,7 +38,7 @@ Follow these steps to create a new Prisma Postgres database:
8238
1. In the **Region** dropdown, select the region that's closest to your current location, e.g. **US East (N. Virginia)**.
8339
1. Click the **Create project** button.
8440

85-
Once your database was provisioned, find your Prisma Postgres connection URL in the **Set up database access** section and save it for later, you'll need it in step 3.
41+
With your Prisma Postgres instance being created, you can move to the next step.
8642

8743
## 2. Export data from your existing database
8844

@@ -118,18 +74,6 @@ Expand below for provider-specific instructions that help you determine the righ
11874
```no-copy
11975
postgres://postgres.apbkobhfnmcqqzqeeqss:[YOUR-PASSWORD]@aws-0-ca-central-1.pooler.supabase.com:5432/postgres
12076
```
121-
<!-- - Include the argument `-n public` to only dump the public schema.
122-
123-
Your command would look like: -->
124-
125-
<!-- ```
126-
pg_dump \
127-
-Fc \
128-
-v \
129-
-d "postgresql://user:password@host:port/db" \
130-
-n public \
131-
-f db_dump.bak
132-
``` -->
13377

13478
</details>
13579

@@ -156,80 +100,51 @@ Running this command will create a backup file named `db_dump.bak` which you wil
156100

157101
## 3. Import data into Prisma Postgres
158102

159-
In this step, you'll use the [TCP tunnel](/postgres/database/tcp-tunnel) to connect to your Prisma Postgres instance and import data via `pg_restore`.
103+
In this section, you'll use a [direct connection](/postgres/database/direct-connections) in order to connect to your Prisma Postgres instance and import data via `pg_restore`.
160104

161-
You'll also need the Prisma Postgres connection URL from step 1, it should look similar to this:
105+
Follow these steps to obtain the connection string for your Prisma Postgres instance:
162106

163-
```no-copy
164-
prisma+postgres://accelerate.prisma-data.net/?api_key=ey...
165-
```
166107

167-
If you already have a `.env` file in your current directory with `DATABASE_URL` set, the tunnel CLI will automatically pick it up, no need to manually export it. However, if you haven't set up a `.env` file, you'll need to set the `DATABASE_URL` environment variable explicitly.
108+
1. Navigate to your active Prisma Postgres instance.
109+
1. Click the **API Keys** tab in the project's sidenav.
110+
1. Click the **Create API key** button.
111+
1. In the popup, provide a **Name** for the API key and click **Create**.
112+
1. Copy the connection string starting with `postgres://`, this is your direct connection string.
168113

169-
To set the environment variable, open your terminal and set the `DATABASE_URL` environment variable to the value of your Prisma Postgres database URL (replace the `__API_KEY__` placeholder with the API key of your actual database connection URL):
114+
The connection string should look similar to this:
170115

171-
```terminal
172-
export DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=__API_KEY__"
116+
```no-copy
117+
DATABASE_URL="postgres://__USER__:__PASSWORD__@postgres.prisma-data.net:5432/?sslmode=require"
173118
```
174-
:::note
175-
If you explicitly set `DATABASE_URL` in your terminal, that value will take precedence over the one in your `.env` file.
176-
:::
177-
178-
Next, start the TCP tunnel:
179119

180-
<CodeWithResult outputResultText="" expanded={true}>
181-
182-
<cmd>
120+
Now, use the `db_dump.bak` backup file from the previous step to restore data into your Prisma Postgres database with the `pg_restore` command:
183121

184122
```terminal
185-
npx @prisma/ppg-tunnel --host 127.0.0.1 --port 5433
186-
```
187-
188-
</cmd>
189-
190-
<cmdResult>
191-
192-
```code no-copy wrap
193-
Prisma Postgres auth proxy listening on 127.0.0.1:5433 🚀
194-
195-
Your connection is authenticated using your Prisma Postgres API key.
196-
...
197-
198-
==============================
199-
hostname: 127.0.0.1
200-
port: 5433
201-
username: <anything>
202-
password: <none>
203-
==============================
123+
PGPASSWORD=__PASSWORD__ \
124+
pg_restore \
125+
-U __USER__ \
126+
-h postgres.prisma-data.net \
127+
-p 5432 \
128+
-v \
129+
-d postgres \
130+
./db_dump.bak \
131+
&& echo "-complete-"
204132
```
205133

206-
</cmdResult>
207-
208-
</CodeWithResult>
209-
210-
:::note
134+
Be sure to replace the `__USER__` and `__PASSWORD__` placeholders with the values from your own connection string, this may look as follows:
211135

212-
Keep your current terminal window or tab open so that the tunnel process continues running and the connection remains open.
213-
214-
:::
215-
216-
Now, use the `db_dump.bak` backup file from the previous step to restore data into your Prisma Postgres database with the `pg_restore` command:
217-
218-
```terminal
219-
PGSSLMODE=disable \
136+
```terminal no-copy
137+
PGPASSWORD=sk_QZ3u8fMPFfBzOID4ol-mV \
220138
pg_restore \
221-
-h 127.0.0.1 \
222-
-p 5433 \
139+
-U 2f9881cc7eef46f094ac913df34c1fb441502fe66cbe28cc48998d4e6b20336b \
140+
-h postgres.prisma-data.net \
141+
-p 5432 \
223142
-v \
224143
-d postgres \
225144
./db_dump.bak \
226145
&& echo "-complete-"
227146
```
228147

229-
:::note
230-
You don't need to provide username and password credentials to this command because the TCP tunnel already authenticated you via the API key in your Prisma Postgres connection URL.
231-
:::
232-
233148
You now successfully imported the data from your your existing PostgreSQL database into Prisma Postgres 🎉
234149

235150
To validate that the import worked, you can use [Prisma Studio](/postgres/database/tooling#viewing-and-editing-data-in-prisma-studio). Either open it in the [Platform Console](https://console.prisma.io) by clicking the **Studio** tab in the left-hand sidenav in your project or run this command to launch Prisma Studio locally:

‎content/100-getting-started/03-prisma-postgres/115-import-from-existing-database-mysql.mdx

Lines changed: 14 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ This guide provides step-by-step instructions for importing data from an existin
1515
You can accomplish this migration in four steps:
1616

1717
1. Create a new Prisma Postgres database.
18-
1. Connect directly to a Prisma Postgres instance using the [`@prisma/ppg-tunnel` package](https://www.npmjs.com/package/@prisma/ppg-tunnel).
18+
1. Connect directly to a Prisma Postgres instance using a [direct connection](/postgres/database/direct-connections).
1919
1. Migrate your MySQL data to Prisma Postgres using [pgloader](https://pgloader.io/).
2020
1. Configure your Prisma project for Prisma Postgres.
2121

@@ -39,75 +39,30 @@ Follow these steps to create a new Prisma Postgres database:
3939
1. In the **Region** dropdown, select the region that's closest to your current location, e.g. **US East (N. Virginia)**.
4040
1. Click the **Create project** button.
4141

42-
Once your database was provisioned, find your Prisma Postgres connection URL in the **Set up database access** section and save it for later, you'll need it in the next step.
42+
Once your database was provisioned, find your direct Prisma Postgres connection string:
43+
44+
1. Navigate to your active Prisma Postgres instance.
45+
1. Click the **API Keys** tab in the project's sidenav.
46+
1. Click the **Create API key** button.
47+
1. In the popup, provide a **Name** for the API key and click **Create**.
48+
1. Copy the connection string starting with `postgres://`, this is your direct connection string.
49+
50+
Save the connection string, you'll need it in the next step.
4351

4452
## 2. Connect directly to a Prisma Postgres instance
4553

46-
In this step, you'll use a secure [TCP tunnel](/postgres/database/tcp-tunnel) to connect to your Prisma Postgres instance.
54+
In this step, you'll use a [direct connection](/postgres/database/direct-connections) to connect to your Prisma Postgres instance.
4755

4856
You'll need the Prisma Postgres connection URL from [step 1](/getting-started/prisma-postgres/import-from-existing-database-mysql#1-create-a-new-prisma-postgres-database):
4957

5058
```no-copy
5159
prisma+postgres://accelerate.prisma-data.net/?api_key=ey...
5260
```
53-
If you already have a `.env` file in your current directory with `DATABASE_URL` set, the tunnel CLI will automatically pick it up, no need to manually export it. However, if you haven't set up a `.env` file, you'll need to set the `DATABASE_URL` environment variable explicitly.
54-
55-
To set the environment variable, open your terminal and set the `DATABASE_URL` environment variable to the value of your Prisma Postgres database URL (replace the `__API_KEY__` placeholder with the API key of your actual database connection URL):
56-
57-
```terminal
58-
export DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=__API_KEY__"
59-
```
60-
61-
:::note
62-
If you explicitly set `DATABASE_URL` in your terminal, that value will take precedence over the one in your `.env` file.
63-
:::
64-
65-
Next, start the TCP tunnel using the `@prisma/ppg-tunnel` package, by executing the following command:
66-
67-
<CodeWithResult outputResultText="" expanded={true}>
68-
<cmd>
69-
70-
```terminal
71-
npx @prisma/ppg-tunnel --host 127.0.0.1 --port 5433
72-
```
73-
74-
:::note
7561

76-
You can [specify a different host and port](/postgres/database/tcp-tunnel#customizing-host-and-port) by providing your own host and port values using the `--port` and `--host` flags. Just be sure to use the same host and port values consistently throughout the guide.
77-
78-
:::
79-
80-
</cmd>
81-
82-
<cmdResult>
83-
84-
```code no-copy wrap
85-
Prisma Postgres auth proxy listening on 127.0.0.1:5433 🚀
86-
87-
Your connection is authenticated using your Prisma Postgres API key.
88-
...
89-
90-
==============================
91-
hostname: 127.0.0.1
92-
port: 5433
93-
username: <anything>
94-
password: <none>
95-
==============================
96-
```
97-
98-
</cmdResult>
99-
100-
</CodeWithResult>
101-
102-
:::note
103-
104-
*Keep your current terminal window or tab open* so that the tunnel process continues running and the connection remains open.
105-
106-
:::
10762

10863
## 3. Migrate your MySQL data to Prisma Postgres using pgloader
10964

110-
Now that you have an active connection to your Prisma Postgres instance, you'll use pgloader to export data from your MySQL database to Prisma Postgres.
65+
Now that you have an active connection to your Prisma Postgres instance, you'll use [pgloader](https://pgloader.io/) to export data from your MySQL database to Prisma Postgres.
11166

11267
Open a separate terminal window and create a `config.load` file:
11368

@@ -120,7 +75,7 @@ Open the `config.load` file in your preferred text editor and copy-paste the fol
12075
```text file=config.load
12176
LOAD DATABASE
12277
FROM mysql://username:password@host:PORT/database_name
123-
INTO postgresql://user:[email protected]:5433/postgres
78+
INTO postgres://__USER__:[email protected]:5432/?sslmode=require
12479
12580
WITH quote identifiers, -- preserve table/column name case by quoting them
12681
include drop,
@@ -137,7 +92,7 @@ Make sure to update the following details in the `config.load` file:
13792
- Replace `username`, `password`, `host`, `PORT`, and `database_name` with the actual connection details for your MySQL database.
13893
- Ensure that your connection string includes `useSSL=true` if SSL is required, for example: `mysql://username:password@host:PORT/database_name?useSSL=true`. Note that when using PlanetScale, appending `sslaccept=strict` will not work.
13994
- `INTO` url (Postgres database URL):
140-
- Update this with your TCP tunnel details if you’re using a custom `host` and `port` (in this example, it’s `127.0.0.1` and port `5433` for consistency).
95+
- Update this with your direct connection string from above, replacing the `__USER__` and `__PASSWORD__` placeholders.
14196
- Update the `database_name` in `ALTER SCHEMA 'database_name' RENAME TO 'public';` to exactly match the `database_name` in your MySQL connection string.
14297

14398
After saving the configuration file with your updated credentials, in the same terminal window, execute the following command:

0 commit comments

Comments
 (0)