Ubuntu版のPostgresqlで利用できる便利な pg_*cluster コマンドについて

毎度、ググっても出てこない小ネタを取り扱っております。
本記事は個人的な見解であり、筆者の所属するいかなる団体にも関係ございません。

# 0. はじめに

Ubuntu版 PostgreSQL はコミュニティ版のPostgresqlとは違って、pg_*cluster[s]コマンドというのがあります。Ubuntu 上で複数のバージョンのPostgresqlを動かしたり、バックアップできたりリストアできたり、アップグレードできたり、DBを作ったり削除したりできるので、便利なのですが、あまり解説されてないようなのでちょっとまとめてみたいと思います。



# 1. どんなコマンドがあるか

以下のようなコマンドがあります。

```
/usr/bin/pg_backupcluster
/usr/bin/pg_createcluster
/usr/bin/pg_ctlcluster
/usr/bin/pg_dropcluster
/usr/bin/pg_renamecluster
/usr/bin/pg_restorecluster
/usr/bin/pg_upgradecluster
/usr/bin/pg_lsclusters
```

Sonnet3.5にまとめてもらいました。

| コマンド名 | 機能概要 |
|------------|----------|
| pg_lsclusters | システム上のPostgreSQLクラスタの一覧を表示 |
| pg_createcluster | 新しいPostgreSQLクラスタを作成 |
| pg_ctlcluster | PostgreSQLクラスタの起動、停止、再起動、状態確認などの制御を実行 |
| pg_dropcluster | 既存のPostgreSQLクラスタを削除 |
| pg_renamecluster | PostgreSQLクラスタの名前を変更 |
| pg_backupcluster | PostgreSQLクラスタのバックアップを作成 |
| pg_restorecluster | バックアップからPostgreSQLクラスタを復元 |
| pg_upgradecluster | PostgreSQLクラスタを新しいメジャーバージョンにアップグレード |

これらのコマンドは、Debian/Ubuntuディストリビューション特有のPostgreSQLクラスタ管理ツールであり、システム管理者がPostgreSQLの運用管理を効率的に行うために使用します。

補足：
- これらのコマンドは通常、rootユーザーまたはsudo権限を持つユーザーが実行します。
- クラスタとは、PostgreSQLのデータベースインスタンスとその設定を含む一連のファイル群を指します。

# 2. 各コマンドについての説明

## 2-1. pg_lsclusters

システム上の全PostgreSQLクラスタの一覧と状態を表示します。

### 使い方
```bash
pg_lsclusters
```
出力例：
```io
Ver Cluster Port Status Owner    Data directory              Log file
14  main    5432 online postgres /var/lib/postgresql/14/main log/postgresql-%Y-%m-%d_%H%M%S.log
16  main    5433 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log
```

### オプション

pg_lsclustersのオプションは以下の通りです。

```bash
Usage: /usr/bin/pg_lsclusters [-hjs]

Options:
  -h --no-header   Omit column headers in output
  -j --json        JSON output
  -s --start-conf  Include start.conf information in status column
     --help        Print help
```

## 2-2. pg_createcluster

新しいPostgreSQLクラスタを作成します。

### 使い方
```bash
pg_createcluster [バージョン] [クラスタ名]
```
例：
```bash
pg_createcluster 14 test_cluster
```

### オプション

```bash
Usage: /usr/bin/pg_createcluster [options] <version> <cluster name> [-- <initdb options>]

Options:
  -u <uid>      cluster owner and superuser (default: 'postgres')
  -g <gid>      group for data files (default: primary group of owner)
  -d <dir>      data directory (default:
                /var/lib/postgresql/<version>/<cluster name>)
  -s <dir>      socket directory (default: /var/run/postgresql for clusters
                owned by 'postgres', /tmp for other clusters)
  -l <dir>      path to desired log file (default:
                /var/log/postgresql/postgresql-<version>-<cluster>.log)
  --locale <encoding>
                set cluster locale (default: inherit from environment)
  --lc-collate/ctype/messages/monetary/numeric/time <locale>
                like --locale, but only set for a particular category
  -e <encoding> Default encoding (default: derived from locale)
  -p <port>     port number (default: next free port starting from 5432)
  --start       start the cluster after creating it
  --start-conf auto|manual|disabled
                Set automatic startup behaviour in start.conf (default: 'auto')
  --createclusterconf=file alternative createcluster.conf to use
  --environment=file alternative environment file to use
  <initdb options> other options to pass to initdb
  ```

