unrag.config.ts Reference

The unrag.config.ts file is the central place to configure UnRAG. It's generated when you run unrag init and contains everything needed to construct a working engine: database connection, embedding provider, and default settings.

Structure overview

A typical generated config looks like:

import { createContextEngine, defineConfig } from "./lib/unrag/core";
import { createAiEmbeddingProvider } from "./lib/unrag/embedding/ai";
import { createDrizzleVectorStore } from "./lib/unrag/store/drizzle";
import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";

export const unragConfig = {
  chunking: {
    chunkSize: 200,
    chunkOverlap: 40,
  },
  retrieval: {
    topK: 8,
  },
  embedding: {
    model: "openai/text-embedding-3-small",
    timeoutMs: 15_000,
  },
} as const;

export function createUnragEngine() {
  const embedding = createAiEmbeddingProvider({
    model: unragConfig.embedding.model,
    timeoutMs: unragConfig.embedding.timeoutMs,
  });

  const databaseUrl = process.env.DATABASE_URL;
  if (!databaseUrl) throw new Error("DATABASE_URL is required");

  const pool = (globalThis as any).__unragPool ?? new Pool({ connectionString: databaseUrl });
  (globalThis as any).__unragPool = pool;

  const db = (globalThis as any).__unragDrizzleDb ?? drizzle(pool);
  (globalThis as any).__unragDrizzleDb = db;

  const store = createDrizzleVectorStore(db);

  return createContextEngine(
    defineConfig({
      embedding,
      store,
      defaults: unragConfig.chunking,
    })
  );
}

export async function retrieve(query: string) {
  const engine = createUnragEngine();
  return engine.retrieve({ query, topK: unragConfig.retrieval.topK });
}

The unragConfig object

This object holds your default settings. Changing values here affects all operations that use these defaults.

chunking.chunkSize — How many words (approximately) per chunk. Smaller chunks give more precise retrieval but cost more to embed. Default: 200.

chunking.chunkOverlap — How many words overlap between adjacent chunks. Overlap preserves context across boundaries. Default: 40.

retrieval.topK — Default number of results returned by retrieve(). Can be overridden per-call. Default: 8.

embedding.model — The embedding model identifier. Format is provider/model-name for the AI SDK. Default: openai/text-embedding-3-small.

embedding.timeoutMs — How long to wait for embedding API responses before timing out. Default: 15000 (15 seconds).

The createUnragEngine function

This function assembles all the pieces into a working engine. You'll typically call it at the start of your request handlers or scripts.

The generated version includes:

Embedding provider creation using your configured model and timeout
Database connection with a singleton pattern to prevent connection exhaustion
Store adapter creation using your chosen adapter type
Engine construction with everything wired together

Customizing database connection

The generated code uses globalThis singletons for connection reuse. You can replace this with your own connection management:

// Use an existing pool from elsewhere in your app
import { pool } from "@/lib/db";
import { drizzle } from "drizzle-orm/node-postgres";

export function createUnragEngine() {
  const db = drizzle(pool);
  const store = createDrizzleVectorStore(db);
  
  // ... rest of function
}

For different database providers, adjust the connection setup:

// Neon serverless
import { neon } from "@neondatabase/serverless";
import { drizzle } from "drizzle-orm/neon-http";

const sql = neon(process.env.DATABASE_URL!);
const db = drizzle(sql);

// Supabase
import { Pool } from "pg";
const pool = new Pool({
  connectionString: process.env.SUPABASE_DB_URL,
});

Adding custom helpers

Extend the config file with application-specific helpers:

// Tenant-scoped retrieval
export async function retrieveForTenant(tenantId: string, query: string) {
  const engine = createUnragEngine();
  return engine.retrieve({
    query,
    topK: unragConfig.retrieval.topK,
    scope: { sourceId: `tenant:${tenantId}:` },
  });
}

// Ingest with validation
export async function ingestDocument(
  sourceId: string,
  content: string,
  metadata: Record<string, unknown>
) {
  if (!sourceId || !content) {
    throw new Error("sourceId and content are required");
  }
  
  const engine = createUnragEngine();
  return engine.ingest({ sourceId, content, metadata });
}

Environment variables

The config file expects these environment variables:

DATABASE_URL — Your Postgres connection string. Required.

AI_GATEWAY_API_KEY — API key for the embedding provider (typically OpenAI). Required by the AI SDK.

AI_GATEWAY_MODEL — Optional override for the embedding model. If set, it takes precedence over the config file setting.

Server-only

Keep unrag.config.ts server-only. It imports database drivers, reads secrets from environment variables, and should never be bundled into client code. In Next.js, the file naturally stays server-side when imported only from Route Handlers and Server Actions.