Database

The @talosjs/database component is the connection layer for relational and key-value stores. Its public API exports the abstract TypeormDatabase base for your own TypeORM-backed adapters, and the concrete RedisDatabase for Bun’s native Redis client. Every adapter exposes the same open, close, and drop lifecycle and registers with the container through @decorator.database().

What it provides

open, close, and drop mean the same thing whether you target a TypeORM-backed database or Redis, so the lifecycle is one thing to learn across both styles. On TypeORM adapters, open(Entity) returns a TypeORM Repository<Entity> with full query-builder and entity-manager access. You register an adapter with @decorator.database() and resolve it from the container. RedisDatabase reads DATABASE_REDIS_URL (or constructor options); a custom TypeormDatabase subclass decides which env vars it uses.

How it works

You pick (or scaffold) an adapter and register it. Relational adapters extend the abstract TypeormDatabase and implement a single getSource() that builds a TypeORM DataSource; the base class handles initialization, repositories, transactions, and teardown. The Redis adapter constructs a Bun RedisClient from a connection URL.

Method	Engine	Purpose
`open<Entity>(entity, database?)`	Postgres / SQLite	Initialize the `DataSource` if needed and return a `Repository<Entity>`.
`open()`	Redis	Connect (if not already) and return the Bun `RedisClient`.
`close()`	All	Destroy the `DataSource` / close the Redis connection.
`drop()`	All	Drop the database schema (`FLUSHDB` for Redis). Destructive.
`getEntityManager(database?)`	Postgres / SQLite	Return the TypeORM `EntityManager` for transactions.
`getSource(database?)`	Postgres / SQLite	Build (and cache) the underlying `DataSource`.
`getClient()`	Redis	Return the underlying Bun `RedisClient`.

The public exports differ in what they abstract, not in how you call them:

Export	Role	Returns from `open`
`TypeormDatabase`	Abstract base class for your own TypeORM-backed adapter subclasses	`Repository<Entity>`
`RedisDatabase`	Ready-to-use Bun Redis adapter	`RedisClient`

For vector search and embeddings, a separate VectorDatabase adapter ships in @talosjs/rag and is scaffolded with vector-database:create (see the CLI command below). synchronize defaults to false on every relational adapter, so schema changes go through migrations rather than auto-sync. Adapters cache their DataSource, so call close() when you are done to release the pool.

Environment variables

Variable	Adapter	Required	Purpose
`DATABASE_REDIS_URL`	`RedisDatabase`	Yes (unless passed in config)	Redis connection string, e.g. `redis://localhost:6379`. Missing throws `DatabaseException` (`CONNECTION_FAILED`).

Custom TypeormDatabase subclasses can read whichever env vars you choose (for example DATABASE_URL or SQLITE_DATABASE_PATH), but that is defined by the subclass rather than by the base package.

DATABASE_REDIS_URL=redis://localhost:6379

Usage

A relational adapter implements getSource() and inherits the lifecycle. Resolve it from the container, then open() per entity to get a repository:

import { container } from "@talosjs/container";
import { UserEntity } from "@/entities/UserEntity";
import { AppDatabase } from "@/databases/AppDatabase";

const database = container.get(AppDatabase);

// Initialize the DataSource (once) and get a typed repository
const userRepository = await database.open(UserEntity);

const users = await userRepository.find({ take: 100, order: { createdAt: "DESC" } });
const user = await userRepository.findOneBy({ id: "123" });

await database.close();

Use the entity manager for transactions:

const userRepository = await database.open(UserEntity);
const manager = userRepository.manager;

await manager.transaction(async (tx) => {
  const user = await tx.findOneBy(UserEntity, { id: "123" });
  const order = tx.create(OrderEntity, { userId: user.id, total: 99.99 });
  await tx.save(order);
});

RedisDatabase hands you Bun’s native client:

import { container } from "@talosjs/container";
import { CacheRedis } from "@/databases/CacheRedis";

const redis = container.get(CacheRedis);

const client = await redis.open();
await client.set("session:123", JSON.stringify(session));
const value = await client.get("session:123");

await redis.close();

Decorator and usage

`@decorator.database()`

Registers a database adapter with the container. It accepts an optional scope (defaults to singleton). Use it on an adapter that extends TypeormDatabase (Postgres/SQLite) or RedisDatabase.

import { DataSource } from "typeorm";
import { TypeormDatabase, DatabaseException, decorator } from "@talosjs/database";
import { inject } from "@talosjs/container";
import { AppEnv } from "@talosjs/app-env";
import { SharedModule } from "@module/shared/SharedModule";

@decorator.database()
export class AppDatabase extends TypeormDatabase {
  public constructor(@inject(AppEnv) private readonly env: AppEnv) {
    super();
  }

