|
| 1 | +# 快速开始 |
| 2 | + |
| 3 | +在本教程中,你将学习如何对 Sequelize 进行一个简单的基础配置。 |
| 4 | + |
| 5 | +## 安装 |
| 6 | + |
| 7 | +Sequelize 可以通过 [npm](https://www.npmjs.com/package/@sequelize/core)(或 [yarn](https://yarnpkg.com/package/@sequelize/core))安装。 |
| 8 | + |
| 9 | +以下命令将安装 Sequelize v7。 |
| 10 | +如果你在寻找 Sequelize v6(包名为 `sequelize`,而不是 `@sequelize/core`),请 |
| 11 | +[访问 v6 文档](https://github.com/demopark/sequelize-docs-Zh-CN/tree/v6) |
| 12 | + |
| 13 | +```bash |
| 14 | +# 这将安装 Sequelize 7(Sequelize 最新的 alpha 版本) |
| 15 | +npm i @sequelize/core@alpha |
| 16 | +``` |
| 17 | + |
| 18 | +## 连接数据库 |
| 19 | + |
| 20 | +要连接数据库,你必须创建一个 Sequelize 实例,并向其传入数据库配置信息,例如方言(dialect)、主机(host)以及用户名和密码。 |
| 21 | + |
| 22 | +不同的方言支持的选项集合不同。请通过下面的链接查看如何连接到你的数据库: |
| 23 | + |
| 24 | +- [PostgreSQL](./databases/postgres.md) |
| 25 | +- [MySQL](./databases/mysql.md) |
| 26 | +- [MariaDB](./databases/mariadb.md) |
| 27 | +- [SQLite](./databases/sqlite.md) |
| 28 | +- [Microsoft SQL Server](./databases/mssql.md) |
| 29 | +- [DB2 for LUW](./databases/db2.md) |
| 30 | +- [DB2 for IBM i](./databases/ibmi.md) |
| 31 | +- [Snowflake](./databases/snowflake.md) |
| 32 | + |
| 33 | +如果你的数据库未在上方列表中,Sequelize 默认并不直接支持它。 |
| 34 | +不过 Sequelize 具有可扩展性:你可以创建自己的方言,或寻找社区维护的方言实现。 |
| 35 | +更多信息请参阅 [支持其他数据库](./databases/new.md)。 |
| 36 | + |
| 37 | +下面是一个连接 SQLite 数据库的简短示例: |
| 38 | + |
| 39 | +```javascript |
| 40 | +import { Sequelize } from '@sequelize/core'; |
| 41 | +import { SqliteDialect } from '@sequelize/sqlite3'; |
| 42 | + |
| 43 | +const sequelize = new Sequelize({ |
| 44 | + dialect: SqliteDialect, |
| 45 | +}); |
| 46 | +``` |
| 47 | + |
| 48 | +`Sequelize` 构造函数接受许多选项。 |
| 49 | +它们都记录在 [API 参考](https://sequelize.org/api/v7/classes/_sequelize_core.index.Sequelize.html#constructor) 中。 |
| 50 | + |
| 51 | +### 测试连接 |
| 52 | + |
| 53 | +你可以使用 `.authenticate()` 函数来测试连接是否正常。 |
| 54 | +注意这完全是可选的,但我们推荐这么做,因为 Sequelize 会在首次连接时获取你的数据库版本。 |
| 55 | +随后它会使用该版本来判断哪些 SQL 功能可用。 |
| 56 | + |
| 57 | +```js |
| 58 | +try { |
| 59 | + await sequelize.authenticate(); |
| 60 | + console.log('Connection has been established successfully.'); |
| 61 | +} catch (error) { |
| 62 | + console.error('Unable to connect to the database:', error); |
| 63 | +} |
| 64 | +``` |
| 65 | + |
| 66 | +### 关闭连接 |
| 67 | + |
| 68 | +Sequelize 使用连接池来管理数据库连接。这意味着即使你已经不再使用它们,某些连接仍可能保持打开状态。 |
| 69 | +如果你希望优雅地关闭应用程序,可以使用 [`sequelize.close()`](https://sequelize.org/api/v7/classes/_sequelize_core.index.Sequelize.html#close) 来关闭所有活动连接。 |
| 70 | + |
| 71 | +一旦调用了 `sequelize.close()`,就无法再打开新的连接。若要再次访问数据库,你需要创建一个新的 Sequelize 实例。 |
| 72 | + |
| 73 | +## 术语约定 |
| 74 | + |
| 75 | +请注意,在上面的示例中,`Sequelize` 指的是这个库本身,而小写的 `sequelize` 指的是 Sequelize 的一个实例。 |
| 76 | +这是我们推荐的命名约定,本文档将始终遵循这一约定。 |
| 77 | + |
| 78 | +## TypeScript |
| 79 | + |
| 80 | +Sequelize 提供内置的 TypeScript 支持。 |
| 81 | + |
| 82 | +请前往 [版本策略页面](/releases) 了解支持哪些 TypeScript 版本, |
| 83 | +并确保你的项目已安装与你的 Node.js 版本相对应的 [`@types/node`](https://www.npmjs.com/package/@types/node) 包。 |
| 84 | + |
| 85 | +Sequelize 使用了 `package.json` 中的 [`exports`](https://nodejs.org/api/packages.html#exports) 字段。 |
| 86 | +你可能需要更新 `tsconfig.json` 配置,以确保 TypeScript 的模块解析支持它。 |
| 87 | + |
| 88 | +在撰写本文时(TS 5.4),可以通过两种方式实现: |
| 89 | + |
| 90 | +- Set [`moduleResolution`](https://www.typescriptlang.org/tsconfig#moduleResolution) to `node16`, `nodenext`, or `bundler`, |
| 91 | +- 或将 [`resolvePackageJsonExports`](https://www.typescriptlang.org/tsconfig#resolvePackageJsonExports) 设置为 `true`。 |
| 92 | + |
| 93 | +## CommonJS 还是 ESM? |
| 94 | + |
| 95 | +本文档大量使用 ECMAScript Modules(ESM),但 Sequelize 也完全支持 CommonJS。 |
| 96 | +要在 CommonJS 项目中使用 Sequelize,只需用 `require` 替代 `import`: |
| 97 | + |
| 98 | +```js |
| 99 | +// 在 ESM 中如何导入 Sequelize |
| 100 | +import { Sequelize, Op, Model, DataTypes } from '@sequelize/core'; |
| 101 | + |
| 102 | +// 在 CommonJS 中如何导入 Sequelize |
| 103 | +const { Sequelize, Op, Model, DataTypes } = require('@sequelize/core'); |
| 104 | +``` |
| 105 | + |
| 106 | +Sequelize 提供的大多数方法都是异步的,因此会返回 [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)。 |
| 107 | +我们强烈建议使用 **ECMAScript Modules**,因为它能让你使用 [Top-Level Await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await),而我们在示例中也大量使用了它。 |
| 108 | +请参阅 [Node.js 文档](https://nodejs.org/api/esm.html) 了解如何在 Node.js 中使用 ESM。 |
| 109 | + |
| 110 | +## 日志 |
| 111 | + |
| 112 | +为了便于调试,你可以在 Sequelize 中启用日志。做法是将 `logging` 选项设置为一个函数,每当 Sequelize 需要输出日志时就会执行该函数。 |
| 113 | + |
| 114 | +示例: |
| 115 | + |
| 116 | +```js |
| 117 | +const sequelize = new Sequelize({ |
| 118 | + dialect: SqliteDialect, |
| 119 | + |
| 120 | + // 禁用日志(默认) |
| 121 | + logging: false, |
| 122 | + |
| 123 | + // 将日志输出到控制台 |
| 124 | + logging: console.log, |
| 125 | + |
| 126 | + // 你也可以使用任意函数,例如把日志发送到日志工具 |
| 127 | + logging: (...msg) => console.log(msg), |
| 128 | +}); |
| 129 | +``` |
| 130 | + |
| 131 | +如果你只需要记录特定查询,可以在所有会执行查询的模型方法中使用 `logging` 选项, |
| 132 | +以及在所有 `queryInterface` 方法中使用它。 |
| 133 | + |
| 134 | +## 下一步 |
| 135 | + |
| 136 | +现在你已经有了一个 Sequelize 实例,接下来可以从 [定义你的第一个模型](./models/defining-models.md) 开始。 |
0 commit comments