これはPGroonga 2.X and 3.X用のドキュメントです。古いPGroongaを使っているならPGroonga 1.xのドキュメントを見てください。

WALリソースマネージャーを使ったストリーミングレプリケーション

PGroongaは3.2.1からPostgreSQL組み込みのカスタムWALリソースマネージャー機能をサポートしています。カスタムWALリソースマネージャーはPostgreSQL 15以上で利用できます。

これによりWALベースのストリーミングレプリケーションの運用が楽になります。

PGroongaのWALは次のように処理されます。

sequenceDiagram
    box transparent Primary
        participant User
        participant PGroonga
        participant WAL sender
    end
    box transparent Standby
        participant WAL receiver
        participant PGroonga WAL resource manager
    end

    User->>+PGroonga:INSERT/UPDATE/DELETE
    Note right of PGroonga:Write WAL
    PGroonga->>+WAL sender:Notify write WAL
    WAL sender->>+WAL receiver:Send WAL
    WAL receiver->>+PGroonga WAL resource manager:Call
    Note right of PGroonga WAL resource manager:Apply WAL

このドキュメントではPostgreSQL組み込みのWALベースのストリーミングレプリケーション機能をPGroongaのWALリソースマネージャーと組み合わせて利用するときの設定方法を説明します。多くの手順は通常のストリーミングレプリケーションの設定手順です。いくつかPGroonga固有の手順があります。

概要

PostgreSQL組み込みのWALベースのストリーミングレプリケーション機能をPGroongaのWALリソースマネージャと組み合わせて利用する設定手順は次の通りです。「[通常]」タグは通常のストリーミングレプリケーション用の手順であることを示しています。「[固有]」タグはPGroonga固有の手順であることを示しています。

[通常] プライマリーとスタンバイでPostgreSQLをインストールする
[固有] プライマリーとスタンバイでPGroongaをインストールする
[通常] プライマリーでストリーミングレプリケーション用にPostgreSQLを設定する
[固有] プライマリーでPGroonga用にPostgreSQLを設定する
[通常] プライマリーでデータを追加する
[固有] プライマリーでPGroongaのインデックスを作る
[固有] プライマリーでPGroonga関連のデータを書き出す
[通常] スタンバイでpg_basebackupを実行する
[固有] スタンバイでPGroonga用にPostgreSQLを設定する
[通常] スタンバイでPostgreSQLを起動する

このドキュメントでは次の環境を使います。

プライマリー：
- OS: Ubuntu 24.04
- IPアドレス：192.168.0.30
- データベース名：blog
- レプリケーションユーザー名：replicator
- レプリケーションユーザーのパスワード：passw0rd
スタンバイ1：
- OS: Ubuntu 24.04
- IPアドレス：192.168.0.31
スタンバイ2：
- OS: Ubuntu 24.04
- IPアドレス：192.168.0.32

このドキュメントではUbuntu 24.04用のコマンドラインを書いています。もし、他のプラットフォームを使っている場合は自分でコマンドラインを調整してください。

[通常] プライマリーとスタンバイでPostgreSQLをインストールする

これは通常の手順です。

プライマリーとスタンバイでPostgreSQL 16をインストールします。

sudo apt install -y gpg lsb-release wget
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo gpg --no-default-keyring --keyring /usr/share/keyrings/pdgd-keyring.gpg --import -
echo "deb [signed-by=/usr/share/keyrings/pdgd-keyring.gpg] http://apt.postgresql.org/pub/repos/apt/ $(lsb_release -cs)-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list
sudo apt update
sudo apt install -y postgresql-16

[固有] プライマリーとスタンバイでPGroongaをインストールする

これはPGroonga固有の手順です。

プライマリーとスタンバイでPGroongaをインストールします。

sudo apt install -y software-properties-common
sudo add-apt-repository -y universe
sudo add-apt-repository -y ppa:groonga/ppa
sudo apt install -y lsb-release
wget https://packages.groonga.org/ubuntu/groonga-apt-source-latest-$(lsb_release --codename --short).deb
sudo apt install -y -V ./groonga-apt-source-latest-$(lsb_release --codename --short).deb
rm -f groonga-apt-source-latest-$(lsb_release --codename --short).deb
sudo apt update
sudo apt install -y -V postgresql-16-pgdg-pgroonga

[通常] プライマリーでストリーミングレプリケーション用にPostgreSQLを設定する

これは通常の手順です。

プライマリーでだけ次のストリーミングレプリケーション用の設定をpostgresql.confに追加します。

listen_addresses = 'localhost,192.168.0.30'

