Configuration

an5 ORM uses configuration files, environment variables, and runtime adapters to tailor behavior to your architecture.

Active Context: Currently configuring for Python with Nbase. The connection string and client runtime examples below are customized for your selection.

an5Orm.config.js

Create an5Orm.config.js in your project root to configure code generation and schema options:

module.exports = {
  // Database for db:push, db:pull, db:migrate:* and db:cleanup.
  // DATABASE_URL overrides this, so commit a development database here and
  // let CI set its own. Keep passwords in the environment.
  connectionString: "nbase://localhost:1307",

  // Schema directory (default: 'an5Schema')
  schemaDir: "an5Schema",

  // Output configuration
  outputs: {
    typescript: {
      outputDir: "an5Client/typescript",
      metadataFile: "an5Client/typescript/an5Metadata.ts",
    },
    python: {
      metadataFile: "an5Client/python/an5_metadata.py",
    },
    dotnet: {
      outputDir: "an5Client/dotnet",
    },
    golang: {
      outputDir: "an5Client/golang",
    },
    rust: {
      outputDir: "an5Client/rust",
    },
  },

  // Database pull options
  pull: {
    exclude: ["^__", "^sys\\."], // Exclude system tables
    preserveRelations: true,
  },

  // Code generation options
  generation: {
    generateMetadata: true, // Write the generated metadata module
  },
};

Validation

The file is checked before anything uses it, so a mistyped key or a wrong type stops generation instead of quietly changing where the output goes:

❌ Invalid an5Orm.config.js:
  outputs.typescript.outputDirs  unknown option; did you mean "outputDir"?
  pull.exclude                   expected an array of strings, received string
  generation.generateComments    unknown option; expected one of "generateMetadata"

Every problem is reported at once. Each key is known, each value has an expected type, and a key that is close to a real one gets a suggestion. The four CLI commands and the generator all read the file through this loader.

Provider Detection

The connection string scheme selects the database provider and determines allowed schema field types:

  • sqlserver:// → SQL Server
  • postgres:// or postgresql:// → PostgreSQL
  • mysql:// or mariadb:// → MySQL
  • sqlite:// or .sqlite/.db path → SQLite
  • googlesheets:// → Google Sheets
  • nbase:// → NBase Vector Database
# Selected provider connection string
DATABASE_URL=nbase://localhost:1307

Runtime Adapter Setup

In Python applications:

import os
from an5_adapter import create_an5_adapter

conn_str = os.getenv("DATABASE_URL", "sqlserver://localhost:1433;database=db")
db = create_an5_adapter(conn_str)

SQLite ranks a VECTOR(n) column inside the database. Two adapter options control it, and the TypeScript adapter takes both at construction:

Option Type Default Applies to
sqliteVec string unset SQLite only
vectorStrategy 'auto' \| 'sqlite-vec' \| 'udf' \| 'sql' \| 'memory' 'auto' SQLite only

Other runtimes spell the same option sqlite_vec / vector_strategy (Python), SqliteVec / VectorStrategy (.NET), VectorSupport (Go), vector_strategy (Rust), sqliteVecPath / vectorStrategy (Swift), An5.vectorStrategy(…) (Kotlin) and setVectorStrategy(…) (Java). See Vector Search.

LLM & Embedding Runtime Config

This API belongs to the TypeScript runtime: getLlmConfig, setLlmConfig, getEmbeddingConfig, setEmbeddingConfig and resetAdapter are exported from @an5/adapters, and no other runtime exposes them.

Next Steps