インストール

本章ではPG-Stromのインストール手順について説明します。

チェックリスト

• ハードウェア
  • CUDA ToolkitのサポートするLinuxオペレーティングシステムを動作可能な x86_64 アーキテクチャのハードウェアが必要です。
  • CPU、ストレージ、およびネットワークデバイスには特別な要件はありませんが、note002:HW Validation Listはハードウェア選定の上で参考になるかもしれません。
  • GPUダイレクトSQL実行を利用するにはNVME規格に対応したSSD、またはRoCEに対応した高速NICが必要で、GPUと同一のPCIe Root Complex配下に接続されている必要があります。
• GPUデバイス
  • PG-Stromを実行するには少なくとも一個のGPUデバイスがシステム上に必要です。これらはCUDA Toolkitでサポートされており、computing capability が7.5以降のモデル（Turing世代以降）である必要があります。
  • 002: HW Validation List - List of supported GPU modelsを参考にGPUを選定してください。
• Operating System
  • PG-Stromの実行には、CUDA Toolkitによりサポートされているx86_64アーキテクチャ向けのLinux OSが必要です。推奨環境はRed Hat Enterprise LinuxまたはRocky Linuxバージョン 10.x、9.x、または8.xです。
  • GPUダイレクトSQL（cuFileドライバ）を利用するには、CUDA Toolkitに含まれるnvidia-fsドライバと、Mellanox OFED (OpenFabrics Enterprise Distribution) ドライバのインストールが必要です。
• PostgreSQL
  • PG-Strom v6.1の実行にはPostgreSQLバージョン15以降が必要です。
  • PG-Stromが内部的に利用しているAPIの中には、これ以前のバージョンでは提供されていないものが含まれています。
• CUDA Toolkit
  • PG-Stromの実行にはCUDA Toolkit バージョン13.0以降が必要です。
  • PG-Stromが内部的に利用しているAPIの中には、これ以前のバージョンでは提供されていないものが含まれています。

インストール手順

一連のインストール手順は以下の通りとなります。

1. H/Wの初期設定
2. OSのインストール
3. MOFEDドライバのインストール
4. CUDA Toolkit のインストール
5. HeteroDB拡張モジュールのインストール
6. PostgreSQLのインストール
7. PG-Stromのインストール
8. PostgreSQL拡張モジュールのインストール（必要に応じて）
   • PostGIS
   • contrib/cube

OSのインストール

CUDA ToolkitのサポートするLinuxディストリビューションを選択し、個々のディストリビューションのインストールプロセスに従ってインストール作業を行ってください。 CUDA ToolkitのサポートするLinuxディストリビューションは、NVIDIA DEVELOPER ZONEにおいて紹介されています。

Red Hat Enterprise Linux 8.x系列（Rocky Linux 8.x系列を含む）の場合、ソフトウェア構成は、ベース環境として「最小限のインストール」を選択し、さらに追加のソフトウェアとして「開発ツール」を選択してください。

Red Hat Enterprise Linux 9.x系列（Rocky Linux 9.x系列を含む）の場合、ソフトウェア構成は、ベース環境として「最小限のインストール」を選択し、さらに追加のソフトウェアとして「標準」「開発ツール」を選択してください。

Red Hat Enterprise Linux 10.x系列（Rocky Linux 10.x系列を含む）の場合、ソフトウェア構成は、ベース環境として「最小限のインストール」を選択し、さらに追加のソフトウェアとして「標準」「開発ツール」を選択してください。

サーバーへのOSインストール後、サードパーティーのパッケージをインストールするために、パッケージリポジトリの設定を行います。

なお、インストーラで「開発ツール」を選択しなかった場合、以下のコマンドでOSインストール後に追加インストールする事が可能です。

# dnf groupinstall 'Development Tools'

IOMMUの無効化

GPU-Direct SQLはCUDAのGPUDirect Storage (cuFile)というAPIを使用しています。

GPUDirect Storageの利用に先立って、OS側でIOMMUの設定を無効化する必要があります。

NVIDIA GPUDirect Storage Installation and Troubleshooting Guideの記述を参考に、カーネル起動オプションの設定を行ってください。

IOMMUを無効化するには、カーネル起動オプションにamd_iommu=off (AMD製CPUの場合)または、intel_iommu=off (Intel製CPUの場合)の設定を付加します。

RHEL9/RHEL10における設定

以下のコマンドを実行し、カーネル起動オプションを追加してください。

# grubby --update-kernel=ALL --args="amd_iommu=off"

RHEL8における設定

エディタで/etc/default/grubを編集し、GRUB_CMDLINE_LINUX_DEFAULT=行に上記のオプションを付加してください。

例えば、以下のような設定となるはずです。

  :
GRUB_CMDLINE_LINUX="rhgb quiet amd_iommu=off"
  :

以下のコマンドを実行し、この設定をカーネル起動オプションに反映します。

-- for BIOS based system
# grub2-mkconfig -o /boot/grub2/grub.cfg
# shutdown -r now

-- for UEFI based system
# grub2-mkconfig -o /boot/efi/EFI/redhat/grub.cfg
# shutdown -r now

nouveauドライバの無効化

NVIDIA製GPU向けオープンソースの互換ドライバであるnouveauドライバがロードされている場合、nvidiaドライバをロードする事ができません。 この場合は、nouveauドライバの無効化設定を行った上でシステムを一度再起動してください。

nouveauドライバを無効化するには、以下の設定を/etc/modprobe.d/disable-nouveau.confという名前で保存し、dracutコマンドを実行してLinux kernelのブートイメージに反映します。 その後、システムを一度再起動してください。