## 2-3. pg_ctlcluster

PostgreSQLクラスタの制御（起動、停止、再起動など）を行います。

### 使い方
```bash
pg_ctlcluster [バージョン] [クラスタ名] [アクション] [-- <pg_ctl options>]
```
例：
```bash
pg_ctlcluster 14 main start   # 起動
pg_ctlcluster 14 main stop    # 停止
pg_ctlcluster 14 main restart # 再起動
pg_ctlcluster 14 main status  # 状態確認
```

## 2-4. pg_dropcluster

既存のPostgreSQLクラスタを完全に削除します。

### 使い方
```bash
pg_dropcluster [バージョン] [クラスタ名] [--stop]
```
例：
```bash
pg_dropcluster 14 test_cluster --stop
```

## 2-5. pg_renamecluster

既存のPostgreSQLクラスタの名前を変更します。

### 使い方
```bash
pg_renamecluster [OPTIONS] [バージョン] [旧クラスタ名] [新クラスタ名]
```
例：
```bash
pg_renamecluster 14 old_name new_name
```

## 2-6. pg_backupcluster

PostgreSQLクラスタの完全バックアップを作成します。

### 使い方
```bash
pg_backupcluster [options] [バージョン] [クラスタ名] [アクション]
```

```bash
Syntax: /usr/bin/pg_backupcluster [options] <version> <cluster> <action>
Actions:
  createdirectory        Create /var/backups/version-cluster
  basebackup             Backup using pg_basebackup
  dump                   Backup using pg_dump
  expiredumps <N>        Remove all but last N dumps
  expirebasebackups <N>  Remove all but last N basebackups
  receivewal             Launch pg_receivewal
  compresswal            Compress WAL files in archive
  archivecleanup         Remove obsolete WAL files from archive
  list                   Show dumps, basebackups, and WAL
Options:
  -c --checkpoint <spread|fast>  Passed to pg_basebackup
  -k --keep-on-error     Keep faulty backup directory on error
  -v --verbose           Verbose output
```


## 2-7. pg_restorecluster

バックアップからPostgreSQLクラスタを復元します。

### 使い方
```bash
pg_restorecluster [options] [バージョン] [クラスタ名] [バックアップパス]
```
例：
```bash
pg_restorecluster 14 main
```

### オプション

```bash
Syntax: /usr/bin/pg_restorecluster [options] <version> <cluster> <backup>
Options:
  -d --datadir DIR  Data directory for restored cluster (default per createcluster.conf)
  -p --port PORT    Use port PORT for restored cluster (default is next free port)
  -s --start        Start cluster after restoring (default for restore from dump)
     --archive      Configure recovery from WAL archive
     --pitr TIMEST  Configure point-in-time recovery to TIMESTAMP from WAL archive
     --wal-archive DIR  Read WAL from archive DIR (default <backup>/../wal)
```

## 2-8. pg_upgradecluster

PostgreSQLクラスタを新しいメジャーバージョンにアップグレードします。

### 使い方
```bash
pg_upgradecluster [旧バージョン] [クラスタ名] [<new data directory>]
```
例：
```bash
pg_upgradecluster 13 main
```

補足事項：
- これらのコマンドは通常、root権限またはsudo権限が必要です
- クラスタ操作前にはデータのバックアップを推奨します
- 実行前に`pg_lsclusters`でクラスタの状態を確認することを推奨します
- 本番環境での操作は十分な検証と計画の後に実施してください

# 3. まとめ

コマンドの説明でした。

別記事で、
1. バックアップ
1. アップグレード
を実践してみたいと思います。

# 4. 参照

Ubuntu版 PostgreSQL と コミュニティ版 PostgreSQLの違いのまとめ \#Ubuntu \- Qiita 
https://qiita.com/etaka/items/7e4e392561b5c8109098