pgvector extension: add vector similarity search to Postgres

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

Install the package

pnpm add @prisma-next/extension-pgvector

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],
});

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],
});

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' }),
  },
});

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.

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.

Get Started

Core Concepts

Guides

Extensions

pgvector extension: add vector similarity search to Postgres

What the extension provides

Setup

Querying with vector operations

Operations reference

cosineDistance

cosineSimilarity

Types

Vector<N>

OperationTypes

Database setup reference

Capability flag

​What the extension provides

​Setup

​Querying with vector operations

​Operations reference

​cosineDistance

​cosineSimilarity

​Types

​Vector<N>

​OperationTypes

​Database setup reference

​Capability flag

What the extension provides

Setup

Querying with vector operations

Operations reference

cosineDistance

cosineSimilarity

Types

Vector<N>

OperationTypes

Database setup reference

Capability flag