API EntityManager

Неофициальный Бета-перевод

Эта страница переведена PageTurner AI (бета). Не одобрена официально проектом. Нашли ошибку? Сообщить о проблеме →

• dataSource - Источник данных, используемый EntityManager.

const dataSource = manager.dataSource

• queryRunner - Построитель запросов, используемый EntityManager. Применяется только в транзакционных экземплярах EntityManager.

const queryRunner = manager.queryRunner

• transaction - Предоставляет транзакцию, в рамках которой несколько запросов к базе данных выполняются как единое целое. Подробнее о Транзакциях.

await manager.transaction(async (manager) => {
    // NOTE: you must perform all database operations using the given manager instance
    // it's a special instance of EntityManager working with this transaction
    // and don't forget to await things here
})

• query - Выполняет сырой SQL-запрос.

const rawData = await manager.query(`SELECT * FROM USERS`)

// You can also use parameters to avoid SQL injection
// The syntax differs between the drivers

// aurora-mysql, better-sqlite3, capacitor, cordova,
// expo, mariadb, mysql, nativescript, react-native,
// sap, sqlite, sqljs
const rawData = await manager.query(
    "SELECT * FROM USERS WHERE name = ? and age = ?",
    ["John", 24],
)

// aurora-postgres, cockroachdb, postgres
const rawData = await manager.query(
    "SELECT * FROM USERS WHERE name = $1 and age = $2",
    ["John", 24],
)

// oracle
const rawData = await manager.query(
    "SELECT * FROM USERS WHERE name = :1 and age = :2",
    ["John", 24],
)

// spanner
const rawData = await manager.query(
    "SELECT * FROM USERS WHERE name = @param0 and age = @param1",
    ["John", 24],
)

// mssql
const rawData = await manager.query(
    "SELECT * FROM USERS WHERE name = @0 and age = @1",
    ["John", 24],
)

• sql - Выполняет сырой SQL-запрос с использованием шаблонных литералов.

const rawData =
    await manager.sql`SELECT * FROM USERS WHERE name = ${"John"} and age = ${24}`

Подробнее об использовании синтаксиса SQL-тегов.

• createQueryBuilder - Создает построитель запросов для формирования SQL-запросов. Подробнее о QueryBuilder.

const users = await manager
    .createQueryBuilder()
    .select()
    .from(User, "user")
    .where("user.name = :name", { name: "John" })
    .getMany()

• hasId - Проверяет, определён ли первичный столбец у указанной сущности.

if (manager.hasId(user)) {
    // ... do something
}

• getId - Получает значение первичного столбца указанной сущности. Для сущностей с составными первичными ключами возвращается объект с именами и значениями первичных столбцов.

const userId = manager.getId(user) // userId === 1

• create - Создает новый экземпляр сущности (например, User). Может принимать объект со свойствами, которые будут записаны в создаваемый объект.

const user = manager.create(User) // same as const user = new User();
const user = manager.create(User, {
    id: 1,
    firstName: "Timber",
    lastName: "Saw",
}) // same as const user = new User(); user.firstName = "Timber"; user.lastName = "Saw";

• merge - Объединяет несколько сущностей в одну.

const user = new User()
manager.merge(User, user, { firstName: "Timber" }, { lastName: "Saw" }) // same as user.firstName = "Timber"; user.lastName = "Saw";

• preload - Создает новую сущность из обычного javascript-объекта. Если сущность уже существует в базе, она загружается (вместе со связанными данными), все значения заменяются новыми из переданного объекта, и возвращается обновлённая сущность. Фактически, новая сущность загружается из базы с заменой всех свойств.

const partialUser = {
    id: 1,
    firstName: "Rizzrak",
    profile: {
        id: 1,
    },
}
const user = await manager.preload(User, partialUser)
// user will contain all missing data from partialUser with partialUser property values:
// { id: 1, firstName: "Rizzrak", lastName: "Saw", profile: { id: 1, ... } }

• save - Сохраняет указанную сущность или массив сущностей. Если сущность уже существует в базе, она обновляется. Если сущности нет в базе, она добавляется. Все сущности сохраняются в одной транзакции (если менеджер сущностей не транзакционный). Поддерживает частичное обновление: неопределённые свойства пропускаются. Для установки NULL явно укажите значение null.

await manager.save(user)
await manager.save([category1, category2, category3])

• remove - Удаляет указанную сущность или массив сущностей. Все сущности удаляются в одной транзакции (если менеджер сущностей не транзакционный).

await manager.remove(user)
await manager.remove([category1, category2, category3])

• insert - Добавляет новую сущность или массив сущностей.

await manager.insert(User, {
    firstName: "Timber",
    lastName: "Timber",
})

await manager.insert(User, [
    {
        firstName: "Foo",
        lastName: "Bar",
    },
    {
        firstName: "Rizz",
        lastName: "Rak",
    },
])

• update - Обновляет сущности по их id, массиву id или условиям. Устанавливает поля из частичного объекта сущности.

await manager.update(User, { age: 18 }, { category: "ADULT" })
// executes UPDATE user SET category = ADULT WHERE age = 18

