@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()ordb.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 theTypedAn5Adapter/AdapterAPIhelper types - Relations & Eager Loading — Query nested relations with
include, relation-levelselect,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) andgroupBy - Field Math Operators — Atomic updates with
increment,decrement,multiply,divide,set - Vector Search — Similarity search using external vector databases (NBase, Qdrant, Chroma, Pinecone, Weaviate, Milvus), pgvector (PostgreSQL),
VECTOR_DISTANCE(MSSQL), SQLite, 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, Rust, Java, Kotlin, and Swift
- 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.
Java
# Included in the npm package under java/, which ships its own pom.xml
java/ is a Maven module with no dependencies: the adapter speaks JDBC through
java.sql, so the app picks the driver it already has — org.xerial:sqlite-jdbc,
org.postgresql:postgresql or com.microsoft.sqlserver:mssql-jdbc. That is what lets one
runtime serve all three engines and what keeps it usable on Android, where an adapter that
dragged in three drivers would not fit.
<dependency>
<groupId>io.github.an5orm</groupId>
<artifactId>an5-adapters-java</artifactId>
<version>0.2.14</version>
</dependency>
From a checkout the same module is built and installed into ~/.m2:
mvn -f java/pom.xml install
mvn -f java/pom.xml test
Kotlin
# Included in the npm package under kotlin/, which ships build.gradle.kts
Gradle rather than Maven, because Kotlin on Android is built with Gradle and a runtime a phone app cannot resolve is not a mobile runtime. The Kotlin runtime depends on the Java one rather than reimplementing it, so the dialect rules and the where builder exist once:
dependencies {
implementation("io.github.an5orm:an5-adapters-kotlin:0.2.14")
}
From a checkout the Kotlin module resolves its Java sibling from ~/.m2 — declared as
mavenLocal() in build.gradle.kts, so the checkout builds without publishing anything
first:
mvn -f java/pom.xml install
gradle -p kotlin build
Both JVM modules publish to Maven Central, and each release ships both
io.github.an5orm:an5-adapters-java:<version> and
io.github.an5orm:an5-adapters-kotlin:<version>: a v* tag runs the
publish-maven job in .github/workflows/publish.yml (mvn -Prelease deploy and
gradle publish), and a manual run is available through the workflow's publish-maven
input. It needs the repository secrets MAVEN_CENTRAL_USERNAME and MAVEN_CENTRAL_TOKEN
(a Central Portal token), MAVEN_GPG_PRIVATE_KEY and MAVEN_GPG_PASSPHRASE.
Swift
.package(url: "https://github.com/an5ORM/an5Adapters.git", from: "0.2.14")
A SwiftPM package that links the system SQLite — the database every Apple platform
already ships, so there is no bundled engine and the same file works on device and in the
simulator. Building it needs SQLite's headers (apt-get install libsqlite3-dev on Linux).
The runtime takes a SQLDriver, so an app that already has a database layer can put GRDB or
SQLite.swift underneath instead.
Vector Database Providers
@an5/adapters supports six external vector databases behind a unified VectorStoreProvider abstraction (@an5/adapters/vector). Pass any vector database URI directly as connectionString to createAn5Adapter.
NBase (nbase://)
NBase is a partitioned vector database with HNSW, LSH, and KNN indexing behind a REST API.
| 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 |
Query options: token, timeoutMs, method, idField, modelField.
import { createAn5Adapter } from '@an5/adapters';
import { createNBaseVectorClient } from '@an5/adapters/nbase';
const db = createAn5Adapter({
connectionString: 'nbase://localhost:1307',
});
await db.$connect();
const hits = await db.article.vectorSearch({ vector: queryEmbedding, take: 5 });
// Standalone client
const nbase = createNBaseVectorClient({ url: 'http://localhost:1307' });
await nbase.health();
Qdrant (qdrant://)
Uses Qdrant's REST API (/collections/{collection}/points/...).
- Connection strings:
qdrant://localhost:6333?collection=articles,qdrant:https://cloud.qdrant.io:6333?apiKey=...&collection=articles - Query options:
collection,apiKey,timeoutMs
import { createAn5Adapter } from '@an5/adapters';
import { createQdrantClient } from '@an5/adapters/qdrant';
const db = createAn5Adapter({
connectionString: 'qdrant://localhost:6333?collection=articles&apiKey=secret',
});
await db.$connect();
const hits = await db.article.vectorSearch({ vector: queryEmbedding, take: 5 });
// Standalone client
const qdrant = createQdrantClient('qdrant://localhost:6333?collection=articles');
await qdrant.health();
Chroma / ChromaDB (chroma://)
Uses Chroma's v2 REST API (/api/v2/tenants/{tenant}/databases/{database}/collections).
- Connection strings:
chroma://localhost:8000?collection=articles&tenant=default_tenant&database=default_database,chroma:https://chroma.example.com?collection=articles&token=... - Query options:
collection,tenant,database,token,timeoutMs
import { createAn5Adapter } from '@an5/adapters';
import { createChromaClient } from '@an5/adapters/chroma';
const db = createAn5Adapter({
connectionString: 'chroma://localhost:8000?collection=articles',
});
await db.$connect();
const hits = await db.article.vectorSearch({ vector: queryEmbedding, take: 5 });
// Standalone client
const chroma = createChromaClient('chroma://localhost:8000?collection=articles');
await chroma.upsert([{ id: 'Article:1', vector: [0.1, 0.2], metadata: { an5Id: '1', an5Model: 'Article' } }]);
Pinecone (pinecone://)
Uses Pinecone's index data-plane REST API (/vectors/upsert, /query, /vectors/delete, /describe_index_stats).
- Connection strings:
pinecone://my-index.svc.region.pinecone.io?apiKey=...&namespace=articles,pinecone:https://my-index.svc.region.pinecone.io?apiKey=... - Query options:
apiKey,namespace,timeoutMs
import { createAn5Adapter } from '@an5/adapters';
import { createPineconeClient } from '@an5/adapters/pinecone';
const db = createAn5Adapter({
connectionString: 'pinecone://my-index.svc.region.pinecone.io?apiKey=pcsk_...&namespace=articles',
});
// Standalone client
const pinecone = createPineconeClient({
url: 'https://my-index.svc.region.pinecone.io',
apiKey: 'pcsk_...',
namespace: 'articles',
});
const results = await pinecone.search([0.1, 0.2], { k: 5 });
Weaviate (weaviate://)
Uses Weaviate's REST & GraphQL API (/v1/batch/objects, /v1/graphql, /v1/objects/..., /v1/.well-known/ready).
- Connection strings:
weaviate://localhost:8080?className=Article,weaviate:https://cluster.weaviate.network?className=Article&apiKey=...&tenant=t1 - Query options:
className(orcollection),apiKey,tenant,timeoutMs
import { createAn5Adapter } from '@an5/adapters';
import { createWeaviateClient } from '@an5/adapters/weaviate';
const db = createAn5Adapter({
connectionString: 'weaviate://localhost:8080?className=Article',
});
// Standalone client
const weaviate = createWeaviateClient('weaviate://localhost:8080?className=Article');
await weaviate.health();
Milvus / Zilliz (milvus://)
Uses Milvus / Zilliz Cloud v2 REST API (/v2/vectordb/entities/upsert, /search, /delete, /collections/list).
- Connection strings:
milvus://localhost:19530?collection=articles&dbName=default,milvus:https://in01-xxx.api.gcp-us-west1.zillizcloud.com?collection=articles&token=... - Query options:
collection,token,dbName,timeoutMs
import { createAn5Adapter } from '@an5/adapters';
import { createMilvusClient } from '@an5/adapters/milvus';
const db = createAn5Adapter({
connectionString: 'milvus://localhost:19530?collection=articles&token=root:Milvus',
});
// Standalone client
const milvus = createMilvusClient('milvus://localhost:19530?collection=articles');
await milvus.health();
Unified Factory & Multi-language Support
Use createVectorStore(connectionString) to auto-detect any of the six providers at runtime:
import { createVectorStore } from '@an5/adapters/vector';
const store = createVectorStore(process.env.VECTOR_URL!);
await store.health();
Zero-dependency REST clients for all six vector providers (nbase, qdrant, chroma, pinecone, weaviate, milvus) are included across every language runtime:
- TypeScript:
typescript/src/vector/(@an5/adapters/vector) - Python:
python/base/vector_providers.py(create_vector_store,create_an5_adapter("qdrant://..."),vector_health()) - Go:
golang/vector/vector.go(vector.CreateVectorStore,NewVectorAn5Adapter,SetVectorStore,VectorHealth) - Rust:
rust/src/vector.rs(an5_adapters::vector::HttpVectorClient) - Java:
java/src/main/java/an5/adapters/vector/VectorStoreProvider.java - .NET:
dotnet/Vector/VectorProviders.cs - Kotlin:
kotlin/src/main/kotlin/an5/adapters/VectorProviders.kt - Swift:
swift/Sources/An5Adapters/VectorProviders.swift
SQLite — vector search without a vector database
For host-language-free distance calculation, build the shared
AN5 C extension with
npm run build:sqlite:native and pass the printed library path as sqliteVec.
It runs cosine, Euclidean and dot-product distances natively, with SSE2 on
x86-64 and query-vector caching. The existing fallback remains available when
an extension is not loaded.
SQLite has no vector type, so a VECTOR(n) column stores a BLOB of
little-endian float32 — 4 bytes per dimension. Write a plain array of numbers
and the adapter encodes it; read it back and you get the same array. A column
that already holds JSON text ('[0.1, 0.2]') keeps working, so nothing has to
be migrated.
await db.article.create({ data: { title: '…', embedding: queryEmbedding } });
const row = await db.article.findFirst({ where: { title: '…' } });
row.embedding; // number[]
The search is ranked inside the database, trying four strategies in order:
| Order | Strategy | Needs | Reaches |
|---|---|---|---|
| 1 | sqlite-vec |
The extension loaded | Scalar distances over ordinary tables |
| 2 | udf |
A driver that can register a function | BLOB and legacy text columns |
| 3 | sql |
JSON1 (built in since SQLite 3.38) | Legacy text columns |
| 4 | memory |
Nothing | Any column, whole table loaded |
Strategies 1-3 transfer only the rows that match, which is the reason to prefer them. A row whose stored vector cannot be scored is left out rather than returned with a null distance.
sqlite-vec supplies native vector distance
functions for exact search. The adapter scans an ordinary table with those
functions; it does not create or synchronize a vec0 virtual table:
const db = createAn5Adapter({
connectionString: 'sqlite:///app.db',
sqliteVec: require('sqlite-vec').getLoadablePath(),
});
vectorStrategy pins one strategy instead of probing — 'auto' (the default),
'sqlite-vec', 'udf', 'sql' or 'memory'. In TypeScript it can also be
supplied per query on vectorSearch. Every other runtime implements
the same four strategies with the same order; sqlx (Rust) and JDBC (Java,
Kotlin) use sql for JSON text and memory for BLOB columns without
driver-specific vector functions.
from an5_adapter import create_an5_adapter
db = create_an5_adapter("sqlite:///app.db", sqlite_vec="vec0", vector_strategy="auto")
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 |
vectorStore() |
Return the configured VectorStoreProvider instance (if any) |
$vectorHealth() |
Probe health of the configured external vector store |
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 |
indexVectors(args) |
Index table embeddings into the configured vectorStore (indexVectorsInNBase alias also supported) |
vectorSearch(args) |
Semantic vector similarity search; uses dedicated vector stores (NBase, Qdrant, Chroma, Pinecone, Weaviate, Milvus) when configured via connectionString, SQLite in-DB ranking, native SQL vector distance, or in-memory fallback |
Generated TypeScript field metadata marks schema primary keys with isId: true.
SQL and Google Sheets create use this marker to identify custom primary-key
names before falling back to id or ...Id for older metadata. Regenerate the
client to enable this behavior for existing custom-key schemas.
createMany uses a bulk statement when every row supplies the same columns.
Rows with different column sets or missing generated UUID keys are inserted
individually so omitted columns retain their defaults and UUID keys are assigned. Bulk failures are propagated without retrying
individual rows. Wrap mixed-column inserts in $transaction when they must
succeed or roll back together.
For SQL adapters, skipDuplicates: true skips only unique or primary-key
violations. Connection failures and other constraint errors are propagated.
Google Sheets does not enforce unique constraints; this flag does not deduplicate
sheet rows, and failed batch appends are propagated without individual retries.
For SQL adapters, findMany and groupBy accept skip without take to
return all remaining rows or groups. Supply orderBy for stable row pagination;
groupBy orders by its grouping fields when pagination has no explicit ordering.
With relation metadata configured, groupBy.where supports the same relation
filters as findMany.where, including some, none, every, is, and isNot.
License
MIT
Google Sheets desktop OAuth
Google Sheets connections accept accessToken, refreshToken, oauthClientId, optional oauthClientSecret, and tokenExpiresAt (Unix milliseconds). The VS Code connection UI can generate and store this URI after browser sign-in and spreadsheet selection. Values in the semicolon-delimited URI must be URL encoded. Keep offline credentials in secure storage; do not commit them.
The adapter refreshes expired access tokens before requests, shares concurrent refresh requests, and retries authentication failures once after refreshing. Revoked credentials report a reconnect error. Existing service account, API key and access-token-only configurations remain supported.
For web applications, use a Google Web OAuth client and per-user access tokens. The browser adapter rejects offline desktop credentials and service account private keys. A browser connection manager must handle account selection, token reacquisition and SQLite persistence; see the browser connection design.
Metadata
Release files for an5-adapters 0.2.18
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| an5_adapters-0.2.18.tar.gz | 44.1 kB | Without provenance | Details for an5_adapters-0.2.18.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| an5_adapters-0.2.18-py3-none-any.whl | Python 3 | none | any | Details for an5_adapters-0.2.18-py3-none-any.whl |
Total release size: 84.9 kB
Release files / an5_adapters-0.2.18.tar.gz
| Download URL | an5_adapters-0.2.18.tar.gz |
|---|---|
| Size | 44.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
47d15f96f80159f165d0bfd5a5972a10f27a33bff53bd22f0e129920601d4780
|
|
BLAKE2b-256 checksum How to use checksums |
e8bc11d379fbb1201832c50e0cc5ae2be03352c83a58f56b0217179a3ee7b3b2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Release files / an5_adapters-0.2.18-py3-none-any.whl
| Download URL | an5_adapters-0.2.18-py3-none-any.whl |
|---|---|
| Size | 40.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c4aa18f8db88e25f4cde549e40a12d0674faac2efe7ea1ba7618751253e83024
|
|
BLAKE2b-256 checksum How to use checksums |
d8252a418a34b24651f562d1790ac1fdbfbd1b78e168102eb1448718eef25a72
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Security for an5-adapters 0.2.18
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.