an5Adapters
Standalone runtime adapters for AN5 ORM. Provides connection pooling, query execution, typed table clients in TypeScript, Python, .NET (C#), Golang, and Google Sheets API.
Adapters are runtime packages only. They do not import generated an5Client artifacts; generated clients or applications can pass model metadata explicitly when table-name mapping or field type coercion is needed.
Features
- Connection pooling — Managed connection pools with configurable limits
- Type-safe table clients — Generic CRUD operations with type inference
- Full query support — WHERE, ORDER BY, pagination, aggregates
- Vector search — Cosine, euclidean, and dot product similarity
- Transactions — Begin/commit/rollback with automatic cleanup
- Cross-language — Same API in TypeScript, Python, .NET (C#), and Golang
- Google Sheets — Use spreadsheets as a database with the same CRUD API
Installation
TypeScript
npm install @an5/adapters
Python
pip install an5-adapters
.NET
dotnet add package An5Adapters
Go
The Go adapter sources are included in the npm package under golang/ and can also be copied into Go projects that use the an5adapters module layout.
Usage
TypeScript
import { createAn5Adapter, setAdapterMetadata } from '@an5/adapters';
setAdapterMetadata({
modelToTable: { User: 'dbo.users' },
modelFields: {
User: {
id: { ts: 'string', sql: 'uniqueidentifier', isId: true },
active: { ts: 'boolean', sql: 'bit' },
},
},
});
const db = createAn5Adapter({
connectionString: 'sqlserver://localhost:1433;database=mydb;user=sa;password=pass',
});
// Table client
const users = db.table<User>('users');
await users.findMany({ where: { active: true }, take: 10 });
// Raw queries
const rows = await db.exec('SELECT * FROM users WHERE id = @id', { id: '123' });
// Transactions
await db.$transaction(async (tx) => {
await tx.table('users').create({ data: { name: 'John' } });
});
const tx = await db.$begin();
try {
await tx.table('users').create({ data: { name: 'Jane' } });
await tx.$commit();
} catch (error) {
await tx.$rollback();
throw error;
}
Python
from an5_adapter import create_an5_adapter
from base.metadata import set_adapter_metadata
set_adapter_metadata({
"modelToTable": {"User": "dbo.users"},
"modelFields": {
"User": {
"id": {"py": "str", "sql": "uniqueidentifier", "isId": True},
"active": {"py": "bool", "sql": "bit"},
}
},
})
db = create_an5_adapter("sqlserver://localhost:1433;database=mydb;user=sa;password=pass")
# Table client
users = db.table("User")
users.find_many(where={"active": True}, take=10)
# Raw queries
rows = db.exec("SELECT * FROM users WHERE id = ?", params=["123"])
# Transactions
db.transaction(lambda tx: tx.table("User").create({"name": "John"}))
.NET
using System.Collections.Generic;
using An5Orm;
var db = new An5Adapter("sqlserver://localhost:1433;database=mydb;user=sa;password=pass");
// Table client
var users = db.Table<User>("dbo.users");
var activeUsers = users.FindMany(
"IsActive = @p",
new Dictionary<string, object> { ["p"] = true });
// Raw queries
var rows = db.QueryRaw("SELECT * FROM users WHERE Id = @id",
new Dictionary<string, object> { ["id"] = "123" });
// Create / Update / Delete
users.Create(new User { Name = "John", IsActive = true });
users.Update(existingUser); // uses the Id property as the key
users.Delete("123");
// Transactions (must return a value; use db.Transaction<int> for void-style)
db.Transaction(tx =>
{
tx.Table<User>("dbo.users").Create(new User { Name = "John" });
return 0;
});
Note: QueryRaw/FindMany take parameters as a Dictionary<string, object>,
not anonymous objects. See dotnet/An5Adapter.cs for the full API.
Go
package main
import (
"context"
"database/sql"
an5 "an5adapters"
)
func example(db *sql.DB) error {
ctx := context.Background()
adapter := an5.NewAn5Adapter(db, "postgres://localhost/mydb")
users := adapter.Table("users")
_, err := users.Create(ctx, map[string]interface{}{"name": "John", "active": true})
if err != nil {
return err
}
rows, err := users.FindMany(ctx, an5.QuoteIdentifier("active", adapter.Dialect)+" = $1", true)
if err != nil {
return err
}
_ = rows
_, err = users.UpdateMany(ctx, map[string]interface{}{"active": false}, an5.QuoteIdentifier("name", adapter.Dialect)+" = $1", "John")
return err
}
Google Sheets
import { createAn5SheetsAdapter } from '@an5/adapters/googlesheets';
const db = createAn5SheetsAdapter({
spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
// Option 1: client email + private key
clientEmail: 'sa@project.iam.gserviceaccount.com',
privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
// Option 2: full service account JSON
// credentials: { client_email: '...', private_key: '...' },
// Optional: map model names to sheet names
sheetMapping: { users: 'UsersData', orders: 'OrdersData' },
});
// Table client (same API as SQL adapters)
const users = db.table<User>('users');
await users.findMany({ where: { active: true }, take: 10 });
await users.create({ data: { name: 'John', email: 'john@example.com' } });
await users.update({ where: { email: 'john@example.com' }, data: { name: 'Johnny' } });
await users.delete({ where: { email: 'john@example.com' } });
// Raw range access (Google Sheets specific)
const rawData = await db.readRange('Sheet1!A1:C10');
await db.writeRange('Sheet1!A1:B2', [['Name', 'Age'], ['Alice', '30']]);
await db.appendRange('Sheet1!A:A', [['Bob', '25']]);
// Auto-creates sheet + header row on first create()
await db.table('orders').create({ data: { id: '1', total: 100 } });
// List, delete sheets
const sheets = await db.listSheets();
await db.deleteSheet('OldSheet');
// Clear data (keeps headers) or delete all rows
await db.table('users').clear();
await db.table('users').deleteAll();
Browser Mode (Google Sheets)
For browser environments (React, Vue, Svelte, Next.js client components), import from @an5/adapters/browser and configure accessToken or apiKey. In browser mode, the adapter uses native fetch() without importing Node.js modules (googleapis, crypto, fs).
import { createAn5SheetsAdapter } from '@an5/adapters/browser';
// Option 1: OAuth2 Access Token (e.g. from Firebase Auth or Google Sign-In)
const db = createAn5SheetsAdapter({
spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
accessToken: userOAuthAccessToken,
});
// Option 2: Google API Key
const db2 = createAn5SheetsAdapter({
spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
apiKey: 'AIzaSy...',
});
Integrated factory (auto-detect adapter)
import { createAn5Adapter, An5Adapter } from '@an5/adapters';
// Auto-detects from connection string
const sqlDb = createAn5Adapter({ connectionString: 'sqlserver://localhost:1433;database=mydb;user=sa;password=pass' });
const sheetsDb = createAn5Adapter({
connectionString: 'googlesheets://spreadsheetId;clientEmail=sa@project.iam.gserviceaccount.com;privateKey=...',
});
// Or use the Sheets config object directly (also auto-detected)
const sheetsDb2 = createAn5Adapter({
spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
clientEmail: 'sa@project.iam.gserviceaccount.com',
privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
});
// Constructor form also delegates googlesheets:// to the Sheets adapter
const sheetsDb3 = new An5Adapter({
connectionString: 'googlesheets://spreadsheetId;clientEmail=sa@project.iam.gserviceaccount.com;privateKey=...',
});
Notes:
- Each model/table maps to a sheet tab (first row = headers)
- Sheets without header rows get auto-created on first
create() - Type coercion can use optional adapter metadata (
setAdapterMetadata) for field types and model-to-table mapping - Numeric strings (without leading zeros) are auto-coerced;
"00123"stays string - Boolean strings
"true"/"false"are auto-coerced - Sheet names with spaces are automatically escaped (A1 notation)
- Supports service account JSON or individual
clientEmail+privateKey - Automatic retry with exponential backoff for rate limits (429/500/503)
Provider Imports
Use the package root for normal SQL applications:
import { createAn5Adapter, An5Adapter } from '@an5/adapters';
The Sheets adapter is exposed from the package root and through its own subpath:
import { createAn5SheetsAdapter, An5SheetsAdapter, SheetsTableClient, parseSheetsConnectionString } from '@an5/adapters';
import { An5SheetsAdapter, createAn5SheetsAdapter } from '@an5/adapters/googlesheets';
import { parseSheetsConnectionString } from '@an5/adapters/googlesheets';
Browser builds (no Node.js modules) use @an5/adapters/browser. The public SQL factory createAn5Adapter lives in typescript/src/an5Adapter.ts and auto-detects googlesheets:// connection strings.
API Reference
An5Adapter / An5SheetsAdapter
| Method | Description |
|---|---|
exec(query, params) |
Execute query, return rows (SQL only) |
table<T>(name) |
Get typed table client |
$transaction(fn) |
Execute in transaction |
$connect() |
Open connection / authenticate |
$disconnect() |
Close connection / clear auth |
readRange(range) |
Read raw sheet range (Sheets only) |
writeRange(range, values) |
Write raw sheet range (Sheets only) |
appendRange(range, values) |
Append rows to sheet (Sheets only) |
listSheets() |
List all sheet tab names (Sheets only) |
deleteSheet(name) |
Delete a sheet tab (Sheets only) |
AdapterTableClient / SheetsTableClient
| Method | Description |
|---|---|
findMany(args) |
Query multiple rows |
findFirst(args) |
Query single row |
findUnique(where) |
Find by unique key |
count(where) |
Count rows |
create(data) |
Insert row |
createMany(data) |
Bulk insert |
update(where, data) |
Update row |
updateMany(where, data) |
Update multiple rows |
delete(where) |
Delete row |
deleteMany(where) |
Delete multiple rows |
upsert(where, create, update) |
Insert or update |
aggregate(args) |
SUM, AVG, MIN, MAX, COUNT |
groupBy(args) |
Group by fields |
vectorSearch(args) |
Semantic similarity search |
clear() |
Clear all data rows, keep headers (Sheets only) |
deleteAll() |
Delete all data rows including headers (Sheets only) |
Config functions
Exported from the package root (and from the @an5/adapters/config subpath):
| 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 |
import { getLlmConfig, setLlmConfig, setEmbeddingConfig, resetAdapter } from '@an5/adapters';
setLlmConfig({ provider: 'openai', model: 'gpt-4o-mini', apiKey: '...' });
setEmbeddingConfig({ provider: 'openai', model: 'text-embedding-3-small', apiKey: '...' });
resetAdapter();
Provider Layout
- TypeScript source providers live under
typescript/src/{base,mssql,postgres,mysql,sqlite,googlesheets};npm run buildcompiles them intodist/(also exposed via@an5/adapters/base,@an5/adapters/mssql, … subpaths). - Python providers live under
python/{base,mssql,postgres}, withpython/an5_adapter.pykept as the public facade.npm run build:python(orpython -m build --outdir dist-py) builds the package intodist-py/. - .NET providers live under
dotnet/{Base,Mssql,Postgres}, withdotnet/An5Adapter.cskept as the public facade. - Go providers live under
golang/{base,mssql,postgres}, withgolang/an5_adapter.goandgolang/table_client.gokept as the public facade. - Adapters do not depend on generated
an5-clientartifacts; generated clients may pass metadata in explicitly when they need model/table mapping.
Testing
# TypeScript/Node
node test/unit.test.js
node test/package.test.js
# Package smoke test: npm pack + install into a fresh project + verify
npm run test:package:smoke
# Python
npm run test:python
# .NET
npm run test:dotnet
# Go
npm run test:go
License
MIT
Metadata
Release files for an5-adapters 0.2.5
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.5.tar.gz | 13.1 kB | Without provenance | Details for an5_adapters-0.2.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| an5_adapters-0.2.5-py3-none-any.whl | Python 3 | none | any | Details for an5_adapters-0.2.5-py3-none-any.whl |
Total release size: 27.8 kB
Release files / an5_adapters-0.2.5.tar.gz
| Download URL | an5_adapters-0.2.5.tar.gz |
|---|---|
| Size | 13.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ef6043a1b50d08926f738bd2550d6e226fda4f07c66e7e8ac20c866603bc9915
|
|
BLAKE2b-256 checksum How to use checksums |
7687d64005b665da39aca8704b63bf5f86528a3a06d17fa95152b20bb31b3c9f
|
| 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.5-py3-none-any.whl
| Download URL | an5_adapters-0.2.5-py3-none-any.whl |
|---|---|
| Size | 14.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3e52271a9df24f96bffc96e7acc847a9c412465aaf9d52c47c77ed973535bccd
|
|
BLAKE2b-256 checksum How to use checksums |
c56a8b80d07dbec1cef5ed2a826f57babaf78459cbe1ecc22e536f3a3fd1282a
|
| 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.5
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.