Skip to content

Add docs on Data Proxy directUrl property #4377

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ruheni merged 15 commits into from
Feb 7, 2023
Merged

Add docs on Data Proxy directUrl property #4377

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
fe70289
Update schema reference
Jan 10, 2023
8817b32
Merge branch 'main' into direct-url
Jan 10, 2023
010c7cd
Update CLI commands with Data Proxy page
Jan 10, 2023
bb69e69
Update content/800-data-platform/050-data-proxy/700-prisma-cli-with-d…
Jan 11, 2023
79f36f5
Merge branch 'main' into direct-url
Jan 11, 2023
662103f
Remove firewall admonition
Jan 13, 2023
945bf7e
Update directUrl argument description
Jan 13, 2023
da33132
Move list of commands to its own section
Jan 13, 2023
965d494
Link to list of commands
Jan 17, 2023
d4c27a0
Merge branch 'main' into direct-url
janpio Feb 4, 2023
1ad2ee9
Revises a sentence for clarity
sabinadams Feb 6, 2023
1eedb80
Merge branch 'main' into direct-url
ruheni Feb 7, 2023
cab2e83
Merge branch 'main' into direct-url
ruheni Feb 7, 2023
050576b
Merge branch 'main' into direct-url
ruheni Feb 7, 2023
d05d111
Merge branch 'main' into direct-url
ruheni Feb 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 8 additions & 7 deletions content/400-reference/200-api-reference/100-prisma-schema-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,14 @@ Defines a [data source](/concepts/components/prisma-schema/data-sources) <span c

A `datasource` block accepts the following fields:

| Name | Required | Type | Description |
| ------------------- | -------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | **Yes** | String (`postgresql`, `mysql`, `sqlite`, `sqlserver`, `mongodb`, `cockroachdb`) | Describes which data source connectors to use. |
| `url` | **Yes** | String (URL) | Connection URL including authentication info. Most connectors use [the syntax provided by the database](/reference/database-reference/connection-urls#format). |
| `shadowDatabaseUrl` | No | String (URL) | Connection URL to the shadow database used by Prisma Migrate. Allows you to use a cloud-hosted database as the shadow database. |
| `relationMode` | No | String (`foreignKeys`, `prisma`) | Sets whether [referential integrity](/concepts/components/prisma-schema/relations/relation-mode) is enforced by foreign keys in the database or emulated in the Prisma Client.<br /><br />In preview in versions 3.1.1 and later. The field is named `relationMode` in versions 4.5.0 and later, and was previously named `referentialIntegrity`. |
| `extensions` | No | List of strings (PostgreSQL extension names) | Allows you to [represent PostgreSQL extensions in your schema](/concepts/components/prisma-schema/postgresql-extensions#how-to-represent-postgresql-extensions-in-your-prisma-schema). Available in preview for PostgreSQL only in Prisma versions 4.5.0 and later. |
| Name | Required | Type | Description |
| ------------------- | -------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | **Yes** | String (`postgresql`, `mysql`, `sqlite`, `sqlserver`, `mongodb`, `cockroachdb`) | Describes which data source connectors to use. |
| `url` | **Yes** | String (URL) | Connection URL including authentication info. Most connectors use [the syntax provided by the database](/reference/database-reference/connection-urls#format). |
| `shadowDatabaseUrl` | No | String (URL) | Connection URL to the shadow database used by Prisma Migrate. Allows you to use a cloud-hosted database as the shadow database. |
| `directUrl` | No | String (URL) | Connection URL for [direct connection to the database](/data-platform/data-proxy/prisma-cli-with-data-proxy#set-a-direct-database-connection-url-in-your-prisma-schema).<br /><br />If you use a connection pooler URL in the `url` argument (for example, if you use the Data Proxy or pgBouncer), Prisma CLI commands [that require a direct connection to the database](/data-platform/data-proxy/prisma-cli-with-data-proxy#prisma-cli-commands-that-require-a-direct-database-connection) (such as `migrate dev` or `db pull`) use the URL in the `directUrl` argument. |
| `relationMode` | No | String (`foreignKeys`, `prisma`) | Sets whether [referential integrity](/concepts/components/prisma-schema/relations/relation-mode) is enforced by foreign keys in the database or emulated in the Prisma Client.<br /><br />In preview in versions 3.1.1 and later. The field is named `relationMode` in versions 4.5.0 and later, and was previously named `referentialIntegrity`. |
| `extensions` | No | List of strings (PostgreSQL extension names) | Allows you to [represent PostgreSQL extensions in your schema](/concepts/components/prisma-schema/postgresql-extensions#how-to-represent-postgresql-extensions-in-your-prisma-schema). Available in preview for PostgreSQL only in Prisma versions 4.5.0 and later. |

The following providers are available:

Expand Down
53 changes: 25 additions & 28 deletions content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,17 @@ tocDepth: 3

Currently, you can only use [Prisma Client](/concepts/components/prisma-client) with the Data Proxy to _query_ your database.

</TopBlock>

When using Prisma CLI, you need a direct (non-Data Proxy) database connection if you apply schema changes to your database with [Prisma Migrate](/concepts/components/prisma-migrate/get-started) or [`db push`](/concepts/components/prisma-migrate/db-push), or if you [introspect](/concepts/components/introspection) your database. See [Prisma CLI commands that require a direct database connection](#prisma-cli-commands-that-require-a-direct-database-connection).

### Problem
If you want to run [migrations](/concepts/components/prisma-migrate/get-started), [introspection](/concepts/components/introspection), or any of the [Prisma CLI commands](/reference/api-reference/command-reference) listed below, you can only do so on a direct (non-Data Proxy) database connection.
In Prisma versions 4.9.0 and later, you can [set a direct database connection URL in your Prisma schema](#set-a-direct-database-connection-url-in-your-prisma-schema).

<Admonition type="warning">
In earlier versions, you must add an [environment variable](/guides/development-environment/environment-variables) with the direct database connection URL and overwrite the [`DATABASE_URL` environment variable](/guides/development-environment/environment-variables#example-set-the-database_url-environment-variable-in-an-env-file) when you need a direct connection.

**Important**<br /><br />
</TopBlock>

If your database is behind a firewall, add your local IP address to the allowlist of your database.
## Prisma CLI commands that require a direct database connection

</Admonition>
The following [Prisma CLI commands](/reference/api-reference/command-reference) require a direct connection:
Comment thread
keerlu marked this conversation as resolved.

- `prisma db pull`
- `prisma migrate deploy`
Expand All @@ -35,29 +33,28 @@ If your database is behind a firewall, add your local IP address to the allowlis
- `prisma db execute`
- `prisma studio`

### Solution

Assuming that you have `env("DATABASE_URL")` in your `schema.prisma` file, you must override the `DATABASE_URL` environment variable before you run `npx prisma migrate deploy` or any of the commands in the list above.

You can declare the environment variable `MIGRATE_DATABASE_URL`, and use that to override the connection.
## Set a direct database connection URL in your Prisma schema
Comment thread
keerlu marked this conversation as resolved.

For example:
To provide a URL for a direct database connection, set the `directUrl` property in the [`datasource`](/reference/api-reference/prisma-schema-reference#datasource) block of your Prisma schema:

```bash file=.env highlight=2;add
DATABASE_URL="prisma://..."
MIGRATE_DATABASE_URL="postgresql://..."
```prisma file=schema.prisma highlight=8;add
generator client {
provider = "prisma-client-js"
}

datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
directUrl = env("DIRECT_URL")
}
```

Then, in `package.json` under `scripts`, you can add a new line for each Prisma CLI command you want to use so as to override the Data Proxy connection string.
Then add the `DIRECT_URL` environment variable to your [`.env` file](/guides/development-environment/environment-variables#using-env-files):

```js file=package.json highlight=5,6;add
{
...,
"scripts": {
"generate-client": "prisma generate --data-proxy",
"migrate-deploy": "DATABASE_URL=\"$MIGRATE_DATABASE_URL\" prisma migrate deploy",
"dev": "DATABASE_URL=\"$MIGRATE_DATABASE_URL\" prisma migrate dev",
}
}
```
```env file=.env highlight=4-5;add
# Connection to Prisma Data Proxy. Used by Prisma Client.
DATABASE_URL="prisma://__HOST__/?api_key=__KEY__"

# Connection to the database. Used for migrations and introspection.
DIRECT_URL="postgresql://__USER__:__PASSWORD__@__HOST__:__PORT__/__DATABASE__"
```