Database
This page shows how to create, drop and check a database from code. The CLI equivalents are db create and db drop.
Related pages: Schema (drift, migrations, repair helpers), Locks (advisory and row locks) and Errors (classifying driver errors).
Create
import { DataSource } from 'typeorm';
import type { DataSourceOptions } from 'typeorm';
import { createDatabase } from 'typeorm-extension';
const options: DataSourceOptions = {
type: 'better-sqlite3',
database: 'db.sqlite',
};
await createDatabase({ options });
const dataSource = new DataSource(options);
await dataSource.initialize();createDatabase takes the DataSourceOptions in one of three ways:
options: the options you pass, as above.optionsfromawait buildDataSourceOptions(), which finds the data-source file (or reads the environment) and lets you change the result before the call.- no
optionsat all: the data-source file is discovered, as described on the Data Source page. PassfindOptionsto say where to look.
What happens on the call:
- The database is created only if it does not exist yet (
ifNotExist, defaulttrue). - On postgres, "if it does not exist" is a lookup in
pg_databasefollowed byCREATE DATABASE. Two callers running at the same moment can both see no database, and the secondCREATEfails. Create the database once, for example in a release step, not from every replica (see Deploying with several replicas). - With
synchronize(defaulttrue) the schema is set up right after, also when the database already existed: the migrations run when the options configure any, otherwisesynchronize(false)runs. Passsynchronize: falseto only create the database. - The options are used with
synchronize,migrationsRunanddropSchematurned off and without subscribers, so nothing beyond the step above touches the schema.
For every option, see createDatabase.
Drop
import { buildDataSourceOptions, dropDatabase } from 'typeorm-extension';
const options = await buildDataSourceOptions();
await dropDatabase({ options });- The options can be passed, built or discovered, the same three ways as for
createDatabase. - A missing database is not an error (
ifExist, defaulttrue). - On oracle, dropping a database is not supported: the call does nothing.
For every option, see dropDatabase.
Check
checkDatabase tells setup code whether the database exists and whether its schema is current. It never synchronizes, migrates or drops the schema.
import type { DataSourceOptions } from 'typeorm';
import { checkDatabase, createDatabase } from 'typeorm-extension';
declare const options: DataSourceOptions;
const check = await checkDatabase({ options });
if (!check.exists) {
await createDatabase({ options });
}The result has three fields:
exists: whether the database exists. A missing database is reported asfalse, on cockroachdb as well. Any failure to connect (also wrong credentials or an unreachable host) is reported asfalse. On better-sqlite3, connecting creates a missing database file, soexistsistruethere.schema: whether the schema is up to date. With migrations configured, this istruewhen none are pending. Without migrations, a database which already has a migrations table counts as up to date only when no entities are defined. Otherwise the entity tables are compared against the entity metadata.migrationsPending: the migrations which have not run yet.
Where the data source comes from:
- Without
options, the data source is looked up byaliasin the registry, or discovered the same way as forcreateDatabase. - A data source passed as
dataSourcetakes precedence overoptionsandalias. - An initialized data source (passed or registered) is used as is and never destroyed. An uninitialized one is left untouched and the check runs on a copy.
- A copy, like any data source the check builds itself, never synchronizes, runs migrations or drops the schema, and on postgres it installs no extensions.
For details, see checkDatabase.
NOTE
mongodb has no schema to compare. Without migrations configured, schema is always true there, and exists is true once the connection succeeds: mongodb creates a database lazily, so a missing one is not reported.
Custom Connection
By default, the library opens a raw connection with the driver's native client (for example pg or mysql2) to run the CREATE and DROP statements. For server-backed drivers you can inject a server-level connection of your own instead, such as an existing admin pool or a tunnelled connection.
import type { DataSourceOptions } from 'typeorm';
import { createDatabase } from 'typeorm-extension';
declare const options: DataSourceOptions;
declare const pool: { query: (statement: string) => Promise<unknown> };
await createDatabase({
options,
connection: {
execute: (statement) => pool.query(statement),
},
});- The injected object only needs the
executepart of theIDatabaseConnectioninterface. - It is treated as already open: the library never opens or closes it. Its lifecycle stays with you.
- For full control over how connections are opened (for example one per target database), implement the
IDatabaseConnectionFactoryinterface instead. Both types are exported from the package.
NOTE
The former per-driver helpers (createPostgresDatabase, dropMySQLDatabase, ...) are deprecated and will be removed in the next major release. Use createDatabase and dropDatabase: the driver is picked from the type of the options. On oracle, dropping a database is not supported and the create statement is passed through unchanged.