From fe702894f6a723cb937513de29166d7cb2a8776c Mon Sep 17 00:00:00 2001 From: Lucy Keer Date: Tue, 10 Jan 2023 10:41:01 +0000 Subject: [PATCH 1/8] Update schema reference --- .../200-api-reference/100-prisma-schema-reference.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx b/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx index 4fde0f9103..e4294f9bbe 100644 --- a/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx +++ b/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx @@ -19,6 +19,7 @@ A `datasource` block accepts the following fields: | `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.

If you use the Data Proxy, the generated Prisma Client uses the URL defined by the `url` argument. All other connections use the URL defined by 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.

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. | @@ -1468,7 +1469,7 @@ Defines a multi-field ID (composite ID) on the model. | ----------- | -------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fields` | **Yes** | `FieldReference[]` | A list of field names - for example, `["firstname", "lastname"]` | | `name` | **No** | `String` | The name that the Client API will expose for the argument covering all fields, e.g. `fullName` in `fullName: { firstName: "First", lastName: "Last"}` | -| `map` | **No** | `String` | The name of the underlying primary key constraint in the database.

Not supported for MySQL. | +| `map` | **No** | `String` | The name of the underlying primary key constraint in the database.

Not supported for MySQL. | | `length` | **No** | `number` | Allows you to specify a maximum length for the subpart of the value to be indexed.

MySQL only. In preview in versions 3.5.0 and later, and in general availability in versions 4.0.0 and later. | | `sort` | **No** | `String` | Allows you to specify in what order the entries of the ID are stored in the database. The available options are `Asc` and `Desc`.

SQL Server only. In preview in versions 3.5.0 and later, and in general availability in versions 4.0.0 and later. | | `clustered` | **No** | `Boolean` | Defines whether the ID is clustered or non-clustered. Defaults to `true`.

SQL Server only. In preview in versions 3.13.0 and later, and in general availability in versions 4.0.0 and later. | From 010c7cd2208a2d21f6b99aae683ea7e78322f25e Mon Sep 17 00:00:00 2001 From: Lucy Keer Date: Tue, 10 Jan 2023 14:32:31 +0000 Subject: [PATCH 2/8] Update CLI commands with Data Proxy page --- .../700-prisma-cli-with-data-proxy.mdx | 63 ++++++++++--------- 1 file changed, 33 insertions(+), 30 deletions(-) diff --git a/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx b/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx index 053e1abd0f..e006cc3e11 100644 --- a/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx +++ b/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx @@ -9,19 +9,9 @@ tocDepth: 3 Currently, you can only use [Prisma Client](/concepts/components/prisma-client) with the Data Proxy to _query_ your database. - - +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. -### 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. - - - -**Important**

- -If your database is behind a firewall, add your local IP address to the allowlist of your database. - - +The following [Prisma CLI commands](/reference/api-reference/command-reference) require a direct connection: - `prisma db pull` - `prisma migrate deploy` @@ -35,29 +25,42 @@ If your database is behind a firewall, add your local IP address to the allowlis - `prisma db execute` - `prisma studio` -### Solution +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). -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. +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. -You can declare the environment variable `MIGRATE_DATABASE_URL`, and use that to override the connection. + -For example: +**Important**

-```bash file=.env highlight=2;add -DATABASE_URL="prisma://..." -MIGRATE_DATABASE_URL="postgresql://..." +If your database is behind a firewall, add your local IP address to the allowlist of your database. -``` + + + + +## Set a direct database connection URL in your Prisma schema + +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: -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. +```prisma file=schema.prisma highlight=8;add +generator client { + provider = "prisma-client-js" +} -```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", - } +datasource db { + provider = "postgresql" + url = env("DATABASE_URL") + directUrl = env("DIRECT_URL") } -``` \ No newline at end of file +``` + +Then add the `DIRECT_URL` environment variable to your [`.env` file](/guides/development-environment/environment-variables#using-env-files): + +```env file=.env highlight=4-5;add +# Connection to Prisma Data Proxy. Used by Prisma Client. +URL="prisma://__HOST__/?api_key=__KEY__" + +# Connection to the database. Used for migrations and introspection. +DIRECT_URL="postgresql://__USER__:__PASSWORD__@__HOST__:__PORT__/__DATABASE__" +``` From bb69e69d934b9beb8984ae41d04550ea5a8d81ac Mon Sep 17 00:00:00 2001 From: Lucy Keer Date: Wed, 11 Jan 2023 09:32:29 +0000 Subject: [PATCH 3/8] Update content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx Co-authored-by: Jan Piotrowski --- .../050-data-proxy/700-prisma-cli-with-data-proxy.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx b/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx index e006cc3e11..253f239c77 100644 --- a/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx +++ b/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx @@ -59,7 +59,7 @@ Then add the `DIRECT_URL` environment variable to your [`.env` file](/guides/dev ```env file=.env highlight=4-5;add # Connection to Prisma Data Proxy. Used by Prisma Client. -URL="prisma://__HOST__/?api_key=__KEY__" +DATABASE_URL="prisma://__HOST__/?api_key=__KEY__" # Connection to the database. Used for migrations and introspection. DIRECT_URL="postgresql://__USER__:__PASSWORD__@__HOST__:__PORT__/__DATABASE__" From 662103f811f9d27181ca4e5ce60e9a4b81ec8941 Mon Sep 17 00:00:00 2001 From: Lucy Keer Date: Fri, 13 Jan 2023 10:03:15 +0000 Subject: [PATCH 4/8] Remove firewall admonition --- .../050-data-proxy/700-prisma-cli-with-data-proxy.mdx | 8 -------- 1 file changed, 8 deletions(-) diff --git a/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx b/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx index 253f239c77..fb5a582a92 100644 --- a/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx +++ b/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx @@ -29,14 +29,6 @@ In Prisma versions 4.9.0 and later, you can [set a direct database connection UR 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**

