Data Source Management

/**
 * Main database connection class for TypeORM applications
 */
class DataSource {
  /**
   * Creates a new DataSource instance with the provided options
   * @param options - Database connection configuration options
   */
  constructor(options: DataSourceOptions);

  /**
   * Initializes the data source, establishes database connection
   * @returns Promise resolving to the initialized DataSource instance
   */
  initialize(): Promise<DataSource>;

  /**
   * Closes the database connection and cleans up resources
   * @returns Promise resolving when connection is closed
   */
  destroy(): Promise<void>;

  /**
   * Gets a repository for the specified entity
   * @param target - Entity class, schema, or name
   * @returns Repository instance for the entity
   */
  getRepository<Entity>(target: EntityTarget<Entity>): Repository<Entity>;

  /**
   * Gets a tree repository for the specified entity
   * @param target - Entity class, schema, or name
   * @returns TreeRepository instance for hierarchical data
   */
  getTreeRepository<Entity>(target: EntityTarget<Entity>): TreeRepository<Entity>;

  /**
   * Gets a MongoDB repository for the specified entity
   * @param target - Entity class, schema, or name
   * @returns MongoRepository instance for MongoDB operations
   */
  getMongoRepository<Entity>(target: EntityTarget<Entity>): MongoRepository<Entity>;

  /**
   * Executes operations within a database transaction
   * @param runInTransaction - Function to execute within transaction
   * @returns Promise resolving to the transaction result
   */
  transaction<T>(runInTransaction: (manager: EntityManager) => Promise<T>): Promise<T>;

  /**
   * Executes raw SQL query with optional parameters
   * @param query - SQL query string
   * @param parameters - Query parameters
   * @returns Promise resolving to query results
   */
  query(query: string, parameters?: any[]): Promise<any>;

  /**
   * Creates a query runner for advanced database operations
   * @returns QueryRunner instance
   */
  createQueryRunner(): QueryRunner;

  /**
   * Synchronizes database schema with entity definitions
   * @param dropBeforeSync - Whether to drop existing database before sync
   * @returns Promise resolving when synchronization completes
   */
  synchronize(dropBeforeSync?: boolean): Promise<void>;

  /**
   * Drops the entire database
   * @returns Promise resolving when database is dropped
   */
  dropDatabase(): Promise<void>;

  /**
   * Runs pending database migrations
   * @param options - Migration execution options
   * @returns Promise resolving to array of executed migrations
   */
  runMigrations(options?: MigrationRunOptions): Promise<Migration[]>;

  /**
   * Undoes the last executed migration
   * @param options - Migration undo options
   * @returns Promise resolving when migration is undone
   */
  undoLastMigration(options?: MigrationUndoOptions): Promise<void>;

  /**
   * Lists all migrations and whether they have been run
   * @returns Promise resolving to true if there are pending migrations
   */
  showMigrations(): Promise<boolean>;

  /**
   * Gets metadata for the specified entity
   * @param target - Entity class, schema, or name
   * @returns Entity metadata for the target
   */
  getMetadata(target: EntityTarget<any>): EntityMetadata;

  /**
   * Checks if metadata exists for the specified entity
   * @param target - Entity class, schema, or name
   * @returns True if metadata exists for the target
   */
  hasMetadata(target: EntityTarget<any>): boolean;

  /**
   * Creates a new entity manager with optional query runner
   * @param queryRunner - Optional query runner for transaction context
   * @returns New EntityManager instance
   */
  createEntityManager(queryRunner?: QueryRunner): EntityManager;

  /**
   * Creates a generic query builder for custom SQL operations
   * @param queryRunner - Optional query runner for transaction context
   * @returns SelectQueryBuilder instance for custom queries
   */
  createQueryBuilder(queryRunner?: QueryRunner): SelectQueryBuilder<any>;

  /** Whether the data source has been initialized */
  readonly isInitialized: boolean;

  /** The EntityManager instance for this data source */
  readonly manager: EntityManager;

  /** The configured database driver */
  readonly driver: Driver;

  /** Connection options used to create this data source */
  readonly options: DataSourceOptions;
}

import { DataSource } from "typeorm";
import { User, Post } from "./entities";

// PostgreSQL connection
const dataSource = new DataSource({
  type: "postgres",
  host: "localhost",
  port: 5432,
  username: "myuser",
  password: "mypassword",
  database: "mydatabase",
  entities: [User, Post],
  synchronize: false,
  logging: true,
});

// Initialize connection
await dataSource.initialize();

// Get repositories
const userRepository = dataSource.getRepository(User);
const postRepository = dataSource.getRepository(Post);

// Execute transaction
await dataSource.transaction(async manager => {
  const user = await manager.save(User, { name: "John" });
  const post = await manager.save(Post, { title: "Hello", author: user });
});

// Raw query
const results = await dataSource.query(
  "SELECT * FROM users WHERE age > $1",
  [18]
);

// Cleanup
await dataSource.destroy();

/**
 * Union type of all supported database connection options
 */
type DataSourceOptions =
  | MysqlConnectionOptions
  | PostgresConnectionOptions
  | SqliteConnectionOptions
  | BetterSqlite3ConnectionOptions
  | CockroachConnectionOptions
  | OracleConnectionOptions
  | MssqlConnectionOptions
  | MongoConnectionOptions
  | AuroraDataApiConnectionOptions
  | AuroraDataApiPostgresConnectionOptions
  | AuroraDataApiMysqlConnectionOptions
  | SapConnectionOptions
  | SpannerConnectionOptions;

/**
 * Base connection options shared across all database types
 */
