Skip to main content

@an5/adapters

Standalone runtime database adapter and query engine for AN5 ORM. Provides connection pooling, SQL dialect query building (parseWhere, buildOrderBy, quote), dynamic model proxy access, eager loading (include), nested writes, vector search, transactions, and typed table clients across TypeScript, Python, .NET (C#), Golang, and Google Sheets.

Features

  • Dynamic Model Access — Access models directly via db.user.findMany() or db.User.create() (proxy resolves casing/plurals via metadata); db.table('User') is the escape hatch for runtime-known model names
  • Typed Model Access — Bind generated delegates for full type-safety: createAn5Adapter<{ user: UserTableClient }>({...}), plus the TypedAn5Adapter / AdapterAPI helper types
  • Relations & Eager Loading — Query nested relations with include, relation-level select, where, orderBy, pagination, and _count
  • Nested Writes — Create and update records with nested relation writes (create, update, disconnect)
  • Query Builder & Dialects — Dialect-aware SQL formatting for MSSQL, PostgreSQL, MySQL, and SQLite
  • Aggregations & GroupBy — Standard ORM aggregates (_count, _sum, _avg, _min, _max) and groupBy
  • Field Math Operators — Atomic updates with increment, decrement, multiply, divide, set
  • Vector Search — Similarity search using NBase, pgvector (PostgreSQL), VECTOR_DISTANCE (MSSQL), or in-memory cosine/euclidean/dot similarity
  • Real Transactions — Interactive and callback transactions ($transaction(async tx => ...) and $begin()/$commit()/$rollback())
  • Cross-Language — Unified API in TypeScript, Python, .NET (C#), Golang, and Rust
  • Google Sheets Database — Use spreadsheets as a live database with full CRUD and SQL syntax support

Installation

TypeScript

npm install @an5/adapters

Python

pip install an5-adapters

.NET

dotnet add package An5Adapters

Go

# Included in the npm package under golang/ or via go module

Rust

cargo add an5-adapters

The crate is driver-agnostic — it depends on sqlx with any, so the app enables the driver it needs. See crates.io and docs.rs.


NBase — Neural Vector Database

NBase is a partitioned vector database with HNSW, LSH and KNN indexing behind a REST API. an5 can run vector search there instead of loading every row into memory, which matters once a table holds millions of embeddings.

The rows stay in your relational table: only the vectors move to NBase, each one tagged with its row id, and search results are hydrated from the table.

Configure

NBase is configured through the connection string, like every other backend:

import { createAn5Adapter } from '@an5/adapters';

const db = createAn5Adapter({ connectionString: 'nbase://localhost:1307' });
await db.$connect(); // probes NBase

Accepted forms:

Form Result
nbase://localhost:1307 http://localhost:1307
nbase:localhost:1307 http://localhost:1307
nbase:http://localhost:1307 http://localhost:1307
nbase:https://vectors.example.com https://vectors.example.com
nbase://localhost:1307?token=t&timeoutMs=500&method=hnsw options applied

?token, ?timeoutMs, ?method, ?idField and ?modelField are read from the query string, and a path is kept as a base path for deployments behind a reverse proxy.

This adapter is vector-only: it has no relational database, so a search returns the NBase hits — id, metadata and distance — instead of table rows.

With an nbase:// connection string, search returns the hits themselves:

const hits = await db.table('Article').vectorSearch({ vector: queryEmbedding, take: 5 });
// hits[0] = { id: 'Article:42', an5Id: '42', an5Model: 'Article', distance: 0.11 }

Search rows from your own table

To get real rows back, keep your database connection string and point it at the same NBase instance. NBase is still configured with a connection string, never a params object:

const db = createAn5Adapter({
  connectionString: 'sqlserver://localhost:1433;database=mydb',
  nbase: 'nbase://localhost:1307',
});

await db.table('Article').indexVectorsInNBase({ vectorField: 'embedding' });
// → { indexed: 1200 }

const hits = await db.table('Article').vectorSearch({ vector: queryEmbedding, take: 5 });
// hits[0] = { id, title, ..., distance }

Vectors are tagged with their row id, so a hit is hydrated from the table by that id and the result keeps the { ...row, distance } shape the other engines return.

Standalone client

import { createNBaseVectorClient } from '@an5/adapters/nbase';

const nbase = createNBaseVectorClient({ url: 'http://localhost:1307' });
await nbase.health();
await nbase.addVectors([{ id: 'a:1', vector: [0.1, 0.2], metadata: { an5Id: '1' } }]);
const { results } = await nbase.search([0.1, 0.2], { k: 5, distanceMetric: 'cosine' });

If NBase is unreachable, vectorSearch logs a warning and falls back to the database's native vector support, then to in-memory similarity, so an outage degrades performance rather than breaking queries.

Usage

TypeScript

import { createAn5Adapter } from '@an5/adapters';

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

// Dynamic model access
const users = await db.user.findMany({
  where: { active: true },
  include: {
    orders: {
      where: { status: 'paid' },
      orderBy: { total: 'desc' },
      take: 5,
    },
    _count: true,
  },
  take: 10,
});

// Nested writes
const created = await db.user.create({
  data: {
    email: 'alpha@example.com',
    name: 'Alpha',
    orders: {
      create: [
        { total: 100, status: 'open' },
        { total: 250, status: 'paid' },
      ],
    },
  },
  include: { orders: true, _count: true },
});

// Atomic updates
await db.user.update({
  where: { id: created.id },
  data: {
    score: { increment: 10 },
  },
});

// Aggregations
const stats = await db.order.aggregate({
  _count: true,
  _sum: { total: true },
  _avg: { total: true },
});
console.log(stats._count._all, stats._sum.total, stats._avg.total);

// Transactions
await db.$transaction(async (tx) => {
  await tx.user.update({
    where: { id: created.id },
    data: { score: { increment: 5 } },
  });
  await tx.order.create({
    data: { userId: created.id, total: 50, status: 'paid' },
  });
});

// Raw query
const rawRows = await db.$queryRawUnsafe('SELECT * FROM users WHERE active = @p_0', 1);

// Disconnect
await db.$disconnect();

Python

from an5_adapter import create_an5_adapter

db = create_an5_adapter("sqlserver://localhost:1433;database=mydb;user=sa;password=pass")

# Dynamic model access
users = db.user.find_many(where={"active": True}, take=10)

# Nested create
created = db.user.create({
    "data": {
        "email": "alpha@example.com",
        "name": "Alpha",
    }
})

# Transactions
def perform_transfer(tx):
    tx.user.update({"where": {"id": "u1"}, "data": {"score": {"increment": 10}}})

db.transaction(perform_transfer)

API Reference

An5Adapter

Method / Property Description
db[modelName] Dynamic proxy returning AdapterTableClient for the model
table<T>(name) Explicitly returns AdapterTableClient<T>
exec(query, params) Execute raw parameterized query returning rows
$queryRawUnsafe(sql, ...args) Positional raw query
$executeRaw(sql, ...args) Raw DML execution returning affected count
$transaction(fn) Callback transaction with automatic commit/rollback
$begin() Interactive transaction returning An5AdapterTx
$connect() Open connection / pool
$disconnect() Close connections

AdapterTableClient

Method Description
findMany(args) Query multiple records with where, orderBy, skip, take, select, include
findFirst(args) Query first matching record
findUnique(args) Query unique record by unique filter
create(args) Insert a record with support for nested relation writes
createMany(args) Bulk insert records
update(args) Update record with field math operations & nested relation writes
updateMany(args) Update multiple records
delete(args) Delete a single record
deleteMany(args) Delete multiple records
upsert(args) Insert or update a record
count(args) Count matching records
aggregate(args) Compute _count, _sum, _avg, _min, _max
groupBy(args) Group by fields with aggregations and pagination
vectorSearch(args) Semantic vector similarity search

License

MIT

Metadata

Release files for an5-adapters 0.2.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for an5-adapters 0.2.9
File Size Uploaded Provenance Actions
an5_adapters-0.2.9.tar.gz 18.7 kB Without provenance Details for an5_adapters-0.2.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for an5-adapters 0.2.9
File Interpreter ABI Platform Actions
an5_adapters-0.2.9-py3-none-any.whl Python 3 none any Details for an5_adapters-0.2.9-py3-none-any.whl

Total release size: 39.5 kB

Release files / an5_adapters-0.2.9.tar.gz

Download URL an5_adapters-0.2.9.tar.gz
Size 18.7 kB
Tags Source
SHA-256 checksum
How to use checksums
49a0da66bbfbd55342a6f754c3371c5c5d0787347841f08309c87b855f507396
BLAKE2b-256 checksum
How to use checksums
96a260ce9289c0ae6d74dcebbec8196a875612de70743f779acc9ec47e414b25
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / an5_adapters-0.2.9-py3-none-any.whl

Download URL an5_adapters-0.2.9-py3-none-any.whl
Size 20.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
661ef7ab8fd36cb186f7e676c80d420d992be61ab5b6a6b66cf1b46af7531c67
BLAKE2b-256 checksum
How to use checksums
018fb7f7df976de0ecbc274ea44e6dd688006d8b0ac57ba1ab26e0bd9ce6bc4a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for an5-adapters 0.2.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page