# cat > /etc/modprobe.d/disable-nouveau.conf <<EOF
blacklist nouveau
options nouveau modeset=0
EOF
# dracut -f
# shutdown -r now

追加リポジトリの有効化

EPEL(Extra Packages for Enterprise Linux)

PG-Stromの実行に必要なソフトウェアモジュールのいくつかは、EPEL(Extra Packages for Enterprise Linux)の一部として配布されています。 これらのソフトウェアを入手するためにEPELパッケージ群のリポジトリ定義をyumシステムに追加する必要があります。

EPELリポジトリから入手するパッケージの一つがDKMS(Dynamic Kernel Module Support)です。これは動作中のLinuxカーネルに適合したLinuxカーネルモジュールをオンデマンドでビルドするためのフレームワークで、NVIDIAのGPUデバイスドライバなど関連するカーネルモジュールが使用しています。 Linuxカーネルモジュールは、Linuxカーネルのバージョンアップに追従して再ビルドが必要であるため、DKMSなしでのシステム運用は現実的ではありません。

EPELリポジトリの定義は epel-release パッケージにより提供され、Fedora Projectのサイトから入手する事ができます。

-- For RHEL10
# dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-10.noarch.rpm

-- For RHEL9
# dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm

-- For RHEL8
# dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

-- For Rocky8/Rocky9
# dnf install epel-release

Red Hat CodeReady Linux Builder

MOFED（Mellanox OpenFabrics Enterprise Distribution）ドライバのインストールには、Red Hat Enterprise Linux 8.xの標準インストール構成では無効化されている Red Hat CodeReady Linux Builder リポジトリを有効化する必要があります。Rokey Linuxにおいては、このリポジトリは PowerTools と呼ばれています。

このリポジトリを有効化するには、以下のコマンドを実行します。

-- For RHEL10
# subscription-manager repos --enable codeready-builder-for-rhel-10-x86_64-rpms

-- For RHEL9
# subscription-manager repos --enable codeready-builder-for-rhel-9-x86_64-rpms

-- For Rocky9/Rocky10
# dnf config-manager --set-enabled crb

-- For RHEL8
# subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms

-- For Rocky8
# dnf config-manager --set-enabled powertools

DOCA(OFED)ドライバのインストール

NVME-SSDからの直接データ読み出し（GPU-Direct SQL）を使用するには、DOCA(OFED)モジュールに含まれるnvmeドライバによって、OS標準のINBOXドライバを置き換える必要があります。 本節では、DOCA(OFED)モジュールの導入方法を説明します。

なお、DOCA(OFED)モジュールの公式インストール手順はこちらとなります。

リポジトリ定義の追加

以下のようにDOCAのリポジトリ定義を追加します。 RHEL8/9系列の場合、${releasever_major}および${releasever_minor}マクロが使用できないため、OSのバージョンを直接記入します。

RHEL10の場合の設定例

# cat > /etc/yum.repos.d/doca.repo <<EOF
[doca]
name=DOCA Online Repo
baseurl=https://linux.mellanox.com/public/repo/doca/latest/rhel\${releasever_major}.\${releasever_minor}/\${basearch}/
enabled=1
gpgcheck=0
EOF

RHEL9の場合の設定例

# cat > /etc/yum.repos.d/doca.repo <<EOF
[doca]
name=DOCA Online Repo
baseurl=https://linux.mellanox.com/public/repo/doca/latest/rhel9.6/\${basearch}/
enabled=1
gpgcheck=0
EOF

DOCAパッケージのインストール

NVIDIAから配布されているDOCAパッケージのうち、必要なものをインストールします。 以下の例の通り、kernel-module-extra-<KERNEL VERSION>（インストール済みであるはず）と、doca-ofedおよびdoca-extraをインストールしてください。

# dnf install -y kernel-modules-extra-$(uname -r)
# dnf install -y doca-ofed doca-extra

NVMEドライバのビルド

NVIDIAから配布されているDOCA(OFED)パッケージにもnvmeドライバは含まれているのですが、 このドライバはGPU-Direct Storageの有効化に必要な--with-gdsオプション付きでビルド されていません。

そのため、このままではGPU-Direct SQLを実行できないため、ドライバの再コンパイルを行います。 手順はスクリプト化されており、以下のように/opt/mellanox/doca/tools/doca-kernel-supportを 実行します。

# /opt/mellanox/doca/tools/doca-kernel-support
doca-kernel-support: Building under /tmp/DOCA.EhUCIyOzbU
           :
