# Capabilities (/docs/orm/next/contract-authoring/capabilities)

> For the complete Prisma documentation index, see [llms.txt](https://www.prisma.io/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL.

Capabilities record what your database stack supports, so Prisma Next can reject unsupported features early with a clear error.

Location: ORM > Next > Contract authoring > Capabilities

Not every database stack supports every feature. One setup can run lateral joins, `RETURNING` clauses, and vector distance operations; another cannot.

Capabilities are how the [data contract](https://www.prisma.io/docs/orm/next/contract-authoring/the-data-contract) records what yours supports. Prisma Next checks them before using a gated feature, so an unsupported feature fails early, with an error that names the missing capability, instead of surfacing as a database error mid-query.

## Where capabilities come from [#where-capabilities-come-from]

You do not write capabilities yourself. When [`prisma-next contract emit`](https://www.prisma.io/docs/cli/next/contract-emit) runs, it merges the capability declarations of every component composed in your project: the target (PostgreSQL, SQLite, MongoDB), its adapter and driver, and any extension packs from the config. The merged result lands in the contract's `capabilities` section, grouped by namespace:

```json title="prisma/contract.json (excerpt)"
{
  "capabilities": {
    "postgres": {
      "distinctOn": true,
      "jsonAgg": true,
      "lateral": true,
      "limit": true,
      "orderBy": true,
      "pgvector.cosine": true,
      "returning": true
    },
    "sql": {
      "defaultInInsert": true,
      "enums": true,
      "lateral": true,
      "returning": true,
      "scalarList": true
    }
  }
}
```

The `sql` namespace holds keys shared across SQL databases; the `postgres` namespace holds PostgreSQL-specific keys. Extension packs contribute keys of their own: composing the pgvector pack is what adds `pgvector.cosine` above. Because the packs declare the keys, adding or removing an extension in `prisma-next.config.ts` and re-running `contract emit` changes the capability set with no further work.

## What capabilities gate [#what-capabilities-gate]

Capabilities are checked at two points, both before any SQL reaches the database.

**When the contract is built.** A schema feature the target cannot store fails emission with a diagnostic. For example, SQLite does not report the `scalarList` capability, so a scalar list field in a contract targeting SQLite fails to emit:

```text
Field "User.tags" is a scalar list, but target "sqlite" does not support
scalar lists (the adapter does not report the "scalarList" capability).
```

**When a query is built.** Query-builder methods that depend on a capability check the contract's matrix and throw if the key is missing, naming the method and the capability:

```text
distinctOn() requires capability postgres.distinctOn
lateralJoin() requires capability sql.lateral
```

The error fires when your code constructs the query, which makes it easy to catch in tests: a query that uses a feature your stack lacks cannot be built at all.

## Example capabilities [#example-capabilities]

A few of the keys the built-in components declare, to give a sense of the granularity:

| Capability                 | Gates                                                                    |
| -------------------------- | ------------------------------------------------------------------------ |
| `sql.lateral`              | Lateral joins (`lateralJoin()`); PostgreSQL declares it, SQLite does not |
| `sql.returning`            | `RETURNING` clauses on writes                                            |
| `sql.enums`                | Enum value sets enforced in the database; SQLite does not declare it     |
| `sql.defaultInInsert`      | Using `DEFAULT` as a value in multi-row inserts                          |
| `sql.scalarList`           | Scalar list fields in the schema                                         |
| `postgres.distinctOn`      | `DISTINCT ON` queries (`distinctOn()`)                                   |
| `postgres.jsonAgg`         | JSON aggregation for nested reads                                        |
| `postgres.pgvector.cosine` | Cosine distance operations, contributed by the pgvector pack             |

This is an illustration, not the full registry; each target, adapter, and pack ships its own declarations. The emitted `contract.json` of your own project is the authoritative list of what your stack supports.

MongoDB currently declares no capability keys: the capability system mostly differentiates SQL targets and their extensions, and the MongoDB pipeline does not yet gate features this way.

## Capabilities and verification [#capabilities-and-verification]

Capabilities describe what the composed software stack supports, as declared by the target, adapter, and packs. They are recorded in the contract at emit time rather than probed from the live database, so the same contract behaves identically in every environment. Database-side verification is the separate hash-and-marker mechanism described in [the contract artifact](https://www.prisma.io/docs/orm/next/contract-authoring/the-contract-artifact#the-content-hashes): [`prisma-next db verify`](https://www.prisma.io/docs/cli/next/db-verify) checks that the database matches the contract's schema and profile.

Extensions are the main source of capabilities beyond the core; [Using extensions](https://www.prisma.io/docs/orm/next/extensions/using-extensions) shows the full install-to-query flow.

## Prompt your coding agent [#prompt-your-coding-agent]

Projects scaffolded with `create-prisma@next` install [Prisma Next skills](https://www.prisma.io/docs/ai/tools/skills#available-skills-for-prisma-next) for your coding agent; the `prisma-next-contract` skill covers this page. Ask your agent to:

* "Which capabilities does our contract currently require, and which package provides each?"
* "Add pgvector to the project and confirm the capability shows up in the emitted contract."

## Next steps [#next-steps]

* See where the `capabilities` block sits in [the contract artifact](https://www.prisma.io/docs/orm/next/contract-authoring/the-contract-artifact).
* Compose extension packs, and the capabilities they bring, in the [CLI configuration](https://www.prisma.io/docs/cli/next/configuration).

## Related pages

- [`Author in PSL`](https://www.prisma.io/docs/orm/next/contract-authoring/psl-syntax): Write the Prisma Next contract as a Prisma schema file, using the schema language you already know plus the Prisma Next additions.
- [`Author in TypeScript`](https://www.prisma.io/docs/orm/next/contract-authoring/typescript-schema-builder): Define the Prisma Next contract with a typed builder API instead of a schema file. Same models, same artifacts, no separate language.
- [`The data contract`](https://www.prisma.io/docs/orm/next/contract-authoring/the-data-contract): The data contract is the single description of your data model and its storage layout. Everything in Prisma Next is typed, planned, and verified against it.
- [`The emitted artifacts`](https://www.prisma.io/docs/orm/next/contract-authoring/the-contract-artifact): contract.json and contract.d.ts are the deterministic artifacts every other part of Prisma Next consumes. Here is what is inside them.