README-zh_CN
TypeORM 是一个 ORM 框架,它可以运行在 NodeJS、Browser、Cordova、PhoneGap、Ionic、React Native、Expo 和 Electron 平台上,可以与 TypeScript 和 JavaScript (ES5,ES6,ES7,ES8)一起使用。 它的目标是始终支持最新的 JavaScript 特性并提供额外的特性以帮助你开发任何使用数据库的(不管是只有几张表的小型应用还是拥有多数据库的大型企业应用)应用程序。
不同于现有的所有其他 JavaScript ORM 框架,TypeORM 支持 Data Mapper 和 Active Record 模式,这意味着你可以以最高效的方式编写高质量的、松耦合的、可扩展的、可维护的应用程序。
TypeORM 的一些特性:
- 实体和列
- 数据库特性列类型
- 实体管理
- 存储库和自定义存储库
- 清晰的对象关系模型
- 关联(关系)
- 贪婪和延迟关系
- 单向的,双向的和自引用的关系
- 支持多重继承模式
- 级联
- 索引
- 事务
- 迁移和自动迁移
- 连接池
- 主从复制
- 使用多个数据库连接
- 使用多个数据库类型
- 跨数据库和跨模式查询
- 优雅的语法,灵活而强大的 QueryBuilder
- 左联接和内联接
- 使用联查查询的适当分页
- 查询缓存
- 原始结果流
- 日志
- 监听者和订阅者(钩子)
- 支持闭包表模式
- 在模型或者分离的配置文件中声明模式
- 支持 MySQL / MariaDB / Postgres / SQLite / Microsoft SQL Server / Oracle / SAP Hana / 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); // 根据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
- MongoDB (试验性)
npm install mongodb --save
- NativeScript, react-native 和 Cordova
- SAP Hananpm config set @sap:registry https://npm.sap.comnpm i @sap/hana-clientnpm i hdb-pool
TypeScript 配置
此外,请确保你使用的 TypeScript 编译器版本是3.3或更高版本,并且已经在
tsconfig.json
中启用了以下设置:"emitDecoratorMetadata": true,
"experimentalDecorators": true,
除此之外,你可能还需要在编译器选项的
lib
中启用 es6
,或者安装 es6-shim
的 @types
。首先全局安装 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
装饰器装饰的模型。将为此类模型创建数据库表。你可以使用 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) 类型(取决于数据库类型)。 数字被映射到一个类似 integer 类型(取决于数据库类型)。但是我们不希望所有的列都是有限的 varchars 或 integer,让我们修改下代码以设置想要的数据类型:
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
和 database
正确设置。我们将 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(100) | |
| description | text | |
| filename | varchar(255) | |
| views | int(11) | |
| isPublished | boolean | |
+-------------+--------------+----------------------------+
现在创建一个新的 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"并返回。我们可以使用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));
我们刚创建了一张新 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 对象数组,其中包含从数据库加载的数据。现在让我们重构之前的代码,并使用
Repository
替代 EntityManager
。每个实体都有自己的repository,可以处理其实体的所有操作。当你经常处理实体时,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 尝试更多的加载操作:
import { createConnection } from "typeorm";
import { Photo } from "./entity/Photo";