typeorm / typeorm / 22853215566

import type { Driver } from "../driver/Driver"

import { registerQueryBuilders } from "../query-builder"

import type { Repository } from "../repository/Repository"

import type { EntitySubscriberInterface } from "../subscriber/EntitySubscriberInterface"

import type { EntityTarget } from "../common/EntityTarget"

import type { EntityManager } from "../entity-manager/EntityManager"

import { DefaultNamingStrategy } from "../naming-strategy/DefaultNamingStrategy"

import {

    CannotConnectAlreadyConnectedError,

    CannotExecuteNotConnectedError,

    EntityMetadataNotFoundError,

    QueryRunnerProviderAlreadyReleasedError,

    TypeORMError,

} from "../error"

import type { TreeRepository } from "../repository/TreeRepository"

import type { NamingStrategyInterface } from "../naming-strategy/NamingStrategyInterface"

import type { EntityMetadata } from "../metadata/EntityMetadata"

import type { Logger } from "../logger/Logger"

import type { MigrationInterface } from "../migration/MigrationInterface"

import { MigrationExecutor } from "../migration/MigrationExecutor"

import type { Migration } from "../migration/Migration"

import type { MongoRepository } from "../repository/MongoRepository"

import type { MongoEntityManager } from "../entity-manager/MongoEntityManager"

import { EntityMetadataValidator } from "../metadata-builder/EntityMetadataValidator"

import type { DataSourceOptions } from "./DataSourceOptions"

import { EntityManagerFactory } from "../entity-manager/EntityManagerFactory"

import { DriverFactory } from "../driver/DriverFactory"

import { ConnectionMetadataBuilder } from "../connection/ConnectionMetadataBuilder"

import type { QueryRunner } from "../query-runner/QueryRunner"

import { SelectQueryBuilder } from "../query-builder/SelectQueryBuilder"

import { LoggerFactory } from "../logger/LoggerFactory"

import { QueryResultCacheFactory } from "../cache/QueryResultCacheFactory"

import type { QueryResultCache } from "../cache/QueryResultCache"

import type { SqljsEntityManager } from "../entity-manager/SqljsEntityManager"

import { RelationLoader } from "../query-builder/RelationLoader"

import { ObjectUtils } from "../util/ObjectUtils"

import type { IsolationLevel } from "../driver/types/IsolationLevel"

import type { ReplicationMode } from "../driver/types/ReplicationMode"

import { RelationIdLoader } from "../query-builder/RelationIdLoader"

import { DriverUtils } from "../driver/DriverUtils"

import { InstanceChecker } from "../util/InstanceChecker"

import type { ObjectLiteral } from "../common/ObjectLiteral"

import { buildSqlTag } from "../util/SqlTagUtils"

registerQueryBuilders()

/**

 * DataSource is a pre-defined connection configuration to a specific database.

 * You can have multiple data sources connected (with multiple connections in it),

 * connected to multiple databases in your application.

 *

 * Before, it was called `Connection`, but now `Connection` is deprecated

 * because `Connection` isn't the best name for what it's actually is.

 */

export class DataSource {

    readonly "@instanceof" = Symbol.for("DataSource")

    // -------------------------------------------------------------------------

    // Public Readonly Properties

    // -------------------------------------------------------------------------

    /**

     * Connection options.

     */

    readonly options: DataSourceOptions

    /**

     * Indicates if DataSource is initialized or not.

     */

    readonly isInitialized: boolean

    /**

     * Database driver used by this connection.

     */

    driver: Driver

    /**

     * EntityManager of this connection.

     */

    readonly manager: EntityManager

    /**

     * Naming strategy used in the connection.

     */

    namingStrategy: NamingStrategyInterface

    /**

     * Name for the metadata table

     */

    readonly metadataTableName: string

    /**

     * Logger used to log orm events.

     */

    logger: Logger

    /**

     * Migration instances that are registered for this connection.

     */

    readonly migrations: MigrationInterface[] = []

    /**

     * Entity subscriber instances that are registered for this connection.

     */