doca-kernel-support: Rebuilding kernel modules
doca-kernel-support: Building mlnx-ofa_kernel under /tmp/DOCA.EhUCIyOzbU/build/mlnx-ofa_kernel with log /tmp/DOCA.EhUCIyOzbU/logs/mlnx-ofa_kernel.log
doca-kernel-support: Building iser under /tmp/DOCA.EhUCIyOzbU/build/iser with log /tmp/DOCA.EhUCIyOzbU/logs/iser.log
doca-kernel-support: Building isert under /tmp/DOCA.EhUCIyOzbU/build/isert with log /tmp/DOCA.EhUCIyOzbU/logs/isert.log
doca-kernel-support: Building srp under /tmp/DOCA.EhUCIyOzbU/build/srp with log /tmp/DOCA.EhUCIyOzbU/logs/srp.log
doca-kernel-support: Building mlnx-nfsrdma under /tmp/DOCA.EhUCIyOzbU/build/mlnx-nfsrdma with log /tmp/DOCA.EhUCIyOzbU/logs/mlnx-nfsrdma.log
doca-kernel-support: Building mlnx-nvme under /tmp/DOCA.EhUCIyOzbU/build/mlnx-nvme with log /tmp/DOCA.EhUCIyOzbU/logs/mlnx-nvme.log
doca-kernel-support: Building virtiofs under /tmp/DOCA.EhUCIyOzbU/build/virtiofs with log /tmp/DOCA.EhUCIyOzbU/logs/virtiofs.log
doca-kernel-support: Building knem under /tmp/DOCA.EhUCIyOzbU/build/knem with log /tmp/DOCA.EhUCIyOzbU/logs/knem.log
doca-kernel-support: Building xpmem under /tmp/DOCA.EhUCIyOzbU/build/xpmem with log /tmp/DOCA.EhUCIyOzbU/logs/xpmem.log
doca-kernel-support: Building kernel-mft under /tmp/DOCA.EhUCIyOzbU/build/kernel-mft with log /tmp/DOCA.EhUCIyOzbU/logs/kernel-mft.log
doca-kernel-support: Creating a rpm meta package:
doca-kernel-support: Creating a package repository in /tmp/DOCA.EhUCIyOzbU/repo/usr/share/doca-host-25.07-0.9.7.0/Modules/6.12.0-55.41.1.el10_0.x86_64
doca-kernel-support: Built single package: /tmp/DOCA.EhUCIyOzbU/doca-kernel-repo-25.07.0.9.7.0-1.kver.6.12.0.55.41.1.el10.0.x86.64.x86_64.rpm
doca-kernel-support: Done
Now you should install the generated single repository package to make its
files available:

  rpm -Uvh /tmp/DOCA.EhUCIyOzbU/doca-kernel-repo-25.07.0.9.7.0-1.kver.6.12.0.55.41.1.el10.0.x86.64.x86_64.rpm

After installing the package, doca-kernel-6.12.0.55.41.1.el10.0.x86.64 metapackage should be available.

Next steps could probably be:
  dnf makecache

Then, install ofed packages (e.g. doca-all, doca-ofed):
        dnf install doca-ofed-userspace
        dnf install --disablerepo=doca doca-kernel-6.12.0.55.41.1.el10.0.x86.64

スクリプトが正常終了すると、この次に行うべき処理を提示してくれます。 まず、再ビルドしたkernel moduleを含むローカルリポジトリを構築するためにdoca-kernel-<KERNEL_VERSION>を インストールします。

[root@saba~]# rpm -Uvh /tmp/DOCA.EhUCIyOzbU/doca-kernel-repo-25.07.0.9.7.0-1.kver.6.12.0.55.41.1.el10.0.x86.64.x86_64.rpm
Verifying...                          ################################# [100%]
Preparing...                          ################################# [100%]
Updating / installing...
   1:doca-kernel-repo-25.07.0.9.7.0-1.################################# [100%]

次いで、doca-kernel-supportスクリプトの指示に従ってdoca-kernel-<KERNEL_VERSION>および、 kmod-mlnx-nvmeとkmod-mlnx-nfsrdmaパッケージをインストールします。

# dnf makecache
# dnf install doca-ofed-userspace
# dnf install --disablerepo=doca doca-kernel-6.12.0.55.41.1.el10.0.x86.64
# dnf install --disablerepo=doca kmod-mlnx-nvme kmod-mlnx-nfsrdma

modinfoコマンドを用いてnvmeモジュールの情報を出力してみます。 このカーネルモジュールがextra/mlnx-nvme/hostディレクトリ配下にインストールされていれば成功です。 （OS標準のINBOXドライバはkernel/drivers/nvme/host配下に格納されています。）

# modinfo nvme
filename:       /lib/modules/6.12.0-55.41.1.el10_0.x86_64/extra/mlnx-nvme/host/nvme.ko
description:    NVMe host PCIe transport driver
version:        1.0
license:        GPL
author:         Matthew Wilcox <willy@linuxintel.com>
rhelversion:    10.0
srcversion:     951B0D9C33E4E9A9D30FF50
alias:          pci:v*d*sv*sd*bc01sc08i02*
alias:          pci:v0000106Bd00002005sv*sd*bc*sc*i*
           :

dracutコマンドでブートイメージを更新し、新しいnvmeドライバを反映させるためにシステムを再起動します。

# dracut -f
# shutdown -r now

CUDA Toolkitのインストール

本節ではCUDA Toolkitのインストールについて説明します。 既に最新のCUDA Toolkitをインストール済みである場合、本節の初期設定と合致しているかどうか確認してください。

NVIDIAはCUDA Toolkitのインストールに２通りの方法を提供しています。一つは自己実行型アーカイブ（runfile）によるもの。もう一つはRPMパッケージによるもので、PG-StromのセットアップにはRPMパッケージによるインストールを推奨します。

CUDA Toolkitのインストール用パッケージはNVIDIA DEVELOPER ZONEからダウンロードする事ができます。 適切なOS、アーキテクチャ、ディストリビューション、バージョンを指定し、『rpm(network)』版を選択してください。

『rpm(network)』を選択すると、リポジトリを登録し、ネットワーク経由でパッケージをインストールするためのシェルコマンドが表示されます。ガイダンス通りにインストールを進めてください。 以下の例は、RHEL10にCUDA Toolkit 13をインストールするものです。

# dnf config-manager --add-repo https://developer.download.nvidia.com/compute/cuda/repos/rhel10/x86_64/cuda-rhel10.repo
# dnf clean all
# dnf install cuda-toolkit-13-0
# dnf install nvidia-gds-13-0

