Skip to content
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.

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

fix(dbgenerated): Fix wording and details around dbgenerated and default #5007

Merged
merged 14 commits into from
Jun 10, 2024
Merged
Original file line number Diff line number Diff line change
Expand Up @@ -1053,9 +1053,9 @@ model Post {

[`cuid()`](/reference/api-reference/prisma-schema-reference#cuid) <span class="api"></span> and [`uuid()`](/reference/api-reference/prisma-schema-reference#uuid) <span class="api"></span> are implemented by Prisma and therefore are not "visible" in the underlying database schema. You can still use them when using [introspection](/concepts/components/introspection) by [manually changing your Prisma schema](/concepts/components/prisma-client/working-with-prismaclient/use-custom-model-and-field-names) and [generating Prisma Client](/concepts/components/prisma-client/working-with-prismaclient/generating-prisma-client), in that case the values will be generated by Prisma's [query engine](/concepts/components/prisma-engines/query-engine)

Support for [`autoincrement()`](/reference/api-reference/prisma-schema-reference#autoincrement) <span class="api"></span>, [`now()`](/reference/api-reference/prisma-schema-reference#now) <span class="api"></span> and [`dbgenerated()`](/reference/api-reference/prisma-schema-reference#dbgenerated) <span class="api"></span> differ between databases.
Support for [`autoincrement()`](/reference/api-reference/prisma-schema-reference#autoincrement) <span class="api"></span>, [`now()`](/reference/api-reference/prisma-schema-reference#now) <span class="api"></span> and [`dbgenerated(...)`](/reference/api-reference/prisma-schema-reference#dbgenerated) <span class="api"></span> differ between databases.

**Relational database connectors** implement `autoincrement()`, `dbgenerated()`, and `now()` at database level. The **MongoDB connector** does not support `autoincrement()` or `dbgenerated()`, and `now()` is implemented at Prisma level. The [`auto()`](/reference/api-reference/prisma-schema-reference#auto) function is used to generate an `ObjectId`.
**Relational database connectors** implement `autoincrement()`, `dbgenerated(...)`, and `now()` at database level. The **MongoDB connector** does not support `autoincrement()` or `dbgenerated(...)`, and `now()` is implemented at Prisma level. The [`auto()`](/reference/api-reference/prisma-schema-reference#auto) function is used to generate an `ObjectId`.

## Relations

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ model Post {
}
```

However, you can also use **native database functions** to define default values with [`dbgenerated()`](/reference/api-reference/prisma-schema-reference#dbgenerated) <span class="api"></span> on relational databases (MongoDB does not have the concept of database-level functions). The following example uses the PostgreSQL `gen_random_uuid()` function to populate the `id` field:
However, you can also use **native database functions** to define default values with [`dbgenerated(...)`](/reference/api-reference/prisma-schema-reference#dbgenerated) <span class="api"></span> on relational databases (MongoDB does not have the concept of database-level functions). The following example uses the PostgreSQL `gen_random_uuid()` function to populate the `id` field:

```prisma
model User {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1160,7 +1160,7 @@ Defines a single-field ID on the model.
##### Relational databases

- Corresponding database type: `PRIMARY KEY`
- Can be annotated with a [`@default()`](#default) value that uses [functions](#attribute-functions) to auto-generate an ID:
- Can be annotated with a [`@default`](#default) value that uses [functions](#attribute-functions) to auto-generate an ID:
janpio marked this conversation as resolved.
Show resolved Hide resolved

- [`autoincrement()`](#autoincrement)
- [`cuid()`](#cuid)
Expand All @@ -1183,7 +1183,7 @@ Defines a single-field ID on the model.
id String @db.ObjectId @map("_id")
```

- Optionally, annotate your field with a [`@default()`](#default) value that uses [the `auto()` function](#auto) to auto-generate an `ObjectId`
- Optionally, annotate your field with a [`@default`](#default) value that uses [the `auto()` function](#auto) to auto-generate an `ObjectId`
janpio marked this conversation as resolved.
Show resolved Hide resolved

```prisma
id String @db.ObjectId @map("_id") @default(auto())
Expand Down Expand Up @@ -1465,7 +1465,7 @@ Defines a multi-field ID (composite ID) on the model.
#### Remarks

- Corresponding database type: `PRIMARY KEY`
- Can be annotated with a [`@default()`](#default) value that uses [functions](#attribute-functions) to auto-generate an ID
- Can be annotated with a [`@default`](#default) value that uses [functions](#attribute-functions) to auto-generate an ID
janpio marked this conversation as resolved.
Show resolved Hide resolved
- Cannot be optional
- Can be defined on any scalar field (`String`, `Int`, `enum`)
- Cannot be defined on a relation field
Expand Down Expand Up @@ -1671,12 +1671,12 @@ Defines a [default value for a field](/concepts/components/prisma-schema/data-mo

- [`autoincrement()`](#autoincrement)
- [`sequence()`](#sequence) (CockroachDB only)
- [`dbgenerated()`](#dbgenerated)
- [`dbgenerated(...)`](#dbgenerated)
- [`cuid()`](#cuid)
- [`uuid()`](#uuid)
- [`now()`](#now)

- Default values that cannot yet be represented in the Prisma schema are represented by the `dbgenerated()` function when you use [introspection](/concepts/components/introspection).
- Default values that cannot yet be represented in the Prisma schema are represented by the [`dbgenerated(...)` function](#dbgenerated) when you use [introspection](/concepts/components/introspection).
- Default values are not allowed on relation fields in the Prisma schema. Note however that you can still define default values on the fields backing a relation (the ones listed in the `fields` argument in the `@relation` attribute). A default value on the field backing a relation will mean that relation is populated automatically for you.
- Default values can be used with [scalar lists](/concepts/components/prisma-client/working-with-fields/working-with-scalar-lists-arrays) in databases that natively support them.

Expand Down Expand Up @@ -3234,22 +3234,23 @@ Set a timestamp of the time when a record is created.

- Implemented at Prisma level

### <inlinecode>dbgenerated()</inlinecode>
### <inlinecode>dbgenerated(...)</inlinecode>

Represents **default values** that cannot be expressed in the Prisma schema (such as `random()`).

#### Remarks

##### Relational databases

- Compatible with any type
- If a value is present, it cannot be empty (for example, `dbgenerated("")`) - [2.21.0](https://github.com/prisma/prisma/releases/tag/2.21.0) and later
- Compatible with any scalar type
- Needs a value, `dbgenerated()` is not allowed in [TODO](https://github.com/prisma/prisma/releases/tag/TODO) and later
nikolasburk marked this conversation as resolved.
Show resolved Hide resolved
nikolasburk marked this conversation as resolved.
Show resolved Hide resolved
- Can not be an empty string `dbgenerated("")` in [2.21.0](https://github.com/prisma/prisma/releases/tag/2.21.0) and later
- Accepts a `String` value in [2.17.0](https://github.com/prisma/prisma/releases/tag/2.17.0) and later, which allows you to:

- [Set default values for `Unsupported` types](#set-default-value-for-unsupported-type)
- [Override default value behavior for supported types](#override-default-value-behavior-for-supported-types)

- String values in `dbgenerated` might not match what the DB returns as the default value, because values such as strings may be explicitly cast (e.g. `'hello'::STRING`). When a mismatch is present, Prisma Migrate indicates a migration is still needed. You can use `prisma db pull` to infer the correct value to resolve the discrepancy. ([Related issue](https://github.com/prisma/prisma/issues/14917))
- String values in `dbgenerated(...)` might not match what the DB returns as the default value, because values such as strings may be explicitly cast (e.g. `'hello'::STRING`). When a mismatch is present, Prisma Migrate indicates a migration is still needed. You can use `prisma db pull` to infer the correct value to resolve the discrepancy. ([Related issue](https://github.com/prisma/prisma/issues/14917))

#### Examples

Expand All @@ -3272,7 +3273,7 @@ circle Unsupported("circle")? @default(dbgenerated("'<(10,4),11>'::circle"
<TabbedContent tabs={[<FileWithIcon text="Relational databases only" icon="database"/>]}>
<tab>

You can also use `dbgenerated()` to set the default value for supported types. For example, in PostgreSQL you can generate UUIDs at the database level rather than rely on Prisma's `uuid()`:
You can also use `dbgenerated(...)` to set the default value for supported types. For example, in PostgreSQL you can generate UUIDs at the database level rather than rely on Prisma's `uuid()`:

```prisma highlight=2;add|3;delete
model User {
Expand Down