    readonly subscribers: EntitySubscriberInterface<any>[] = []

    /**

     * All entity metadatas that are registered for this connection.

     */

    readonly entityMetadatas: EntityMetadata[] = []

    /**

     * All entity metadatas that are registered for this connection.

     * This is a copy of #.entityMetadatas property -> used for more performant searches.

     */

    readonly entityMetadatasMap = new Map<EntityTarget<any>, EntityMetadata>()

    /**

     * Used to work with query result cache.

     */

    queryResultCache?: QueryResultCache

    /**

     * Used to load relations and work with lazy relations.

     */

    readonly relationLoader: RelationLoader

    readonly relationIdLoader: RelationIdLoader

    // -------------------------------------------------------------------------

    // Constructor

    // -------------------------------------------------------------------------

    constructor(options: DataSourceOptions) {

        registerQueryBuilders()

        this.options = options

        this.logger = new LoggerFactory().create(

            this.options.logger,

            this.options.logging,

        )

        this.driver = new DriverFactory().create(this)

        this.manager = this.createEntityManager()

        this.namingStrategy =

            options.namingStrategy || new DefaultNamingStrategy()

        this.metadataTableName = options.metadataTableName || "typeorm_metadata"

        this.queryResultCache = options.cache

            : undefined

        this.relationLoader = new RelationLoader(this)

        this.relationIdLoader = new RelationIdLoader(this)

        this.isInitialized = false

    }

    // -------------------------------------------------------------------------

    // Public Accessors

    // -------------------------------------------------------------------------

    /**

     * Gets the mongodb entity manager that allows to perform mongodb-specific repository operations

     * with any entity in this connection.

     *

     * Available only in mongodb connections.

     * @returns the mongodb entity manager

     */

    get mongoManager(): MongoEntityManager {

        if (!InstanceChecker.isMongoEntityManager(this.manager))

        return this.manager as MongoEntityManager

    }

    /**

     * Gets a sql.js specific Entity Manager that allows to perform special load and save operations

     *

     * Available only in connection with the sqljs driver.

     * @returns an sqljs specific Entity Manager

     */

    get sqljsManager(): SqljsEntityManager {

        if (!InstanceChecker.isSqljsEntityManager(this.manager))

        return this.manager

    }

    // -------------------------------------------------------------------------

    // Public Methods

    // -------------------------------------------------------------------------

    /**

     * Updates current connection options with provided options.

     * @param options

     */

    setOptions(options: Partial<DataSourceOptions>): this {

        Object.assign(this.options, options)

        // todo: we must update the database in the driver as well, if it was set by setOptions method

        //  in the future we need to refactor the code and remove "database" from the driver, and instead

        //  use database (and options) from a single place - data source.

            this.driver.database = DriverUtils.buildDriverOptions(

                this.options,

            ).database

        }

        // todo: need to take a look if we need to update schema and other "poor" properties

