typeorm/query-runner/QueryRunner.d.ts

Data-Mapper ORM for TypeScript and ES2023+. Supports MySQL/MariaDB, PostgreSQL, MS SQL Server, Oracle, SAP HANA, SQLite, MongoDB databases.

import type { TableColumn } from "../schema-builder/table/TableColumn";
import type { Table } from "../schema-builder/table/Table";
import type { TableForeignKey } from "../schema-builder/table/TableForeignKey";
import type { TableIndex } from "../schema-builder/table/TableIndex";
import type { DataSource } from "../data-source/DataSource";
import type { ReadStream } from "../platform/PlatformTools";
import type { EntityManager } from "../entity-manager/EntityManager";
import type { ObjectLiteral } from "../common/ObjectLiteral";
import type { SqlInMemory } from "../driver/SqlInMemory";
import type { TableUnique } from "../schema-builder/table/TableUnique";
import type { View } from "../schema-builder/view/View";
import type { Broadcaster } from "../subscriber/Broadcaster";
import type { TableCheck } from "../schema-builder/table/TableCheck";
import type { IsolationLevel } from "../driver/types/IsolationLevel";
import type { TableExclusion } from "../schema-builder/table/TableExclusion";
import type { QueryResult } from "./QueryResult";
import type { ReplicationMode } from "../driver/types/ReplicationMode";
/**
 * Runs queries on a single database connection.
 */
