index

​​
​

​
 ​​
 ​​
 ​​
​


TypeORM 是一个ORM框架，它可以运行在 NodeJS、Browser、Cordova、PhoneGap、Ionic、React Native、Expo 和 Electron 平台上，可以与 TypeScript 和 JavaScript (ES5,ES6,ES7,ES8)一起使用。 它的目标是始终支持最新的 JavaScript 特性并提供额外的特性以帮助你开发任何使用数据库的（不管是只有几张表的小型应用还是拥有多数据库的大型企业应用）应用程序。
不同于现有的所有其他 JavaScript ORM 框架，TypeORM 支持 Active Record 和 Data Mapper 模式，这意味着你可以以最高效的方式编写高质量的、松耦合的、可扩展的、可维护的应用程序。
TypeORM 参考了很多其他优秀 ORM 的实现, 比如 Hibernate, Doctrine 和 Entity Framework。
TypeORM 的一些特性:
支持 DataMapper 和 ActiveRecord (随你选择)
实体和列
数据库特性列类型
实体管理
存储库和自定义存储库
清晰的对象关系模型
关联（关系）
贪婪和延迟关系
单向的，双向的和自引用的关系
支持多重继承模式
级联
索引
事务
迁移和自动迁移
连接池
主从复制
使用多个数据库连接
使用多个数据库类型
跨数据库和跨模式查询
优雅的语法，灵活而强大的 QueryBuilder
左联接和内联接
使用联查查询的适当分页
查询缓存
原始结果流
日志
监听者和订阅者（钩子）
支持闭包表模式
在模型或者分离的配置文件中声明模式
支持 MySQL / MariaDB / Postgres / SQLite / Microsoft SQL Server / Oracle / sql.js
支持 MongoDB NoSQL 数据库
可在 NodeJS / 浏览器 / Ionic / Cordova / React Native / Expo / Electron 平台上使用
支持 TypeScript 和 JavaScript
生成高性能、灵活、清晰和可维护的代码
遵循所有可能的最佳实践
命令行工具
还有更多...
通过使用 TypeORM 你的 models 看起来像这样:
import { Entity, PrimaryGeneratedColumn, Column } from "typeorm"
​
@Entity()
export class User {
    @PrimaryGeneratedColumn()
    id: number
​
    @Column()
    firstName: string
​
    @Column()
    lastName: string
​
    @Column()
    age: number
}
逻辑操作就像是这样:
const user = new User()
user.firstName = "Timber"
user.lastName = "Saw"
user.age = 25
await repository.save(user)
​
const allUsers = await repository.find()
const firstUser = await repository.findOne(1) // find by id
const timber = await repository.findOne({
    firstName: "Timber",
    lastName: "Saw",
})
​
await repository.remove(timber)
或者，如果你更喜欢使用ActiveRecord实现，也可以这样用：
import { Entity, PrimaryGeneratedColumn, Column, BaseEntity } from "typeorm"
​
@Entity()
export class User extends BaseEntity {
    @PrimaryGeneratedColumn()
    id: number
​
    @Column()
    firstName: string
​
    @Column()
    lastName: string
​
    @Column()
    age: number
}
逻辑操作如下所示:
const user = new User()
user.firstName = "Timber"
user.lastName = "Saw"
user.age = 25
await user.save()
​
const allUsers = await User.find()
const firstUser = await User.findOne(1)
const timber = await User.findOne({ firstName: "Timber", lastName: "Saw" })
​
await timber.remove()
入门
安装
1.通过npm安装:
npm install typeorm --save
2.你还需要安装 reflect-metadata:
npm install reflect-metadata --save
并且需要在应用程序的全局位置导入（例如在app.ts中）
import "reflect-metadata";
3.你可能还需要安装 node typings(以此来使用 Node 的智能提示):
npm install @types/node --save
4.安装数据库驱动:
MySQL 或者 MariaDB
npm install mysql --save (也可以安装 mysql2)
PostgreSQL
npm install pg --save
SQLite
npm install sqlite3 --save
Microsoft SQL Server
npm install mssql --save
sql.js
npm install sql.js --save
Oracle
npm install oracledb --save
根据你使用的数据库，仅安装其中一个即可。 要使 Oracle 驱动程序正常工作，需要按照其站点中的安装说明进行操作。
MongoDB (试验性)
npm install mongodb --save
NativeScript, react-native 和 Cordova
查看 支持的平台​
TypeScript 配置
此外，请确保你使用的是 TypeScript 编译器版本2.3或更高版本，并且已经在tsconfig.json中启用了以下设置:
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
你可能还需要在编译器选项的lib中启用es6，或者从@types安装es6-shim。
快速开始
开始使用 TypeORM 的最快方法是使用其 CLI 命令生成启动项目。 只有在 NodeJS 应用程序中使用 TypeORM 时，此操作才有效。如果你使用的是其他平台，请继续执行分步指南。
首先全局安装 TypeORM:
npm install typeorm -g
然后转到要创建新项目的目录并运行命令：
typeorm init --name MyProject --database mysql
其中name是项目的名称，database是您将使用的数据库。
数据库可以是以下值之一: mysql, mariadb, postgres, sqlite, mssql, oracle, mongodb, cordova, react-native, expo, nativescript.
此命令将在MyProject目录中生成一个包含以下文件的新项目:
MyProject
├── src              // TypeScript 代码
│   ├── entity       // 存储实体（数据库模型）的位置
│   │   └── User.ts  // 示例 entity
│   ├── migration    // 存储迁移的目录
│   └── index.ts     // 程序执行主文件
├── .gitignore       // gitignore文件
├── ormconfig.json   // ORM和数据库连接配置
├── package.json     // node module 依赖
├── README.md        // 简单的 readme 文件
└── tsconfig.json    // TypeScript 编译选项
你还可以在现有 node 项目上运行typeorm init，但要注意，此操作可能会覆盖已有的某些文件。
接下来安装项目依赖项：
cd MyProject
npm install
在安装过程中，编辑ormconfig.json文件并在其中放置您自己的数据库连接配置选项：
{
    "type": "mysql",
    "host": "localhost",
    "port": 3306,
    "username": "test",
    "password": "test",
    "database": "test",
    "synchronize": true,
    "logging": false,
    "entities": ["src/entity/**/*.ts"],
    "migrations": ["src/migration/**/*.ts"],
    "subscribers": ["src/subscriber/**/*.ts"]
}
绝大多数情况下，你只需要配置 host, username, password, database 或者 port。
完成配置并安装所有 node modules 后，即可运行应用程序：
npm start
至此你的应用程序应该成功运行并将新用户插入数据库。你可以继续使用此项目并集成所需的其他模块并创建更多实体。
你可以通过运行typeorm init --name MyProject --database mysql --express来生成一个更高级的 Express 项目
分步指南
您对 ORM 有何期待？您期望它将为您创建数据库表，并且无需编写大量难以维护的 SQL 语句来查找/插入/更新/删除您的数据。本指南将向您展示如何从头开始设置 TypeORM 并实现这些操作。
创建一个模型
使用数据库从创建表开始。如何告诉 TypeORM 创建数据库表？答案是 - 通过模型。 应用程序中的模型即是数据库中的表。
举个例子, 你有一个Photo 模型:
export class Photo {
    id: number
    name: string
    description: string
    filename: string
    views: number
}
并且希望将 photos 存储在数据库中。要在数据库中存储内容，首先需要一个数据库表，并从模型中创建数据库表。但是并非所有模型，只有您定义为entities的模型。
创建一个实体
Entity是由@Entity装饰器装饰的模型。将为此类模型创建数据库表。你可以使用 TypeORM 处理各处的实体，可以使用它们 load/insert/update/remove 并执行其他操作。
让我们将Photo模型作为一个实体
import { Entity } from "typeorm"
​
@Entity()
export class Photo {
    id: number
    name: string
    description: string
    filename: string
    views: number
    isPublished: boolean
}
现在，将为Photo实体创建一个数据库表，我们将能够在应用程序中的任何位置使用它。 我们已经创建了一个数据库表，但是没有哪个字段属于哪一列，下面让我们在数据库表中创建几列。
添加表列
要添加数据库列，你只需要将要生成的实体属性加上@Column装饰器。
import { Entity, Column } from "typeorm"
​
@Entity()
export class Photo {
    @Column()
    id: number
​
    @Column()
    name: string
​
    @Column()
    description: string
​
    @Column()
    filename: string
​
    @Column()
    views: number
​
    @Column()
    isPublished: boolean
}
现在 id, name, description, filename, views 和 isPublished 列将会被添加到photo表中。 数据库中的列类型是根据你使用的属性类型推断的，例如： number将被转换为integer，string将转换为varchar，boolean转换为bool等。但你也可以通过在@Column装饰器中隐式指定列类型来使用数据库支持的任何列类型。
我们已经生成了一个包含列的数据库表，但还剩下一件事。每个数据库表必须具有包含主键的列。
创建主列
每个实体必须至少有一个主键列。这是必须的，你无法避免。要使列成为主键，您需要使用@PrimaryColumn装饰器。
import { Entity, Column, PrimaryColumn } from "typeorm"
​
@Entity()
export class Photo {
    @PrimaryColumn()
    id: number
​
    @Column()
    name: string
​
    @Column()
    description: string
​
    @Column()
    filename: string
​
    @Column()
    views: number
​
    @Column()
    isPublished: boolean
}
创建自动生成的列
假设你希望 id 列自动生成（这称为 auto-increment/sequence/serial/generated identity column）。为此你需要将@PrimaryColumn装饰器更改为@PrimaryGeneratedColumn装饰器：
import { Entity, Column, PrimaryGeneratedColumn } from "typeorm"
​
@Entity()
export class Photo {
    @PrimaryGeneratedColumn()
    id: number
​
    @Column()
    name: string
​
    @Column()
    description: string
​
    @Column()
    filename: string
​
    @Column()
    views: number
​
    @Column()
    isPublished: boolean
}
列数据类型
接下来，让我们修复数据类型。默认情况下，字符串被映射到一个 varchar(255)类型（取决于数据库类型）。 数字被映射到一个类似整数类型（取决于数据库类型）。但是我们不希望所有的列都是有限的 varchars 或整数，让我们修改下代码以设置想要的数据类型：
import { Entity, Column, PrimaryGeneratedColumn } from "typeorm"
​
@Entity()
export class Photo {
    @PrimaryGeneratedColumn()
    id: number
​
    @Column({
        length: 100,
    })
    name: string
​
    @Column("text")
    description: string
​
    @Column()
    filename: string
​
    @Column("double")
    views: number
​
    @Column()
    isPublished: boolean
}
列类型是特定于数据库的。你可以设置数据库支持的任何列类型。有关支持的列类型的更多信息，请参见此处。
创建数据库的连接
当实体被创建后，让我们创建一个index.ts（或app.ts，无论你怎么命名）文件，并配置数据库连接：:
import "reflect-metadata"
import { createConnection } from "typeorm"
import { Photo } from "./entity/Photo"
​
createConnection({
    type: "mysql",
    host: "localhost",
    port: 3306,
    username: "root",
    password: "admin",
    database: "test",
    entities: [Photo],
    synchronize: true,
    logging: false,
})
    .then((connection) => {
        // 这里可以写实体操作相关的代码
    })
    .catch((error) => console.log(error))
