Configure the database

Register the provider#

import { Application } from "@veap/kernel";
import { DatabaseServiceProvider } from "@veap/database";

export const app = Application.configure()
  .use(DatabaseServiceProvider)
  .create();

await app.bootstrap();

The provider initializes Knex during its boot phase and registers the connection under the database token and the Knex token.

Environment-driven configuration#

The provider resolves its URL in this order: explicit provider config databaseUrl, ConfigService.get("DATABASE_URL"), process.env.DATABASE_URL, then process.env.DATABASE_FILE. If none exists, it uses dev.sqlite.

# SQLite file for local development
DATABASE_URL=./dev.sqlite

For PostgreSQL:

DATABASE_URL=postgresql://app_user:replace-me@db.example.internal:5432/app

Use a secret manager or deployment environment settings for credentials. Never commit a production connection string.

Explicit Knex config#

DatabaseServiceProvider accepts a config object as its second constructor argument:

import { DatabaseServiceProvider } from "@veap/database";

const provider = new DatabaseServiceProvider(undefined, {
  config: {
    client: "pg",
    connection: process.env.DATABASE_URL,
    pool: { min: 0, max: 10 },
  },
});

The provider's constructor requires a container argument before the config object. In normal application composition, use new DatabaseServiceProvider(container, config) only when you explicitly manage the container; otherwise prefer default provider registration if environment-based configuration is sufficient.

Drivers#

• SQLite: better-sqlite3; local filesystem paths are supported.
• PostgreSQL: pg; PostgreSQL SSL configuration is derived from the URL and production configuration.
• MySQL: mysql2; install the driver explicitly because it is not declared as a dependency in the inspected package manifest.

Serverless and persistence#

The connection code redirects a file-backed SQLite path to /tmp in known serverless environments and logs a warning. Temporary serverless files are not durable across cold starts. Use a managed persistent database for production data.

Connection lifecycle#

The provider's shutdown() attempts to destroy the active Knex connection. Call shutdown only when you own the application lifecycle; do not close a shared server connection at the end of each request.