#База данных

#Обзор

База данных — это инструмент для взаимодействия с базами данных, предоставляемый NocoBase, который обеспечивает удобные функции взаимодействия с базами данных для no-code и low-code приложений. В настоящее время поддерживаются следующие базы данных:

• SQLite 3.8.8+
• MySQL 8.0.17+
• PostgreSQL 10.0+

#Подключение к базе данных

В конструкторе Database вы можете настроить подключение к базе данных, передав параметр options.

const { Database } = require('@nocobase/database');

// Параметры конфигурации базы данных SQLite
const database = new Database({
  dialect: 'mysql',
  host: 'localhost',
  port: 3306,
  database: 'nocobase',
  username: 'root',
  password: 'password'
})

// Параметры конфигурации базы данных MySQL \ PostgreSQL
const database = new Database({
  dialect: /* 'postgres' или 'mysql' */,
  database: 'database',
  username: 'username',
  password: 'password',
  host: 'localhost',
  port: 'port'
})

Подробные параметры конфигурации см. в разделе Конструктор.

#Определение модели данных

Database определяет структуру базы данных с помощью коллекции. Объект коллекции представляет собой таблицу в базе данных.

// Определение коллекции
const UserCollection = database.collection({
  name: 'users',
  fields: [
    {
      name: 'name',
      type: 'string',
    },
    {
      name: 'age',
      type: 'integer',
    },
  ],
});

После определения структуры базы данных вы можете использовать метод sync() для её синхронизации.

await database.sync();

Более подробное использование коллекции см. в разделе Коллекция.

#Чтение и запись данных

Database выполняет операции с данными через Repository.

const UserRepository = UserCollection.repository();

// Создание
await UserRepository.create({
  name: '张三',
  age: 18,
});

// Запрос
const user = await UserRepository.findOne({
  filter: {
    name: '张三',
  },
});

// Изменение
await UserRepository.update({
  values: {
    age: 20,
  },
});

// Удаление
await UserRepository.destroy(user.id);

Более подробное использование CRUD-операций с данными см. в разделе Repository.

#Конструктор

Сигнатура

• constructor(options: DatabaseOptions)

Создаёт экземпляр базы данных.

Параметры

#Методы, связанные с миграциями

#addMigration()

Добавляет один файл миграции.

Сигнатура

• addMigration(options: MigrationItem)

Параметры

Пример

db.addMigration({
  name: '20220916120411-test-1',
  async up() {
    const queryInterface = this.context.db.sequelize.getQueryInterface();
    await queryInterface.query(/* your migration sqls */);
  },
});

#addMigrations()

Добавляет файлы миграций из указанной директории.

Сигнатура

• addMigrations(options: AddMigrationsOptions): void

Параметры

Пример

db.addMigrations({
  directory: path.resolve(__dirname, './migrations'),
  namespace: 'test',
});

#Вспомогательные методы

#inDialect()

Проверяет, соответствует ли текущий тип базы данных одному из указанных типов.

Сигнатура

• inDialect(dialect: string[]): boolean

Параметры

#getTablePrefix()

Получает префикс имени таблицы из конфигурации.

Сигнатура

• getTablePrefix(): string

#Конфигурация коллекций

#collection()

Определяет коллекцию. Этот вызов аналогичен методу define в Sequelize: он создаёт структуру таблицы только в памяти. Чтобы сохранить её в базе данных, вам нужно вызвать метод sync.

Сигнатура

• collection(options: CollectionOptions): Collection

Параметры

Все параметры конфигурации options соответствуют конструктору класса коллекции; см. Коллекция.

События

• 'beforeDefineCollection': Срабатывает перед определением коллекции.
• 'afterDefineCollection': Срабатывает после определения коллекции.

Пример

db.collection({
  name: 'books',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
    {
      type: 'float',
      name: 'price',
    },
  ],
});

// синхронизировать коллекцию как таблицу с БД
await db.sync();

#getCollection()

Получает определённую коллекцию.

Сигнатура

• getCollection(name: string): Collection

Параметры

Пример

const collection = db.getCollection('books');

#hasCollection()

Проверяет, определена ли указанная коллекция.

Сигнатура

• hasCollection(name: string): boolean

Параметры

Пример

db.collection({ name: 'books' });

db.hasCollection('books'); // true

db.hasCollection('authors'); // false

