Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/prisma/prisma-next/llms.txt

Use this file to discover all available pages before exploring further.

Prisma Next is designed around a thin, stable core. Domain-specific capabilities — vector similarity search, geospatial queries, encrypted columns, full-text search — are delivered as extension packs that you compose into your project rather than built into the core library. Extension packs contribute codecs, operations, migration support, and schema annotations, all gated by what you declare in your contract.

​
What extension packs contribute

An extension pack is a structured bundle that can provide any combination of the following:
  • Schema annotations — new attributes you can apply to fields in PSL or TypeScript authoring (e.g. @pgvector.column(length: 1536))
  • Codecs — encode/decode implementations for new data types (e.g. number[] for vector columns, branded Geometry for PostGIS)
  • Query operations — new methods on column references in the DSL (e.g. .cosineDistance(), .cosineSimilarity())
  • Capability declarations — capability keys that gate whether the runtime is allowed to use the pack’s operations
  • Baseline migrations — on-disk migration files that install required database extensions (e.g. CREATE EXTENSION IF NOT EXISTS vector)
Extension packs declare their contributions via a manifest. The emitter validates that your contract’s declared capabilities match what the pack supports, so mismatches surface at emit time rather than at runtime.

​
Adding an extension pack

1

Install the pack package

pnpm add @prisma-next/extension-pgvector
2

Add it to prisma-next.config.ts

Import the pack’s control-plane descriptor and add it to the extensions list. Use extensions with the simplified @prisma-next/postgres/config facade, or extensionPacks with the full @prisma-next/cli/config-types directly:
// prisma-next.config.ts (full config)
import { defineConfig } from '@prisma-next/cli/config-types';
import postgresAdapter from '@prisma-next/adapter-postgres/control';
import sql from '@prisma-next/family-sql/control';
import postgres from '@prisma-next/target-postgres/control';
import pgvector from '@prisma-next/extension-pgvector/control';

export default defineConfig({
  family: sql,
  target: postgres,
  adapter: postgresAdapter,
  extensionPacks: [pgvector],
});
3

Use the pack in your contract

In TypeScript authoring mode, pass the pack’s pack-ref to defineContract and use its column types:
// prisma/contract.ts
import { defineContract, field, model } from '@prisma-next/sql-contract-ts/contract-builder';
import { vector } from '@prisma-next/extension-pgvector/column-types';
import pgvector from '@prisma-next/extension-pgvector/pack';
import sqlFamily from '@prisma-next/family-sql/pack';
import postgresPack from '@prisma-next/target-postgres/pack';

export const contract = defineContract({
  family: sqlFamily,
  target: postgresPack,
  extensionPacks: { pgvector },
  models: {
    Post: model('Post', {
      fields: {
        id:        field.id.uuidv4(),
        title:     field.text(),
        embedding: field.column(vector(1536)).optional(),
      },
    }).sql({ table: 'post' }),
  },
});
In PSL mode, use the annotation syntax the pack provides:
model Document {
  id        Int    @id
  title     String
  embedding Bytes  @pgvector.column(length: 1536)
}
4

Emit the contract

prisma-next contract emit
The emitter validates the pack’s capabilities against the contract and embeds the pack’s type imports and codec references into contract.d.ts.
5

Register the pack at runtime

When constructing your execution stack, include the pack’s runtime descriptor:
import pgvector from '@prisma-next/extension-pgvector/runtime';
import { createSqlExecutionStack } from '@prisma-next/sql-runtime';

const stack = createSqlExecutionStack({
  target: postgresTarget,
  adapter: postgresAdapter,
  extensionPacks: [pgvector],
});

​
How extension packs gate capabilities

Every operation contributed by a pack is gated by a capability key declared in the contract. For example, the pgvector pack declares the pgvector.cosine capability. Your contract must include that key in its capabilities section for the cosineDistance and cosineSimilarity operations to be available in queries. The migration runner verifies — before applying any migration — that the live database satisfies the declared capabilities. For pgvector, this means the vector Postgres extension must be installed. The pgvector pack ships a baseline migration that runs CREATE EXTENSION IF NOT EXISTS vector automatically when you run prisma-next db init or prisma-next db update. If a query uses an operation from a pack that is not declared in the contract, the emitter or runtime surfaces a structured error — not a silent type mismatch or SQL error at execution time. The @prisma-next/extension-pgvector pack adds support for the vector Postgres type and cosine distance/similarity operations. 
import { param } from '@prisma-next/sql-query/param';

const searchVector = [0.1, 0.2, /* ... 1536 dimensions total */];

const plan = db.sql
  .from(tables.post)
  .select({
    id:       tables.post.columns.id,
    title:    tables.post.columns.title,
    distance: tables.post.columns.embedding.cosineDistance(param('searchVector')),
  })
  .orderBy(tables.post.columns.embedding.cosineDistance(param('searchVector')).asc())
  .limit(10)
  .build({ params: { searchVector } });

const results = await runtime.execute(plan);
// results: Array<{ id: string; title: string; distance: number }>
The vector(N) column factory enforces that every vector column declares an explicit dimension. The runtime codec is constructed against { length: N }, ensuring type-level dimension information (Vector<1536>) flows through to contract.d.ts and query result types.

​
Available extension packs

pgvector

Vector similarity search for PostgreSQL using the pgvector extension. Adds the vector type, cosineDistance, and cosineSimilarity operations.

PostGIS

Geospatial data support for PostgreSQL. Adds geometry and geography types, spatial indexes, and spatial query operations.

CipherStash

Encrypted column support using CipherStash EQL. Adds searchable encryption for sensitive fields with full query capability.

Build docs developers (and LLMs) love

Get started for freeTalk to us