多くのスタンバイがいる場合はmax_wal_sendersも設定する必要があります。max_wal_sendersのデフォルト値は10です。スタンバイ2台では10で十分です。

PostgreSQL：ドキュメント：レプリケーションも参照してください。

/etc/postgresql/16/main/postgresql.conf:

変更前：

#listen_addresses = 'localhost'

変更後：

listen_addresses = 'localhost,192.168.0.30'

プライマリーでだけ以下のストリーミングレプリケーション用の設定をpg_hba.confに追加します。

192.168.0.0/24からのレプリケーションユーザーreplicatorでのレプリケーション接続を許可します。

/etc/postgresql/16/main/pg_hba.conf:

変更前：

local   replication     all                                     peer
host    replication     all             127.0.0.1/32            scram-sha-256
host    replication     all             ::1/128                 scram-sha-256

変更後：

local   replication     all                                     peer
host    replication     all             127.0.0.1/32            scram-sha-256
host    replication     all             ::1/128                 scram-sha-256
host    replication     all             192.168.0.0/24          scram-sha-256

プライマリーでだけレプリケーションユーザーを作成します。

$ sudo -u postgres -H createuser --pwprompt --replication replicator
Enter password for new role: (passw0rd)
Enter it again: (passw0rd)

[固有] プライマリーでPGroonga用にPostgreSQLを設定する

これはPGroonga固有の手順です。

PGroongaのWALリソースマネージャー関連の設定とクラッシュセーフ関連の設定を追加する必要があります。

PGroonga WALリソースマネージャー用にはpgroonga_wal_resource_managerモジュールをshared_preload_librariesパラメーターに追加してpgronga.enable_wal_resource_manager = onも追加する必要があります。

クラッシュセーフ用には、pgroonga_crash_saferモジュールをshared_preload_librariesパラメーターに追加してpgroonga.enable_crash_safe = onも追加する必要があります。

注意：pgroonga_crash_saferモジュールを使うと書き込み性能が低下します。メンテナンス性と性能のトレードオフがあります。最大の書き込み性能が必要な場合はこのモジュールを使えません。このトレードオフについてはクラッシュセーフも参照してください。

/etc/postgresql/16/main/postgresql.conf:

変更前：

#shared_preload_libraries = ''

変更後：

shared_preload_libraries = 'pgroonga_wal_resource_manager,pgroonga_crash_safer'

/etc/postgresql/16/main/conf.d/pgroonga.conf:

pgroonga.enable_wal_resource_manager = on
pgroonga.enable_crash_safe = on

pgroonga_crash_saferモジュールを使わない場合は、shared_preload_librariesからpgroonga_crash_saferを除いて、pgroonga.enable_crash_safe = onも消します。

この設定を反映するためにPostgreSQLを再起動します。

sudo -H systemctl restart postgresql

[通常] プライマリーでデータを挿入する

これは通常の手順です。

プライマリーでだけ一般ユーザーを作成します。

sudo -u postgres -H createuser ${USER}

プライマリーでだけデータベースを作成します。

sudo -u postgres -H createdb --template template0 --locale C --encoding UTF-8 --owner ${USER} blog

プライマリーでだけ作成したデータベースにテーブルを追加します。

作成したblogデータベースに接続します。

psql blog

entriesテーブルを作成します。

CREATE TABLE entries (
  title text,
  body text
);

作成したentriesテーブルにデータを追加します。

INSERT INTO entries VALUES ('PGroonga', 'PGroonga is a PostgreSQL extension for fast full text search that supports all languages. It will help us.');
INSERT INTO entries VALUES ('Groonga', 'Groonga is a full text search engine used by PGroonga. We did not know about it.');
INSERT INTO entries VALUES ('PGroonga and replication', 'PGroonga 3.2.1 supports custom WAL resource manager. We should try it!');

[固有] プライマリーでPGroongaのインデックスを作成する

これはPGroonga固有の手順です。

このデータベースにPGroongaをインストールします。スーパーユーザー権限が必要です。

sudo -u postgres -H psql blog --command "CREATE EXTENSION pgroonga;"
sudo -u postgres -H psql blog --command "GRANT USAGE ON SCHEMA pgroonga TO ${USER};"

再度一般ユーザーでPostgreSQLに接続します。

psql blog

プライマリーでPGroongaのインデックスを作成します。

CREATE INDEX entries_full_text_search ON entries USING pgroonga (title, body);

作成したインデックスを確認します。

SET enable_seqscan TO off;
SELECT title FROM entries WHERE title &@~ 'replication';
--           title           
-- --------------------------
--  PGroonga and replication
-- (1 row)