我们在此示例中使用 MySQL，你可以使用任何其他受支持的数据库。要使用其他数据库，只需将选项中的type更改为希望使用的数据库类型：mysql，mariadb，postgres，sqlite，mssql，oracle，cordova，nativescript，react-native，expo 或 mongodb。同时还要确保 host, port, username, password 和数据库设置的正确性。
我们将 Photo 实体添加到此连接的实体列表中。所有需要在连接中使用的每个实体都必须加到这个表中。
设置synchronize可确保每次运行应用程序时实体都将与数据库同步。
加载目录中所有实体
之后当我们创建更多实体时，都需要将一一它们添加到配置中的实体中，但是这不是很方便，所以我们可以设置整个目录，从中连接所有实体并在连接中使用：
import { createConnection } from "typeorm"
​
createConnection({
    type: "mysql",
    host: "localhost",
    port: 3306,
    username: "root",
    password: "admin",
    database: "test",
    entities: [__dirname + "/entity/*.js"],
    synchronize: true,
})
    .then((connection) => {
        // 这里可以写实体操作相关的代码
    })
    .catch((error) => console.log(error))
但要小心这种方法。 如果使用的是ts-node，则需要指定.ts文件的路径。 如果使用的是outDir，那么需要在outDir目录中指定.js文件的路径。 如果使用outDir，当你删除或重命名实体时，请确保清除outDir目录并再次重新编译项目，因为当你删除.ts源文件时，其编译的.js版本不会从输出目录中删除,并且 TypeORM 依然会从outDir中加载这些文件，从而导致异常。
启动应用
现在可以启动app.ts，启动后可以发现数据库自动被初始化，并且 Photo 这个表也会创建出来。
+-------------+--------------+----------------------------+
|                         photo                           |
+-------------+--------------+----------------------------+
| id          | int(11)      | PRIMARY KEY AUTO_INCREMENT |
| name        | varchar(500) |                            |
| description | text         |                            |
| filename    | varchar(255) |                            |
| views       | int(11)      |                            |
| isPublished | boolean      |                            |
+-------------+--------------+----------------------------+
添加和插入 photo
现在创建一个新的 photo 存到数据库：
import { createConnection } from "typeorm"
import { Photo } from "./entity/Photo"
​
createConnection(/*...*/)
    .then((connection) => {
        let photo = new Photo()
        photo.name = "Me and Bears"
        photo.description = "I am near polar bears"
        photo.filename = "photo-with-bears.jpg"
        photo.views = 1
        photo.isPublished = true
​
        return connection.manager.save(photo).then((photo) => {
            console.log("Photo has been saved. Photo id is", photo.id)
        })
    })
    .catch((error) => console.log(error))
