Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[improve][docs] improve docs #941

Merged
merged 1 commit into from
Nov 6, 2023
Merged

[improve][docs] improve docs #941

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions docs/reader/accessreader.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,5 @@ bin/addax.sh job/access2stream.json

## 参数说明

因本插件基于[Addax RDBMS Reader][2] 实现，所以参数说明请参考 [Addax RDBMS Reader][2]。
AccessReader 基于 [rdbmsreader](../rdbmsreader) 实现，因此可以参考 rdbmsreader 的所有配置项。

[1]: https://en.wikipedia.org/wiki/Microsoft_Access
[2]: ../rdbmsreader
28 changes: 4 additions & 24 deletions docs/reader/databendreader.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
DatabendReader 插件实现了从 [Databend](https://databend.rs) 读取数据

注意，databender 有兼容 MySQL 客户端的协议实现，因此你可以直接使用 [mysqlreader](../mysqlreader) 来读取 Databend 数据。

## 示例

我们可以通过如下方式启动 Databend 数据库
Expand Down Expand Up @@ -49,29 +50,8 @@ bin/addax.sh job/databend2stream.json

## 参数说明

| 配置项 | 是否必须 | 类型 | 默认值 | 描述 |
| :-------------- | :------: | ------ |------------- |--------------|
| jdbcUrl | 是 | list | 无 | 对端数据库的JDBC连接信息 |
| username | 是 | string | 无 | 数据源的用户名 |
| password | 否 | string | 无 | 数据源指定用户名的密码 |
| table | 是 | list | 无 | 所选取的需要同步的表名,使用JSON数据格式，当配置为多张表时，用户自己需保证多张表是同一表结构 |
| column | 是 | list | 无 | 所配置的表中需要同步的列名集合，详细描述 [rdbmreader](../rdbmsreader) |
| where | 否 | string | 无 | 针对表的筛选条件 |
| querySql | 否 | list | 无 | 使用自定义的SQL而不是指定表来获取数据，当配置了这一项之后，Addax系统就会忽略 `table`，`column`这些配置项 |


## 类型转换

目前MysqlReader支持大部分Mysql类型，但也存在部分个别类型没有支持的情况，请注意检查你的类型。

下面列出MysqlReader针对Mysql类型转换列表:
DatabendReader 基于 [rdbmsreader](../rdbmsreader) 实现，因此可以参考 rdbmsreader 的所有配置项。

| Addax 内部类型| MySQL 数据类型 |
| -------- | ----- |
| Long |int, tinyint, smallint, mediumint, int, bigint|
| Double |float, double, decimal|
| String |varchar, char, tinytext, text, mediumtext, longtext, year |
| Date |date, datetime, timestamp, time |
| Boolean |bit, bool |
| Bytes |tinyblob, mediumblob, blob, longblob, varbinary |
## 限制

暂无
47 changes: 6 additions & 41 deletions docs/reader/mysqlreader.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# MySQL Reader

MysqlReader 插件实现了从Mysql读取数据
MysqlReader 插件实现了从 MySQL 读取数据的能力

## 示例

Expand Down Expand Up @@ -30,20 +30,7 @@ bin/addax.sh job/mysql2stream.json

## 参数说明

| 配置项 | 是否必须 | 类型 | 默认值 | 描述 |
| :-------------- | :------: | ------ |------------- |--------------|
| jdbcUrl | 是 | list | 无 | 对端数据库的JDBC连接信息，jdbcUrl按照RDBMS官方规范，并可以填写连接[附件控制信息][1] |
| driver | 否 | string | 无 | 自定义驱动类名，解决兼容性问题，详见下面描述 |
| username | 是 | string | 无 | 数据源的用户名 |
| password | 否 | string | 无 | 数据源指定用户名的密码 |
| table | 是 | list | 无 | 所选取的需要同步的表名,使用JSON数据格式，当配置为多张表时，用户自己需保证多张表是同一表结构 |
| column | 是 | list | 无 | 所配置的表中需要同步的列名集合，详细描述 [rdbmreader](../rdbmsreader) |
| splitPk | 否 | string | 无 | 使用splitPk代表的字段进行数据分片，详细描述见 [rdbmreader](../rdbmsreader)|
| autoPk | 否 | bool | false | 是否自动猜测分片主键，`3.2.6` 版本引入 |
| where | 否 | string | 无 | 针对表的筛选条件 |
| querySql | 否 | list | 无 | 使用自定义的SQL而不是指定表来获取数据，当配置了这一项之后，Addax系统就会忽略 `table`，`column`这些配置项 |

[1]: http://dev.mysql.com/doc/connector-j/en/connector-j-reference-configuration-properties.html
MysqlReader 基于 [rdbmsreader](../rdbmsreader) 实现，因此可以参考 rdbmsreader 的所有配置项。

### driver

Expand All @@ -61,32 +48,10 @@ bin/addax.sh job/mysql2stream.json

在你的 json 文件类，配置 `"driver": "com.mysql.jdbc.Driver"`

## 类型转换
## 类型转换注意事项

目前MysqlReader支持大部分Mysql类型，但也存在部分个别类型没有支持的情况，请注意检查你的类型。
* `tinyint(1)` 会视为整形
* `year` 被视为整形
* `bit` 如果是 `bit(1)` 被视为布尔类型，否则当作二进制类型

下面列出MysqlReader针对Mysql类型转换列表:

| Addax 内部类型| MySQL 数据类型 |
| -------- | ----- |
| Long |int, tinyint, smallint, mediumint, int, bigint|
| Double |float, double, decimal|
| String |varchar, char, tinytext, text, mediumtext, longtext, year |
| Date |date, datetime, timestamp, time |
| Boolean |bit, bool |
| Bytes |tinyblob, mediumblob, blob, longblob, varbinary |

请注意:

* 除上述罗列字段类型外，其他类型均不支持
* `tinyint(1)` Addax视作为整形
* `year` Addax视作为字符串类型
* `bit` Addax属于未定义行为

### 数据库编码问题

Mysql本身的编码设置非常灵活，包括指定编码到库、表、字段级别，甚至可以均不同编码。优先级从高到低为字段、表、库、实例。我们不推荐数据库用户设置如此混乱的编码，最好在库级别就统一到UTF-8。

MysqlReader底层使用JDBC进行数据抽取，JDBC天然适配各类编码，并在底层进行了编码转换。因此MysqlReader不需用户指定编码，可以自动获取编码并转码。

对于Mysql底层写入编码和其设定的编码不一致的混乱情况，MysqlReader对此无法识别，对此也无法提供解决方案，对于这类情况，`导出有可能为乱码`。
57 changes: 3 additions & 54 deletions docs/reader/oraclereader.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Oracle Reader

OracleReader 插件用于从Oracle读取数据
OracleReader 插件用于从 Oracle 读取数据

## 配置样例

Expand All @@ -14,38 +14,8 @@ OracleReader 插件用于从Oracle读取数据

## 参数说明

| 配置项 | 是否必须 | 默认值 | 描述 |
| :-------- | :------: | ------ | -------------------------------------------------------------------------------------------------------- |
| jdbcUrl | 是 | 无 | 对端数据库的JDBC连接信息，jdbcUrl按照RDBMS官方规范，并可以填写连接[附件控制信息][1] |
| username | 是 | 无 | 数据源的用户名 |
| password | 否 | 无 | 数据源指定用户名的密码 |
| table | 是 | 无 | 所选取的需要同步的表名,使用JSON数据格式，当配置为多张表时，用户自己需保证多张表是同一表结构 |
| column | 是 | 无 | 所配置的表中需要同步的列名集合，详细描述见 [rdbmsreader](../rdbmsreader) |
| splitPk | 否 | 无 | 使用splitPk代表的字段进行数据分片，Addax因此会启动并发任务进行数据同步，这样可以大大提供数据同步的效能 |
| autoPk | 否 | false | 是否自动猜测分片主键，`3.2.6` 版本引入 |
| where | 否 | 无 | 针对表的筛选条件 |
| querySql | 否 | 无 | 使用自定义的SQL而不是指定表来获取数据，当配置了这一项之后，Addax系统就会忽略 `table`，`column`这些配置项 |
| fetchSize | 否 | 1024 | 定义了插件和数据库服务器端每次批量数据获取条数，调高该值可能导致 Addax 出现OOM |
| session | 否 | 无 | 针对本地连接,修改会话配置,详见下文 |
OracleReader 基于 [rdbmsreader](../rdbmsreader) 实现，因此可以参考 rdbmsreader 的所有配置项。

[1]: http://www.oracle.com/technetwork/database/enterprise-edition/documentation/index.html

### session

控制写入数据的时间格式，时区等的配置，如果表中有时间字段，配置该值以明确告知写入 oracle 的时间格式。通常配置的参数为：`NLS_DATE_FORMAT`,`NLS_TIME_FORMAT`。其配置的值为 `json` 格式，例如：

```json
{
"session": [
"alter session set NLS_DATE_FORMAT='yyyy-mm-dd hh24:mi:ss'",
"alter session set NLS_TIMESTAMP_FORMAT='yyyy-mm-dd hh24:mi:ss'",
"alter session set NLS_TIMESTAMP_TZ_FORMAT='yyyy-mm-dd hh24:mi:ss'",
"alter session set TIME_ZONE='Asia/Chongqing'"
]
}
```

注意 `"`是 `"` 的转义字符串

## 对 GEOMETRY 类型的支持

Expand All @@ -63,25 +33,4 @@ OracleReader 插件用于从Oracle读取数据
--8<-- "assets/output/oracle_geom_reader.txt
```

注意：该数据类型目前还处于实验支持阶段，作者对次数据类型的理解并不深刻，也未经过全面的测试，请勿直接在生产环境使用。

## 类型转换

| Addax 内部类型 | Oracle 数据类型 |
| -------------- |------------------------------------------------------------------------------------------------|
| Long | NUMBER, INTEGER, INT, SMALLINT |
| Double | NUMERIC, DECIMAL, FLOAT, DOUBLE PRECISION, REAL |
| String | LONG ,CHAR, NCHAR, VARCHAR, VARCHAR2, NVARCHAR2, CLOB, NCLOB, CHARACTER, STRUCT |
| String | CHARACTER VARYING, CHAR VARYING, NATIONAL CHARACTER, NATIONAL CHAR, NATIONAL CHARACTER VARYING |
| String | NATIONAL CHAR VARYING, NCHAR VARYING |
| Date | TIMESTAMP, DATE |
| Boolean | bit, bool |
| Bytes | BLOB, BFILE, RAW, LONG RAW |

请注意: 除上述罗列字段类型外，其他类型均不支持

### 数据库编码问题

OracleReader底层使用JDBC进行数据抽取，JDBC天然适配各类编码，并在底层进行了编码转换。因此OracleReader不需用户指定编码，可以自动获取编码并转码。

对于Oracle底层写入编码和其设定的编码不一致的混乱情况，OracleReader对此无法识别，对此也无法提供解决方案，对于这类情况，**导出有可能为乱码**。
注意：该数据类型目前还处于实验支持阶段，作者对此数据类型的理解并不深刻，也未经过全面的测试，请勿直接在生产环境使用。
30 changes: 1 addition & 29 deletions docs/reader/postgresqlreader.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,32 +30,4 @@ bin/addax.sh job/postgres2stream.json

## 参数说明

| 配置项 | 是否必须 | 默认值 | 描述 |
| :-------- | :------: | ------ | -------------------------------------------------------------------------------------------------------- |
| jdbcUrl | 是 | 无 | 对端数据库的JDBC连接信息，jdbcUrl按照RDBMS官方规范，并可以填写连接 [附件控制信息][1] |
| username | 是 | 无 | 数据源的用户名 |
| password | 否 | 无 | 数据源指定用户名的密码 |
| table | 是 | 无 | 所选取的需要同步的表名,使用JSON数据格式，当配置为多张表时，用户自己需保证多张表是同一表结构 |
| column | 是 | 无 | 所配置的表中需要同步的列名集合，详细描述见 [rdbmsreader](../rdbmsreader/) |
| splitPk | 否 | 无 | 使用splitPk代表的字段进行数据分片，Addax因此会启动并发任务进行数据同步，这样可以大大提供数据同步的效能 |
| autoPk | 否 | false | 是否自动猜测分片主键，`3.2.6` 版本引入 |
| where | 否 | 无 | 针对表的筛选条件 |
| querySql | 否 | 无 | 使用自定义的SQL而不是指定表来获取数据，当配置了这一项之后，Addax系统就会忽略 `table`，`column`这些配置项 |
| fetchSize | 否 | 1024 | 定义了插件和数据库服务器端每次批量数据获取条数，调高该值可能导致 Addax 出现OOM |

[1]: http://jdbc.postgresql.org/documentation/93/connect.html

## 类型转换

| Addax 内部类型 | PostgreSQL 数据类型 |
| -------------- | ---------------------------------------------------------------------- |
| Long | bigint, bigserial, integer, smallint, serial |
| Double | double precision, money, numeric, real |
| String | varchar, char, text, bit(>1), inet, cidr, macaddr, array,uuid,json,xml |
| Date | date, time, timestamp |
| Boolean | bool,bit(1) |
| Bytes | bytea |

## 已知限制

除上述罗列字段类型外，其他类型均不支持;
PostgresqlReader 基于 [rdbmsreader](../rdbmsreader) 实现，因此可以参考 rdbmsreader 的所有配置项。
Loading
Loading