CUDA Toolkitのインストールに続いて、ドライバをインストールのためのコマンドが２種類表示されています。 ここではオープンソース版のnvidia-driverを使用してください。オープンソース版のみがGPUDirect Storage機能をサポートしており、PG-StromのGPU-Direct SQLは本機能を利用しています。

続いて、GPU-Direct Storage(GDS)を利用するためのドライバモジュールnvidia-gdsをインストールします。 パッケージ名に続いてCUDA Toolkitのバージョンと同一のバージョン名を指定してください。

-- For RHEL9
# dnf module install nvidia-driver:open-dkms
-- For RHEL10
# dnf install nvidia-open

正常にインストールが完了すると、/usr/local/cuda配下にCUDA Toolkitが導入されています。

# ls /usr/local/cuda/
bin                             extras   man               share
compute-sanitizer               gds      nsightee_plugins  src
CUDA_Toolkit_Release_Notes.txt  include  nvml              targets
DOCS                            lib64    nvvm              tools
EULA.txt                        LICENSE  README            version.json

インストールが完了したら、GPUが正しく認識されている事を確認してください。nvidia-smiコマンドを実行すると、以下の出力例のように、システムに搭載されているGPUの情報が表示されます。

# nvidia-smi
Tue Oct 28 14:22:43 2025
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 580.95.05              Driver Version: 580.95.05      CUDA Version: 13.0     |
+-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA H100 PCIe               Off |   00000000:42:00.0 Off |                    0 |
| N/A   37C    P0             48W /  350W |       0MiB /  81559MiB |      0%      Default |
|                                         |                        |             Disabled |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI              PID   Type   Process name                        GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|  No running processes found                                                             |
+-----------------------------------------------------------------------------------------+

# dnf install nvidia-fabricmanager
# systemctl enable nvidia-fabricmanager.service
# systemctl start nvidia-fabricmanager.service

GPUDirect Storageの確認

上記の手順でCUDA Toolkitのインストールが完了すると、GPUDirect Storageが利用可能な状態となっているはずです。 以下の通り、gdscheckツールを用いてストレージデバイス毎のコンフィグを確認してください。 （この例では、nvmeだけでなく、nvme-rdmaやrpcrdmaカーネルモジュールもロードしているため、関連する機能がSupportedとなっています）

# /usr/local/cuda/gds/tools/gdscheck -p
 GDS release version: 1.15.1.6
 nvidia_fs version:  2.26 libcufile version: 2.12
 Platform: x86_64
 ============
 ENVIRONMENT:
 ============
 =====================
 DRIVER CONFIGURATION:
 =====================
 NVMe P2PDMA        : Unsupported
 NVMe               : Supported
 NVMeOF             : Unsupported
 SCSI               : Unsupported
 ScaleFlux CSD      : Unsupported
 NVMesh             : Unsupported
 DDN EXAScaler      : Unsupported
 IBM Spectrum Scale : Unsupported
 NFS                : Supported
 BeeGFS             : Unsupported
 ScaTeFS            : Unsupported
 WekaFS             : Unsupported
 Userspace RDMA     : Unsupported
 --Mellanox PeerDirect : Disabled
 --rdma library        : Not Loaded (libcufile_rdma.so)
 --rdma devices        : Not configured
 --rdma_device_status  : Up: 0 Down: 0
 =====================
 CUFILE CONFIGURATION:
 =====================
 properties.use_pci_p2pdma : false
 properties.use_compat_mode : true
 properties.force_compat_mode : false
 properties.gds_rdma_write_support : true
 properties.use_poll_mode : false
 properties.poll_mode_max_size_kb : 4
 properties.max_batch_io_size : 128
 properties.max_batch_io_timeout_msecs : 5
 properties.max_direct_io_size_kb : 16384
 properties.max_device_cache_size_kb : 131072
 properties.per_buffer_cache_size_kb : 1024
 properties.max_device_pinned_mem_size_kb : 33554432
 properties.posix_pool_slab_size_kb : 4 1024 16384
 properties.posix_pool_slab_count : 128 64 64
 properties.rdma_peer_affinity_policy : RoundRobin
 properties.rdma_dynamic_routing : 0
 fs.generic.posix_unaligned_writes : false
 fs.lustre.posix_gds_min_kb: 0
 fs.beegfs.posix_gds_min_kb: 0
 fs.scatefs.posix_gds_min_kb: 0
 fs.weka.rdma_write_support: false
 fs.gpfs.gds_write_support: false
 fs.gpfs.gds_async_support: true
 profile.nvtx : false
 profile.cufile_stats : 0
 miscellaneous.api_check_aggressive : false
 execution.max_io_threads : 4
 execution.max_io_queue_depth : 128
 execution.parallel_io : true
 execution.min_io_threshold_size_kb : 8192
 execution.max_request_parallelism : 4
 properties.force_odirect_mode : false
 properties.prefer_iouring : false
 =========
 GPU INFO:
 =========
 GPU index 0 NVIDIA H100 PCIe bar:1 bar size (MiB):131072 supports GDS, IOMMU State: Disabled
 ==============
 PLATFORM INFO:
 ==============
 IOMMU: disabled
 Nvidia Driver Info Status: Supported(Nvidia Open Driver Installed)
 Cuda Driver Version Installed:  13000
 Platform: AS -2015CS-TNR, Arch: x86_64(Linux 6.12.0-55.41.1.el10_0.x86_64)
 Platform verification succeeded

PCI Bar1メモリの設定

GPU-Direct SQLは、GPUデバイスメモリをホストシステム上のPCI BAR1領域（物理アドレス空間）にマップし、そこをDestinationとするP2P-RDMA要求をNVME機器に対して行う事で、ロスのない高速なデータ読出しを実現します。