保存实体后，它将获得新生成的 ID。 save方法返回传递给它的同一对象的实例。但它不是对象的新副本，只是修改了它的"id"并返回它。
使用 async/await 语法
我们可以使用最新的 ES8（ES2017）功能，并使用 async / await 语法代替：
import { createConnection } from "typeorm"
import { Photo } from "./entity/Photo"
​
createConnection(/*...*/)
    .then(async (connection) => {
        let photo = new Photo()
        photo.name = "Me and Bears"
        photo.description = "I am near polar bears"
        photo.filename = "photo-with-bears.jpg"
        photo.views = 1
        photo.isPublished = true
​
        await connection.manager.save(photo)
        console.log("Photo has been saved")
    })
    .catch((error) => console.log(error))
使用 Entity Manager
我们刚创建了一张新 photo 并将其保存在数据库中。使用EntityManager你可以操纵应用中的任何实体。
例如，加载已经保存的实体：
import { createConnection } from "typeorm"
import { Photo } from "./entity/Photo"
​
createConnection(/*...*/)
    .then(async (connection) => {
        /*...*/
        let savedPhotos = await connection.manager.find(Photo)
        console.log("All photos from the db: ", savedPhotos)
    })
    .catch((error) => console.log(error))
savedPhotos是一个 Photo 对象数组，其中包含从数据库加载的数据。
了解更多有关 EntityManager 的信息。
使用 Repositories
现在让我们重构之前的代码，并使用Repository而不是EntityManager。每个实体都有自己的存储库，可以处理其实体的所有操作。当你经常处理实体时，Repositories 比 EntityManagers 更方便使用：
import { createConnection } from "typeorm"
import { Photo } from "./entity/Photo"
​
createConnection(/*...*/)
    .then(async (connection) => {
        let photo = new Photo()
        photo.name = "Me and Bears"
        photo.description = "I am near polar bears"
        photo.filename = "photo-with-bears.jpg"
        photo.views = 1
        photo.isPublished = true
​
        let photoRepository = connection.getRepository(Photo)
​
        await photoRepository.save(photo)
        console.log("Photo has been saved")
​
        let savedPhotos = await photoRepository.find()
        console.log("All photos from the db: ", savedPhotos)
    })
    .catch((error) => console.log(error))
