API reference - IMP Docs

All signatures on this page are verified against the current @exulu/backend source. For what each method does and how to structure your initdb script, see Configuration.

Import

import { ExuluDatabase } from "@exulu/backend";

ExuluDatabase is a plain object — not a class instance. There is nothing to construct.

ExuluDatabase.init()

ExuluDatabase.init({
  contexts: ExuluContext[];
  litellm?: boolean;
}): Promise<void>

Initialises or updates the IMP database schema. Idempotent — safe to call on every boot.

contexts

ExuluContext[]

required

All ExuluContext instances registered in this application. IMP creates the items table (and chunks table when the context has an embedder) for any context whose tables do not yet exist.

litellm

boolean

default:"true"

When true, also calls initLitellmDb() to push the LiteLLM proxy schema to the database at LITELLM_DATABASE_URL. Pass false to skip.

What init() does on every call:

Runs up(db) — creates or alters the ~26 core application tables.
Calls contextDatabases(contexts) — creates missing items and chunks tables for each context.
Inserts the admin role if absent.
Inserts the default role if absent.
Inserts the default admin user (admin@exulu.com) if absent.
Calls generateApiKey("exulu", "api@exulu.com") and logs the result. The key is persisted only if no api@exulu.com user exists (first boot). See persistence semantics.
Optionally calls initLitellmDb().

// Typical initdb script:
import { ExuluDatabase } from "@exulu/backend";
import { docsContext } from "./contexts";

await ExuluDatabase.init({ contexts: [docsContext] });

ExuluDatabase.update()

ExuluDatabase.update({
  contexts: ExuluContext[];
  litellm?: boolean;
}): Promise<void>

Alias for init(). Identical behaviour. Use when adding contexts or upgrading an existing installation to make the intent explicit.

// Adding a new context to an existing database:
await ExuluDatabase.update({ contexts: [existingContext, newContext] });

ExuluDatabase.api.key.generate()

ExuluDatabase.api.key.generate(
  name: string,
  email: string,
): Promise<{ key: string }>

Creates an API user record and returns the plain-text API key. Calling this function is the only way to obtain the clear-text key — it is never stored in the database in recoverable form.

name

string

required

Human-readable identifier for this API key. Used as the name column on the API user record and as the sanitized postfix in the key string: sk_…/sanitized_name (lowercased, spaces replaced with underscores).

string

required

Email address for the API user record. Trimmed and lowercased before use. Used as the lookup key — if a user with this email already exists, the new key is returned but not persisted (see persistence semantics below).

key

string

The generated plain-text API key. Format: sk_{random}_{random}/{sanitized_name}. Example: sk_9x7h3j2k5l8_4m6n1p9q8r/my_app_api.

Key format

The returned key has three parts:

Part	Example	Description
Prefix	`sk_`	Identifies the string as a secret key
Random body	`9x7h3j2k5l8_4m6n1p9q8r`	Two segments of `Math.random().toString(36)`, joined with `_`
Postfix	`/my_app_api`	Sanitized name, lowercased with spaces replaced by `_`

The database stores {bcrypt_hash(plain_key)}/{sanitized_name} in the apikey column. The hash uses 12 bcrypt salt rounds. IMP’s authentication middleware extracts the postfix suffix to find the user record before verifying the hash.

Persistence semantics

const existingUser = await db.from("users").where({ email }).first();
if (!existingUser) {
  // Insert new user with the hashed key — KEY IS PERSISTED
  await db.from("users").insert({ ..., apikey: `${hash}/${postfix}` });
} else {
  // User already exists — KEY IS NOT PERSISTED
  console.log("[EXULU] API user with that name already exists.");
}
// In both cases, return the plain-text key
return { key: `${plainKey}${postfix}` };

The function always returns a valid-looking key. Only the key generated when no prior user with that email exists is stored and will authenticate. Keys returned for existing users are discarded and will fail authentication.

The first call with a given email address is the only one that persists the key. If you regenerate a key for an existing email, the new key will not work. To replace a key, delete the user record first and call generate() again.

Example

import { ExuluDatabase } from "@exulu/backend";

// First call — key is persisted and will authenticate:
const { key } = await ExuluDatabase.api.key.generate(
  "my-app-api",
  "api@my-app.com",
);
console.log(key); // sk_abc123_xyz456/my_app_api — SAVE THIS NOW

// Second call with the same email — key is NOT persisted:
const { key: key2 } = await ExuluDatabase.api.key.generate(
  "my-app-api",
  "api@my-app.com",
);
// key2 will not authenticate; key from the first call is still the valid one

Generating multiple keys

To provision keys for different services, use different email addresses:

const keys = await Promise.all([
  ExuluDatabase.api.key.generate("frontend", "api-frontend@my-app.com"),
  ExuluDatabase.api.key.generate("backend",  "api-backend@my-app.com"),
  ExuluDatabase.api.key.generate("mobile",   "api-mobile@my-app.com"),
]);

// Store all keys in your secrets manager before this script exits
for (const { key } of keys) {
  console.log(key);
}

The first-boot key

ExuluDatabase.init() calls generateApiKey("exulu", "api@exulu.com") internally on every run and logs the result:

[EXULU] Default api key: sk_9x7h3j2k5l8_4m6n1p9q8r/exulu

Only the key logged on the first boot is persisted. Keys logged on subsequent boots are not stored and will not authenticate. Capture the key before log rotation or terminal scrollback clears it:

npm run utils:initdb 2>&1 | tee initdb.log
grep "Default api key" initdb.log

For a dedicated application key with a stable email, call ExuluDatabase.api.key.generate() explicitly after init() in your initdb script — that key is tied to your email address and will not conflict with the default api@exulu.com entry.

Context table helpers

These methods are called by ExuluDatabase.init() internally via ExuluContext. You rarely need to invoke them directly; they are listed here for completeness and are documented on the ExuluContext API reference page.

Method	Called by	Notes
`context.tableExists()`	`init()`	Returns `true` when the items table exists
`context.createItemsTable()`	`init()`	Creates the items table from the context’s field schema
`context.chunksTableExists()`	`init()`	Returns `true` when the chunks table exists
`context.createChunksTable()`	`init()`	Creates the chunks table with the correct `VECTOR(N)` dimension

Next steps

Configuration

Options for init() / update(), the LiteLLM flag, and the complete initdb example.

Self-hosting — database

The no-migration model, first-boot bootstrap, and database backup strategy.

​Import

​ExuluDatabase.init()

​ExuluDatabase.update()

​ExuluDatabase.api.key.generate()

​Key format

​Persistence semantics

​Example

​Generating multiple keys

​The first-boot key

​Context table helpers

​Next steps

Configuration

Self-hosting — database

Import

ExuluDatabase.init()

ExuluDatabase.update()

ExuluDatabase.api.key.generate()

Key format

Persistence semantics

Example

Generating multiple keys

The first-boot key

Context table helpers

Next steps