Kysely Database Options for NestJS

PostgreSQL ,ClickHouse , MySql ,Microsoft SQL Server (MSSQL) ,SQLite

Інтерфейси для налаштування з'єднання з базою даних за допомогою Kysely ORM у додатку NestJS. Наведені типи та інтерфейси допомагають структурувати та керувати різними параметрами бази даних, включаючи підтримку асинхронних конфігурацій та специфічних налаштувань для PostgreSQL.

🛠️ Встановлення

Щоб почати використовувати ці інтерфейси, встановіть необхідні залежності:

npm install kysely @nestjs/config

📚 Огляд інтерфейсів

DbOption<DbShem>

Визначає основні параметри для підключення до бази даних.

Властивості:

• nameInjection?: string - Необов'язкова назва для ін'єкції залежностей.
• dialect: Dialect - Діалект бази даних (наприклад, PostgreSQL, MySQL).
• migrations?: MigrationType - Масив або шлях до міграцій.
• migrationRun?: boolean - Автоматичний запуск міграцій під час підключення.
• dbLogLevel?: string[] - Рівні логування для бази даних.

DbOptionPg<DbShem>

Розширює DbOption для специфічних налаштувань PostgreSQL.

Властивості:

• connectionString: string - Рядок підключення до бази даних.
• nameInjection: string - Обов'язкова назва для ін'єкції залежностей.

DbOptionAsync<DbShem>

Визначає асинхронні параметри для бази даних.

Властивості:

• inject: any[] - Масив залежностей для ін'єкції.
• nameInjection: string - Обов'язкова назва для ін'єкції залежностей.
• useFactory: (...args: any[]) => DbOption<DbShem> - Фабрична функція для створення налаштувань бази даних.

DbOptionPgAsync<DbShem>

Розширює DbOption для асинхронних конфігурацій PostgreSQL.

Властивості:

• inject: any[] - Масив залежностей для ін'єкції.
• nameInjection: string - Обов'язкова назва для ін'єкції залежностей.
• useFactory: (...args: any[]) => ({ connectionString: string, migrationRun?: boolean, migrations?: MigrationType, dbLogLevel?: LogConfig }) - Фабрична функція для створення налаштувань PostgreSQL.

MigrationType

Визначає тип для міграцій, який може бути рядком або масивом об'єктів MigrationExport.

MigrationExport

Розширює інтерфейс Migration з Kysely, додаючи додаткову властивість sortKey для сортування міграцій.

Властивості:

• sortKey: string - Ключ для сортування міграцій.

DbOptionTypes<T>

Тип, який об'єднує всі можливі варіанти параметрів бази даних:

• DbOption<T>
• DbOptionPg<T>
• DbOptionAsync<T>
• DbOptionPgAsync<T>

MigrationsMap

Визначає карту експортованих міграцій.

Структура:

interface MigrationsMap {
  [key: string]: MigrationExport;
}

🚀 Приклад використання

Реєстрація модулів бази даних у NestJS

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { DatabaseModule } from './database.module';
import { DbOptionPgAsync, DbOptionAsync, DbOptionPg } from './db-options';
import { Pool } from 'pg';
import { PostgresDialect, PostgresDialectConfig } from 'kysely';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      expandVariables: true,
    }),

    // Реєстрація PostgreSQL бази даних з асинхронною конфігурацією
    DatabaseModule.registerPgAsync([
      {
        useFactory: (configService: ConfigService) => ({
          connectionString: configService.get<string>('DATABASE_URL'),
          dbLogLevel: JSON.parse(configService.get<string>('DATABASE_LOG_LEVELS')),
        }),
        inject: [ConfigService],
        nameInjection: 'DB_WAR_RICK',
      } as DbOptionPgAsync<any>,
    ]),

    // Загальна асинхронна конфігурація бази даних {{Можливо використовувати інщі бази данних}} 
    DatabaseModule.registerAsync([
      {
        useFactory: (configService: ConfigService) => ({
          dialect: new PostgresDialect({
            pool: new Pool({ connectionString: configService.get('DATABASE_URL') }),
          } as PostgresDialectConfig),
          migrationRun: configService.get<boolean>('MIGRATION_RUNNING'),
          dbLogLevel: JSON.parse(configService.get<string>('DATABASE_LOG_LEVELS')),
        }),
        inject: [ConfigService],
        nameInjection: 'DB_WAR_RICK',
      } as DbOptionAsync<any>,
    ]),

    // Синхронна конфігурація PostgreSQL
    DatabaseModule.registerPg([
      {
        nameInjection: 'DB_PG',
        connectionString: 'postgres://postgres:postgres@localhost:5467/war_risks',
        dbLogLevel: ['query'],
      } as DbOptionPg<any>,
    ]),
  ],
})
export class AppModule {}

Також використовуються три діалекти баз даних:

1. PostgreSQL (через pg та PostgresDialect із Kysely)
2. SQLite (через better-sqlite3 та SqliteDialect із Kysely)
3. ClickHouse (через ClickhouseDialect із @founderpath/kysely-clickhouse)

Пояснення імпортів

Імпортовані наступні модулі, сервіси та діалекти:

• ConfigModule: Обробляє змінні оточення.
• AppController, AppService: Базова логіка додатку.
• DatabaseModule: Кастомний модуль для обробки підключень до баз даних.
• LogConfig, PostgresDialect, SqliteDialect із Kysely: Для обробки підключень до баз даних.
• Pool із pg: Пул підключень PostgreSQL.
• SQLite із better-sqlite3: Драйвер для SQLite.
• ClickhouseDialect із @founderpath/kysely-clickhouse: Діалект бази даних ClickHouse.

Реєстрація в DatabaseModule

DatabaseModule використовується для реєстрації кількох підключень до баз даних як синхронними, так і асинхронними методами.

Реєстрація баз даних за допомогою DatabaseModule.register()

Реєстрація SQLite в пам'яті

DatabaseModule.register([
  {
    nameInjection: 'DB_LITE',
    dialect: new SqliteDialect({
      database: new SQLite(':memory:'),
    } as SqliteDialectConfig),
    migrations,
    migrationRun: true,
    dbLogLevel: ['query'],
  } as DbOption<DatabaseLite>,
  {
    nameInjection: 'DB_WAR_RICK',
    dialect: new PostgresDialect({
      pool: new Pool({
        connectionString: 'postgres://postgres:postgres@localhost:5467/war_risks',
      }),
    } as PostgresDialectConfig),
  } as DbOption<WarRisckShem>,
]);

Реєстрація PostgreSQL за допомогою DatabaseModule.registerPgAsync()

DatabaseModule.registerPgAsync([
  {
    useFactory: (configService: ConfigService) => ({
      connectionString: configService.get<string>('DATABASE_URL'),
      dbLogLevel: JSON.parse(configService.get<string>('DATABASE_LOG_LEVELS')),
    }),
    inject: [ConfigService],
    nameInjection: 'DB_WAR_RICK',
  } as DbOptionPgAsync<WarRisckShem>,
]);

Реєстрація баз даних за допомогою DatabaseModule.registerAsync()

PostgreSQL

DatabaseModule.registerAsync([
  {
    nameInjection: 'DB_POSTGRES',
    useFactory: (configService: ConfigService) => ({
      dialect: new PostgresDialect({
        pool: new Pool({ connectionString: configService.get('DATABASE_URL') }),
      } as PostgresDialectConfig),
      migrationRun: configService.get<boolean>('DATABASE_MIGRATION_RUN'),
      dbLogLevel: JSON.parse(configService.get<string>('DATABASE_LOG_LEVELS')),
    }),
    inject: [ConfigService],
  } as DbOptionAsync<WarRisckShem>,

  {
    nameInjection: 'DB_SQLITE',
    useFactory: (configService: ConfigService) => ({
      dialect: new SqliteDialect({
        database: new SQLite(configService.get<string>('DATABASE_URL_SQLITE')),
      } as SqliteDialectConfig),
      migrations,
      migrationRun: configService.get<boolean>('DATABASE_MIGRATION_RUN'),
      dbLogLevel: configService.get<string[]>('DATABASE_LOG_LEVELS'),
    }),
    inject: [ConfigService],
  } as DbOptionAsync<DatabaseLite>,

  {
    nameInjection: 'DB_CLICKHOUSE',
    useFactory: (configService: ConfigService) => ({
      dialect: new ClickhouseDialect({
        options: {
          url: 'http://localhost:8123',
          username: 'admmin',
          password: 'admmin',
          database: 'testdb',
        },
      }),
    }),
    inject: [ConfigService],
  } as DbOptionAsync<any>,
]);

Реєстрація PostgreSQL за допомогою DatabaseModule.registerPg()

DatabaseModule.registerPg([
  {
    nameInjection: 'DB_WAR_RICK',
    connectionString: 'postgres://postgres:postgres@localhost:5467/war_risks',
    dbLogLevel: ['query', 'error', 'warn'],
  } as DbOptionPg<WarRisckShem>,
]);

Змінні оточення

Для налаштування баз даних використовуються наступні змінні оточення:

• DATABASE_URL: Рядок підключення до PostgreSQL.
• DATABASE_URL_SQLITE: Шлях до файлу бази даних SQLite.
• DATABASE_MIGRATION_RUN: Булевий параметр для ввімкнення або вимкнення міграцій.
• DATABASE_LOG_LEVELS: JSON-масив для налаштування рівнів логування.

Приклад міграцій для SQLite

Міграції для SQLite визначені у об’єкті migrations, імпортованому з ./db/migrations/sqlite. Переконайтеся, що файли міграцій мають правильну структуру для коректного виконання.

Підсумок

Цей модуль демонструє, як реєструвати та налаштовувати кілька підключень до баз даних у додатку NestJS із використанням Kysely. Він показує як синхронну, так і асинхронну конфігурацію та підтримує діалекти PostgreSQL, SQLite та ClickHouse.

Основні моменти:

• Використовуйте ConfigService для інжектування змінних оточення.
• Реєструйте кілька баз даних через DatabaseModule.
• Використовуйте відповідні діалекти для кожного типу бази даних.
• Динамічно налаштовуйте логування та міграції через змінні оточення.

Ця конфігурація забезпечує ефективну роботу додатку з кількома базами даних та підтримує чистий і масштабований код.

📖 Документація

• Kysely Documentation
• NestJS Documentation