了解更多有关 Repository 的信息。
从数据库加载
让我们使用 Repository 尝试更多的加载操作:
import { createConnection } from "typeorm"
import { Photo } from "./entity/Photo"
​
createConnection(/*...*/)
    .then(async (connection) => {
        /*...*/
        let allPhotos = await photoRepository.find()
        console.log("All photos from the db: ", allPhotos)
​
        let firstPhoto = await photoRepository.findOne(1)
        console.log("First photo from the db: ", firstPhoto)
​
        let meAndBearsPhoto = await photoRepository.findOne({
            name: "Me and Bears",
        })
        console.log("Me and Bears photo from the db: ", meAndBearsPhoto)
​
        let allViewedPhotos = await photoRepository.find({ views: 1 })
        console.log("All viewed photos: ", allViewedPhotos)
​
        let allPublishedPhotos = await photoRepository.find({
            isPublished: true,
        })
        console.log("All published photos: ", allPublishedPhotos)
​
        let [allPhotos, photosCount] = await photoRepository.findAndCount()
        console.log("All photos: ", allPhotos)
        console.log("Photos count: ", photosCount)
    })
    .catch((error) => console.log(error))
在数据库中更新
让我们从数据库加载出 photo，更新并保存到数据库：
import { createConnection } from "typeorm"
import { Photo } from "./entity/Photo"
​
createConnection(/*...*/)
    .then(async (connection) => {
        /*...*/
        let photoToUpdate = await photoRepository.findOne(1)
        photoToUpdate.name = "Me, my friends and polar bears"
        await photoRepository.save(photoToUpdate)
    })
    .catch((error) => console.log(error))