interface BaseConnectionOptions {
  /** Database type identifier */
  type: DatabaseType;

  /** Custom connection name for multiple connections */
  name?: string;

  /** Array of entity classes to be used with this connection */
  entities?: (ObjectType<any> | EntitySchema<any> | string)[];

  /** Array of subscriber classes */
  subscribers?: (ObjectType<any> | string)[];

  /** Array of migration classes */
  migrations?: (ObjectType<any> | string)[];

  /** Logger configuration */
  logger?: "advanced-console" | "simple-console" | "file" | "debug" | Logger;

  /** Enable/disable logging */
  logging?: boolean | "all" | ("query" | "schema" | "error" | "warn" | "info" | "log" | "migration")[];

  /** Auto schema synchronization (dev only) */
  synchronize?: boolean;

  /** Drop schema on connection */
  dropSchema?: boolean;

  /** Run migrations automatically */
  migrationsRun?: boolean;

  /** Enable connection pooling */
  pool?: {
    max?: number;
    min?: number;
    acquire?: number;
    idle?: number;
  };

  /** Connection timeout in milliseconds */
  connectTimeoutMS?: number;

  /** Extra connection options */
  extra?: any;
}

/**
 * PostgreSQL specific connection options
 */
interface PostgresConnectionOptions extends BaseConnectionOptions {
  type: "postgres";
  host?: string;
  port?: number;
  username?: string;
  password?: string | (() => string) | (() => Promise<string>);
  database?: string;
  schema?: string;
  ssl?: boolean | TlsOptions;
  uuidExtension?: "uuid-ossp" | "pgcrypto";
  logNotifications?: boolean;
  installExtensions?: boolean;
  applicationName?: string;
  replication?: {
    master: {
      host: string;
      port: number;
      username: string;
      password: string;
      database: string;
    };
    slaves: {
      host: string;
      port: number;
      username: string;
      password: string;
      database: string;
    }[];
  };
}

/**
 * MySQL specific connection options
 */
interface MysqlConnectionOptions extends BaseConnectionOptions {
  type: "mysql" | "mariadb";
  host?: string;
  port?: number;
  username?: string;
  password?: string | (() => string) | (() => Promise<string>);
  database?: string;
  charset?: string;
  timezone?: string;
  connectTimeout?: number;
  acquireTimeout?: number;
  timeout?: number;
  ssl?: string | (tls.SecureContextOptions & { rejectUnauthorized?: boolean });
  socketPath?: string;
  debug?: boolean;
  trace?: boolean;
  multipleStatements?: boolean;
  flags?: string;
  bigNumberStrings?: boolean;
  dateStrings?: boolean | string[];
  supportBigNumbers?: boolean;
  legacySpatialSupport?: boolean;
}

// PostgreSQL with SSL
const postgresConfig: DataSourceOptions = {
  type: "postgres",
  host: "localhost",
  port: 5432,
  username: "user",
  password: "password",
  database: "mydb",
  ssl: {
    rejectUnauthorized: false,
    ca: fs.readFileSync("ca-certificate.crt").toString(),
  },
  entities: ["src/entities/*.ts"],
  synchronize: false,
  logging: ["error", "warn"],
  pool: {
    max: 20,
    min: 5,
  }
};

// MySQL with multiple statements
const mysqlConfig: DataSourceOptions = {
  type: "mysql",
  host: "localhost",
  port: 3306,
  username: "root",
  password: "password",
  database: "test",
  charset: "utf8mb4",
  timezone: "+00:00",
  multipleStatements: true,
  entities: [User, Post],
  migrations: ["src/migrations/*.ts"],
  migrationsRun: true,
};

// SQLite for development
const sqliteConfig: DataSourceOptions = {
  type: "sqlite",
  database: ":memory:", // or "path/to/database.sqlite"
  entities: [User, Post],
  synchronize: true,
  logging: true,
};

/**
 * Options for running migrations
 */
interface MigrationRunOptions {
  /** Transaction mode: "all" | "none" | "each" */
  transaction?: "all" | "none" | "each";
  /** Whether to run migrations in fake mode */
  fake?: boolean;
}

/**
 * Options for undoing migrations
 */
interface MigrationUndoOptions {
  /** Transaction mode: "all" | "none" | "each" */
  transaction?: "all" | "none" | "each";
  /** Whether to undo migrations in fake mode */
  fake?: boolean;
}

/**
 * @deprecated Use DataSource instead
 * Legacy Connection class for backward compatibility
 */
class Connection {
  /** @deprecated Use DataSource.initialize() instead */
  connect(): Promise<Connection>;
  /** @deprecated Use DataSource.destroy() instead */
  close(): Promise<void>;
  /** @deprecated Use DataSource.getRepository() instead */
  getRepository<Entity>(target: EntityTarget<Entity>): Repository<Entity>;
}

/**
 * @deprecated Use DataSource instead
 * Legacy connection manager for multiple connections
 */
class ConnectionManager {
  /** @deprecated Create DataSource instances directly */
  create(options: ConnectionOptions): Connection;
  /** @deprecated Use DataSource.getRepository() directly */
  get(name?: string): Connection;
}

/**
 * Reads connection configuration from files
 * Supports ormconfig.json, ormconfig.js, ormconfig.env, etc.
 */
class ConnectionOptionsReader {
  /**
   * Reads all connection options from configuration files
   * @returns Promise resolving to array of connection options
   */
  all(): Promise<DataSourceOptions[]>;

  /**
   * Gets connection options by name
   * @param name - Connection name to retrieve
   * @returns Promise resolving to connection options
   */
  get(name: string): Promise<DataSourceOptions>;
}