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

Update documentation for ORM 6.2 #6567

Merged
merged 9 commits into from
Jan 7, 2025
18 changes: 12 additions & 6 deletions content/200-orm/050-overview/500-databases/500-sqlite.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,15 @@ metaDescription: 'This page explains how Prisma can connect to a SQLite database
tocDepth: 3
---

<TopBlock>

The SQLite data source connector connects Prisma ORM to a [SQLite](https://www.sqlite.org/) database file. These files always have the file ending `.db` (e.g.: `dev.db`).

By default, the SQLite connector contains a database driver responsible for connecting to your database. You can use a [driver adapter](/orm/overview/databases/database-drivers#driver-adapters) (Preview) to connect to your database using a JavaScript database driver from Prisma Client.

</TopBlock>

## Example

To connect to a SQLite database file, you need to configure a [`datasource`](/orm/prisma-schema/overview/data-sources) block in your [Prisma schema](/orm/prisma-schema):

```prisma file=schema.prisma showLineNumbers
```prisma file=schema.prisma
datasource db {
provider = "sqlite"
url = "file:./dev.db"
Expand Down Expand Up @@ -46,8 +42,18 @@ The SQLite connector maps the [scalar types](/orm/prisma-schema/data-model/model
| `Float` | `REAL` |
| `Decimal` | `DECIMAL` |
| `DateTime` | `NUMERIC` |
| `Json` | Not supported |
| `Json` | `JSONB` |
| `Bytes` | `BLOB` |
| `Enum` | `TEXT` |

:::warning

When using `enum` fields in SQLite, be aware of the following:

- **No database-level enforcement for correctness**: If you bypass Prisma ORM and store an invalid enum entry in the database, Prisma Client queries will fail at runtime when reading that entry.
- **No migration-level enforcement for correctness**: It's possible to end up with incorrect data after schema changes similarly to MongoDB (since the enums aren't checked by the database).

:::

## Rounding errors on big numbers

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ const users = await prisma.user.findFirst()
If you want to customize the result and have a different combination of fields returned, you can:

- Use [`select`](/orm/reference/prisma-client-reference#select) to return specific fields. You can also use a [nested `select`](/orm/prisma-client/queries/relation-queries#select-specific-fields-of-included-relations) by selecting relation fields.
- Use [`omit`](/orm/reference/prisma-client-reference#omit-preview) to exclude specific fields from the result. `omit` can be seen as the "opposite" to `select`.
- Use [`omit`](/orm/reference/prisma-client-reference#omit) to exclude specific fields from the result. `omit` can be seen as the "opposite" to `select`.
- Use [`include`](/orm/reference/prisma-client-reference#include) to additionally [include relations](/orm/prisma-client/queries/relation-queries#nested-reads).

In all cases, the query result will be statically typed, ensuring that you don't accidentally access any fields that you did not actually query from the database.
Expand Down
134 changes: 34 additions & 100 deletions content/200-orm/200-prisma-client/100-queries/063-excluding-fields.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,44 +4,23 @@ metaTitle: 'Excluding fields'
metaDescription: 'This page explains how to exclude sensitive fields from Prisma Client'
---

By default Prisma Client returns all fields from a model. You can use `select` to narrow the result set, but that can be unwieldy if you have a large model and you only want to exclude one or two fields.
By default Prisma Client returns all fields from a model. You can use [`select`](/orm/prisma-client/queries/select-fields) to narrow the result set, but that can be unwieldy if you have a large model and you only want to exclude a small number of fields.

:::info

As of Prisma ORM 5.16.0, excluding fields globally and locally is supported via the `omitApi` Preview feature.
As of Prisma ORM 6.2.0, excluding fields is supported via the `omit` option that you can pass to Prisma Client. From versions 5.16.0 through 6.1.0, you must use the `omitApi` Preview feature to access this option.

:::

## Excluding a field globally using `omit`

The following is a type-safe way to exclude a field globally using the [`omitApi` Preview feature](/orm/reference/preview-features):
The following is a type-safe way to exclude a field _globally_ (i.e. for _all_ queries against a given model):

<TabbedContent code>

<TabItem value="Schema">

```prisma
generator client {
provider = "prisma-client-js"
previewFeatures = ["omitApi"]
}

model User {
id Int @id @default(autoincrement())
firstName String
lastName String
email String @unique
password String
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
}
nikolasburk marked this conversation as resolved.
Show resolved Hide resolved
```

</TabItem>

<TabItem value="Code">

```tsx
```ts
const prisma = new PrismaClient({
omit: {
user: {
Expand All @@ -56,38 +35,33 @@ const user = await prisma.user.findUnique({ where: { id: 1 } })

</TabItem>

</TabbedContent>

## Excluding a field locally using `omit`

The following is a type-safe way to exclude a field locally using the `omitApi` Preview feature:

<TabbedContent code>

<TabItem value="Schema">

```prisma
generator client {
provider = "prisma-client-js"
previewFeatures = ["omitApi"]
}

model User {
id Int @id @default(autoincrement())
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
firstName String
lastName String
email String @unique
password String
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
}
```

</TabItem>

</TabbedContent>

## Excluding a field locally using `omit`

The following is a type-safe way to exclude a field _locally_ (i.e. for a _single_ query):

<TabbedContent code>

<TabItem value="Code">

```tsx
```ts
const prisma = new PrismaClient()

// The password field is excluded only in this query
Expand All @@ -103,6 +77,23 @@ const user = await prisma.user.findUnique({

</TabItem>


<TabItem value="Schema">

```prisma
model User {
id Int @id @default(autoincrement())
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
firstName String
lastName String
email String @unique
password String
}
```

</TabItem>

</TabbedContent>

## How to omit multiple fields
Expand Down Expand Up @@ -171,64 +162,7 @@ const user = await prisma.user.findUnique({

It's important to understand when to omit a field globally or locally:

- If you are omitting a field in order to prevent it from accidentally being included in a query, it's best to omit it globally. For example: Globally omitting the password field from a User model so that sensitive information doesn't accidentally get exposed.
- If you are omitting a field because it's not needed in a query, it's best to omit it locally.
- If you are omitting a field in order to prevent it from accidentally being included in a query, it's best to omit it _globally_. For example: Globally omitting the `password` field from a `User` model so that sensitive information doesn't accidentally get exposed.
- If you are omitting a field because it's not needed in a query, it's best to omit it _locally_.

Local omit (when an `omit` option is provided in a query) only applies to the query it is defined in, while a global omit applies to every query made with the same Prisma Client instance, [unless a specific select is used or the omit is overridden](#how-to-select-a-previously-omitted-field).

## Excluding the password field without using `omit`

:::note

The `omitApi` Preview feature, released in Prisma ORM 5.13.0, is the preferred way of omitting fields from a query result. The ability to globally omit fields was added to the `omitApi` Preview feature in Prisma ORM 5.16.0. This documentation is still relevant for versions of Prisma ORM prior to 5.13.0.

:::

The following is a type-safe `exclude` function returns a user without the `password` field.

<TabbedContent code>

<TabItem value="TypeScript">

```tsx
// Exclude keys from user
function exclude<User, Key extends keyof User>(
user: User,
keys: Key[]
): Omit<User, Key> {
return Object.fromEntries(
Object.entries(user).filter(([key]) => !keys.includes(key))
)
}

function main() {
const user = await prisma.user.findUnique({ where: 1 })
const userWithoutPassword = exclude(user, ['password'])
}
```

</TabItem>

<TabItem value="JavaScript">

```js
// Exclude keys from user
function exclude(user, keys) {
return Object.fromEntries(
Object.entries(user).filter(([key]) => !keys.includes(key))
);
}

function main() {
const user = await prisma.user.findUnique({ where: 1 })
const userWithoutPassword = exclude(user, ['password'])
}
```

</TabItem>

</TabbedContent>

In the TypeScript example, we've provided two generics: `User` and `Key`. The `Key` generic is defined as the keys of a `User` (e.g. `email`, `password`, `firstName`, etc.).

These generics flow through the logic, returning a `User` that omits the list of `Key`s provided.
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,6 @@ metaDescription: 'How to read, write, and filter by Json fields.'
tocDepth: 3
---

<TopBlock>

Use the [`Json`](/orm/reference/prisma-schema-reference#json) Prisma ORM field type to read, write, and perform basic filtering on JSON types in the underlying database. In the following example, the `User` model has an optional `Json` field named `extendedPetsData`:

```prisma highlight=6;normal
Expand Down Expand Up @@ -35,7 +33,6 @@ Example field value:
}
```

> **Note**: The `Json` field is only supported if the [underlying database](/orm/overview) has a corresponding JSON data type.

The `Json` field supports a few additional types, such as `string` and `boolean`. These additional types exist to match the types supported by [`JSON.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse):

Expand All @@ -49,8 +46,6 @@ export declare type JsonValue =
| JsonArray
```

</TopBlock>

## Use cases for JSON fields

Reasons to store data as JSON rather than representing data as related models include:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ await user.save()

## Using `omit` query option with `result` extension component

You can use the [`omit` (Preview) option](/orm/reference/prisma-client-reference#omit-preview) with [custom fields](#add-a-custom-field-to-query-results) and fields needed by custom fields.
You can use the [`omit` (Preview) option](/orm/reference/prisma-client-reference#omit) with [custom fields](#add-a-custom-field-to-query-results) and fields needed by custom fields.

### `omit` fields needed by custom fields from query result

Expand Down
Loading
Loading