安装指南

1. 概述

IvorySQL安装方式包括以下5种:

本章将详细介绍每种方式的安装、运行及卸载过程。想要更快获得IvorySQL,请参阅快速开始。

同样,安装前请先创建一个用户,并赋予其root权限,安装、使用和卸载均以该用户执行。这里以ivorysql用户为例。

2. yum源安装

创建或编辑IvorySQL yum源配置文件/etc/yum.repos.d/ivorysql.repo

vim /etc/yum.repos.d/ivorysql.repo
[ivorysql5]
name=IvorySQL Server 5 $releasever - $basearch
baseurl=https://yum.highgo.com/dists/ivorysql-rpms/5/redhat/rhel-$releasever-$basearch
enabled=1
gpgcheck=0

保存退出后,安装IvorySQL5

$ sudo dnf install -y ivorysql5-5.6

3. docker安装

  • 从Docker Hub上获取IvorySQL镜像

$ docker pull ivorysql/ivorysql:5.6-ubi8
国内用户也可使用 IvorySQL 社区的 Harbor 镜像服务加速拉取,将上述地址替换为 registry.highgo.com/ivorysql/ivorysql:5.6-ubi8 即可。
  • 运行IvorySQL

$ docker run --name ivorysql -p 5434:5432 -e IVORYSQL_PASSWORD=your_password -d ivorysql/ivorysql:5.6-ubi8

-e参数说明

参数名

是否必填

描述

IVORYSQL_USER

否

数据库用户,默认 ivorysql

IVORYSQL_PASSWORD

是

数据库用户密码

IVORYSQL_DB

否

数据库名称,默认 ivorysql

POSTGRES_HOST_AUTH_METHOD

否

修改主机身份验证方式,参考值:md5

POSTGRES_INITDB_ARGS

否

为initdb是添加额外参数,参考值:"--data-checksums"

PGDATA

否

将数据目录定义到其他路径文件夹下(例如子目录),默认 /var/lib/ivorysql/data

POSTGRES_INITDB_WALDIR

否

定义IvorySQL transaction文件夹路径,默认在数据目录(PGDATA)的子目录中。

  1. 不推荐将POSTGRES_HOST_AUTH_METHOD参数填写为trust,这样将会使IVORYSQL_PASSWORD设置失效。

  2. 如果POSTGRES_HOST_AUTH_METHOD参数设置为scram-sha-256,同时需将POSTGRES_INITDB_ARGS设置为—​auth-host=scram-sha-256,才会使数据库正确进行初始化。

4. rpm安装

  • 安装依赖

$ sudo dnf install -y lz4 libicu libxslt python3
  • 获取rpm包

$ sudo wget https://github.com/IvorySQL/IvorySQL/releases/download/IvorySQL_5.6/IvorySQL-5.6-9d890e9-20251120.x86_64.rpm
  • 安装rpm包

    使用以下命令安装所有rpm包:

$ sudo yum --disablerepo=* localinstall *.rpm

数据库将被安装在/usr/ivory-5/路径下。

5. 源码安装

  • 安装依赖

# CentOS
$ sudo dnf install -y bison readline-devel zlib-devel openssl-devel uuid-devel
$ sudo dnf groupinstall -y 'Development Tools'

# Ubuntu
$ sudo apt install -y bison libreadline-dev zlib1g-dev libssl-dev
$ sudo apt install -y build-essential
$ sudo apt install -y pkg-config uuid-dev
  • 获取IvorySQL源代码

$ git clone https://github.com/IvorySQL/IvorySQL.git
$ cd IvorySQL
$ git checkout -b IVORY_REL_5_STABLE origin/IVORY_REL_5_STABLE
  • 配置

    在IvorySQL目录下,执行以下命令进行配置,请使用—​prefix指定安装目录:

$ ./configure --prefix=/usr/local/ivorysql/ivorysql-5
  • 编译

    执行以下命令进行编译:

$ make

编译完毕,安装之前可先执行make check或make all-check-world测试刚刚编译的结果。

  • 安装

    执行以下命令安装,数据库将被安装在上述由—​prefix指定的路径下:

$ sudo make install

6. deb安装

  • 安装依赖

$ sudo apt -y install pkg-config libreadline-dev libicu-dev libldap2-dev uuid-dev tcl-dev libperl-dev python3-dev bison flex openssl libssl-dev libpam-dev libxml2-dev libxslt-dev libossp-uuid-dev libselinux-dev gettext
  • 获取deb包

