Configuration

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

Active Context: Currently configuring for Swift with Sqlite. 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: "sqlite://./dev.db",

  // 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=sqlite:///path/to/database.db

Runtime Adapter Setup

In Swift applications:

import An5Adapters

let adapter = try An5Adapter(path: "dev.db")  // file-backed SQLite
let rows = try adapter.query("SELECT 1")

The Swift runtime drives the system SQLite library, so the connection string is turned into a file path: try An5Db(connectionString:) is the generated client over the same adapter, and db.an5 is that adapter itself.

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