十分な多重度を持ったP2P-RDMAを行うには、GPUがバッファをマップするのに十分なPCI BAR1領域を有している必要があります。大半のGPUではPCI BAR1領域の大きさは固定で、PG-Stromにおいては、それがGPUデバイスメモリのサイズを上回っている製品を推奨しています。

しかし、一部のGPU製品においては『動作モード』を切り替える事でPCI BAR1領域のサイズを切り替える事ができるものが存在します。お使いのGPUがそれに該当する場合は、NVIDIA Display Mode Selector Toolを参照の上、PCI BAR1領域のサイズを最大化するモードへと切り替えてください。

2023年12月時点では、以下のGPUの場合にNVIDIA Display Mode Selector Toolを利用して*Display Offモードへと切り替える必要があります。

• NVIDIA L40S
• NVIDIA L40
• NVIDIA A40
• NVIDIA RTX 6000 Ada
• NVIDIA RTX A6000
• NVIDIA RTX A5500
• NVIDIA RTX A5000

システムに搭載されているGPUのメモリサイズやPCI BAR1サイズを確認するには、nvidia-smi -qコマンドを利用します。以下のように、メモリ関連の状態が表示されます。

$ nvidia-smi -q
        :
    FB Memory Usage
        Total                             : 46068 MiB
        Reserved                          : 685 MiB
        Used                              : 4 MiB
        Free                              : 45377 MiB
    BAR1 Memory Usage
        Total                             : 65536 MiB
        Used                              : 1 MiB
        Free                              : 65535 MiB
        :

/etc/cufile.jsonの編集

GPUダイレクトSQLが内部的に利用するcuFileライブラリの設定ファイル /etc/cufile.json を編集します。

JSON形式で記述されたコンフィグのうち、"execution"セクションの"parallel_io"の値をfalseに変更します。

  "execution" : {
          :
      // enable support for parallel IO
      "parallel_io" : false,
          :
  },

HeteroDB 拡張モジュール

PG-Stromほか関連パッケージはHeteroDB Software Distribution Centerから配布されています。 これらのソフトウェアを入手するために、HeteroDB-SWDCのリポジトリ定義をyumシステムに追加する必要があります。

HeteroDB-SWDCリポジトリの定義はheterodb-swdcパッケージにより提供されます。 WebブラウザなどでHeteroDB Software Distribution Centerへアクセスし、ページの先頭にリンクの記載されているheterodb-swdcパッケージをダウンロードしてインストールしてください。（RHEL10の場合はheterodb-swdc-1.3-1.el10.noarch.rpm） heterodb-swdcパッケージがインストールされると、HeteroDB-SWDCからソフトウェアを入手するためのyumシステムへの設定が追加されます。

以下のようにheterodb-swdcパッケージをインストールします。

# dnf install https://heterodb.github.io/swdc/yum/rhel10-noarch/heterodb-swdc-1.3-1.el10.noarch.rpm

heterodb-extraモジュールは、PG-Stromに以下の機能を追加します。

• マルチGPUの対応
• GPUダイレクトSQL
• GiSTインデックス対応
• ライセンス管理機能

これらの機能を使用せず、オープンソース版の機能のみを使用する場合は heterodb-extra モジュールのインストールは不要です。 本節の内容は読み飛ばして構いません。

以下のように、SWDCからheterodb-extraパッケージをインストールしてください。

# dnf install heterodb-extra

ライセンスの有効化

heterodb-extraモジュールの全ての機能を利用するには、HeteroDB社が提供するライセンスの有効化が必要です。ライセンスなしで運用する事も可能ですが、その場合、下記の機能が制限を受けます。

• マルチGPUの利用
• GPUダイレクトSQLにおける複数NVME-SSDによるストライピング(md-raid0)
• GPUダイレクトSQLにおけるNVME-oFデバイスの利用
• GPU版PostGISにおけるGiSTインデックスの利用

ライセンスファイルは以下のような形式でHeteroDB社から入手する事ができます。

IAgIVdKxhe+BSer3Y67jQW0+uTzYh00K6WOSH7xQ26Qcw8aeUNYqJB9YcKJTJb+QQhjmUeQpUnboNxVwLCd3HFuLXeBWMKp11/BgG0FSrkUWu/ZCtDtw0F1hEIUY7m767zAGV8y+i7BuNXGJFvRlAkxdVO3/K47ocIgoVkuzBfLvN/h9LffOydUnHPzrFHfLc0r3nNNgtyTrfvoZiXegkGM9GBTAKyq8uWu/OGonh9ybzVKOgofhDLk0rVbLohOXDhMlwDl2oMGIr83tIpCWG+BGE+TDwsJ4n71Sv6n4bi/ZBXBS498qShNHDGrbz6cNcDVBa+EuZc6HzZoF6UrljEcl=
----
VERSION:2
SERIAL_NR:HDB-TRIAL
ISSUED_AT:2019-05-09
EXPIRED_AT:2019-06-08
GPU_UUID:GPU-a137b1df-53c9-197f-2801-f2dccaf9d42f

これを /etc/heterodb.license にコピーし、PostgreSQLを再起動します。

以下のようにPostgreSQLの起動ログにライセンス情報が出力され、ライセンスの有効化が行われた事が分かります。

    :
 LOG:  HeteroDB Extra module loaded [api_version=20231105,cufile=on,nvme_strom=off,githash=9ca2fe4d2fbb795ad2d741dcfcb9f2fe499a5bdf]
 LOG:  HeteroDB License: { "version" : 2, "serial_nr" : "HDB-TRIAL", "issued_at" : "2022-11-19", "expired_at" : "2099-12-31", "nr_gpus" : 1, "gpus" : [ { "uuid" : "GPU-13943bfd-5b30-38f5-0473-78979c134606" } ]}
 LOG:  PG-Strom version 5.0.1 built for PostgreSQL 15 (githash: 972441dbafed6679af86af40bc8613be2d73c4fd)
    :