$ sudo wget https://github.com/IvorySQL/IvorySQL/releases/download/IvorySQL_5.6/IvorySQL-5.6-a50789d-20250304.amd64.deb
  • 安装deb包

$ sudo dpkg -i IvorySQL-5.6-a50789d-20250304.amd64.deb

数据库将被安装在/usr/ivory-5/路径下。

7. 启动数据库

参考yum源安装、rpm安装、源码安装、deb安装的用户,需要手动启动数据库。

  • 赋权

    执行以下命令为安装用户赋权,示例用户为ivorysql,安装目录为/usr/ivory-5/:

$ sudo chown -R ivorysql:ivorysql /usr/ivory-5/
  • 配置环境变量

    将以下配置写入用户的~/.bash_profile文件并使用source命令该文件使环境变量生效:

PATH=/usr/ivory-5/bin:$PATH
export PATH
PGDATA=/usr/ivory-5/data
export PGDATA
$ source ~/.bash_profile
  • 数据库初始化

$ mkdir /usr/ivory-5/data
$ initdb -D /usr/ivory-5/data
  其中-D参数用来指定数据库的数据目录。更多参数使用方法,请使用initdb --help命令获取。
  • 启动数据库服务

$ pg_ctl -D /usr/ivory-5/data -l ivory.log start

其中-D参数用来指定数据库的数据目录,如果[配置环境变量] 配置了PGDATA,则该参数可以省略。-l参数用来指定日志文件。更多参数使用方法,请使用pg_ctl --help命令获取。

查看确认数据库启动成功:

$ ps -ef | grep postgres
ivorysql  130427       1  0 02:45 ?        00:00:00 /usr/ivory-5/bin/postgres -D /usr/ivory-5/data
ivorysql  130428  130427  0 02:45 ?        00:00:00 postgres: checkpointer
ivorysql  130429  130427  0 02:45 ?        00:00:00 postgres: background writer
ivorysql  130431  130427  0 02:45 ?        00:00:00 postgres: walwriter
ivorysql  130432  130427  0 02:45 ?        00:00:00 postgres: autovacuum launcher
ivorysql  130433  130427  0 02:45 ?        00:00:00 postgres: logical replication launcher
ivorysql  130445  130274  0 02:45 pts/1    00:00:00 grep --color=auto postgres

8. 配置文件与参数说明

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.* 参数中的 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.* 参数。

其余 11 个 ivorysql.* 参数不出现在样例中并非遗漏: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 确认。

9. 数据库连接

psql连接数据库:

$ psql -d YOUR_DATABASE
psql (18.6)
Type "help" for help.

ivorysql=#
  其中-d参数用来指定想要连接到的数据库名称。IvorySQL默认使用ivorysql数据库,但较低版本的IvorySQL首次使用时需用户先连接postgres数据库,然后自己创建ivorysql数据库。较高版本的IvorySQL则已为用户创建好ivorysql数据库,可以直接连接。

  更多参数使用方法,请使用psql --help命令获取。
Docker运行IvorySQL时,需要添加额外参数,参考:psql -d ivorysql -U ivorysql -h 127.0.0.1 -p 5434

10. 卸载IvorySQL

使用任何一种方法卸载前请先停止数据库服务并做好数据备份。

10.1. yum源安装的卸载

执行以下命令依次卸载:

$ sudo dnf remove -y ivorysql5-5.0

10.2. docker安装的卸载

执行以下命令,使IvorySQL容器停止运行,并删除IvorySQL容器和镜像:

$ docker stop ivorysql
$ docker rm ivorysql
$ docker rmi ivorysql/ivorysql:5.6-ubi8

10.3. rpm安装的卸载

执行以下命令卸载并清理文件夹:

$ sudo yum remove --disablerepo=* ivorysql5\*
$ sudo rm -rf /usr/ivory-5

10.4. 源码安装的卸载

执行以下命令卸载数据库并清理文件夹:

$ sudo make uninstall
$ make clean
$ sudo rm -rf /usr/ivory-5

10.5. deb安装的卸载

执行以下命令卸载数据库并清理文件夹:

$ sudo dpkg -P IvorySQL-5.6
$ sudo rm -rf /usr/ivory-5