1. Installation planning

By the end of this chapter: You decide the setup type, server specifications, OS settings, disk layout, and items to bring in.

1.1 Setup types

• In a single-database setup, each write to a registered table waits for confirmation that the GritDB engine received it. So it is not recommended for production write workloads.
• In an analytics setup, the operational database side also has work to do. For wal_level, publication, replication account, pg_hba.conf, firewall, free space in pg_wal on the operational database, and max_slot_wal_keep_size, see 6.4.1 and 6.4.3. For monitoring, see 7.5.
• While the GritDB of an analytics setup is stopped, the replication slot on the operational database holds WAL. So decide in advance how long GritDB can stay stopped and how much free disk space the operational database has (4.7).
• Do not receive data through physical replication (streaming standby server) of the operational database. An analytics setup receives data through PostgreSQL logical replication, CDC, or ETL (6.4).
• 1.1 does not offer GritDB redundancy (standby, HA), multiple nodes, or adding GritDB to a PostgreSQL already in use. The installation script creates a new data directory with initdb, so you cannot add GritDB to an existing PostgreSQL. For details, see 10.6.

1.2 Supported platforms

• The supported OS is Ubuntu 24.04 LTS only. Other operating systems and containers are outside the supported environment. Even if installation and start succeed, there is no guarantee.
• On RHEL 9 and Rocky Linux 9, glibc is older than min_glibc, so they fail the installation check (QuickStart 2.4 checklist item 4).
• The installation script only prints a warning and continues the installation even if glibc or the CPU instructions fall short. If you see a warning below, stop the installation and go back to QuickStart 2.4 checklist items 3 and 4.
  • [WARN] Host glibc <version> is older than required <version>; binaries may not start.
  • [WARN] CPU may lack required flags (cx16, sse4.2); startup guard will refuse if so.
• In a container, the GritDB engine sizes memory and vCPUs by the host values. It does not look at the container limits. If GritDB hits a limit, the OS forcibly ends a GritDB process, and all of GritDB stops (4.3).

Check the shared libraries before installation. Run the command in the extracted directory.

cd ~/pkg/gritdb-*/
ldd bin/postgres bin/grit_admin bin/grit_surfer_process bin/grit_catalog_process | grep 'not found'

No output is normal. If a library is missing, the installation finishes, but GritDB stops at start. In that case, install that library from an OS package, then check again.

1.3 Sizing

• A server sold as 8 GB usually shows a total smaller than 8192. The kernel and firmware reserve part of the memory. So it falls short of the minimum.
• 1.1 has no setting that reduces the vCPUs or memory that GritDB uses. GritDB uses as much as the size of the server (virtual server). So decide the size when you choose the server.

Memory breakdown:

Disk breakdown:

The number of rows that one transaction can write to registered tables (single-transaction size) has a limit. The limit depends on server memory, and no setting changes it. Check it with 6.8 after installation.

• If an analytics setup receives a large table, or the operational database has large batches, contact support (chapter 0) before you choose the server.

Calculation example:

• The minimum disk space is only a minimum. The size of cold files depends on the workload, so measure the trend from the start of operation (7.4).

1.4 OS settings

① Open file limit — root adds two lines to /etc/security/limits.conf.

cat >> /etc/security/limits.conf <<'EOF'
gritdb soft nofile 65536
gritdb hard nofile 65536
EOF

• To check again, run ulimit -n and ulimit -Hn in a new gritdb login shell. Both return 65536 or more.
• QuickStart 2.1 (create the account) adds the same two lines. If you followed it as written, the limit is already raised, so only check it.
• If you start GritDB as a service at server boot, this file does not apply. In that case, see LimitNOFILE in 4.6.

② Core files — The GritDB engine raises the core size limit up to the hard value. At a quick stop or an abnormal termination, one core file can be tens of GB (9.6).

• Decide whether to keep core files and where to put them. The settings are the hard limit (the core line in /etc/security/limits.conf) and the location in kernel.core_pattern.
• If kernel.core_pattern starts with | (Ubuntu default), the OS core collection program receives the core. In that case, check that program’s location and settings first (9.6).
• The location is a place other than the data volume, with space for several core files (1.5).