await manager.update(User, 1, { firstName: "Rizzrak" })
// executes UPDATE user SET firstName = Rizzrak WHERE id = 1

• updateAll - Обновляет все сущности указанного типа (без условия WHERE). Устанавливает поля из частичного объекта сущности.

await manager.updateAll(User, { category: "ADULT" })
// executes UPDATE user SET category = ADULT

• upsert - Добавляет новую сущность или массив сущностей, если они не существуют, либо обновляет существующие. Поддерживается в AuroraDataApi, Cockroach, Mysql, Postgres и Sqlite.

При обновлении во время upsert-операции (из-за конфликта) специальные колонки вроде @UpdateDateColumn и @VersionColumn автоматически обновляются.

await manager.upsert(
    User,
    [
        { externalId: "abc123", firstName: "Rizzrak" },
        { externalId: "bca321", firstName: "Karzzir" },
    ],
    ["externalId"],
)
/** executes
 *  INSERT INTO user
 *  VALUES
 *      (externalId = abc123, firstName = Rizzrak),
 *      (externalId = cba321, firstName = Karzzir),
 *  ON CONFLICT (externalId) DO UPDATE firstName = EXCLUDED.firstName
 **/

• delete - Удаляет сущности по их id, массиву id или условиям.

await manager.delete(User, 1)
await manager.delete(User, [1, 2, 3])
await manager.delete(User, { firstName: "Timber" })

• deleteAll - Удаляет все сущности указанного типа (без условия WHERE).

await manager.deleteAll(User)
// executes DELETE FROM user

См. также метод clear, который выполняет операцию TRUNCATE TABLE.

• increment - Увеличивает значение столбца на указанную величину для сущностей, соответствующих условиям.

await manager.increment(User, { firstName: "Timber" }, "age", 3)

• decrement - Уменьшает значение столбца на указанную величину для сущностей, соответствующих условиям.

await manager.decrement(User, { firstName: "Timber" }, "age", 3)

• exists - Проверяет существование хотя бы одной сущности, соответствующей FindOptions.

const exists = await manager.exists(User, {
    where: {
        firstName: "Timber",
    },
})

• existsBy - Проверяет существование хотя бы одной сущности, соответствующей FindOptionsWhere.

const exists = await manager.existsBy(User, { firstName: "Timber" })

• count - Считает сущности, соответствующие FindOptions. Полезно для пагинации.

const count = await manager.count(User, {
    where: {
        firstName: "Timber",
    },
})

• countBy - Считает сущности, соответствующие FindOptionsWhere. Полезно для пагинации.

const count = await manager.countBy(User, { firstName: "Timber" })

• find - Находит сущности, соответствующие FindOptions.

const timbers = await manager.find(User, {
    where: {
        firstName: "Timber",
    },
})

• findBy - Находит сущности, соответствующие FindWhereOptions.

const timbers = await manager.findBy(User, {
    firstName: "Timber",
})

• findAndCount - Находит сущности, соответствующие FindOptions. Дополнительно подсчитывает все подходящие сущности, игнорируя настройки пагинации (параметры from и take).

const [timbers, timbersCount] = await manager.findAndCount(User, {
    where: {
        firstName: "Timber",
    },
})

• findAndCountBy - Находит сущности, соответствующие заданным FindOptionsWhere. Также подсчитывает все подходящие сущности, игнорируя параметры пагинации (from и take).

const [timbers, timbersCount] = await manager.findAndCountBy(User, {
    firstName: "Timber",
})

• findOne - Находит первую сущность, соответствующую заданным FindOptions.

const timber = await manager.findOne(User, {
    where: {
        firstName: "Timber",
    },
})

• findOneBy - Находит первую сущность, соответствующую заданным FindOptionsWhere.

const timber = await manager.findOneBy(User, { firstName: "Timber" })

• findOneOrFail - Находит первую сущность по ID или условиям поиска. Отклоняет промис, если совпадений не найдено.

const timber = await manager.findOneOrFail(User, {
    where: {
        firstName: "Timber",
    },
})

• findOneByOrFail - Находит первую сущность, соответствующую заданным FindOptions. Отклоняет промис, если совпадений не найдено.

const timber = await manager.findOneByOrFail(User, { firstName: "Timber" })

• clear - Очищает все данные из указанной таблицы (выполняет TRUNCATE/DROP).

await manager.clear(User)

• getRepository - Получает Repository для работы с конкретной сущностью. Подробнее: Репозитории.

const userRepository = manager.getRepository(User)

• getTreeRepository - Получает TreeRepository для работы с иерархическими сущностями. Подробнее: Репозитории.

const categoryRepository = manager.getTreeRepository(Category)

• getMongoRepository - Получает MongoRepository для работы с MongoDB. Подробнее: MongoDB.

const userRepository = manager.getMongoRepository(User)

• withRepository - Получает кастомный репозиторий в транзакционном контексте. Подробнее: Кастомные репозитории.

const myUserRepository = manager.withRepository(UserRepository)

• release - Освобождает query runner менеджера сущностей. Используется только при ручном управлении query runner.

await manager.release()