#removeCollection()

Удаляет определённую коллекцию. Она удаляется только из памяти; чтобы сохранить изменение, вам нужно вызвать метод sync.

Сигнатура

• removeCollection(name: string): void

Параметры

События

• 'beforeRemoveCollection': Срабатывает перед удалением коллекции.
• 'afterRemoveCollection': Срабатывает после удаления коллекции.

Пример

db.collection({ name: 'books' });

db.removeCollection('books');

#import()

Импортирует все файлы из директории как конфигурации коллекций в память.

Сигнатура

• async import(options: { directory: string; extensions?: ImportFileExtension[] }): Promise<Map<string, Collection>>

Параметры

Пример

Коллекция, определённая в файле ./collections/books.ts, выглядит следующим образом:

export default {
  name: 'books',
  fields: [
    {
      type: 'string',
      name: 'title',
    },
  ],
};

Импортируйте соответствующую конфигурацию при загрузке плагина:

class Plugin {
  async load() {
    await this.app.db.import({
      directory: path.resolve(__dirname, './collections'),
    });
  }
}

#Регистрация и получение расширений

#registerFieldTypes()

Регистрирует пользовательские типы полей.

Сигнатура

• registerFieldTypes(fieldTypes: MapOf<typeof Field>): void

Параметры

fieldTypes — это пара ключ-значение, где ключ — это имя типа поля, а значение — класс типа поля.

Пример

import { Field } from '@nocobase/database';

class MyField extends Field {
  // ...
}

db.registerFieldTypes({
  myField: MyField,
});

#registerModels()

Регистрирует пользовательские классы моделей данных.

Сигнатура

• registerModels(models: MapOf<ModelStatic<any>>): void

Параметры

models — это пара ключ-значение, где ключ — это имя модели, а значение — класс модели.

Пример

import { Model } from '@nocobase/database';

class MyModel extends Model {
  // ...
}

db.registerModels({
  myModel: MyModel,
});

db.collection({
  name: 'myCollection',
  model: 'myModel',
});

#registerRepositories()

Регистрирует пользовательские классы репозиториев.

Сигнатура

• registerRepositories(repositories: MapOf<RepositoryType>): void

Параметры

repositories — это пара ключ-значение, где ключ — это имя репозитория, а значение — класс репозитория.

Пример

import { Repository } from '@nocobase/database';

class MyRepository extends Repository {
  // ...
}

db.registerRepositories({
  myRepository: MyRepository,
});

db.collection({
  name: 'myCollection',
  repository: 'myRepository',
});

#registerOperators()

Регистрирует пользовательские операторы запросов данных.

Сигнатура

• registerOperators(operators: MapOf<OperatorFunc>)

Параметры

operators — это пара ключ-значение, где ключ — это имя оператора, а значение — функция, генерирующая оператор сравнения.

Пример

db.registerOperators({
  $dateOn(value) {
    return {
      [Op.and]: [
        { [Op.gte]: stringToDate(value) },
        { [Op.lt]: getNextDay(value) },
      ],
    };
  },
});

db.getRepository('books').count({
  filter: {
    createdAt: {
      // зарегистрированный оператор
      $dateOn: '2020-01-01',
    },
  },
});

#getModel()

Получает определённый класс модели данных. Если пользовательский класс модели ранее не был зарегистрирован, будет возвращён класс модели Sequelize по умолчанию. Имя по умолчанию совпадает с именем коллекции.

Сигнатура

• getModel(name: string): Model

Параметры

Пример

db.registerModels({
  books: class MyModel extends Model {},
});

const ModelClass = db.getModel('books');

console.log(ModelClass.prototype instanceof MyModel); // true

Примечание: Класс модели, полученный из коллекции, не строго равен зарегистрированному классу модели, но наследует от него. Поскольку свойства класса модели Sequelize изменяются в процессе инициализации, NocoBase автоматически обрабатывает это отношение наследования. За исключением неравенства классов, все остальные определения могут использоваться в обычном режиме.

#getRepository()

Получает пользовательский класс репозитория. Если пользовательский класс репозитория ранее не был зарегистрирован, будет возвращён класс репозитория NocoBase по умолчанию. Имя по умолчанию совпадает с именем коллекции.

Классы репозиториев в основном используются для CRUD-операций на основе моделей данных; см. Repository.