这个id = 1的 photo 在数据库中就成功更新了。
从数据库中删除
让我们从数据库中删除我们的 Photo:
import { createConnection } from "typeorm"
import { Photo } from "./entity/Photo"
​
createConnection(/*...*/)
    .then(async (connection) => {
        /*...*/
        let photoToRemove = await photoRepository.findOne(1)
        await photoRepository.remove(photoToRemove)
    })
    .catch((error) => console.log(error))
这个id = 1的 photo 在数据库中被移除了。
创建一对一的关系
让我们与另一个类创建一对一的关系。先在PhotoMetadata.ts中创建一个新类。此 PhotoMetadata 类应包含 photo 的其他元信息：
import {
    Entity,
    Column,
    PrimaryGeneratedColumn,
    OneToOne,
    JoinColumn,
} from "typeorm"
import { Photo } from "./Photo"
​
@Entity()
export class PhotoMetadata {
    @PrimaryGeneratedColumn()
    id: number
​
    @Column("int")
    height: number
​
    @Column("int")
    width: number
​
    @Column()
    orientation: string
​
    @Column()
    compressed: boolean
​
    @Column()
    comment: string
​
    @OneToOne((type) => Photo)
    @JoinColumn()
    photo: Photo
}
这里我们使用了一个名为@OneToOne的新装饰器,它允许我们在两个实体之间创建一对一的关系。 type => Photo是一个函数，返回我们想要与之建立关系的实体的类。由于特定于语言的关系，我们只能使用一个返回类的函数，而不是直接使用该类。 同时也可以把它写成()=> Photo，但是type => Photo显得代码更有可读性。type 变量本身不包含任何内容。
我们还添加了一个@JoinColumn装饰器，表明实体键的对应关系。关系可以是单向的或双向的。但是只有一方是拥有者。在关系的所有者方面需要使用@JoinColumn 装饰器。
如果运行该应用程序，你将看到一个新生成的表，它将包含一个带有关系外键的列：
+-------------+--------------+----------------------------+
|                     photo_metadata                      |
+-------------+--------------+----------------------------+
| id          | int(11)      | PRIMARY KEY AUTO_INCREMENT |
| height      | int(11)      |                            |
| width       | int(11)      |                            |
| comment     | varchar(255) |                            |
| compressed  | boolean      |                            |
| orientation | varchar(255) |                            |
| photoId     | int(11)      | FOREIGN KEY                |
+-------------+--------------+----------------------------+
保存一对一的关系
现在来创建一个 photo，它的元信息将它们互相连接起来。
import { createConnection } from "typeorm"
import { Photo } from "./entity/Photo"
import { PhotoMetadata } from "./entity/PhotoMetadata"
​
createConnection(/*...*/)
    .then(async (connection) => {
        // 创建 photo
        let photo = new Photo()
        photo.name = "Me and Bears"
        photo.description = "I am near polar bears"
        photo.filename = "photo-with-bears.jpg"
        photo.isPublished = true
​
        // 创建 photo metadata
        let metadata = new PhotoMetadata()
        metadata.height = 640
        metadata.width = 480
        metadata.compressed = true
        metadata.comment = "cybershoot"
        metadata.orientation = "portait"
        metadata.photo = photo // 联接两者
​
        // 获取实体 repositories
        let photoRepository = connection.getRepository(Photo)
        let metadataRepository = connection.getRepository(PhotoMetadata)
​
        // 先保存photo
        await photoRepository.save(photo)
​
        // 然后保存photo的metadata
        await metadataRepository.save(metadata)
​
        // 完成
        console.log(
            "Metadata is saved, and relation between metadata and photo is created in the database too",
        )
    })
    .catch((error) => console.log(error))
