database

Typed queries, vector search, and migrations with Drizzle ORM

Overview

The database module provides a provider-agnostic Postgres client powered by Drizzle ORM with built-in vector search (pgvector), multi-tenant support, and SQL injection prevention.

Peer dependencies: drizzle-orm, postgres

npm install drizzle-orm postgres

yarn add drizzle-orm postgres

pnpm add drizzle-orm postgres

Quick Start

import { createDatabase } from '@jamaalbuilds/ai-toolkit/database';

const db = await createDatabase({
  connectionString: process.env.DATABASE_URL!,
});

const users = await db.query('SELECT * FROM users WHERE active = true');

API Reference

createDatabase(config)

Create a database client with connection pooling and query helpers.

function createDatabase(config: DatabaseConfig): Promise<DatabaseClient>

const db = await createDatabase({
  connectionString: process.env.DATABASE_URL!,
});

// Typed query
const users = await db.query('SELECT * FROM users WHERE id = $1', [userId]);

// Single row
const user = await db.queryOne('SELECT * FROM users WHERE id = $1', [userId]);

// Multi-tenant
const tenantRows = await db.withTenant(tenantId, 'SELECT * FROM data');

// Cleanup
await db.end();

vectorSearch(db, options)

Perform vector similarity search using pgvector.

function vectorSearch(db: DatabaseClient, options: VectorSearchTableOptions): Promise<VectorSearchResult[]>

import { vectorSearch } from '@jamaalbuilds/ai-toolkit/database';

import { getVectorColumn } from '@jamaalbuilds/ai-toolkit/database';

// Define your Drizzle table with a vector column
const vectorCol = await getVectorColumn();
// Use with your Drizzle schema: vectorCol('embedding', { dimensions: 1536 })

const results = await vectorSearch(db, {
  table: documentsTable,       // Drizzle table reference
  column: documentsTable.embedding, // Drizzle column reference
  queryVector: queryEmbedding,
  threshold: 0.7,
  limit: 10,
  metric: 'cosine',
});

migrate(options)

Run database migrations.

function migrate(options: MigrateOptions): Promise<MigrateResult>

import { migrate } from '@jamaalbuilds/ai-toolkit/database';

await migrate({
  connectionString: process.env.DATABASE_URL!,
  migrationsFolder: './drizzle',
});

detectProvider(url)

Auto-detect the database provider from the connection URL.

function detectProvider(url: string): DatabaseProvider

vectorSearchRaw(db, options)

Raw vector search returning unprocessed results.

getVectorColumn()

Get a pgvector column factory for defining vector columns in Drizzle schemas.

async function getVectorColumn(): Promise<(name: string, config: { dimensions: number }) => unknown>

const vectorCol = await getVectorColumn();
// Use in your Drizzle schema definition:
// embedding: vectorCol('embedding', { dimensions: 1536 })

Types

• DatabaseClient — client with query, queryOne, withTenant, end
• DatabaseConfig — connectionString, provider
• DatabaseProvider — 'neon' | 'supabase' | 'aws-rds' | 'local'
• VectorSearchTableOptions — table, column, queryVector, threshold, limit, metric, select
• VectorSearchResult — row data with similarity score
• DistanceMetric — 'cosine' | 'l2' | 'innerProduct'
• MigrateOptions — connectionString, migrationsFolder