Сигнатура

• getRepository(name: string): Repository
• getRepository(name: string, relationId?: string | number): Repository

Параметры

Если имя представляет собой имя ассоциации, например 'tables.relations', будет возвращён связанный класс репозитория. Если предоставлен второй параметр, репозиторий будет использовать значение внешнего ключа связанных данных при выполнении операций (запрос, обновление и т. д.).

Пример

Предположим, есть две коллекции: posts и authors, и коллекция posts имеет внешний ключ, указывающий на коллекцию authors:

const AuthorsRepo = db.getRepository('authors');
const author1 = AuthorsRepo.create({ name: 'author1' });

const PostsRepo = db.getRepository('authors.posts', author1.id);
const post1 = AuthorsRepo.create({ title: 'post1' });
asset(post1.authorId === author1.id); // true

#События базы данных

#on()

Прослушивает события базы данных.

Сигнатура

• on(event: string, listener: (...args: any[]) => void | Promise<void>): void

Параметры

Имена событий по умолчанию поддерживают события модели Sequelize. Для глобальных событий используйте формат <sequelize_model_global_event>, а для событий одной модели — формат <model_name>.<sequelize_model_event>.

Описание параметров и подробные примеры всех встроенных типов событий см. в разделе Встроенные события.

#off()

Удаляет функцию обработчика события.

Сигнатура

• off(name: string, listener: Function)

Параметры

Пример

const listener = async (model, options) => {
  console.log(model);
};

db.on('afterCreate', listener);

db.off('afterCreate', listener);

#Операции с базой данных

#auth()

Аутентификация подключения к базе данных. Может использоваться для проверки установления соединения приложения с данными.

Сигнатура

• auth(options: QueryOptions & { retry?: number } = {}): Promise<boolean>

Параметры

Пример

await db.auth();

#reconnect()

Переподключается к базе данных.

Пример

await db.reconnect();

#closed()

Проверяет, закрыто ли соединение с базой данных.

Сигнатура

• closed(): boolean

#close()

Закрывает соединение с базой данных. Эквивалентно sequelize.close().

#sync()

Синхронизирует структуру коллекции базы данных. Эквивалентно sequelize.sync(); параметры см. в документации Sequelize.

#clean()

Очищает базу данных, удаляя все коллекции.

Сигнатура

• clean(options: CleanOptions): Promise<void>

Параметры

Пример

Удаляет все коллекции, кроме коллекции users.

await db.clean({
  drop: true,
  skip: ['users'],
});

#Экспорты на уровне пакета

#defineCollection()

Создаёт содержимое конфигурации для коллекции.

Сигнатура

• defineCollection(name: string, config: CollectionOptions): CollectionOptions

Параметры

Пример

Для файла конфигурации коллекции, который будет импортирован методом db.import():

import { defineCollection } from '@nocobase/database';

export default defineCollection({
  name: 'users',
  fields: [
    {
      type: 'string',
      name: 'name',
    },
  ],
});

#extendCollection()

Расширяет содержимое конфигурации коллекции, уже находящейся в памяти, в основном для содержимого файлов, импортированных методом import(). Этот метод является методом верхнего уровня, экспортируемым пакетом @nocobase/database, и не вызывается через экземпляр db. Также можно использовать псевдоним extend.

Сигнатура

• extendCollection(collectionOptions: CollectionOptions, mergeOptions?: MergeOptions): ExtendedCollectionOptions

Параметры

Пример

Исходное определение коллекции книг (books.ts):

export default {
  name: 'books',
  fields: [{ name: 'title', type: 'string' }],
};

Расширенное определение коллекции книг (books.extend.ts):

import { extend } from '@nocobase/database';

// расширить ещё раз
export default extend({
  name: 'books',
  fields: [{ name: 'price', type: 'number' }],
});

Если два вышеуказанных файла импортируются при вызове import(), то после повторного расширения с помощью extend() коллекция книг будет иметь поля title и price.

Этот метод очень полезен для расширения структур коллекций, уже определённых существующими плагинами.

#Встроенные события

База данных генерирует следующие соответствующие события на различных этапах своего жизненного цикла. Подписка на них с помощью метода on() позволяет выполнять специфическую обработку для удовлетворения определённых бизнес-потребностей.

#'beforeSync' / 'afterSync'

