Skip to content

Commit

Permalink
[improve][docs] improve docs (#941)
Browse files Browse the repository at this point in the history
  • Loading branch information
@wgzhao
wgzhao authored Nov 6, 2023
1 parent c5ca188 commit 4e5dd59
Show file tree
Hide file tree
Showing 20 changed files with 113 additions and 446 deletions.
4 changes: 1 addition & 3 deletions docs/reader/accessreader.md
View file
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
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
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
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
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

0 comments on commit 4e5dd59

Please sign in to comment.