PostgreSQLのインストール

本節ではRPMによるPostgreSQLのインストールについて紹介します。 ソースからのインストールに関しては既にドキュメントが数多く存在し、./configureスクリプトのオプションが多岐にわたる事から、ここでは紹介しません。

Linuxディストリビューションの配布するパッケージにもPostgreSQLは含まれていますが、必ずしも最新ではなく、PG-Stromの対応バージョンよりも古いものである事が多々あります。例えば、Red Hat Enterprise Linux 7.xで配布されているPostgreSQLはv9.2.xですが、これはPostgreSQLコミュニティとして既にEOLとなっているバージョンです。

PostgreSQL Global Development Groupは、最新のPostgreSQLおよび関連ソフトウェアの配布のためにyumリポジトリを提供しています。 EPELの設定のように、yumリポジトリの設定を行うだけの小さなパッケージをインストールし、その後、PostgreSQLやその他のソフトウェアをインストールします。

yumリポジトリ定義の一覧は http://yum.postgresql.org/repopackages.php です。

PostgreSQLメジャーバージョンとLinuxディストリビューションごとに多くのリポジトリ定義がありますが、あなたのLinuxディストリビューション向けのPostgreSQL 15以降のものを選択する必要があります。

以下のステップで PostgreSQL のインストールを行います。

• yumリポジトリの定義をインストール
• OS標準のPostgreSQLモジュールの無効化
• PostgreSQLパッケージのインストール

例えばPostgreSQL v18を使用する場合、PG-Stromのインストールにはpostgresql18-serverおよびpostgresql18-develパッケージが必要です。

以下は、RHEL10においてPostgreSQL v18をインストールする手順の例です。

# dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-10-x86_64/pgdg-redhat-repo-latest.noarch.rpm
# dnf install -y postgresql18-devel postgresql18-server

libarrow/libparquetのインストール

PG-Strom v6.1以降では、ビルドとインストールにlibarrowとlibparquetが必要です。

Linuxディストリビューションの提供しているパッケージは古い場合があるため、開発者コミュニティのガイダンスにしたがって、arrow-develパッケージとparquet-develパッケージをインストールしてください。

ここまでのインストール手順との重複を除く、最小インストールに必要なステップは以下の通りです。

$ sudo dnf install -y https://packages.apache.org/artifactory/arrow/almalinux/$(cut -d: -f5 /etc/system-release-cpe | cut -d. -f1)/apache-arrow-release-latest.rpm
$ sudo dnf install -y arrow-devel
$ sudo dnf install -y parquet-devel

PG-Stromのインストール

本節ではPG-Stromのインストール方法について説明します。 推奨はRPMによるインストールですが、開発者向けにソースコードからのビルド方法についても紹介します。

RPMによるインストール

PG-Stromおよび関連パッケージはHeteroDB Software Distribution Centerより配布されています。 既にyumシステムへリポジトリを追加済みであれば、それほど作業は多くありません。

基盤となるPostgreSQLのバージョンごとに別個のPG-StromのRPMパッケージが準備されており、PostgreSQL v17用であればpg_strom-PG17パッケージを、PostgreSQL v18用であればpg_strom-PG18パッケージをインストールします。

これは、PostgreSQL拡張モジュールのバイナリ互換性に伴う制約です。

# dnf install -y pg_strom-PG18

以上でパッケージのインストールは完了です。

ソースからのインストール

開発者向けに、ソースコードからPG-Stromをビルドする方法についても紹介します。

ソースコードの入手

RPMパッケージと同様に、ソースコードのtarballをHeteroDB Software Distribution Centerから入手する事ができます。

ただ、tarballのリリースにはある程度のタイムラグが生じてしまうため、最新の開発版を使いたい場合にはPG-StromのGitHubリポジトリのmasterブランチをチェックアウトする方法の方が好まれるかもしれません。

$ git clone https://github.com/heterodb/pg-strom.git
Cloning into 'pg-strom'...
remote: Counting objects: 13797, done.
remote: Compressing objects: 100% (215/215), done.
remote: Total 13797 (delta 208), reused 339 (delta 167), pack-reused 13400
Receiving objects: 100% (13797/13797), 11.81 MiB | 1.76 MiB/s, done.
Resolving deltas: 100% (10504/10504), done.

PG-Stromのビルド

PG-Stromをビルドする時のコンフィグは、インストール先のPostgreSQLと厳密に一致していなければいけません。例えば、同じ構造体がビルド時のコンフィグによりPostgreSQLとPG-Stromで異なったレイアウトを持ってしまったとすれば、非常に発見の難しいバグを生み出してしまうかもしれません。 したがって、（一貫性のない状態を避けるため）PG-Stromは独自にconfigureスクリプトを走らせたりはせず、pg_configを使ってPostgreSQLのビルド時設定を参照します。

pg_configにパスが通っており、それがインストール先のPostgreSQLのものであれば、そのままmake、make installを実行します。 直接パスが通っていない場合は、makeコマンドにPG_CONFIG=...パラメータを与え、pg_configのフルパスを渡します。

$ cd pg-strom/src
$ make PG_CONFIG=/usr/pgsql-18/bin/pg_config
$ sudo make install PG_CONFIG=/usr/pgsql-18/bin/pg_config

