Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
26 changes: 26 additions & 0 deletions CN/modules/ROOT/pages/4.1.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,32 @@ ivorysql 130433 130427 0 02:45 ? 00:00:00 postgres: logical replicatio
ivorysql 130445 130274 0 02:45 pts/1 00:00:00 grep --color=auto postgres
```

== 配置文件与参数说明

Oracle 模式下,`initdb` 会在数据目录中生成 `ivorysql.conf`,内容取自安装目录 share 下的 `ivorysql.conf.sample`(仅 Oracle 端口与 `shared_preload_libraries` 会按实际安装值替换),并由同目录 `postgresql.conf` 中的 `include_if_exists = 'ivorysql.conf'` 引入;PostgreSQL 模式下该引入行被注释,也不会使用该文件。

`ivorysql.conf.sample`(IvorySQL 5.6)只涉及 15 个 `ivorysql.{asterisk}` 参数中的 4 个,这 15 个参数在 `src/backend/utils/misc/ivy_guc.c` 中注册。出现在样例中的 4 个是 `ivorysql.listen_addresses`、`ivorysql.port`、`ivorysql.identifier_case_switch` 与 `ivorysql.enable_emptystring_to_NULL`:前 3 个以注释形式给出示例,只有 `ivorysql.enable_emptystring_to_NULL` 是未注释的生效行。样例中另一个生效赋值是 `shared_preload_libraries`,它不属于 `ivorysql.{asterisk}` 参数。

其余 11 个 `ivorysql.{asterisk}` 参数不出现在样例中并非遗漏:IvorySQL 在注册这些参数时带上了 `GUC_NOT_IN_SAMPLE` 标记(定义见 `src/include/utils/guc.h`),测试用例 `src/test/modules/test_misc/t/003_check_guc.pl` 会断言「样例文件中的参数集合」等于「不带该标记的参数集合」。因此把这 11 个参数手工写进 `ivorysql.conf.sample` 会令该测试失败,它们应在使用时按需设置。

按使用方式,这 11 个参数可分为两类:

* 面向用户的参数:用 `SHOW` 查看、用 `SET` 在当前会话中修改,例如 `ivorysql.compatible_mode`、`ivorysql.database_mode`、`ivorysql.datetime_ignore_nls_mask` 与 `ivorysql.enable_case_switch`。其中 `ivorysql.compatible_mode` 与 `ivorysql.database_mode` 本身不允许在配置文件中设置。
* 开发者/诊断参数:除 `GUC_NOT_IN_SAMPLE` 外还带 `GUC_NO_SHOW_ALL`,默认不出现在 `SHOW ALL` 与 `pg_settings` 视图中,供排查问题或开发调试时按需打开。

因此以超级用户连接后执行以下语句,默认返回 8 条而非 15 条,属于正常现象:

```
SELECT name, pg_settings_get_flags(name) AS flags
FROM pg_settings
WHERE name LIKE 'ivorysql.%'
ORDER BY name;
```

结果中不带 `NOT_IN_SAMPLE` 的正是样例文件里的那 4 个参数;带 `NOT_IN_SAMPLE` 的参数应通过 `SHOW` / `SET` 使用,无需写进配置文件。

上述参数的说明与取值见 7.2「GUC框架」中的「新增变量(目前)」参数表(样例中的 4 个均在该表内);该表未列出的开发者参数,可结合上面的查询与源码 `src/backend/utils/misc/ivy_guc.c` 确认。

== 数据库连接

psql连接数据库:
Expand Down
26 changes: 26 additions & 0 deletions EN/modules/ROOT/pages/4.1.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -227,6 +227,32 @@ ivorysql 130433 130427 0 02:45 ? 00:00:00 postgres: logical replicatio
ivorysql 130445 130274 0 02:45 pts/1 00:00:00 grep --color=auto postgres
```

== Configuration Files and Parameters

In Oracle mode, `initdb` creates `ivorysql.conf` in the data directory. Its content comes from `ivorysql.conf.sample` in the share directory of the installation (only the Oracle port and `shared_preload_libraries` are replaced with the actual installation values), and the file is pulled in by `include_if_exists = 'ivorysql.conf'` in `postgresql.conf`. In PostgreSQL mode that include line is commented out and the file is not used.

`ivorysql.conf.sample` (IvorySQL 5.6) covers only 4 of the 15 `ivorysql.{asterisk}` parameters, which are registered in `src/backend/utils/misc/ivy_guc.c`: `ivorysql.listen_addresses`, `ivorysql.port`, `ivorysql.identifier_case_switch` and `ivorysql.enable_emptystring_to_NULL`. The first three are given as commented-out examples, and only `ivorysql.enable_emptystring_to_NULL` is an active, uncommented line. The other active setting in the sample is `shared_preload_libraries`, which is not an `ivorysql.{asterisk}` parameter.

The remaining 11 `ivorysql.{asterisk}` parameters are not missing from the sample by accident: IvorySQL registers them with the `GUC_NOT_IN_SAMPLE` flag (defined in `src/include/utils/guc.h`), and the test `src/test/modules/test_misc/t/003_check_guc.pl` asserts that the set of parameters in the sample file equals the set of parameters without that flag. Adding these 11 parameters to `ivorysql.conf.sample` by hand would therefore make that test fail; set them only when they are actually needed.

From a usage point of view the 11 parameters fall into two groups:

* User-facing parameters: read with `SHOW` and changed for the current session with `SET`, for example `ivorysql.compatible_mode`, `ivorysql.database_mode`, `ivorysql.datetime_ignore_nls_mask` and `ivorysql.enable_case_switch`. Note that `ivorysql.compatible_mode` and `ivorysql.database_mode` cannot be set in a configuration file at all.
* Developer and diagnostic parameters: besides `GUC_NOT_IN_SAMPLE` they also carry `GUC_NO_SHOW_ALL`, so they do not appear in `SHOW ALL` or in the `pg_settings` view by default; they are switched on as needed when diagnosing a problem or during development.

For this reason the following statement, executed in a superuser session, returns 8 rows by default instead of 15, which is expected:

```
SELECT name, pg_settings_get_flags(name) AS flags
FROM pg_settings
WHERE name LIKE 'ivorysql.%'
ORDER BY name;
```

The rows without `NOT_IN_SAMPLE` are exactly the four parameters present in the sample file; parameters that carry `NOT_IN_SAMPLE` are meant to be used with `SHOW` / `SET` and need not be written into the configuration file.

Descriptions and accepted values of these parameters, including the four present in the sample, are listed in the "New variables(currently)" table of 7.2 "GUC Framework"; for developer parameters that are not listed there, use the statement above together with `src/backend/utils/misc/ivy_guc.c`.

== Connecting to IvorySQL

Connect to IovrySQL via psql:
Expand Down
Loading