Inspected version: 0.1.1 · Source →

The database package is an Active Record layer over Knex. It uses node:async_hooks for transaction context propagation and filesystem APIs for SQLite path handling.

Entry points #

The manifest exports ., /migrations, /relations and /package.json.

Connection APIs #

initDatabase(config) creates a Knex instance and registers it globally.
setKnex(instance) injects/overrides the global Knex instance.
getKnex() returns the active transaction when inside transaction() or the configured Knex instance otherwise.
dbClient is a proxy that delegates calls and properties to getKnex().
isDatabaseInitialized() checks whether a database or active transaction exists.
transaction(callback, options?) starts a transaction and propagates it through async execution context; nested calls reuse the active transaction unless savepoint: true is specified.

DatabaseConfig extends Knex.Config and optionally accepts driver: "postgres" | "sqlite" | "mysql". The initializer maps these driver names to pg, better-sqlite3 and mysql2. Install the driver package appropriate to the chosen engine.

Models #

Model declares static table, not static tableName. Other important static options include:

primaryKey (default "id")
autoUuid (default true)
timestamps (default true; can be false or a list of timestamp column names)
casts
softDeletes (default false)
deletedAtColumn (default "deleted_at")
hidden, fillable, guarded
globalScopes

The model supports direct property access through a proxy. New instances use fillable/guarded mass-assignment rules; database hydration follows a separate path.

Common static helpers include query, withTrashed, onlyTrashed, find, findOrFail, all, count, where, create, forceCreate, firstOrCreate, firstOrNew and updateOrCreate. Read the generated declaration for full overloads and exact return types.

Query builder #

ModelQueryBuilder supports query chaining, camelCase-to-snake_case column conversion, dynamic local scopes (scopeName), global scopes, soft-delete filtering, relation eager loading and pagination. It delegates unrecognized query methods to the underlying Knex builder where supported.

Common methods used by the guides include where, orWhere, with, first, get, orderBy, paginate, withTrashed, onlyTrashed, withoutGlobalScope, withoutGlobalScopes and toKnex. Verify exact overloads against your installed declarations.

Relations #

The /relations entry point exports the relation classes and helpers. The source includes BelongsTo, HasOne, HasMany, BelongsToMany, MorphTo, MorphOne, MorphMany, MorphToMany, MorphedByMany, MorphMap and eager-loading support. Relation method signatures depend on the model's foreign-key and pivot-table conventions; consult the implementation and tests before relying on implicit defaults.

Migrations #

The /migrations entry point exports the migration generator, runner and schema builder. A migration has a stable name, an up(db, schema) function and an optional down(db, schema). runMigrations(scope, migrations) executes pending migrations for a scope and records applied names in the migrations table. rollbackMigrations(scope, migrations) rolls back the latest batch for that scope in reverse order when a matching down function exists.

The runner wraps a batch in a transaction and attempts a PostgreSQL advisory lock. Do not assume identical DDL transactional semantics across database engines.

Factories and seeders #

defineFactory(ModelClass, definitionFn) creates a callable factory helper. Factories can make in-memory models or persist them; the Seeder base class and runSeeders(seeders, { inTransaction? }) execute seeders sequentially.

Runtime and deployment notes #

SQLite uses better-sqlite3 and is not a general Edge runtime database.
The implementation redirects SQLite paths to /tmp in common serverless environments; that storage is ephemeral.
pg is an optional peer dependency in the package manifest. The source maps MySQL to mysql2, which is not listed as a dependency in the inspected manifest; install it explicitly if using MySQL.
Keep migration execution separate from concurrent serverless request startup in production.

@veap/database