インストール後の設定

データベースクラスタの作成

データベースクラスタの作成が済んでいない場合は、initdbコマンドを実行してPostgreSQLの初期データベースを作成します。

RPMインストールにおけるデフォルトのデータベースクラスタのパスは/var/lib/pgsql/<version number>/dataです。 postgresql-alternativesパッケージをインストールしている場合は、PostgreSQLのバージョンに拠らず/var/lib/pgdataで参照する事ができます。

# su - postgres
$ /usr/pgsql-18/bin/initdb -D /var/lib/pgsql/18/data
            :
Success. You can now start the database server using:

    /usr/pgsql-18/bin/pg_ctl -D /var/lib/pgsql/18/data -l logfile start

postgresql.confの編集

続いて、PostgreSQLの設定ファイルである postgresql.conf を編集します。

PG-Stromを動作させるためには、最低限、以下のパラメータの設定が必要です。 これ以外のパラメータについても、システムの用途や想定ワークロードを踏まえて検討してください。

• shared_preload_libraries
  • PG-Stromモジュールはshared_preload_librariesパラメータによりpostmasterプロセスの起動時にロードされる必要があります。オンデマンドでの拡張モジュールのロードはサポート対象外です。したがって、以下の設定項目は必須です。
  • shared_preload_libraries = '$libdir/pg_strom'
• max_worker_processes
  • PG-Stromは数個のバックグラウンドワーカーを内部的に使用します。そのため、デフォルト値である 8 では、それ以外の処理に利用できるバックグラウンドワーカープロセス数があまりにも少なすぎてしまいます。
  • 以下のように、ある程度の余裕を持った値を設定すべきです。
  • max_worker_processes = 100
• shared_buffers
  • ワークロードによりますが、shared_buffersの初期設定は非常に小さいため、PG-Stromが有効に機能する水準のデータサイズに対しては、ストレージへの読み書きが律速要因となってしまい、GPUの並列計算機能を有効に利用できない可能性があります。
  • 以下のように、ある程度の余裕を持った値を設定すべきです。
  • shared_buffers = 10GB
  • 明らかにメモリサイズよりも大きなデータを処理する必要がある場合は、SSD-to-GPUダイレクトSQL実行の利用を検討してください。
• work_mem
  • ワークロードによりますが、work_memの初期設定は非常に小さいため、解析系クエリで最適なクエリ実行計画が選択されない可能性があります。
  • 典型的な例は、ソート処理にオンメモリのクイックソートではなく、ディスクベースのマージソートを選択するといったものです。
  • 以下のように、ある程度の余裕を持った値を設定すべきです。
  • work_mem = 1GB

OSのリソース制限の拡張

GPUダイレクトSQLを使用する場合は特に、同時に大量のファイルをオープンする事があるため、プロセスあたりファイルディスクリプタ数の上限を拡大しておく必要があります。

また、PostgreSQLのクラッシュ時に確実にコアダンプを生成できるよう、コアファイルのサイズ上限を制限しないことを推奨します。

PostgreSQLをsystemd経由で起動する場合、リソース制限に関する設定は/etc/systemd/system/postgresql-XX.service.d/pg_strom.confに記述します。

RPMによるインストールの場合、デフォルトで以下の内容が設定されます。

環境変数 CUDA_ENABLE_COREDUMP_ON_EXCEPTION に関する設定がコメントアウトされています。これは開発者向けのオプションで、これを有効にして起動すると、GPU側でエラーが発生した場合にGPUのコアダンプを生成させる事ができます。詳しくはCUDA-GDB:GPU core dump supportをご覧ください。

[Service]
LimitNOFILE=65536
LimitCORE=infinity
#Environment=CUDA_ENABLE_COREDUMP_ON_EXCEPTION=1

PostgreSQLの起動

PostgreSQLを起動します。

正常にセットアップが完了していれば、ログにPG-StromがGPUを認識した事を示すメッセージが記録されているはずです。 以下の例では、NVIDIA A100 (PCIE版; 40GB) を認識しており、また、NVME-SSDごとに近傍のGPUがどちらであるのか出力されています。