export interface QueryRunner extends AsyncDisposable {
    /**
     * DataSource used by this query runner.
     */
    readonly dataSource: DataSource;
    /**
     * DataSource used by this query runner.
     *
     * @deprecated since 1.0.0. Use {@link dataSource} instance instead.
     */
    get connection(): DataSource;
    /**
     * Broadcaster used on this query runner to broadcast entity events.
     */
    readonly broadcaster: Broadcaster;
    /**
     * Entity manager working only with this query runner.
     */
    readonly manager: EntityManager;
    /**
     * Indicates if connection for this query runner is released.
     * Once its released, query runner cannot run queries anymore.
     */
    readonly isReleased: boolean;
    /**
     * Indicates if transaction is in progress.
     */
    readonly isTransactionActive: boolean;
    /**
     * Stores temporarily user data.
     * Useful for sharing data with subscribers.
     */
    data: ObjectLiteral;
    /**
     * Creates/uses database connection from the connection pool to perform further operations.
     * Returns obtained database connection.
     */
    connect(): Promise<any>;
    /**
     * Called before migrations are run.
     */
    beforeMigration(): Promise<void>;
    /**
     * Called after migrations are run.
     */
    afterMigration(): Promise<void>;
    /**
     * Releases used database connection.
     * You cannot use query runner methods after connection is released.
     */
    release(): Promise<void>;
    [Symbol.asyncDispose](): Promise<void>;
    /**
     * Removes all tables from the currently connected database.
     * Be careful with using this method and avoid using it in production or migrations
     * (because it can clear all your database).
     */
    clearDatabase(database?: string): Promise<void>;
    /**
     * Starts transaction.
     */
    startTransaction(isolationLevel?: IsolationLevel): Promise<void>;
    /**
     * Commits transaction.
     * Error will be thrown if transaction was not started.
     */
    commitTransaction(): Promise<void>;
    /**
     * Rollbacks transaction.
     * Error will be thrown if transaction was not started.
     */
    rollbackTransaction(): Promise<void>;
    /**
     * Executes a given SQL query and returns raw database results.
     *
     * Note: Parameters may be named if using mysql2 with extra.namedPlaceholders set:
     * Example:
     * ```ts
     * query(
     *   "SELECT * FROM USERS WHERE name = :name and age = :age",
     *   { name: "John", age: 24 },
     * )
     * ```
     */
    query(query: string, parameters: any[] | ObjectLiteral | undefined, useStructuredResult: true): Promise<QueryResult>;
    /**
     * Executes a given SQL query and returns raw database results.
     */
    query(query: string, parameters?: any[] | ObjectLiteral): Promise<any>;
    /**
     * Tagged template function that executes raw SQL query and returns raw database results.
     * Template expressions are automatically transformed into database parameters.
     * Raw query execution is supported only by relational databases (MongoDB is not supported).
     * Note: Don't call this as a regular function, it is meant to be used with backticks to tag a template literal.
     *
     * @example
     * queryRunner.sql`SELECT * FROM table_name WHERE id = ${id}`
     *
     */
    sql<T = any>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T>;
    /**
     * Returns raw data stream.
     */
    stream(query: string, parameters?: any[], onEnd?: Function, onError?: Function): Promise<ReadStream>;
    /**
     * Returns all available database names including system databases.
     */
    getDatabases(): Promise<string[]>;
    /**
     * Returns all available schema names including system schemas.
     * If database parameter specified, returns schemas of that database.
     * Useful for SQLServer and Postgres only.
     */
    getSchemas(database?: string): Promise<string[]>;
    /**
     * Loads a table by a given name from the database.
     */
    getTable(tablePath: string): Promise<Table | undefined>;
    /**
     * Loads all tables from the database and returns them.
     */
    getTables(tablePaths?: string[]): Promise<Table[]>;
    /**
     * Loads a view by a given name from the database.
     */
    getView(viewPath: string): Promise<View | undefined>;
    /**
     * Loads all views from the database and returns them.
     */
    getViews(viewPaths?: string[]): Promise<View[]>;
    /**
     * Returns replication mode (ex: `master` or `slave`).
     */
    getReplicationMode(): ReplicationMode;
    /**
     * Checks if a database with the given name exist.
     */
    hasDatabase(database: string): Promise<boolean>;
    /**
     * Loads currently using database
     */
    getCurrentDatabase(): Promise<string | undefined>;
    /**
     * Checks if a schema with the given name exist.
     */
    hasSchema(schema: string): Promise<boolean>;
    /**
     * Loads currently using database schema
     */
    getCurrentSchema(): Promise<string | undefined>;
    /**
     * Checks if a table with the given name exist.
     */
    hasTable(table: Table | string): Promise<boolean>;
    /**
     * Checks if a column exist in the table.
     */
    hasColumn(table: Table | string, columnName: string): Promise<boolean>;
    /**
     * Creates a new database.
     */
    createDatabase(database: string, ifNotExists?: boolean): Promise<void>;
    /**
     * Drops a database.
     */
    dropDatabase(database: string, ifExists?: boolean): Promise<void>;
    /**
     * Creates a new table schema.
     */
    createSchema(schemaPath: string, ifNotExists?: boolean): Promise<void>;
    /**
     * Drops a table schema.
     * For SqlServer can accept schema path (e.g. 'dbName.schemaName') as parameter.
     * If schema path passed, it will drop schema in specified database.
     */
    dropSchema(schemaPath: string, ifExists?: boolean, isCascade?: boolean): Promise<void>;
    /**
     * Creates a new table.
     */
    createTable(table: Table, ifNotExists?: boolean, createForeignKeys?: boolean, createIndices?: boolean): Promise<void>;
    /**
     * Drops a table.
     */
    dropTable(table: Table | string, ifExists?: boolean, dropForeignKeys?: boolean, dropIndices?: boolean): Promise<void>;
    /**
     * Creates a new view.
     */
    createView(view: View, syncWithMetadata?: boolean, oldView?: View): Promise<void>;
    /**
     * Drops a view.
     */
    dropView(view: View | string, ifExists?: boolean): Promise<void>;
    /**
     * Renames a table.
     */
    renameTable(oldTableOrName: Table | string, newTableName: string): Promise<void>;
    /**
     * Change table comment. Only supports MySQL and MariaDB
     */
    changeTableComment(tableOrName: Table | string, comment?: string): Promise<void>;
    /**
     * Adds a new column.
     */
    addColumn(table: Table | string, column: TableColumn): Promise<void>;
    /**
     * Adds new columns.
     */
    addColumns(table: Table | string, columns: TableColumn[]): Promise<void>;
    /**
     * Renames a column.
     */
    renameColumn(table: Table | string, oldColumnOrName: TableColumn | string, newColumnOrName: TableColumn | string): Promise<void>;
    /**
     * Changes a column in the table.
     */
    changeColumn(table: Table | string, oldColumn: TableColumn | string, newColumn: TableColumn): Promise<void>;
    /**
     * Changes columns in the table.
     */
    changeColumns(table: Table | string, changedColumns: {
        oldColumn: TableColumn;
        newColumn: TableColumn;
    }[]): Promise<void>;
    /**
     * Drops a column in the table.
     */
    dropColumn(table: Table | string, column: TableColumn | string, ifExists?: boolean): Promise<void>;
    /**
     * Drops columns in the table.
     */
    dropColumns(table: Table | string, columns: TableColumn[] | string[], ifExists?: boolean): Promise<void>;
    /**
     * Creates a new primary key.
     */
    createPrimaryKey(table: Table | string, columnNames: string[], constraintName?: string): Promise<void>;
    /**
     * Updates composite primary keys.
     */
    updatePrimaryKeys(table: Table | string, columns: TableColumn[]): Promise<void>;
    /**
     * Drops a primary key.
     */
    dropPrimaryKey(table: Table | string, constraintName?: string, ifExists?: boolean): Promise<void>;
    /**
     * Creates a new unique constraint.
     */
    createUniqueConstraint(table: Table | string, uniqueConstraint: TableUnique): Promise<void>;
    /**
     * Creates new unique constraints.
     */
    createUniqueConstraints(table: Table | string, uniqueConstraints: TableUnique[]): Promise<void>;
    /**
     * Drops a unique constraint.
     */
    dropUniqueConstraint(table: Table | string, uniqueOrName: TableUnique | string, ifExists?: boolean): Promise<void>;
    /**
     * Drops unique constraints.
     */
    dropUniqueConstraints(table: Table | string, uniqueConstraints: TableUnique[], ifExists?: boolean): Promise<void>;
    /**
     * Creates a new check constraint.
     */
    createCheckConstraint(table: Table | string, checkConstraint: TableCheck): Promise<void>;
    /**
     * Creates new check constraints.
     */
    createCheckConstraints(table: Table | string, checkConstraints: TableCheck[]): Promise<void>;
    /**
     * Drops a check constraint.
     */
    dropCheckConstraint(table: Table | string, checkOrName: TableCheck | string, ifExists?: boolean): Promise<void>;
    /**
     * Drops check constraints.
     */
    dropCheckConstraints(table: Table | string, checkConstraints: TableCheck[], ifExists?: boolean): Promise<void>;
    /**
     * Creates a new exclusion constraint.
     */
    createExclusionConstraint(table: Table | string, exclusionConstraint: TableExclusion): Promise<void>;
    /**
     * Creates new exclusion constraints.
     */
    createExclusionConstraints(table: Table | string, exclusionConstraints: TableExclusion[]): Promise<void>;
    /**
     * Drops an exclusion constraint.
     */
    dropExclusionConstraint(table: Table | string, exclusionOrName: TableExclusion | string, ifExists?: boolean): Promise<void>;
    /**
     * Drops exclusion constraints.
     */
    dropExclusionConstraints(table: Table | string, exclusionConstraints: TableExclusion[], ifExists?: boolean): Promise<void>;
    /**
     * Creates a new foreign key.
     */
    createForeignKey(table: Table | string, foreignKey: TableForeignKey): Promise<void>;
    /**
     * Creates new foreign keys.
     */
    createForeignKeys(table: Table | string, foreignKeys: TableForeignKey[]): Promise<void>;
    /**
     * Drops a foreign key.
     */
    dropForeignKey(table: Table | string, foreignKeyOrName: TableForeignKey | string, ifExists?: boolean): Promise<void>;
    /**
     * Drops foreign keys.
     */
    dropForeignKeys(table: Table | string, foreignKeys: TableForeignKey[], ifExists?: boolean): Promise<void>;
    /**
     * Creates a new index.
     */
    createIndex(table: Table | string, index: TableIndex): Promise<void>;
    /**
     * Creates new indices.
     */
    createIndices(table: Table | string, indices: TableIndex[]): Promise<void>;
    /**
     * Drops an index.
     */
    dropIndex(table: Table | string, index: TableIndex | string, ifExists?: boolean): Promise<void>;
    /**
     * Drops indices.
     */
    dropIndices(table: Table | string, indices: TableIndex[], ifExists?: boolean): Promise<void>;
    /**
     * Clears all table contents.
     * Note: this operation uses SQL's TRUNCATE query which cannot be reverted in transactions.
     */
    clearTable(tableName: string, options?: {
        cascade?: boolean;
    }): Promise<void>;
    /**
     * Enables special query runner mode in which sql queries won't be executed,
     * instead they will be memorized into a special variable inside query runner.
     * You can get memorized sql using getMemorySql() method.
     */
    enableSqlMemory(): void;
    /**
     * Disables special query runner mode in which sql queries won't be executed
     * started by calling enableSqlMemory() method.
     *
     * Previously memorized sql will be flushed.
     */
    disableSqlMemory(): void;
    /**
     * Flushes all memorized sqls.
     */
    clearSqlMemory(): void;
    /**
     * Gets sql stored in the memory. Parameters in the sql are already replaced.
     */
    getMemorySql(): SqlInMemory;
    /**
     * Executes up sql queries.
     */
    executeMemoryUpSql(): Promise<void>;
    /**
     * Executes down sql queries.
     */
    executeMemoryDownSql(): Promise<void>;
}