        return this

    }

    /**

     * Performs connection to the database.

     * This method should be called once on application bootstrap.

     * This method not necessarily creates database connection (depend on database type),

     * but it also can setup a connection pool with database to use.

     */

    async initialize(): Promise<this> {

        if (this.isInitialized) throw new CannotConnectAlreadyConnectedError()

        // connect to the database via its driver

        await this.driver.connect()

        // connect to the cache-specific database if cache is enabled

        // set connected status for the current connection

        ObjectUtils.assign(this, { isInitialized: true })

        try {

            // build all metadatas registered in the current connection

            await this.buildMetadatas()

            await this.driver.afterConnect()

            // if option is set - drop schema once connection is done

            if (this.options.dropSchema) await this.dropDatabase()

            // if option is set - automatically synchronize a schema

            if (this.options.migrationsRun)

            // if option is set - automatically synchronize a schema

            if (this.options.synchronize) await this.synchronize()

            // if for some reason build metadata fail (for example validation error during entity metadata check)

            // connection needs to be closed

            await this.destroy()

            throw error

        }

        return this

    }

    /**

     * Closes connection with the database.

     * Once connection is closed, you cannot use repositories or perform any operations except opening connection again.

     */

    async destroy(): Promise<void> {

        await this.driver.disconnect()

        // disconnect from the cache-specific database if cache was enabled

        ObjectUtils.assign(this, { isInitialized: false })

    }

    /**

     * Creates database schema for all entities registered in this connection.

     * Can be used only after connection to the database is established.

     * @param dropBeforeSync If set to true then it drops the database with all its tables and data

     */

    async synchronize(dropBeforeSync: boolean = false): Promise<void> {

        if (dropBeforeSync) await this.dropDatabase()

        const schemaBuilder = this.driver.createSchemaBuilder()

        await schemaBuilder.build()

    }

    /**

     * Drops the database and all its data.

     * Be careful with this method on production since this method will erase all your database tables and their data.

     * Can be used only after connection to the database is established.

     */

    // TODO rename

    async dropDatabase(): Promise<void> {

        const queryRunner = this.createQueryRunner()

        try {

            if (

                DriverUtils.isSQLiteFamily(this.driver)

                const databases: string[] = []

                this.entityMetadatas.forEach((metadata) => {

                    if (

                        metadata.database &&

                        databases.indexOf(metadata.database) === -1

                    )

                        databases.push(metadata.database)

                })

                    databases.push(this.driver.database)

                }

                    await queryRunner.clearDatabase()

                } else {

                    for (const database of databases) {

                        await queryRunner.clearDatabase(database)

                    }

                }

                await queryRunner.clearDatabase()

            }

        } finally {

            await queryRunner.release()

        }

    }

    /**

     * Runs all pending migrations.

     * Can be used only after connection to the database is established.

     * @param options

     * @param options.transaction

     * @param options.fake

     */

    async runMigrations(options?: {

        transaction?: "all" | "none" | "each"

        fake?: boolean

    }): Promise<Migration[]> {

        const migrationExecutor = new MigrationExecutor(this)

        migrationExecutor.transaction =

            this.options?.migrationsTransactionMode ||

            "all"

        const successMigrations =

            await migrationExecutor.executePendingMigrations()

        return successMigrations

    }

    /**

     * Reverts last executed migration.

     * Can be used only after connection to the database is established.

     * @param options

     * @param options.transaction

     * @param options.fake

     */

    async undoLastMigration(options?: {

        transaction?: "all" | "none" | "each"

        fake?: boolean

    }): Promise<void> {

        const migrationExecutor = new MigrationExecutor(this)

        migrationExecutor.transaction =

        await migrationExecutor.undoLastMigration()

    }

    /**

     * Lists all migrations and whether they have been run.

     * Returns true if there are pending migrations

     */

    async showMigrations(): Promise<boolean> {

        const migrationExecutor = new MigrationExecutor(this)

        return await migrationExecutor.showMigrations()

    }

    /**

     * Checks if entity metadata exist for the given entity class, target name or table name.

     * @param target

     */

    hasMetadata(target: EntityTarget<any>): boolean {

        return !!this.findMetadata(target)

    }

    /**

     * Gets entity metadata for the given entity class or schema name.

     * @param target

     */

    getMetadata(target: EntityTarget<any>): EntityMetadata {

        const metadata = this.findMetadata(target)

        return metadata

    }

    /**

     * Gets repository for the given entity.

     * @param target

     */

    getRepository<Entity extends ObjectLiteral>(

        target: EntityTarget<Entity>,

    ): Repository<Entity> {

        return this.manager.getRepository(target)

    }

    /**

     * Gets tree repository for the given entity class or name.

     * Only tree-type entities can have a TreeRepository, like ones decorated with `@Tree` decorator.

     * @param target

     */

    getTreeRepository<Entity extends ObjectLiteral>(

        target: EntityTarget<Entity>,

    ): TreeRepository<Entity> {

        return this.manager.getTreeRepository(target)

    }

    /**

     * Gets mongodb-specific repository for the given entity class or name.

     * Works only if connection is mongodb-specific.

     * @param target

     */

    getMongoRepository<Entity extends ObjectLiteral>(

        target: EntityTarget<Entity>,

    ): MongoRepository<Entity> {

        if (!(this.driver.options.type === "mongodb"))

        return this.manager.getRepository(target) as any

    }

    /**

     * Wraps given function execution (and all operations made there) into a transaction.

     * All database operations must be executed using provided entity manager.

     */

    async transaction<T>(

        runInTransaction: (entityManager: EntityManager) => Promise<T>,

    ): Promise<T>

    async transaction<T>(

        isolationLevel: IsolationLevel,

        runInTransaction: (entityManager: EntityManager) => Promise<T>,

    ): Promise<T>

    async transaction<T>(

        isolationOrRunInTransaction:

            | IsolationLevel

            | ((entityManager: EntityManager) => Promise<T>),

        runInTransactionParam?: (entityManager: EntityManager) => Promise<T>,

    ): Promise<any> {

        return this.manager.transaction(

            isolationOrRunInTransaction as any,

            runInTransactionParam as any,

        )

    }

    /**

     * Executes raw SQL query and returns raw database results.

     * @param query

     * @param parameters

     * @param queryRunner

     * @returns a raw response from the database client

     * @see {@link https://typeorm.io/data-source-api | Official docs} for examples.

     */

    async query<T = any>(

        query: string,

        parameters?: any[],

        queryRunner?: QueryRunner,

    ): Promise<T> {

        if (InstanceChecker.isMongoEntityManager(this.manager))

        if (queryRunner && queryRunner.isReleased)

        const usedQueryRunner = queryRunner || this.createQueryRunner()

        try {

            return await usedQueryRunner.query(query, parameters) // await is needed here because we are using finally

        } finally {

            if (!queryRunner) await usedQueryRunner.release()

        }

    }

    /**

     * 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: dataSource.sql`SELECT * FROM table_name WHERE id = ${id}`

     * @param strings

     * @param values

     * @returns a raw response from the database client

     */

    async sql<T = any>(

        strings: TemplateStringsArray,

        ...values: unknown[]

    ): Promise<T> {

        const { query, parameters } = buildSqlTag({

            driver: this.driver,

            strings: strings,

            expressions: values,

        })

        return await this.query(query, parameters)

    }

    /**

     * Creates a new query builder that can be used to build a SQL query.

     */

    createQueryBuilder<Entity extends ObjectLiteral>(

        entityClass: EntityTarget<Entity>,

        alias: string,

        queryRunner?: QueryRunner,

    ): SelectQueryBuilder<Entity>

    /**

     * Creates a new query builder that can be used to build a SQL query.

     */

    createQueryBuilder(queryRunner?: QueryRunner): SelectQueryBuilder<any>

    /**

     * Creates a new query builder that can be used to build a SQL query.

     * @param entityOrRunner

     * @param alias

     * @param queryRunner

     */

    createQueryBuilder<Entity extends ObjectLiteral>(

        entityOrRunner?: EntityTarget<Entity> | QueryRunner,

        alias?: string,

        queryRunner?: QueryRunner,

    ): SelectQueryBuilder<Entity> {

        if (InstanceChecker.isMongoEntityManager(this.manager))

        if (alias) {

            alias = DriverUtils.buildAlias(this.driver, undefined, alias)

            const metadata = this.getMetadata(

                entityOrRunner as EntityTarget<Entity>,

            )

            return new SelectQueryBuilder(this, queryRunner)

                .select(alias)

                .from(metadata.target, alias)

        } else {

            return new SelectQueryBuilder(

                this,

                entityOrRunner as QueryRunner | undefined,

            )

        }

    }

    /**

     * Creates a query runner used for perform queries on a single database connection.

     * Using query runners you can control your queries to execute using single database connection and

     * manually control your database transaction.

     *

     * Mode is used in replication mode and indicates whatever you want to connect

     * to master database or any of slave databases.

     * If you perform writes you must use master database,

     * if you perform reads you can use slave databases.

     * @param mode

     */

    createQueryRunner(mode: ReplicationMode = "master"): QueryRunner {

        const queryRunner = this.driver.createQueryRunner(mode)

        const manager = this.createEntityManager(queryRunner)

        Object.assign(queryRunner, { manager: manager })

        return queryRunner

    }

    /**

     * Gets entity metadata of the junction table (many-to-many table).

     * @param entityTarget

     * @param relationPropertyPath

     */

    getManyToManyMetadata(

        entityTarget: EntityTarget<any>,

        relationPropertyPath: string,

    ) {

        const relationMetadata =

            this.getMetadata(entityTarget).findRelationWithPropertyPath(

                relationPropertyPath,

            )

        if (!relationMetadata)

        if (!relationMetadata.isManyToMany)

        return relationMetadata.junctionEntityMetadata

    }

    /**

     * Creates an Entity Manager for the current connection with the help of the EntityManagerFactory.

     * @param queryRunner

     */

    createEntityManager(queryRunner?: QueryRunner): EntityManager {

        return new EntityManagerFactory().create(this, queryRunner)

    }

    // -------------------------------------------------------------------------

    // Protected Methods

    // -------------------------------------------------------------------------

    /**

     * Finds exist entity metadata by the given entity class, target name or table name.

     * @param target

     */

    protected findMetadata(

        target: EntityTarget<any>,

    ): EntityMetadata | undefined {

        const metadataFromMap = this.entityMetadatasMap.get(target)

        if (metadataFromMap) return metadataFromMap

        for (const [_, metadata] of this.entityMetadatasMap) {

            if (

                InstanceChecker.isEntitySchema(target) &&

                metadata.name === target.options.name

            ) {

                return metadata

            }

                if (target.indexOf(".") !== -1) {

                        return metadata

                    }

                } else {

                    if (

                        metadata.name === target ||

                        metadata.tableName === target

                    ) {

                        return metadata

                    }

                }

            }

            if (

        }

        return undefined

    }

    /**

     * Builds metadatas for all registered classes inside this connection.

     */

    protected async buildMetadatas(): Promise<void> {

        const connectionMetadataBuilder = new ConnectionMetadataBuilder(this)

        const entityMetadataValidator = new EntityMetadataValidator()

        // create subscribers instances if they are not disallowed from high-level (for example they can disallowed from migrations run process)

        const flattenedSubscribers = ObjectUtils.mixedListToArray(

        )

        const subscribers =

            await connectionMetadataBuilder.buildSubscribers(

                flattenedSubscribers,

            )

        ObjectUtils.assign(this, { subscribers: subscribers })

        // build entity metadatas

        const flattenedEntities = ObjectUtils.mixedListToArray(

        )

        const entityMetadatas =

            await connectionMetadataBuilder.buildEntityMetadatas(

                flattenedEntities,

            )

        ObjectUtils.assign(this, {

            entityMetadatas: entityMetadatas,

            entityMetadatasMap: new Map(

                entityMetadatas.map((metadata) => [metadata.target, metadata]),

            ),

        })

        // create migration instances

        const flattenedMigrations = ObjectUtils.mixedListToArray(

        )

        const migrations =

            await connectionMetadataBuilder.buildMigrations(flattenedMigrations)

        ObjectUtils.assign(this, { migrations: migrations })

        // validate all created entity metadatas to make sure user created entities are valid and correct

        entityMetadataValidator.validateMany(

            this.entityMetadatas.filter(

                (metadata) => metadata.tableType !== "view",

            ),

            this.driver,

        )

        // set current data source to the entities

        for (const entityMetadata of entityMetadatas) {

            if (

                InstanceChecker.isBaseEntityConstructor(entityMetadata.target)

                entityMetadata.target.useDataSource(this)

            }

        }

    }

    /**

     * Get the replication mode SELECT queries should use for this datasource by default

     */

    defaultReplicationModeForReads(): ReplicationMode {

        if (

            this.driver.options.replication

            const value = (

                this.driver.options.replication as {

                    defaultMode?: ReplicationMode

                }

            ).defaultMode

            if (value) {

                return value

            }

        }

        return "slave"

    }

}