Data Source
This page explains how the library finds your TypeORM data source, how environment variables change its options, and how you keep several data sources side by side.
Discovery
The CLI and useDataSource() look for a file that exports a TypeORM DataSource (or one of the other accepted shapes):
// src/database/data-source.ts
import { DataSource } from 'typeorm';
import type { DataSourceOptions } from 'typeorm';
import type { SeederOptions } from 'typeorm-extension';
const options: DataSourceOptions & SeederOptions = {
type: 'postgres',
host: 'localhost',
port: 5432,
username: 'app',
password: 'secret',
database: 'app',
entities: ['src/database/entities/**/*{.ts,.js}'],
migrations: ['src/database/migrations/**/*{.ts,.js}'],
seeds: ['src/database/seeds/**/*{.ts,.js}'],
factories: ['src/database/factories/**/*{.ts,.js}'],
};
export const dataSource = new DataSource(options);Without -d, these paths are tried in order, each with the extensions .js, .cjs, .mjs, .ts, .cts and .mts:
data-sourcesrc/data-sourcesrc/db/data-sourceandsrc/database/data-source
- The paths are relative to the current working directory and to the directory of the
-dfile (without-d:--root, which defaults to the current working directory). -d(--dataSource) names another file, e.g.-d src/config/orm.ts. The path is relative to--root. The named file is tried first, and the paths above stay the fallback.- Unless the process runs under
tsxorts-node, the library assumes compiled code:srcin these paths becomes theoutDirof your tsconfig (defaultdist), and.tsbecomes.js. The same rewrite applies to string paths inentities,migrations,subscribers,seedsandfactories. When the rewritten path matches nothing but the original one does (e.g. Node's type stripping without a build), the original is used. A.tsoriginal only qualifies when TypeScript support is detected (tsx,ts-node, or Node's type stripping; not with--no-experimental-strip-types, and see the tip below for decorators). Pass--preserveFilePathsto turn the rewrite off. - Every export of the file is checked, the default export included (see accepted export shapes). If a file has none of them, the next path is tried.
- The library only reads the
optionsof thatDataSource.useDataSource()creates and initializes a new instance from them, so the exported instance stays uninitialized.
Accepted export shapes
Within one file the first match wins, in this order:
- A
DataSource, or a promise that resolves to one (e.g.export default (async () => new DataSource(...))()). - A default export function without parameters (sync or async) that returns a
DataSource. It is called once, with no arguments. "Without parameters" meansFunction.lengthis0, so a function whose parameters all have defaults ((name = 'app') => ...) or a rest parameter is called too. Named exports are never called, nor are classes or functions with a required parameter, and a result that is not aDataSourceis ignored. - A
DataSourceOptionsobject (an object with a stringtype), default or named. The library reads the options directly; onlyfindDataSource()wraps them innew DataSource(options).
The factory should return an uninitialized DataSource. The library only reads its options and creates its own instance, so an initialized one keeps an open connection the library never closes.
// a factory, e.g. to read a secret first
export default async function createDataSource() {
return new DataSource({ type: 'postgres', password: await readSecret('db-password') });
}// only the options
export const options: DataSourceOptions = { type: 'postgres', database: 'app' };A file which exports a DataSource next to its options or a factory keeps working as before: the DataSource wins.
Import types with import type
When Node loads a .ts file itself (type stripping, behind --experimental-strip-types on older Node 22 releases and on by default since Node 22.18), it removes type annotations but keeps every import. import { DataSource, DataSourceOptions } from 'typeorm' then fails with does not provide an export named 'DataSourceOptions'. Write import type { DataSourceOptions } from 'typeorm'. Node's type stripping also does not support decorators, so files with entities need tsx or a build.
In code, buildDataSourceOptions() runs the same lookup, findDataSource() returns the DataSource it finds and findDataSourceOptions() returns only its options.
Environment variables
Data source options can also come from environment variables. Each variable has a DB_* name and a TYPEORM_* alias. When both are set, the DB_* name wins.
DB_TYPE=postgres
DB_HOST=localhost
DB_USERNAME=app
DB_PASSWORD=secret
DB_DATABASE=app
DB_ENTITIES=dist/database/entities/*.js| Variable | Alias | Sets | Format |
|---|---|---|---|
DB_TYPE | TYPEORM_CONNECTION | type | string |
DB_URL | TYPEORM_URL | url, and type from its scheme if DB_TYPE is unset | string |
DB_HOST | TYPEORM_HOST | host | string |
DB_PORT | TYPEORM_PORT | port | int |
DB_USERNAME | TYPEORM_USERNAME | username | string |
DB_PASSWORD | TYPEORM_PASSWORD | password | string |
DB_DATABASE | TYPEORM_DATABASE | database (better-sqlite3 default: db.sqlite) | string |
DB_SID | TYPEORM_SID | sid (oracle) | string |
DB_SCHEMA | TYPEORM_SCHEMA | schema (postgres, cockroachdb, mssql) | string |
DB_UUID_EXTENSION | TYPEORM_UUID_EXTENSION | uuidExtension (postgres) | string |
DB_DRIVER_EXTRA | TYPEORM_DRIVER_EXTRA | extra | JSON |
DB_SYNCHRONIZE | TYPEORM_SYNCHRONIZE | synchronize | bool |
DB_DROP_SCHEMA | TYPEORM_DROP_SCHEMA | dropSchema | bool |
DB_MIGRATIONS_RUN | TYPEORM_MIGRATIONS_RUN | migrationsRun | bool |
DB_ENTITIES | TYPEORM_ENTITIES | entities | list |
DB_MIGRATIONS | TYPEORM_MIGRATIONS | migrations | list |
DB_SUBSCRIBERS | TYPEORM_SUBSCRIBERS | subscribers | list |
DB_MIGRATIONS_TABLE_NAME | TYPEORM_MIGRATIONS_TABLE_NAME | migrationsTableName | string |
DB_METADATA_TABLE_NAME | TYPEORM_METADATA_TABLE_NAME | metadataTableName | string |
DB_ENTITY_PREFIX | TYPEORM_ENTITY_PREFIX | entityPrefix | string |
DB_LOGGING | TYPEORM_LOGGING | logging | bool, all or list |
DB_LOGGER | TYPEORM_LOGGER | logger | string |
DB_MAX_QUERY_EXECUTION_TIME | TYPEORM_MAX_QUERY_EXECUTION_TIME | maxQueryExecutionTime | int |
DB_CACHE | TYPEORM_CACHE | cache | bool, redis, ioredis, ioredis/cluster or database |
DB_CACHE_OPTIONS | TYPEORM_CACHE_OPTIONS | cache.options (with a cache type) | JSON |
DB_CACHE_ALWAYS_ENABLED | TYPEORM_CACHE_ALWAYS_ENABLED | cache.alwaysEnabled (with a cache type) | bool |
DB_CACHE_DURATION | TYPEORM_CACHE_DURATION | cache.duration (with a cache type) | int |
DB_PIN_TIMEZONE | TYPEORM_PIN_TIMEZONE | pins the session timezone, see pinTimezone | UTC only |
DB_SEEDS | TYPEORM_SEEDING_SEEDS | seeds | list |
DB_FACTORIES | TYPEORM_SEEDING_FACTORIES | factories | list |
DB_DEBUG | TYPEORM_DEBUG | useEnv('debug') only, reserved and currently unused | string |
NODE_ENV | useEnv('env') only (default development) | string |
A list is comma separated. A comma inside a brace group or a character class ([,]) belongs to its glob pattern, so DB_SEEDS=src/database/seeds/**/*{.ts,.js} is one entry. An escaped brace (\{) is a literal character. A bool is true, t or 1, or false, f or 0; any other value counts as unset. A JSON value that does not parse throws when the environment is read.
How the environment combines with the data source file:
- The environment adds data source options only when it names a driver:
DB_TYPE, or aDB_URLwith a scheme. Connection settings without a driver are ignored;assertEnvDataSourceOptions()throws for that case.DB_PIN_TIMEZONEapplies in either case. - No file found: the options come from the environment alone. Neither a file nor a driver:
OptionsError. - File and environment name the same driver: a set variable wins over the file, and the file fills the rest. An unset variable (
DB_LOGGINGincluded) leaves the file's value alone.extraandcacheare merged key by key.entities,migrationsandsubscribersare joined, the environment's entries first. - File and environment name different drivers: the environment's options are used and the file is ignored.
- When the environment names a driver, its defaults apply last, only to an option that the environment does not set and, if the file names the same driver, the file does not set either:
database: 'db.sqlite'for better-sqlite3 andtimeTravelQueries: truefor cockroachdb. Options from a file alone get no defaults. DB_SEEDSandDB_FACTORIESare the fallback: seeds or factories set in the data source options or passed in code win.
The library does not load .env files. Load one with Node (node --env-file=.env ...) or tsx (tsx --env-file=.env ...), or let your shell or process manager set the variables.
useEnv() reads the variables once and caches the result. If you change process.env afterwards (e.g. in tests), call resetEnv():
import { resetEnv, useEnv } from 'typeorm-extension';
process.env.DB_DATABASE = 'test';
resetEnv();
const database = useEnv('database'); // 'test'Multiple instances
The library keeps data sources in a registry under an alias. Without an alias, the alias is default.
import { DataSource } from 'typeorm';
import {
hasDataSource,
setDataSource,
setDataSourceOptions,
unsetDataSource,
useDataSource,
} from 'typeorm-extension';
// 1. a DataSource instance, initialized on first use
setDataSource(new DataSource({
type: 'postgres',
host: 'localhost',
database: 'app',
}));
// 2. only options: the DataSource is created on first use
setDataSourceOptions({
type: 'better-sqlite3',
database: 'reports.sqlite',
}, 'reports');
const app = await useDataSource(); // alias 'default'
const reports = await useDataSource('reports');
hasDataSource('reports'); // true
await reports.destroy();
unsetDataSource('reports');useDataSource(alias)returns the registered instance and initializes it if needed. With only options registered, it creates theDataSourcefrom them.With nothing registered for the alias,
useDataSource()runs the discovery above, combined with the environment.Concurrent
useDataSource()calls for one alias share one build, so only oneDataSourceis created and initialized. A failed build is not cached; the next call tries again.hasDataSource(alias)is true once an instance is registered or built. Registered options alone do not count.unsetDataSource(alias)removes the instance from the registry. It does not destroy it, and registered options stay, so the nextuseDataSource(alias)builds a new instance from them.