[固有] プライマリーでだけPGroonga関連のデータをフラッシュする

これはPGroonga固有の手順です。

プライマリーでだけメモリー上にあるPGroonga関連のデータを確実にディスクに書き出します。以下のどれかの方法を使います。

SELECT pgroonga_command('io_flush');を実行する
すべての接続を切断する

pgroonga_command('io_flush')を使う場合は次のようになります。

SELECT pgroonga_command('io_flush') AS command;
--                     command                    
-- -----------------------------------------------
--  [[0,1478446349.2241,0.1413860321044922],true]
-- (1 row)

プライマリーでは、次のpg_basebackupの手順が終わるまではPGroongaのインデックスを使っているテーブルを変更してはいけません。

[通常] スタンバイで`pg_basebackup`を実行する

これは通常の手順です。

スタンバイでだけpg_basebackupを実行します。pg_basebackupはプライマリーから現在のデータベースをコピーします。

スタンバイ：

sudo -H systemctl stop postgresql
sudo -u postgres -H rm -rf /var/lib/postgresql/16/main

スタンバイ1：

WALの管理がシンプルになるのでレプリケーションスロットを使うべきです。

--create-slot
--slot standby1
- standby1は例です。わかりやすい名前を設定してください

$ sudo -u postgres -H pg_basebackup --create-slot --slot standby1 \
  --host 192.168.0.30 --pgdata /var/lib/postgresql/16/main --progress --username replicator --write-recovery-conf
Password: (passw0rd)
158949/158949 kB (100%), 1/1 tablespace

スタンバイ2：

WALの管理がシンプルになるのでレプリケーションスロットを使うべきです。

--create-slot
--slot standby2
- standby2は例です。わかりやすい名前を設定してください

$ sudo -u postgres -H pg_basebackup --create-slot --slot standby2 \
  --host 192.168.0.30 --pgdata /var/lib/postgresql/16/main --progress --username replicator --write-recovery-conf
Password: (passw0rd)
158949/158949 kB (100%), 1/1 tablespace

[固有] スタンバイでPGroonga用にPostgreSQLを設定する

これはPGroonga固有の手順です。

次のモジュールをshared_preload_librariesパラメーターに追加します。

pgroonga_wal_resource_managerモジュール

注意: スタンバイではpgroonga_crash_saferは必要ありません。pgroonga_wal_resource_managerモジュールはクラッシュリカバリーもできます。

スタンバイ：

/etc/postgresql/16/main/postgresql.conf:

変更前：

#shared_preload_libraries = ''

変更後：

shared_preload_libraries = 'pgroonga_wal_resource_manager'

[通常] スタンバイでPostgreSQLを起動する

これは通常の手順です。

スタンバイでPostgreSQLを起動します。

sudo -H systemctl start postgresql

これで、プライマリーで挿入したデータをプライマリーで作成したPGroongaのインデックスで検索できます。

スタンバイ1：

SET enable_seqscan TO off;
SELECT title FROM entries WHERE title &@~ 'replication';
--           title           
-- --------------------------
--  PGroonga and replication
-- (1 row)

pg_basebacup以降にプライマリーで追加したデータも検索できます。

プライマリー：

INSERT INTO entries VALUES ('PostgreSQL 15 and replication', 'PostgreSQL supports custom WAL resource manager since 15.');

スタンバイ1：

SELECT title FROM entries WHERE title &@~ 'replication';
-              title              
-- -------------------------------
--  PGroonga and replication
--  PostgreSQL 15 and replication
-- (2 rows)

スタンバイ2：

SET enable_seqscan TO off;
SELECT title FROM entries WHERE title &@~ 'replication';
--             title              
-- -------------------------------
--  PGroonga and replication
--  PostgreSQL 15 and replication
-- (2 rows)

WALリソースマネージャーを使ったストリーミングレプリケーション

概要

[通常] プライマリーとスタンバイでPostgreSQLをインストールする

[固有] プライマリーとスタンバイでPGroongaをインストールする

[通常] プライマリーでストリーミングレプリケーション用にPostgreSQLを設定する

[固有] プライマリーでPGroonga用にPostgreSQLを設定する

[通常] プライマリーでデータを挿入する

[固有] プライマリーでPGroongaのインデックスを作成する

[固有] プライマリーでだけPGroonga関連のデータをフラッシュする

[通常] スタンバイでpg_basebackupを実行する

[固有] スタンバイでPGroonga用にPostgreSQLを設定する

[通常] スタンバイでPostgreSQLを起動する

[通常] スタンバイで`pg_basebackup`を実行する