  public getSource(_database?: string): DataSource {
    if (this.source) {
      return this.source;
    }

    const url = this.env.DATABASE_URL ?? "";

    if (!url) {
      throw new DatabaseException(
        "Database URL is required. Please provide a URL either through the constructor options or set the DATABASE_URL environment variable.",
        "CONNECTION_FAILED",
      );
    }

    this.source = new DataSource({
      synchronize: false,
      entities: SharedModule.entities,
      extra: { max: 10 },
      url,
      type: "postgres",
    });

    return this.source;
  }
}

Resolve it from the container and inject it where needed:

import { inject } from "@talosjs/container";

export class UserService {
  constructor(@inject(AppDatabase) private readonly database: AppDatabase) {}
}

Exceptions

The component throws DatabaseException when an adapter is misconfigured or an operation fails. It carries a machine-readable key, a human-readable message, a data object, and a 500 HTTP status.

Key	When
`CONNECTION_FAILED`	A required connection setting is missing — no `DATABASE_URL`, `SQLITE_DATABASE_PATH`, or `DATABASE_REDIS_URL` (and none passed in config).
`OPERATION_FAILED`	A Redis `open`, `close`, or `drop` call failed at runtime. The `data` carries the connection URL and underlying error.

import { DatabaseException } from "@talosjs/database";

try {
  const userRepository = await database.open(UserEntity);
  await userRepository.find();
} catch (error) {
  if (error instanceof DatabaseException) {
    logger.error(`Database error [${error.key}]: ${error.message}`, error.data);
  } else {
    throw error;
  }
}

Operating safely

Keep synchronize off and evolve the schema through migrations, so changes stay reviewable and reversible. Resolve adapters from the container as singletons and let them cache the DataSource; building a fresh connection per request defeats the pool. Whatever you open, close on shutdown (or when a one-off adapter is done) to release the pool and the Redis socket. Be careful with drop(). It destroys data, including a FLUSHDB on Redis, so never point it at a shared or production database. Read connection details from AppEnv so the same code runs across dev, test, and production. Wrap multi-entity writes in manager.transaction() so they commit or roll back together. In custom adapters, throw DatabaseException with a constant key (CONNECTION_FAILED, OPERATION_FAILED) and keep the variable detail in data.

CLI command

Scaffold a database adapter and its test file with the generator. It prompts for the engine (postgres, sqlite, or redis), writes the class under modules/<module>/src/databases/<Name>Database.ts, generates a matching spec, and installs @talosjs/database if it is missing.

# Interactive: prompts for the name and engine
talos database:create

# Provide the name
talos database:create --name=App

# Target a module and overwrite
talos database:create --name=App --module=auth --override

Option	Description	Default
`--name`	Database class name. The `Database` suffix is appended automatically.	Prompted if omitted
`--module`	Target module the class is generated into.	`shared`
`--override`	Overwrite an existing class without prompting.	`false`

The generated SQLite stub starts ready for you to register entities and adjust the DataSource:

import { DataSource } from "typeorm";
import { TypeormDatabase, DatabaseException, decorator } from "@talosjs/database";

@decorator.database()
export class AppDatabase extends TypeormDatabase {
  public getSource(database?: string): DataSource {
    database = database || "var/db";

    this.source = new DataSource({
      synchronize: false,
      entities: [
        // TODO: Load your entities here
      ],
      enableWAL: true,
      busyErrorRetry: 2000,
      busyTimeout: 30_000,
      database,
      type: "sqlite",
    });

    return this.source;
  }
}

For vector search, talos vector-database:create scaffolds a VectorDatabase adapter (from @talosjs/rag) with an embedding model and Arrow schema. See database:create and vector-database:create for the full command references.

Use with Claude and Codex

The generator ships matching database:create and database:migrate skills. They run the scaffold and then guide your AI agent through completing the adapter: registering entities, configuring the DataSource, and applying migrations. Initialize the skills once for your agent:

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language. It maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a PostgreSQL database connection for the app.

talos agent:skills:create

Then ask Codex the same way; it maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a PostgreSQL database connection for the app.

For example, the prompt above maps to database:create --name=App with the postgres engine, then registers your entities on the DataSource.

Getting Started

AI

Framework

Command Line

What it provides

How it works

Environment variables

Usage

Decorator and usage

`@decorator.database()`

Exceptions

Operating safely

CLI command

Use with Claude and Codex

​What it provides

​How it works

​Environment variables

​Usage

​Decorator and usage

​@decorator.database()

​Exceptions

​Operating safely

​CLI command

​Use with Claude and Codex

What it provides

How it works

Environment variables

Usage

Decorator and usage

`@decorator.database()`

Exceptions

Operating safely

CLI command

Use with Claude and Codex