Skip to content

Commit f8348fe

Browse files
demoparkdemopark
committed
Add docs for other dialects and Snowflake
Add two new documentation pages: databases/new.md which explains options for requesting, contributing, or creating third-party Sequelize dialects and the inclusion criteria; and databases/snowflake.md which documents the @sequelize/snowflake dialect, installation and usage example, a note about lack of integration testing, supported connection options (summary table) and other Snowflake-specific settings.
1 parent 29e7ce8 commit f8348fe

File tree

2 files changed

+142
-0
lines changed

2 files changed

+142
-0
lines changed

‎databases/new.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# 其他数据库
2+
3+
4+
如果你正在使用 Sequelize 当前尚未支持的数据库，你有以下几种选择：
5+
6+
- [请求支持新的方言](#requesting-support-for-a-new-dialect)
7+
- [贡献新的方言](#contributing-a-new-dialect)
8+
- [创建第三方方言](#creating-a-third-party-dialect)
9+
10+
11+
## 请求支持新的方言
12+
13+
14+
你可以在 [Sequelize 仓库](https://github.com/sequelize/sequelize) 提交功能请求，申请支持新的方言。
15+
请确保你请求的方言没有已有的 issue。[在这里查看所有新方言的请求列表](https://github.com/sequelize/sequelize/issues?q=is%3Aopen+is%3Aissue+label%3A%22dialect%3A+new%22)。
16+
17+
18+
我们对接受新方言有如下条件：
19+
20+
- 数据库必须支持 SQL 查询。
21+
- 数据库必须有可用于连接的 Node.js 库。
22+
- 我们必须能在 GitHub Codespaces 中运行数据库实例，以保证本地开发可用。
23+
- 我们必须能在 GitHub Actions 中运行数据库实例，以便集成测试。
24+
- 集成测试必须能在 15 分钟内完成。
25+
26+
27+
你也可以通过赞助的方式推动新方言的开发。如果你对此感兴趣，[请通过邮件联系我们](https://github.com/sequelize/sequelize/blob/main/CONTACT.md)。
28+
请注意，上述条件同样适用于赞助方言，并且实现新方言可能需要较大投入。
29+
30+
31+
如果该方言符合要求，我们会在有足够用户请求或获得赞助时考虑实现。
32+
个人贡献者也可以选择[贡献新的方言](#contributing-a-new-dialect)。
33+
34+
35+
## 贡献新的方言
36+
37+
38+
39+
我们不再接受 Sequelize 6 的新方言。
40+
41+
42+
如果你希望通过 pull request 添加新方言，请遵循以下步骤：
43+
44+
- 确保该方言符合 [纳入要求](#requesting-support-for-a-new-dialect)。
45+
- [为新方言提交功能请求](#requesting-support-for-a-new-dialect)，如果还没有的话。
46+
- 在功能请求中注明你正在实现该方言（即使不是你自己发起的请求）。
47+
- 阅读现有方言包的源码以了解其工作方式。目前我们没有创建新方言的官方指南。
48+
49+
50+
## 创建第三方方言
51+
52+
53+
54+
虽然我们正在逐步提供用于创建第三方方言的稳定公共 API，但许多必要的 API 仍为内部实现，且可能会变动。
55+
56+
如果你实现了第三方方言，请注意它可能会在 Sequelize 的后续非主版本中失效。
57+
58+
59+
如果你的方言不符合纳入 Sequelize 的要求，你可以选择创建第三方方言。
60+
61+
Each dialect is a separate package that extends Sequelize with the necessary functionality to connect to the database.
62+
Third-party dialects can be published on npm and used in your project like any other package.
63+
64+
Consider exploring the source code of an existing dialect package to understand how it works.
65+
We unfortunately do not have a guide for creating a new dialect at this time.

‎databases/snowflake.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Sequelize 用于 Snowflake
2+
3+
4+
5+
我们对 Snowflake 的实现并未在真实数据库上进行集成测试。
6+
因此，我们无法保证其能如预期工作，也无法保证其稳定性。
7+
8+
我们依赖社区的帮助来改进此方言。
9+
10+
11+
12+
请参阅 [Releases](/releases#snowflake-support-table) 以了解支持哪些版本的 Snowflake。
13+
14+
15+
要在 Snowflake 上使用 Sequelize，你需要安装 `@sequelize/snowflake` 方言包：
16+
17+
```bash npm2yarn
18+
npm i @sequelize/snowflake
19+
```
20+
21+
22+
然后在 Sequelize 构造函数中使用 `SnowflakeDialect` 作为 dialect 选项：
23+
24+
```ts
25+
import { Sequelize } from '@sequelize/core';
26+
import { SnowflakeDialect } from '@sequelize/snowflake';
27+
28+
const sequelize = new Sequelize({
29+
dialect: SnowflakeDialect,
30+
accessUrl: 'https://myaccount.us-east-1.snowflakecomputing.com',
31+
role: 'myRole',
32+
warehouse: 'myWarehouse',
33+
username: 'myUserName',
34+
password: 'myPassword',
35+
database: 'myDatabaseName',
36+
});
37+
```
38+
39+
40+
## 连接选项
41+
42+
import ConnectionOptions from './_connection-options.md';
43+
44+
<ConnectionOptions />
45+
46+
47+
以下选项会原样传递给 Sequelize 用于连接 Snowflake 的 `snowflake-sdk` 包。
48+
更多关于每个选项的作用，请参考 [Snowflake 官方文档](https://docs.snowflake.com/en/developer-guide/node-js/nodejs-driver-options)。
49+
50+
为方便起见，下面是仅包含 Sequelize 支持选项的文档摘录：
51+
52+
| 选项 | 说明 |
53+
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
54+
| `accessUrl` | 指定用于连接 Snowflake 的完整端点。 |
55+
| `account` | Snowflake 账户标识符 |
56+
| `application` | Specifies the name of the client application connecting to Snowflake. |
57+
| `authenticator` | Specifies the authenticator to use for verifying user login credentials. See the [Snowflake documentation](https://docs.snowflake.com/en/developer-guide/node-js/nodejs-driver-options#authentication-options) for details |
58+
| `clientSessionKeepAlive` | By default, client connections typically time out approximately 3-4 hours after the most recent query was executed.<br/>If the `clientSessionKeepAlive` option is set to `true`, the client’s connection to the server will be kept alive indefinitely, even if no queries are executed.<br/>Note that [the Sequelize Pool](../other-topics/connection-pool.md) also disconnects connections if they are idle after a specified time. |
59+
| `clientSessionKeepAliveHeartbeatFrequency` | Sets the frequency (interval in seconds) between heartbeat messages. |
60+
| `database` | The default database to use for the session after connecting. |
61+
| `password` | Password for the user for when `authenticator` is set to `SNOWFLAKE`. |
62+
| `privateKey` | Specifies the private key (in PEM format) for key pair authentication. |
63+
| `privateKeyPass` | Specifies the passcode to decrypt the private key file, if the file is encrypted. |
64+
| `privateKeyPath` | Specifies the local path to the private key file (e.g. `rsa_key.p8`). |
65+
| `role` | The default security role to use for the session after connecting. |
66+
| `timeout` | Number of milliseconds to keep the connection alive with no response. Default: 60000 (1 minute). |
67+
| `token` | Specifies the OAuth token to use for authentication for when `authenticator` is set to `OAUTH`. |
68+
| `username` | The login name for your Snowflake user or your Identity Provider. |
69+
| `warehouse` | The default virtual warehouse to use for the session after connecting. Used for performing queries, loading data, etc. |
70+
71+
## Other Snowflake Options
72+
73+
The following options are also available for Snowflake:
74+
75+
| Option | Description |
76+
| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
77+
| `showWarnings` | If `true`, warnings produced during the execution of a query will be sent to the `logging` callback. Default is `false`. |

0 commit comments

Comments
 (0)
⚡