Срабатывает до и после синхронизации новой конфигурации структуры коллекции (полей, индексов и т. д.) с базой данных. Обычно это происходит при выполнении collection.sync() (внутренний вызов) и, как правило, используется для обработки логики специальных расширений полей.

Сигнатура

on(eventName: `${string}.beforeSync` | 'beforeSync' | `${string}.afterSync` | 'afterSync', listener: SyncListener): this

Тип

import type { SyncOptions, HookReturn } from 'sequelize/types';

type SyncListener = (options?: SyncOptions) => HookReturn;

Пример

const users = db.collection({
  name: 'users',
  fields: [{ type: 'string', name: 'username' }],
});

db.on('beforeSync', async (options) => {
  // выполнить что-либо
});

db.on('users.afterSync', async (options) => {
  // выполнить что-либо
});

await users.sync();

#'beforeValidate' / 'afterValidate'

Перед созданием или обновлением данных происходит процесс валидации на основе правил, определённых в коллекции. Соответствующие события срабатывают до и после валидации. Это происходит при вызове repository.create() или repository.update().

Сигнатура

on(eventName: `${string}.beforeValidate` | 'beforeValidate' | `${string}.afterValidate` | 'afterValidate', listener: ValidateListener): this

Тип

import type { ValidationOptions } from 'sequelize/types/lib/instance-validator';
import type { HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

type ValidateListener = (
  model: Model,
  options?: ValidationOptions,
) => HookReturn;

Пример

db.collection({
  name: 'tests',
  fields: [
    {
      type: 'string',
      name: 'email',
      validate: {
        isEmail: true,
      },
    },
  ],
});

// все модели
db.on('beforeValidate', async (model, options) => {
  // выполнить что-либо
});
// модель tests
db.on('tests.beforeValidate', async (model, options) => {
  // выполнить что-либо
});

// все модели
db.on('afterValidate', async (model, options) => {
  // выполнить что-либо
});
// модель tests
db.on('tests.afterValidate', async (model, options) => {
  // выполнить что-либо
});

const repository = db.getRepository('tests');
await repository.create({
  values: {
    email: 'abc', // проверяет формат email
  },
});
// или
await repository.update({
  filterByTk: 1,
  values: {
    email: 'abc', // проверяет формат email
  },
});

#'beforeCreate' / 'afterCreate'

Соответствующие события срабатывают до и после создания записи. Это происходит при вызове repository.create().

Сигнатура

on(eventName: `${string}.beforeCreate` | 'beforeCreate' | `${string}.afterCreate` | 'afterCreate', listener: CreateListener): this

Тип

import type { CreateOptions, HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

export type CreateListener = (
  model: Model,
  options?: CreateOptions,
) => HookReturn;

Пример

db.on('beforeCreate', async (model, options) => {
  // выполнить что-либо
});

db.on('books.afterCreate', async (model, options) => {
  const { transaction } = options;
  const result = await model.constructor.findByPk(model.id, {
    transaction,
  });
  console.log(result);
});

#'beforeUpdate' / 'afterUpdate'

Соответствующие события срабатывают до и после обновления записи. Это происходит при вызове repository.update().

Сигнатура

on(eventName: `${string}.beforeUpdate` | 'beforeUpdate' | `${string}.afterUpdate` | 'afterUpdate', listener: UpdateListener): this

Тип

import type { UpdateOptions, HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

export type UpdateListener = (
  model: Model,
  options?: UpdateOptions,
) => HookReturn;

Пример

db.on('beforeUpdate', async (model, options) => {
  // выполнить что-либо
});

db.on('books.afterUpdate', async (model, options) => {
  // выполнить что-либо
});

#'beforeSave' / 'afterSave'

Соответствующие события срабатывают до и после создания или обновления записи. Это происходит при вызове repository.create() или repository.update().

Сигнатура

on(eventName: `${string}.beforeSave` | 'beforeSave' | `${string}.afterSave` | 'afterSave', listener: SaveListener): this

Тип

import type { SaveOptions, HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

export type SaveListener = (model: Model, options?: SaveOptions) => HookReturn;

Пример

db.on('beforeSave', async (model, options) => {
  // выполнить что-либо
});

db.on('books.afterSave', async (model, options) => {
  // выполнить что-либо
});

#'beforeDestroy' / 'afterDestroy'

Соответствующие события срабатывают до и после удаления записи. Это происходит при вызове repository.destroy().

Сигнатура

on(eventName: `${string}.beforeDestroy` | 'beforeDestroy' | `${string}.afterDestroy` | 'afterDestroy', listener: DestroyListener): this

Тип

import type { DestroyOptions, HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

export type DestroyListener = (
  model: Model,
  options?: DestroyOptions,
) => HookReturn;

Пример

db.on('beforeDestroy', async (model, options) => {
  // выполнить что-либо
});

db.on('books.afterDestroy', async (model, options) => {
  // выполнить что-либо
});

#'afterCreateWithAssociations'

Это событие срабатывает после создания записи с иерархическими связанными данными. Оно происходит при вызове repository.create().

Сигнатура

on(eventName: `${string}.afterCreateWithAssociations` | 'afterCreateWithAssociations', listener: CreateWithAssociationsListener): this

Тип

import type { CreateOptions, HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

export type CreateWithAssociationsListener = (
  model: Model,
  options?: CreateOptions,
) => HookReturn;

Пример

db.on('afterCreateWithAssociations', async (model, options) => {
  // выполнить что-либо
});

db.on('books.afterCreateWithAssociations', async (model, options) => {
  // выполнить что-либо
});

#'afterUpdateWithAssociations'

Это событие срабатывает после обновления записи с иерархическими связанными данными. Оно происходит при вызове repository.update().

Сигнатура

on(eventName: `${string}.afterUpdateWithAssociations` | 'afterUpdateWithAssociations', listener: CreateWithAssociationsListener): this

Тип

import type { UpdateOptions, HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

export type UpdateWithAssociationsListener = (
  model: Model,
  options?: UpdateOptions,
) => HookReturn;

Пример

db.on('afterUpdateWithAssociations', async (model, options) => {
  // выполнить что-либо
});

db.on('books.afterUpdateWithAssociations', async (model, options) => {
  // выполнить что-либо
});

#'afterSaveWithAssociations'

Это событие срабатывает после создания или обновления записи с иерархическими связанными данными. Оно происходит при вызове repository.create() или repository.update().

Сигнатура

on(eventName: `${string}.afterSaveWithAssociations` | 'afterSaveWithAssociations', listener: SaveWithAssociationsListener): this

Тип

import type { SaveOptions, HookReturn } from 'sequelize/types';
import type { Model } from '@nocobase/database';

export type SaveWithAssociationsListener = (
  model: Model,
  options?: SaveOptions,
) => HookReturn;

Пример

db.on('afterSaveWithAssociations', async (model, options) => {
  // выполнить что-либо
});

db.on('books.afterSaveWithAssociations', async (model, options) => {
  // выполнить что-либо
});

#'beforeDefineCollection'

Срабатывает перед определением коллекции, например, при вызове db.collection().

Примечание: Это синхронное событие.

Сигнатура

on(eventName: 'beforeDefineCollection', listener: BeforeDefineCollectionListener): this

Тип

import type { CollectionOptions } from '@nocobase/database';

export type BeforeDefineCollectionListener = (
  options: CollectionOptions,
) => void;

Пример

db.on('beforeDefineCollection', (options) => {
  // выполнить что-либо
});

#'afterDefineCollection'

Срабатывает после определения коллекции, например, при вызове db.collection().

Примечание: Это синхронное событие.

Сигнатура

on(eventName: 'afterDefineCollection', listener: AfterDefineCollectionListener): this

Тип

import type { Collection } from '@nocobase/database';

export type AfterDefineCollectionListener = (options: Collection) => void;

Пример

db.on('afterDefineCollection', (collection) => {
  // выполнить что-либо
});

#'beforeRemoveCollection' / 'afterRemoveCollection'

Срабатывает до и после удаления коллекции из памяти, например, при вызове db.removeCollection().

Примечание: Это синхронное событие.

Сигнатура

on(eventName: 'beforeRemoveCollection' | 'afterRemoveCollection', listener: RemoveCollectionListener): this

Тип

import type { Collection } from '@nocobase/database';

export type RemoveCollectionListener = (options: Collection) => void;

Пример

db.on('beforeRemoveCollection', (collection) => {
  // выполнить что-либо
});

db.on('afterRemoveCollection', (collection) => {
  // выполнить что-либо
});