Installation
1. Introduction
The installation methods for IvorySQL include the following five:
This chapter will provide detailed instructions on the installation, execution, and uninstallation processes for each method. For a quicker access to IvorySQL, please refer to Quick installation.
Before getting started, please create an user and grant it root privileges. All the installation steps will be performed by this user. Here we just name it 'ivorysql'.
2. Yum installation
Create or edit IvorySQL yum repository configuration /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
After saving and exiting, you can install IvorySQL 4 with the following steps
$ sudo dnf install -y ivorysql5-5.6
3. Docker installation
-
Get IvorySQL image from Docker Hub
$ docker pull ivorysql/ivorysql:5.6-ubi8
Users in China can also pull from the IvorySQL community Harbor registry for faster downloads — replace the image reference above with registry.highgo.com/ivorysql/ivorysql:5.6-ubi8.
|
-
Run IvorySQL
$ docker run --name ivorysql -p 5434:5432 -e IVORYSQL_PASSWORD=your_password -d ivorysql/ivorysql:5.6-ubi8
-e Parameter Explanation
Parameter Name |
Required |
Description |
IVORYSQL_USER |
No |
Database user, default is ivorysql |
IVORYSQL_PASSWORD |
yes |
Database password |
IVORYSQL_DB |
no |
Database name,default is ivorysql |
POSTGRES_HOST_AUTH_METHOD |
no |
Modify host authentication method,reference value:md5 |
POSTGRES_INITDB_ARGS |
no |
Add additional parameters to initdb,reference value:"--data-checksums" |
PGDATA |
no |
Define the data directory to be located in another path or folder (e.g., subdirectory), defaulting to /var/lib/ivorysql/data |
POSTGRES_INITDB_WALDIR |
no |
Define the IvorySQL transaction folder path, which defaults to a subdirectory within the data directory (PGDATA) |
|
4. rpm installation
-
Installing dependencies
$ sudo dnf install -y lz4 libicu libxslt python3
-
Getting rpms
$ sudo wget https://github.com/IvorySQL/IvorySQL/releases/download/IvorySQL_5.6/IvorySQL-5.6-9d890e9-20251120.x86_64.rpm
-
Installing rpms
Use the following command to install all the rpms:
$ sudo yum --disablerepo=* localinstall *.rpm
IvorySQL then will be installed in the /usr/ivory-5/ directory.
5. Source code installation
-
Installing dependencies
# 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
-
Getting source code
$ git clone https://github.com/IvorySQL/IvorySQL.git
$ cd IvorySQL
$ git checkout -b IVORY_REL_5_STABLE origin/IVORY_REL_5_STABLE
-
Configuring
In the IvorySQL directory run the following command with --prefix to specify the directory where you want the database to be installed:
$ ./configure --prefix=/usr/local/ivorysql/ivorysql-5
-
Compiling
Run the following command to compile the source code:
$ make
|
When the compilation is completed, you can test the result with 'make check' or 'make all-check-world' before your installation. |
-
Installing
Run the following command to install the database system, IvorySQL then will be installed in the directory specified by --prefix:
$ sudo make install
6. deb installation
-
Installing dependencies
$ 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
-
Getting deb
$ sudo wget https://github.com/IvorySQL/IvorySQL/releases/download/IvorySQL_5.6/IvorySQL-5.6-a50789d-20250304.amd64.deb
-
Installing deb
$ sudo dpkg -i IvorySQL-5.6-a50789d-20250304.amd64.deb
IvorySQL will then be installed in the /usr/ivory-5/ directory.
7. Start Database
Users following the instructions in Yum installation, rpm installation, Source code installation and deb installation need to manually start the database.
-
Granting permissions
Execute the following command to grant permissions to the installation user. The example user is ivorysql, and the installation directory is /usr/ivory-5/:
$ sudo chown -R ivorysql:ivorysql /usr/ivory-5/
-
Setting environment variables
Add below contents in ~/.bash_profile file and source to make it effective:
PATH=/usr/ivory-5/bin:$PATH
export PATH
PGDATA=/usr/ivory-5/data
export PGDATA
$ source ~/.bash_profile
-
Initializing database
$ mkdir /usr/ivory-5/data
$ initdb -D /usr/ivory-5/data
The -D option specifies the directory where the database cluster should be stored. This is the only information required by initdb, but you can avoid writing it by setting the PGDATA environment variable, which can be convenient since the database server can find the database directory later by the same variable. For more options, refer to initdb --help.
-
Starting IvorySQL service
$ pg_ctl -D /usr/ivory-5/data -l ivory.log start
The -D option specifies the file system location of the database configuration files. If this option is omitted, the environment variable PGDATA in [setting-environment-variables] is used. -l option appends the server log output to filename. If the file does not exist, it is created.
For more options, refer to pg_ctl --help.
Confirm it’s successfully started:
$ 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. 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.* 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.* parameter.
The remaining 11 ivorysql.* 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
SHOWand changed for the current session withSET, for exampleivorysql.compatible_mode,ivorysql.database_mode,ivorysql.datetime_ignore_nls_maskandivorysql.enable_case_switch. Note thativorysql.compatible_modeandivorysql.database_modecannot be set in a configuration file at all. -
Developer and diagnostic parameters: besides
GUC_NOT_IN_SAMPLEthey also carryGUC_NO_SHOW_ALL, so they do not appear inSHOW ALLor in thepg_settingsview 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.
9. Connecting to IvorySQL
Connect to IovrySQL via psql:
$ psql -d YOUR_DATABASE
psql (18.6)
Type "help" for help.
ivorysql=#
The -d option specifies the name of the database to connect to. ivorysql is the default database of IvorySQL. However,IvorySQL of lower versions need the users themselves to connect to postgres database at the first connection and then create the ivorysql database.The latest IvorySQL can do all these for users. For more options, refer to psql --help.
| When running IvorySQL in Docker, additional parameters need to be added, like: psql -d ivorysql -U ivorysql -h 127.0.0.1 -p 5434 |
10. Uninstallation
|
No matter which method is used for the uninstallation, make sure the service has been stopped cleanly and your data has been backed up safely. |
10.1. Uninstallation for yum installation
Run the following commands in turn and clean the residual folders:
$ sudo dnf remove -y ivorysql5-5.6
10.2. Uninstallation for docker installation
Stop IvorySQL container and remove IvorySQL image:
$ docker stop ivorysql
$ docker rm ivorysql
$ docker rmi ivorysql/ivorysql:5.6-ubi8
10.3. Uninstallation for rpm installation
Uninstall the rpms and clear the residual folders:
$ sudo yum remove --disablerepo=* ivorysql5\*
$ sudo rm -rf IvorySQL-5.6