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.

The pgvector extension pack adds the vector column type and cosine-based similarity operations to Prisma Next for PostgreSQL databases. You define vector columns with an explicit dimension (for example, vector(1536) for OpenAI embeddings), query them with cosineDistance and cosineSimilarity, and let the framework handle the wire format, codec registration, and the CREATE EXTENSION vector baseline migration.

​
What the extension provides

  • vector(N) column type — a dimensioned number[] column backed by the pgvector vector native type. The dimension is carried through contract.d.ts as a Vector<N> branded type.
  • cosineDistance(rhs) — computes cosine distance between two vectors using the pgvector <=> operator.
  • cosineSimilarity(rhs) — computes 1 - cosineDistance, i.e. 1 - (vector1 <=> vector2).
  • Baseline migration — ships an on-disk migration that runs CREATE EXTENSION IF NOT EXISTS vector automatically when the extension is composed into your application.
  • Capability flag — declares pgvector.cosine to signal cosine distance and similarity support.

​
Setup

1

Install the package

pnpm add @prisma-next/extension-pgvector
2

Register the extension in prisma-next.config.ts

Add pgvector to the extensions list. With the simplified @prisma-next/postgres/config facade use extensions; with the full @prisma-next/cli/config-types use extensionPacks:
import { defineConfig } from '@prisma-next/postgres/config';
import pgvector from '@prisma-next/extension-pgvector/control';

export default defineConfig({
  contract: './prisma/schema.psl',
  db: { connection: process.env['DATABASE_URL']! },
  extensions: [pgvector],
});
3

Define vector columns in your contract

Import vector from @prisma-next/extension-pgvector/column-types and use field.column(vector(N)). Every pgvector column must declare an explicit dimension.
src/prisma/contract.ts
import { int4Column, textColumn } from '@prisma-next/adapter-postgres/column-types';
import sqlFamily from '@prisma-next/family-sql/pack';
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 postgres from '@prisma-next/target-postgres/pack';

export const contract = defineContract({
  family: sqlFamily,
  target: postgres,
  extensionPacks: { pgvector },
  models: {
    Post: model('Post', {
      fields: {
        id: field.column(int4Column).id(),
        title: field.column(textColumn),
        embedding: field.column(vector(1536)).optional(),
      },
    }).sql({ table: 'post' }),
  },
});
4

Emit the contract and apply the baseline migration

pnpm prisma-next contract emit
pnpm prisma-next db init
db init applies the bundled baseline migration, which runs CREATE EXTENSION IF NOT EXISTS vector on your database before any application migration.
The baseline migration must be applied before you run workloads that use vector columns. If you are setting up the database manually, run CREATE EXTENSION IF NOT EXISTS vector; before your first migration.
5

Register the extension at runtime

Pass pgvector in the extensionPacks array when creating your execution stack:
src/prisma/db.ts
import { instantiateExecutionStack } from '@prisma-next/framework-components/execution';
import { createExecutionContext, createSqlExecutionStack } from '@prisma-next/sql-runtime';
import postgresAdapter from '@prisma-next/adapter-postgres/runtime';
import postgresTarget from '@prisma-next/target-postgres/runtime';
import pgvector from '@prisma-next/extension-pgvector/runtime';

const stack = createSqlExecutionStack({
  target: postgresTarget,
  adapter: postgresAdapter,
  extensionPacks: [pgvector],
});
const context = createExecutionContext({ contract, stack });
const stackInstance = instantiateExecutionStack(stack);

​
Querying with vector operations

Both operations are available on any vector column as methods on the column expression. Pass the query vector as a param() reference. 
import { sql, tables } from '../prisma/query';
import { param } from '@prisma-next/sql-query/param';

const queryVector = [0.1, 0.2, 0.3, /* ... 1536 values */];

// Order results by cosine distance (nearest first).
const plan = sql
  .from(tables.post)
  .select({
    id: tables.post.columns.id,
    title: tables.post.columns.title,
    distance: tables.post.columns.embedding.cosineDistance(param('queryVector')),
  })
  .orderBy(tables.post.columns.embedding.cosineDistance(param('queryVector')).asc())
  .limit(10)
  .build({ params: { queryVector } });

​
Operations reference

​
cosineDistance

Computes the cosine distance between two vectors. Lower values indicate greater similarity.
  • Signature: cosineDistance(rhs: number[] | vector): number
  • SQL: vector1 <=> vector2 (pgvector <=> operator)

​
cosineSimilarity

Computes the cosine similarity between two vectors (equivalent to 1 - cosineDistance). Higher values indicate greater similarity.
  • Signature: cosineSimilarity(rhs: number[] | vector): number
  • SQL: 1 - (vector1 <=> vector2)

​
Types

​
Vector<N>

Vector<N> is a branded number[] type that carries the vector dimension at the type level. It appears in emitted contract.d.ts files when you use the dimensioned vector(N) column factory. 
import type { CodecTypes, Vector } from '@prisma-next/extension-pgvector/codec-types';

// CodecTypes['pg/vector@1']['output'] is number[]
// Vector<1536> is a branded number[] type for dimensioned columns
type Embedding = Vector<1536>;

​
OperationTypes

import type { QueryOperationTypes } from '@prisma-next/extension-pgvector/operation-types';

// QueryOperationTypes['pg/vector@1']['cosineDistance'] = (rhs: number[] | vector) => number
// QueryOperationTypes['pg/vector@1']['cosineSimilarity'] = (rhs: number[] | vector) => number

​
Database setup reference

The extension ships an on-disk baseline migration in its contract space. The equivalent DDL for manual setup is: 
CREATE EXTENSION IF NOT EXISTS vector;
When pgvector is listed in extensionPacks, both prisma-next db init and prisma-next db update apply this baseline automatically before any application-space migration runs.

​
Capability flag

The extension declares the pgvector.cosine capability. Features that depend on cosine distance and similarity operations can declare a requires: ['pgvector.cosine'] constraint in their capability gate.

Build docs developers (and LLMs) love

Get started for freeTalk to us