③ clocksource — If it is not tsc, GritDB starts, but log/grit_admin_main.log gets a kernel clocksource is warning. root makes the change.

cat /sys/devices/system/clocksource/clocksource0/available_clocksource
echo tsc > /sys/devices/system/clocksource/clocksource0/current_clocksource

• Change it only when the output of the first line contains tsc. If it does not, contact support (chapter 0).
• To keep it after a reboot, add clocksource=tsc to the kernel command line.

④ Temporary directory (TMPDIR)

• During installation, the installation script creates a script for each step in the temporary directory and runs it. If /tmp is noexec, every step can fail. In that case, give it a directory that allows execution.

  mkdir -p ~/tmp
  cd ~/pkg/gritdb-*/
  TMPDIR=~/tmp ./install_gritdb.sh
  

• While running, the GritDB engine writes temporary files for cleanup work (__tkidx_spill_*.tmp). It writes them to the TMPDIR of the shell that started it (/tmp if it is not set). If /tmp is tmpfs or small, give a directory on the data volume when you start GritDB. Keep that directory outside datafiles/, and give the same value at every start.

  TMPDIR=<directory on the data volume> ~/gritdb1/bin/gritdb-start
  

• With GritDB stopped (4.5), delete the temporary files left after an abnormal termination. For details, see 7.6. <temporary directory> is the TMPDIR you gave at start, or /tmp if you gave none.

  ls -l <temporary directory>/__tkidx_spill_*.tmp
  rm -f <temporary directory>/__tkidx_spill_*.tmp
  

  • If several installations use the same temporary directory, stop all of them, then delete the files (2.9).

⑤ RemoveIPC — By default, systemd on Ubuntu removes a regular account’s shared memory when its last login session ends. A service account created with useradd -m (QuickStart 2.1) is a regular account. So when you log in as gritdb and log out, systemd removes the shared memory of the running GritDB (/dev/shm, the 1.4 table). root turns this off as shown below.

mkdir -p /etc/systemd/logind.conf.d
printf '[Login]\nRemoveIPC=no\n' > /etc/systemd/logind.conf.d/gritdb.conf
systemctl restart systemd-logind

• To check, run the check command in the table above. It returns RemoveIPC=no.
• QuickStart 2.1 (create the account) runs the same three lines. If you followed it as written, the setting is already off, so only check it.
• If you created the service account as a system account (useradd -r), systemd does not remove its shared memory. For the source, see systemd RemoveIPC.

Leave the huge page setting, PostgreSQL huge_pages, at the default (try). The GritDB engine does not allocate huge pages separately.

1.5 Disk layout

The recommended layout is to put all of datafiles/ on a dedicated data volume (--datafiles in 2.4). datafiles/ is one unit, so do not put only part of it on another volume.

~/gritdb1/                    installation directory (OS volume)
├── bin/ · lib/ · share/ …    installed files
├── config/                   GritDB engine configuration
├── log/                      logs
├── run/                      runtime state files
└── datafiles → /data/gritdb/datafiles  symlink

/data/                        dedicated data volume (mount point · owned by root)
└── gritdb/                   owned by the service account (reinitialization and restore rename directories in here)
    └── datafiles/
        ├── pgdata/           PostgreSQL data · WAL
        ├── checkpoint/       unify checkpoint (the WAL position up to which the GritDB engine has applied changes durably · not the PostgreSQL checkpoint)
        ├── queue/            GritDB engine queue
        ├── buffer_spill/     data spilled when memory runs short
        └── cold_file/        cold file

⚠ After installation, do not change the real path of datafiles/ (including the relocation target and the mount point)

• Reason: If you start GritDB after the change, you lose the cold files. You cannot undo this.
• Instead: Decide the data volume at the first installation (2.4). If the disk runs short, keep the path and only grow the volume. Restore to the same real path, too (8.1 and 10.5).

