API Reference
Complete API documentation for an5 ORM.
An5Adapter Class (@an5/adapters)
Factory / Constructor
import { createAn5Adapter, An5Adapter } from '@an5/adapters';
const db = createAn5Adapter({
connectionString: process.env.DATABASE_URL!,
});
Methods
| Method / Property | Returns | Description |
|---|---|---|
db[modelName] |
AdapterTableClient<T> |
Dynamic model access property (e.g. db.user, db.order) |
table(name) |
AdapterTableClient<T> |
Explicit dynamic table client instance (adapter.table('User')) |
$connect() |
Promise<void> |
Establish connection to database |
$disconnect() |
Promise<void> |
Close database connection pool |
$transaction(fn, options?) |
Promise<T> |
Execute callback-style transaction |
AdapterTableClient API
findFirst
db.model.findFirst(params: FindFirstArgs): Promise<Model | null>
Params:
{
where?: WhereInput,
orderBy?: OrderByInput,
include?: IncludeInput,
select?: SelectInput,
skip?: number,
take?: number
}
findMany
db.model.findMany(params: FindManyArgs): Promise<Model[]>
Params:
{
where?: WhereInput,
orderBy?: OrderByInput | OrderByInput[],
include?: IncludeInput,
select?: SelectInput,
skip?: number,
take?: number
}
create
db.model.create(params: CreateArgs): Promise<Model>
Params:
{
data: CreateInput,
include?: IncludeInput,
select?: SelectInput
}
createMany
db.model.createMany(params: CreateManyArgs): Promise<BatchPayload>
Params:
{
data: CreateInput[],
skipDuplicates?: boolean
}
update
db.model.update(params: UpdateArgs): Promise<Model>
Params:
{
where: WhereInput,
data: UpdateInput,
include?: IncludeInput,
select?: SelectInput
}
updateMany
db.model.updateMany(params: UpdateManyArgs): Promise<BatchPayload>
Params:
{
where?: WhereInput,
data: UpdateInput
}
upsert
db.model.upsert(params: UpsertArgs): Promise<Model>
Params:
{
where: WhereInput,
create: CreateInput,
update: UpdateInput
}
delete
db.model.delete(params: DeleteArgs): Promise<Model>
Params:
{
where: WhereInput
}
deleteMany
db.model.deleteMany(params: DeleteManyArgs): Promise<BatchPayload>
Params:
{
where?: WhereInput
}
count
db.model.count(params?: CountArgs): Promise<number>
aggregate
db.model.aggregate(params: AggregateArgs): Promise<AggregateResult>
Params:
{
where?: WhereInput,
_count?: boolean,
_sum?: { field: boolean },
_avg?: { field: boolean },
_min?: { field: boolean },
_max?: { field: boolean }
}
groupBy
db.model.groupBy(params: GroupByArgs): Promise<GroupByResult[]>
Params:
{
by: ScalarFieldEnum | ScalarFieldEnum[],
where?: WhereInput,
orderBy?: OrderByInput | OrderByInput[],
skip?: number,
take?: number,
_count?: true | { _all?: true; field?: true },
_sum?: { numericField?: true },
_avg?: { numericField?: true },
_min?: { field?: true },
_max?: { field?: true }
}
vectorSearch
db.model.vectorSearch(params: VectorSearchArgs): Promise<Model[]>
Params:
{
vector: number[],
vectorField?: string,
take?: number,
distanceMetric?: 'cosine' | 'euclidean' | 'dot',
vectorElementType?: 'float32' | 'float16' | 'uint8',
where?: WhereInput,
include?: IncludeInput
}
Returns (Model & { distance: number })[], ordered by distance ascending.
Each provider ranks in the database when it can, and scores the column in the
client when it cannot: dedicated vector databases (NBase, Qdrant, Chroma, Pinecone, Weaviate, Milvus),
then pgvector on PostgreSQL, VECTOR_DISTANCE on SQL Server 2025, then — on SQLite — sqlite-vec,
the runtime’s own an5_vec_* functions, or json_each. A row whose stored vector cannot be
scored is left out rather than returned with a null distance.
vectorElementType applies to SQL Server only; SQLite stores a VECTOR(n)
column as a BLOB of little-endian float32 and decodes both that and the older
JSON text form on read. include is not applied to vector results: a hit is the
whole row.
Where Input
Basic Operators
{
// Equality
field: 'value',
status: { equals: 'active' },
deletedAt: null,
archivedAt: { equals: null },
role: { not: 'banned' },
email: { not: null },
name: { not: { contains: 'legacy' } },
// Comparison
score: { gt: 10 },
age: { gte: 18 },
views: { lt: 1000 },
orderCount: { lte: 10 },
// String
title: { contains: 'text' },
firstName: { startsWith: 'Jo' },
lastName: { endsWith: 'son' },
// List
team: { in: ['a', 'b'] },
tag: { notIn: ['archived', 'deleted'] }
}
Logical Operators
{
AND: [{ field: 'value' }, { field2: 'value' }],
OR: [{ field: 'value' }, { field2: 'value' }],
NOT: [{ field: 'value' }, { field2: { startsWith: 'tmp' } }]
}
AND and NOT accept either a single object or an array of objects.
Relation Filters
{
posts: { some: { title: 'Hello' } },
posts: { none: {} },
posts: { every: { published: true } }
}
Empty relation filters are meaningful: some: {} checks that at least one
related row exists, none: {} checks that no related rows exist, and
every: {} is treated as true.
Update Input
Scalar fields accept direct replacement values. Numeric fields also accept field operations:
{
name: 'Updated',
score: { increment: 1 },
total: { decrement: 10 },
multiplier: { multiply: 2 },
ratio: { divide: 4 },
count: { set: 0 }
}
Common nested writes are supported on relation fields:
{
posts: {
create: [{ title: 'New' }],
connect: [{ id: 'post-1' }],
set: [{ id: 'post-2' }],
disconnect: [{ id: 'post-3' }],
delete: [{ id: 'post-4' }],
update: [{ where: { id: 'post-5' }, data: { title: 'Updated' } }],
upsert: [{
where: { id: 'post-6' },
create: { title: 'Created' },
update: { title: 'Updated' }
}]
}
}
Include Input
{
// Simple include
posts: true,
// With ordering / projection
posts: {
select: { id: true, title: true },
orderBy: { createdAt: 'desc' }
},
// Nested
posts: {
include: {
comments: true,
author: true
}
},
// Count
_count: {
select: { posts: true }
}
}
Select Input
{
id: true,
email: true,
name: true,
posts: {
select: {
id: true,
title: true
}
},
_count: true
}
Relation fields inside select behave as implicit includes. Helper keys needed
to resolve selected relations are fetched internally and removed from the final
projection when not explicitly selected.
{
name: true,
orders: {
select: { id: true }
},
_count: {
select: { orders: true }
}
}
Order By Input
// Single field
{ createdAt: 'desc' }
// Multiple fields
[
{ role: 'asc' },
{ createdAt: 'desc' }
]
For regular find* queries, only scalar columns are supported in orderBy.
groupBy can also order grouped rows through its orderBy argument.
Transaction
$transaction
await db.$transaction(async (tx) => {
// Operations using tx instead of db
const user = await tx.user.create({...});
const order = await tx.order.create({...});
});
$transaction is callback-based and automatically commits or rolls back.
Calling tx.$transaction() inside an active transaction reuses the same
transactional executor when the adapter does not provide native nested
transactions.
Interactive Transactions
const tx = await db.$begin();
try {
await tx.user.update({ where: { id: userId }, data: { active: true } });
await tx.$commit();
} catch (error) {
await tx.$rollback();
throw error;
}
$begin() requires the underlying adapter or custom executor to expose
interactive transaction support. Google Sheets does not support interactive
transactions.
Raw Queries
$queryRaw
// Template tag
const users = await db.$queryRaw`
SELECT * FROM users
WHERE email LIKE ${'%@example.com'}
`;
$executeRaw
const result = await db.$executeRaw`
UPDATE users SET active = 0
WHERE last_login < ${dateThreshold}
`;
Batch Payload
{
count: number // Number of affected rows
}
Error Handling
import { An5ClientKnownRequestError } from '@an5/orm';
try {
await db.user.create({
data: { email: 'john@example.com' }
});
} catch (error) {
if (error instanceof An5ClientKnownRequestError) {
console.log('Code:', error.code);
console.log('Message:', error.message);
}
}
Known Error Codes
| Code | Description |
|---|---|
| P2002 | Unique constraint violation |
| P2003 | Foreign key constraint |
| P2025 | Record not found |
Other failures surface as the underlying driver error.
@an5/adapters
The @an5/adapters package provides database and spreadsheet execution for the ORM
and can also be used standalone. The full public API is exported from the package root.
Factory functions
| Function | Description |
|---|---|
createAn5Adapter(config) |
Create an adapter from An5AdapterConfig. Detects the dialect from the config type or from a connectionString scheme (sqlserver://, postgres://, mysql://, sqlite://, googlesheets://) |
createAn5SheetsAdapter(config) |
Create a Google Sheets adapter from An5SheetsAdapterConfig |
parseSheetsConnectionString(url) |
Parse a googlesheets:// connection string into An5SheetsAdapterConfig |
import {
createAn5Adapter,
createAn5SheetsAdapter,
parseSheetsConnectionString,
} from '@an5/adapters';
// Dialect auto-detection from connection string
const db = createAn5Adapter({
connectionString: 'googlesheets://spreadsheetId;clientEmail=...;privateKey=...',
});
// Direct Sheets configuration
const sheets = createAn5SheetsAdapter({
spreadsheetId: 'spreadsheetId',
clientEmail: 'sa@project.iam.gserviceaccount.com',
privateKey: '...',
sheetMapping: { users: 'Users' },
});
// Parse a connection string
const cfg = parseSheetsConnectionString('googlesheets://spreadsheetId;apiKey=...');
Adapter classes
| Class | Description |
|---|---|
An5Adapter |
Dialect-agnostic adapter (exec, executeRaw, table, $transaction, $connect, $disconnect) |
An5SheetsAdapter |
Spreadsheet adapter. Adds readRange, writeRange, appendRange, listSheets, deleteSheet |
SheetsTableClient<T> |
Typed table client over a sheet (findMany, findFirst, create, update, delete, clear, deleteAll, …) |
Config functions
| Function | Description |
|---|---|
getLlmConfig() / setLlmConfig(config) |
Read/update the active LLM configuration |
getEmbeddingConfig() / setEmbeddingConfig(config) |
Read/update the active embedding configuration |
resetAdapter() |
Clear cached adapter/config state |
setAdapterMetadata(metadata) |
Pass schema metadata explicitly to the adapter |
Subpaths
The package also exposes scoped entry points:
| Subpath | Contents |
|---|---|
@an5/adapters/browser |
Browser-safe bundle (Sheets via fetch + metadata helpers, no SQL engines) |
@an5/adapters/googlesheets |
Google Sheets adapter only |
@an5/adapters/config |
LlmConfigData / EmbeddingConfigData types and helpers |
@an5/adapters/mssql |
SQL Server engine |
@an5/adapters/postgres |
PostgreSQL engine |
@an5/adapters/mysql |
MySQL engine |
@an5/adapters/sqlite |
SQLite engine |
@an5/adapters/base |
Base types and metadata helpers |
@an5/adapters/python |
Packaged Python adapter facade source |
@an5/adapters/dotnet |
Packaged .NET adapter facade source |
@an5/adapters/golang |
Packaged Go adapter facade source |
@an5/adapters/rust |
Packaged Rust adapter Cargo crate |
@an5/adapters/vector |
Unified vector store factory (createVectorStore) and providers |
@an5/adapters/nbase |
NBase dialect adapter |
@an5/adapters/qdrant |
Qdrant vector client |
@an5/adapters/chroma |
ChromaDB vector client |
@an5/adapters/pinecone |
Pinecone vector client |
@an5/adapters/weaviate |
Weaviate vector client |
@an5/adapters/milvus |
Milvus / Zilliz vector client |
Sheets config (An5SheetsAdapterConfig)
| Field | Type | Description |
|---|---|---|
spreadsheetId |
string |
Google Sheets spreadsheet id |
clientEmail? |
string |
OAuth service-account email (use with privateKey) |
privateKey? |
string |
Service-account private key |
credentials? |
object |
Alternative: full service-account JSON credentials |
accessToken? |
string |
OAuth access token (browser mode) |
apiKey? |
string |
Google API key (browser mode) |
sheetMapping? |
Record<string, string> |
Model → sheet name mapping (defaults to model name) |
Browser Adapters API (@an5/adapters/browser)
The @an5/adapters/browser entrypoint provides zero-dependency browser-safe database adapters for Web Browsers, WASM, and Client Components.
createBrowserSqliteAdapter
Creates a type-safe AN5 ORM adapter for in-browser SQLite execution drivers (such as sql.js, WASM, OPFS, or Capacitor/Expo SQLite).
import { createBrowserSqliteAdapter } from '@an5/adapters/browser';
const adapter = createBrowserSqliteAdapter({
driver: {
exec: (sql: string, params?: any[]) => rows
},
dialect: 'sqlite'
});
An5SheetsAdapter / createAn5SheetsAdapter
Creates a browser-safe Google Sheets database adapter.
import { createAn5SheetsAdapter } from '@an5/adapters/browser';
const sheetsDb = createAn5SheetsAdapter({
spreadsheetId: 'YOUR_SHEET_ID',
accessToken: 'YOUR_OAUTH_TOKEN' // or apiKey: 'YOUR_API_KEY'
});
An5Agent Class
Constructor
import { An5Agent } from '@an5/agent';
const agent = new An5Agent(tools?: Tool[]);
Registers the 7 default tools unless overridden; custom tools can be appended.
Methods
| Method | Returns | Description |
|---|---|---|
process(context) |
Promise<AgentResponse> |
Process AgentContext ({ userQuestion, database?, toolContext? }) |
executeTool(name, input, context?) |
Promise<unknown> |
Execute a specific tool |
getTools() |
Tool[] |
Get all registered tools |
getTool(name) |
Tool \| undefined |
Get tool by name |
addTool(tool) |
void |
Register a new tool |
Tools (8 consolidated)
| Tool | Actions | Description |
|---|---|---|
schema |
list, describe, relations | Explore data models |
query |
generate, explain, validate | Work with SQL queries |
database |
execute, describe, health | Database operations |
generateClientCode |
- | Generate client code |
generateCode |
- | Request-specific application code through a model callback, or schema/API context for the calling model |
analyzeSchema |
- | Analyze schema issues |
retrieve |
schema, queries | Semantic search |
task |
create, list, update, delete | Manage tasks |
For detailed tool documentation, see AI Agent Tools.
CLI & Automation Commands
Schema/database workflows run as npm scripts from the an5Orm/ directory or workspace root, while delivery, tunneling, and dashboard operations run via an5-cli (npx an5-cli).
Schema Management
| Command | Description |
|---|---|
npm run generate |
Generate client code from schema |
npm run db:push |
Push schema to database |
npm run db:pull |
Pull schema from database |
npm run db:seed |
Seed database with sample data |
npm run db:migrate diff |
Compare schema with database |
npm run db:migrate:generate |
Generate migration SQL |
npm run db:migrate:apply |
Apply pending migration files; pass -- --preview to preview SQL |
npm run db:migrate:rollback |
Roll back the latest applied migration; pass -- --preview, -- 3, or -- --to <file> |
npm run db:migrate:status |
Show migration status |
Development
The following are workspace-root scripts (run from the repository root, not from an5Orm/):
| Command | Where | Description |
|---|---|---|
npm run build |
workspace root | Build all workspace packages |
npm test |
an5Orm/ or workspace root |
Run tests (an5Orm) or the full workspace suite |
npm run test:full |
workspace root | Run workspace tests plus generator, package smoke, and Python/.NET/Go compile gates |
npm run test:integration:live |
workspace root | Run live adapter Postgres/SQL Server checks plus ORM SQL Server relation/transaction/vector fallback checks when database URLs are configured |
npm run ui |
workspace root | Start local UI |
Release
| Command | Description |
|---|---|
npm run preview |
Preview release changes |
npm run release |
Release across the workspace |
For more CLI commands, see CLI Commands.