- -If your database is behind a firewall, add your local IP address to the allowlist of your database. - - - ## Set a direct database connection URL in your Prisma schema From 945bf7e3fcc016a57584ff29ed99fe42af8a1927 Mon Sep 17 00:00:00 2001 From: Lucy Keer Date: Fri, 13 Jan 2023 10:15:12 +0000 Subject: [PATCH 5/8] Update directUrl argument description --- .../100-prisma-schema-reference.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx b/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx index 82921a0e39..40140932b2 100644 --- a/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx +++ b/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx @@ -14,14 +14,14 @@ Defines a [data source](/concepts/components/prisma-schema/data-sources)
If you use the Data Proxy, the generated Prisma Client uses the URL defined by the `url` argument. All other connections use the URL defined by 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.

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).

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 (such as `migrate` 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.

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: @@ -620,7 +620,7 @@ True or false value. | ----------- | --------------- | | PostgreSQL | `bigint` | | SQL Server | `int` | -| MySQL | `BIGINT` | +| MySQL | `BIGINT` | | MongoDB | `Long` | | SQLite | `INTEGER` | | CockroachDB | `INTEGER` | From da331320f7f5f37ee639cdf29dad4cac2fb20010 Mon Sep 17 00:00:00 2001 From: Lucy Keer Date: Fri, 13 Jan 2023 10:20:27 +0000 Subject: [PATCH 6/8] Move list of commands to its own section --- .../700-prisma-cli-with-data-proxy.mdx | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx b/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx index fb5a582a92..f0077b57bd 100644 --- a/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx +++ b/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx @@ -9,7 +9,15 @@ tocDepth: 3 Currently, you can only use [Prisma Client](/concepts/components/prisma-client) with the Data Proxy to _query_ your database. -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. +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). + +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). + +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. + + + +## Prisma CLI commands that require a direct database connection The following [Prisma CLI commands](/reference/api-reference/command-reference) require a direct connection: @@ -25,12 +33,6 @@ The following [Prisma CLI commands](/reference/api-reference/command-reference) - `prisma db execute` - `prisma studio` -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). - -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. - - - ## Set a direct database connection URL in your Prisma schema 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: From 965d494362cb6d0cab19cc9dd8d8f5ef3b024b86 Mon Sep 17 00:00:00 2001 From: Lucy Keer Date: Tue, 17 Jan 2023 09:29:16 +0000 Subject: [PATCH 7/8] Link to list of commands --- .../100-prisma-schema-reference.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx b/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx index 40140932b2..a9fef8abd7 100644 --- a/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx +++ b/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx @@ -14,14 +14,14 @@ Defines a [data source](/concepts/components/prisma-schema/data-sources)
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 (such as `migrate` 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.

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).

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.

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: From 1ad2ee9fb1e1bd525e6bceb97b0fd5733f6c6532 Mon Sep 17 00:00:00 2001 From: Sabin Adams Date: Mon, 6 Feb 2023 10:30:16 -0800 Subject: [PATCH 8/8] Revises a sentence for clarity --- .../050-data-proxy/700-prisma-cli-with-data-proxy.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx b/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx index f0077b57bd..7a05cd56ed 100644 --- a/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx +++ b/content/800-data-platform/050-data-proxy/700-prisma-cli-with-data-proxy.mdx @@ -9,7 +9,7 @@ tocDepth: 3 Currently, you can only use [Prisma Client](/concepts/components/prisma-client) with the Data Proxy to _query_ your database. -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). +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). 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).