# systemctl start postgresql-18
# journalctl -u postgresql-18
# journalctl -u postgresql-18
Oct 28 16:17:16 saba.heterodb.in systemd[1]: Starting postgresql-18.service - PostgreSQL 18 database server...
Oct 28 16:17:16 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:16.574 JST [4325] LOG:  HeteroDB Extra module loaded [api_version=20250316,cufile=on,nvme_strom=off,nvidia-fs=on,githash=d5044aceca80aecee04c7c1a662c066122986291]
Oct 28 16:17:16 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:16.574 JST [4325] LOG:  HeteroDB License: { "version" : 2, "serial_nr" : "HDB-TRIAL", "issued_at" : "2025-10-28", "expired_at" : "2099-12-31", "nr_gpus" : 1, "gpus" : [ { "uuid" : "GPU-156b86ad-864c-d97d-4729-5c3405d8...
Oct 28 16:17:16 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:16.574 JST [4325] LOG:  PG-Strom version 6.1.0.el9 built for PostgreSQL 18 (githash: )
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.011 JST [4325] LOG:  PG-Strom binary built for CUDA 12.9 (CUDA runtime 13.0)
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.011 JST [4325] LOG:  PG-Strom: GPU0 NVIDIA H100 PCIe (114 SMs; 1755MHz, L2 51200kB), RAM 79.18GB (5120bits, 1.52GHz), CC 9.0
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.012 JST [4325] LOG:  [0000:42:00:0] GPU0 (NVIDIA H100 PCIe; GPU-156b86ad-864c-d97d-4729-5c3405d88e76)
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.012 JST [4325] LOG:  [0000:09:00:0] nvme8 (SAMSUNG MZ1LB960HAJQ-00007) --> GPU0 [dist=130]
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.012 JST [4325] LOG:  [0000:c5:00:0] nvme2 (INTEL SSDPF2KX038TZ) --> GPU0 [dist=130]
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.012 JST [4325] LOG:  [0000:88:00:0] nvme4 (INTEL SSDPF2KX038TZ) --> GPU0 [dist=130]
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.012 JST [4325] LOG:  [0000:c3:00:0] nvme1 (INTEL SSDPF2KX038TZ) --> GPU0 [dist=130]
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.012 JST [4325] LOG:  [0000:c7:00:0] nvme6 (INTEL SSDPF2KX038TZ) --> GPU0 [dist=130]
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.012 JST [4325] LOG:  [0000:c1:00:0] nvme0 (INTEL SSDPF2KX038TZ) --> GPU0 [dist=130]
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.012 JST [4325] LOG:  [0000:41:00:0] mlx5_0 (MT4125) --> GPU0 [dist=130]
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.013 JST [4325] LOG:  [0000:82:00:0] nvme3 (INTEL SSDPF2KX038TZ) --> GPU0 [dist=130]
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.013 JST [4325] LOG:  [0000:01:00:0] nvme5 (INTEL SSDPF2KX038TZ) --> GPU0 [dist=130]
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.013 JST [4325] LOG:  [0000:41:00:1] mlx5_1 (MT4125) --> GPU0 [dist=130]
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.013 JST [4325] LOG:  [0000:84:00:0] nvme7 (INTEL SSDPF2KX038TZ) --> GPU0 [dist=130]
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.142 JST [4325] LOG:  redirecting log output to logging collector process
Oct 28 16:17:17 saba.heterodb.in postgres[4325]: 2025-10-28 16:17:17.142 JST [4325] HINT:  Future log output will appear in directory "log".
Oct 28 16:17:17 saba.heterodb.in systemd[1]: Started postgresql-18.service - PostgreSQL 18 database server.

PG-Stromエクステンションの作成

最後に、PG-Stromに関連するSQL関数などのDBオブジェクトを作成します。 この手順はPostgreSQLのEXTENSION機能を用いてパッケージ化されており、SQLコマンドラインでCREATE EXTENSIONコマンドを実行するだけです。

なお、この手順は新しいデータベースを作成するたびに必要になる事に注意してください。 新しいデータベースを作成した時点で既にPG-Strom関連オブジェクトが作成されていてほしい場合は、予めtemplate1データベースでPG-Stromエクステンションを作成しておけば、CREATE DATABASEコマンドの実行時に新しいデータベースへ設定がコピーされます。

$ psql -U postgres
psql (16.3)
Type "help" for help.

postgres=# CREATE EXTENSION pg_strom ;
CREATE EXTENSION

以上でインストール作業は完了です。

PostGISのインストール

PG-Stromは一部のPostGIS関数のGPU処理をサポートしています。 本節ではPostGISのインストール手順について説明を行いますが、必要に応じて読み飛ばしてください。

PostgreSQLと同様に、PostgreSQL Global Development GroupのyumリポジトリからPostGISモジュールをインストールする事ができます。 以下の例は、PostgreSQL v18向けにビルドされたPostGIS v3.6をインストールするものです。

# dnf install postgis36_18

データベースクラスタを作成してPostgreSQLサーバを起動し、SQLクライアントからCREATE EXTENSIONコマンドを実行してGeometryデータ型や地理情報分析のためのSQL関数を作成します。 これでPostGISのインストールは完了です。

postgres=# CREATE EXTENSION postgis;
CREATE EXTENSION

Ubuntu Linuxへのインストール

現在のところ、Ubuntu Linux向けのパッケージは提供されていませんが、ソースコードからPG-Stromをビルドして動作させることができます。

OSのインストール後、それぞれUbuntu Linux向けのMOFEDドライバ、CUDA Toolkit、およびPostgreSQLをインストールしてください。

続いて、heterodb-extraパッケージをインストールします。 Ubuntu Linux 用の .deb パッケージが提供されていますので、その時点の最新版をSWDCより入手してください。

$ wget https://heterodb.github.io/swdc/deb/heterodb-extra_6.7-1_amd64.deb
$ sudo dpkg -i heterodb-extra_6.7-1_amd64.deb

PG-Stromはソースコードをチェックアウトしてインストールします。 この時、ターゲットとするPostgreSQLのpg_configを指定するのを忘れないようにしてください。

インストール後の設定は Red Hat Enterprise Linux や Rocky Linux の場合とほぼ同じです。

$ git clone https://github.com/heterodb/pg-strom.git
$ cd pg-strom/src
$ make PG_CONFIG=/path/to/pgsql/bin/pg_config -j 8
$ sudo make PG_CONFIG=/path/to/pgsql/bin/pg_config install

ただし、パッケージインストールしたPostgreSQLを使用してsystemctl経由でこれを起動する場合、PATH環境変数がクリアされてしまいます。（これはおそらくセキュリティ面での理由でしょう） そのため、初回起動時にGPUバイナリをビルドするために起動したスクリプトが正しく動作しません。 これを避けるため、Ubuntu Linuxを利用する場合は/etc/postgresql/PGVERSION/main/environmentに以下の内容を追記してください。

/etc/postgresql/PGVERSION/main/environment:


PATH='/usr/local/cuda/bin:/usr/bin:/bin'