反向关系
关系可以是单向的或双向的。目前 PhotoMetadata 和 Photo 之间的关系是单向的。关系的所有者是 PhotoMetadata，而 Photo 对 PhotoMetadata 一无所知。这使得从 Photo 中访问 PhotoMetadata 变得很复杂。要解决这个问题，我们应该在 PhotoMetadata 和 Photo 之间建立双向关系。让我们来修改一下实体：
import {
    Entity,
    Column,
    PrimaryGeneratedColumn,
    OneToOne,
    JoinColumn,
} from "typeorm"
import { Photo } from "./Photo"
​
@Entity()
export class PhotoMetadata {
    /* ... other columns */
​
    @OneToOne((type) => Photo, (photo) => photo.metadata)
    @JoinColumn()
    photo: Photo
}
import { Entity, Column, PrimaryGeneratedColumn, OneToOne } from "typeorm"
import { PhotoMetadata } from "./PhotoMetadata"
​
@Entity()
export class Photo {
    /* ... other columns */
​
    @OneToOne((type) => PhotoMetadata, (photoMetadata) => photoMetadata.photo)
    metadata: PhotoMetadata
}
photo => photo.metadata是用来指定反向关系的名称。Photo 类的元数据属性是在 Photo 类中存储 PhotoMetadata 的地方。你可以选择简单地将字符串传递给@OneToOne装饰器，而不是传递返回 photo 属性的函数，例如"metadata"。这种函数类型的方法使我们的重构更容易。
注意，我们应该仅在关系的一侧使用@JoinColumn装饰器。你把这个装饰者放在哪一方将是这段关系的拥有方。关系的拥有方包含数据库中具有外键的列。
取出关系对象的数据
在一个查询中加载 photo 及 photo metadata 有两种方法。使用find *或使用QueryBuilder。我们先使用find *方法。 find *方法允许你使用FindOneOptions / FindManyOptions接口指定对象。
import { createConnection } from "typeorm"
import { Photo } from "./entity/Photo"
import { PhotoMetadata } from "./entity/PhotoMetadata"
​
createConnection(/*...*/)
    .then(async (connection) => {
        /*...*/
        let photoRepository = connection.getRepository(Photo)
        let photos = await photoRepository.find({ relations: ["metadata"] })
    })
    .catch((error) => console.log(error))
photos 将包含来自数据库的 photos 数组，每个 photo 将包含其 photo metadata。详细了解本文档中的查找选项。
使用查找选项很简单，但是如果你需要更复杂的查询，则应该使用QueryBuilder。 QueryBuilder允许以更优雅的方式使用更复杂的查询：
import { createConnection } from "typeorm"
import { Photo } from "./entity/Photo"
import { PhotoMetadata } from "./entity/PhotoMetadata"
​
createConnection(/*...*/)