• Give --datafiles a directory below the mount point, not the mount point itself (2.4). For example, if /data is the mount point, create /data/gritdb owned by the service account and give /data/gritdb/datafiles. Then reinitialization and restore only rename directories inside the same volume, in a place where the service account can write. If you give the mount point itself, reinitialization moves the old data to the parent file system. That file system can then fill up (3.1).
• log/ is under the installation directory, and no option moves it. So leave room for logs on the volume of the installation directory. postgresql.log keeps growing unless you set up rotation (9.4).
• Core files pile up in the location that kernel.core_pattern sets, so keep that location off the data volume (1.4 and 9.6).
• To grow the disk, keep the path and only grow the volume (warning above).

1.6 Ports and network

• The only port for inbound TCP connections is the PostgreSQL port. GritDB has no other TCP ports.
• The Unix sockets are PostgreSQL /tmp/.s.PGSQL.<port> (unix_socket_directories) and the supervisor process ~/gritdb1/run/grit_admin.sock. The supervisor process socket is for the stop command (11.7).
• GritDB does not communicate outward on its own. It has no license or statistics communication. The only outbound connection is the one that the analytics setup subscription opens to the operational database.
• By default after installation, GritDB accepts connections only from localhost. For remote connections, see 11.4.

1.7 Bringing files into a network without internet access

• Verify the delivered files by following QuickStart 2.3 as written (sha256sum -c SHA256SUMS → install_gritdb.sh --verify-only).
• The installation script does not read SHA256SUMS, so do not skip sha256sum -c.
• For automated checks, exit code 0 from --verify-only means a pass. If it is not 0, tell the cause apart by the text on the screen.
  • If jq is required to read the manifest appears, bring in jq (GDB-INSTALL-002).
  • If hash mismatch or dist verification FAILED appears, get the delivered files again (GDB-INSTALL-003).
• For a patch or upgrade, verify the new installation package with the same procedure (3.4).

1.8 Character set, collation, and time zone

• The database character set is UTF8, and the sort order (collation) is C. Character classification (ctype) is C.UTF-8. The installation sets them, and you cannot change them. They are fixed so that the GritDB engine and PostgreSQL give the same sort results.

  ~/gritdb1/bin/psql -p 5432 -d postgres -Atc "SELECT datname, pg_encoding_to_char(encoding), datcollate, datctype FROM pg_database;"
  

  It is normal if every database shows UTF8|C|C.UTF-8.

• Sort results follow byte order. They differ from the ko_KR and en_US collations. For example, uppercase letters come first in ORDER BY, so B comes before a. Hangul (precomposed syllables) sorts in Korean alphabetical order.

• Do not create databases with another collation or an ICU collation (10.3).

• The server time zone is the OS time zone at installation (TimeZone). To check it, run SHOW timezone;. To change it, see 5.3.

• Queries in an analytics session do not use the session time zone (SET timezone). So set the application’s time zone to match the server time zone (10.3). Analytics sessions compute with the OS time zone, so keep the server time zone equal to the OS time zone (5.3).

1.9 Installation planning checklist

• For the installation command, if items 4, 5, 6, and 10 all use the defaults, follow QuickStart 3.1 as written. If any of them differs, put those values in one command and give them at the first installation (“Examples of combined options” in 2.1).

  cd ~/pkg/gritdb-*/
  TMPDIR=<directory> ./install_gritdb.sh --datafiles /data/gritdb/datafiles --pgport 5433
  

  • You cannot change the installation directory or the data volume after installation (1.5, 2.2, and 2.4).
  • Check with QuickStart 3.2 and 3.3. Substitute only the path and port. Then go to 2.10.

If a problem occurs

• If the installation fails, see the GDB-INSTALL entries in QuickStart, chapter 7, and TroubleShooting.

Learn more

• For installation options, see chapter 2. For memory configuration, see chapter 5. For security, see chapter 11.
• PostgreSQL 17 documentation: Logical replication, WAL settings, Resource consumption, Kernel resources, and Collation