`EntityManager` API

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。发现错误？报告问题 →

dataSource - EntityManager 使用的 DataSource。

const dataSource = manager.dataSource

queryRunner - EntityManager 使用的查询运行器（Query Runner）。仅在事务型 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 查询的查询构建器（Query Builder）。了解更多关于查询构建器的信息。

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

另请参考执行数据库 TRUNCATE TABLE 操作的 clear 方法。

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 或查询选项匹配的第一个实体。如果未找到匹配项，则拒绝返回的 Promise。

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

findOneByOrFail - 查找与给定 FindOptions 匹配的第一个实体。如果未找到匹配项，则拒绝返回的 Promise。

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

clear - 清除给定表中的所有数据（执行 TRUNCATE TABLE 或 DROP TABLE 操作）。

await manager.clear(User)

getRepository - 获取用于对特定实体执行操作的 Repository。了解更多关于存储库的信息。

const userRepository = manager.getRepository(User)

getTreeRepository - 获取用于对特定实体执行操作的 TreeRepository。了解更多关于存储库的信息。

const categoryRepository = manager.getTreeRepository(Category)

getMongoRepository - 获取用于对特定实体执行操作的 MongoRepository。了解更多关于 MongoDB 的信息。

const userRepository = manager.getMongoRepository(User)

withRepository - 获取在事务中使用的自定义存储库实例。了解更多关于自定义存储库的信息。

const myUserRepository = manager.withRepository(UserRepository)

release - 释放实体管理器的查询运行器。仅在手动创建和管理查询运行器时使用。

await manager.release()