2. Installation details

By the end of this chapter: You install GritDB outside the standard paths (another path, a separate data volume, another port, or installing as root).

2.1 All installation options

• The installation script (install_gritdb.sh) is not copied to the installation directory. You run reinitialization, cleanup, and upgrade from the extracted directory. So keep the installation package of the installed version until you install the next version (QuickStart 3.4).
• The installation script does not prompt for input (2.8).

Exit codes:

Examples of combined options (in the extracted directory):

2.2 Another path and a short path

• Give the installation directory with --prefix <path>. Use an absolute path of 80 characters or fewer. The length limit comes from the OS limit on the supervisor process socket path. If the path is longer, see GDB-INSTALL-005.

  echo -n '<path>' | wc -c
  

  It is normal if the output is 80 or fewer.

• If you do not use the standard path, read ~/gritdb1 in this guide as your path (chapter 0, Conventions).

If the home directory path itself is long, root creates a short path and hands it over to the service account. Then you install as the service account.

root:

mkdir -p /opt/gritdb1
chown gritdb: /opt/gritdb1

gritdb:

cd ~/pkg/gritdb-*/
./install_gritdb.sh --prefix /opt/gritdb1

• Check with QuickStart 3.2 and 3.3. In their commands, change only the path to /opt/gritdb1.

⚠ After installation, do not move or rename the installation directory or the data path

• Reason: If the real path of datafiles/ changes, you lose the cold files (1.5). Cold files are files the GritDB engine stores by column for analytic queries. If the installation directory changes, the instance ID also changes (2.9). The instance ID is derived from the installation directory and is used in shared memory and lock names.
• Instead: If you need another path, do a new installation in the new path and load the data again. For an analytics setup, take the tables again (8.6). For a single database, follow the order in 8.3 (schema → registration → data). Back up and restore at the same real path, too (8.4).

2.3 Installing as root (/opt and similar)

• Use this when root installs directly in a location where the service account cannot write (when you cannot use the method in 2.2).
• root creates the path and hands ownership over to the service account, so give --prefix and --user together. Without --prefix, GritDB is installed in root’s home (/root/gritdb1).

root (create the service account in advance as in QuickStart 2.1):

cd <extracted directory>
./install_gritdb.sh --prefix /opt/gritdb1 --user gritdb

• To check, run stat -L -c '%U %n' /opt/gritdb1 /opt/gritdb1/datafiles/pgdata. Both lines start with gritdb.
• A root installation creates the installation path with 755, so the service account runs chmod 700 /opt/gritdb1 (11.7). To check, run stat -c '%a %U %n' /opt/gritdb1. It returns 700 gritdb.
• If you also reinstall, upgrade, or reinitialize as root, give the same --prefix and --user.
  • Without --user, the step that creates a new data directory is rejected (GDB-INSTALL-001).
  • An upgrade that does not create a new data directory finishes without --user. However, it does not set the owner of the new files to the service account.
• Start and stop GritDB only as the service account.

su - gritdb
/opt/gritdb1/bin/gritdb-start

⚠ Do not start GritDB as root

• Reason: PostgreSQL does not run as root, so the start fails (server account). Files owned by root can then remain in run/ and log/ and block start and stop by the service account.
• Instead: Run su - gritdb, then start GritDB. For start at boot, use User=gritdb in 4.6. If you started GritDB as root, check the state with 4.5 and find the remaining files with find /opt/gritdb1 -user root.

2.4 Data volume relocation

--datafiles /data/gritdb/datafiles    --pgdata /data/gritdb/pgdata

~/gritdb1/                            ~/gritdb1/
└── datafiles → /data/gritdb/datafiles └── datafiles/
    ├── pgdata/                           ├── pgdata → /data/gritdb/pgdata
    ├── checkpoint/                       ├── checkpoint/
    ├── queue/                            ├── queue/
    ├── buffer_spill/                     ├── buffer_spill/
    └── cold_file/                        └── cold_file/

The service account must be able to create <path> and write to the parent directory of <path>. Reinitialization, restore, and rollback rename directories inside that parent directory (3.1, 3.2, and 3.7). A mount point is usually owned by root. So root creates a service account directory below it and hands it over, and <path> goes inside that directory.

root (after you mount the data volume):

mkdir -p /data/gritdb
chown gritdb: /data/gritdb
chmod 700 /data/gritdb

gritdb:

cd ~/pkg/gritdb-*/
./install_gritdb.sh --datafiles /data/gritdb/datafiles

• It is normal if the installation ends with Install complete. and the check lines below match.
• To check write access to the parent directory, run test -w "$(dirname "$(readlink -f ~/gritdb1/datafiles)")" && echo OK. It returns OK.
• If the service account cannot create <path>, the installation stops after ▶ 2.1. The line after mkdir: cannot create directory … Permission denied is [ERROR] Relocation target … or Cannot resolve … path. In that case, do the root step above, then run the same command again. The same applies to --pgdata.
• For <path>, give a path that does not exist yet or an empty directory. To check, run ls -A <path>. It shows no output. If old data (pgdata/postgresql.conf) exists, the installation script uses that data as it is without asking. In that case, the installation screen shows the line ▶ 3.1 … SKIP (existing data kept; ...). Do not give a path that another installation uses (2.9).
• Give the option at the first installation. If you give it for an existing installation, the run is rejected. The message is <installation directory>/datafiles already exists as a real directory; move it aside first or drop the relocation flag. At this point, the copy of the installation files (▶ 2.1) has already finished. So run again with the same installation package, without the relocation option, to finish the installation.
• If the target path contains the installation directory (for example, a parent directory of the installation directory), the run is rejected.
• Give a directory below the mount point, not the mount point itself (1.5). PostgreSQL recommends the same in file system mount points.
• To check, run readlink ~/gritdb1/datafiles. It returns the path you gave (real path). Also run df -h ~/gritdb1/datafiles/. It shows the data volume.

⚠ Do not change the relocation values at reinstallation or upgrade

• Reason: If you give different --datafiles or --pgdata values, the symlink changes to the new location. If you change --datafiles, GritDB can start with new, empty data. If you change --pgdata, old data and new PostgreSQL data can mix so that GritDB cannot start.
• Instead: At reinstallation or upgrade, omit the relocation options or give the same values as the first time. If you omit them, the symlink created the first time stays in use.

2.5 Changing the port

The single source of truth for the port is the port line in the managed block of postgresql.conf. The only way to change it is to run the installation script again with --pgport.

1. Check that the new port is free. The installation script does not check for port conflicts.

   ss -ltn | grep -w <new port>
   

   If there is no output, the port is free.

2. Stop GritDB. The installation script does not check whether GritDB is running.

   ~/gritdb1/bin/gritdb-stop
   

   To check, run the stop check in QuickStart 4.5. It shows no output.

3. Run the script again from the extracted directory of the installation package of the same version as the installed one. Also give the options you gave at the first installation (--prefix, --no-config, and --user for root).

   • Before you run it, check the two marker lines of the managed block, as in the check for QuickStart GDB-INSTALL-004. Run grep -n 'gritdb managed' ~/gritdb1/datafiles/pgdata/postgresql.conf. It is normal if # >>> gritdb managed begin and # <<< gritdb managed end each appear once.

   cd <extracted directory of the installed version>
   jq -r .product_version manifest.json ~/gritdb1/share/gritdb/manifest.json
   

   If the two lines are the same, it is the installed version, so run the script (the same as 3.1 step 4).

   ./install_gritdb.sh --pgport <new port>
   

   • [INFO] Upgrading existing 1.x install in place: <installation directory> means that the same version is installed again in the same place. This is normal.
   • Step ▶ 3.1 shows SKIP (existing data kept; ...), and the installation check shows pg port = <new port>.
   • The script rewrites the managed block and appends it to the end of the file. So values inside the block return to the installation defaults. The same settings written by hand outside the block are overridden by the block values. ALTER SYSTEM values remain (5.2 and 5.3).

4. Start GritDB and check it.

   ~/gritdb1/bin/gritdb-start
   ~/gritdb1/bin/pg_isready -p <new port> -d postgres
   

   • pg_isready checks only whether the server accepts connections.

   • It is normal if the start screen’s PG port: line shows the new port and pg_isready shows accepting connections.

• After the change, change -p in every connection command to the new port. Also change the firewall (1.6) and the connection settings of applications, CDC and ETL tools, and report and BI tools.
• Do not use ALTER SYSTEM SET port. The port that GritDB commands read and the port that PostgreSQL actually uses become different.

2.6 Omitting the tuning block (--no-config)

• --no-config writes only the required block and the port to the managed block, and does not write the tuning block (5.2).

• Give it again at every reinstallation, upgrade, and reinitialization. If you omit it, the tuning block comes back.

• Without the tuning block, those 8 settings (including the three memory values) run at the PostgreSQL defaults. For example, max_wal_size is 1GB. In that case, after the first start, set the same settings with ALTER SYSTEM and restart (5.3 and 5.4). Register tables and load data after the restart.

• To check the managed block markers before reinstallation, see 2.5 step 3.

• Use it when you manage all the settings of the tuning block yourself. To change only a few of them, keep the block and override them with ALTER SYSTEM. ALTER SYSTEM values take precedence over the block.

• Keep the tuning block on a small server too. The installation script sets the three memory values, such as shared_buffers, from the server memory (5.5).

• To check, look at the managed block. The lines of the tuning block (5.2) are absent.

  sed -n '/^# >>> gritdb managed begin/,/^# <<< gritdb managed end/p' ~/gritdb1/datafiles/pgdata/postgresql.conf
  

2.7 Reading the installation log

• The installation log is in ~/gritdb1/log/install_gritdb_<timestamp>.log. Each run creates a new file.
• The log contains the step lines and the output of the commands run in each step. The step lines run from [<time>] 1.1 … to [<time>] 5.1 … (▶ 1.1 to ▶ 5.1 on the screen).
• [INFO], [WARN], and [ERROR] lines outside the steps appear only on the screen. Examples are upgrade, relocation, and reinitialization notices, and rejections before the start. If the run is rejected before the installation directory is decided, no log file is created. So keep the screen output too.

cd <extracted directory of the version to run>
./install_gritdb.sh <options> 2>&1 | tee ~/install_console_$(date +%Y%m%d_%H%M%S).log
echo "exit=${PIPESTATUS[0]}"

• To read the installation check (CHECK), see QuickStart 3.2.

2.8 Unattended installation

• The installation script does not prompt for input. --purge-old also deletes without asking (3.3).
• When you run it as root, give --user (2.3).
• To judge the result, do not rely on the exit code alone. Also check the FAIL lines of the installation check output and the Install complete. line.

cd <extracted directory>
./install_gritdb.sh <options> > ~/install_console.log 2>&1
rc=$?
if [ "$rc" -eq 0 ] && grep -q 'Install complete' ~/install_console.log && ! grep -q 'missing!' ~/install_console.log; then
  echo "INSTALL OK"
else
  echo "INSTALL FAILED (rc=$rc)"
fi

• It is normal if INSTALL OK appears.
• If INSTALL FAILED appears, read ~/install_console.log as described in 2.7.

2.9 Multiple installations on one server

• To check the instance ID, run <installation directory>/bin/grit_instance_id <installation directory>.

• ⚠ In each installation, the GritDB engine takes memory as a ratio of physical memory (1.3). Two installations use more memory than the server has, so use this only on test and validation servers.

• Process names are the same in every installation. So the stop check in QuickStart 4.5 (pgrep) shows the processes of all installations. Tell installations apart by the executable path.

for p in $(pgrep -u gritdb -x 'GritAdmin|GritSurfer|GritCatalog|postgres'); do
  echo "$p $(readlink /proc/$p/exe)"
done

• The output shows the PID and the executable path (<installation directory>/bin/…). Tell the installations apart by the installation directory in the path.
• When you clean up shared memory, delete only the entries that end with the instance ID of that installation. Replace ~/gritdb1 in QuickStart GDB-SHUTDOWN-001 with that installation directory.
• Check the status of each installation with 4.5. PID files and locks are separate for each installation directory.

2.10 After installation

1. Check the OS settings again (1.4). Finish RemoveIPC (1.4 ⑤) before the first start.
2. Start GritDB and check that it is normal (QuickStart 4.1 to 4.3). If you decided on a TMPDIR, give it in QuickStart 4.1 in the form of 1.4 ④. Do steps 3 and 6 while connected to the running server.
3. Change the authentication (11.3). The installation default is trust, so any OS user on this server can connect as a superuser without a password. If other users log in to this server, do step 2 of 11.3 before the first start. In that case, do the other steps right after the start, before anything else (QuickStart 3.4).
4. Narrow the file and directory permissions (11.7). Set the installation path and the relocated real paths to 700. A root installation (2.3) creates the installation path with 755.
5. Open remote connections if you need them (11.4).
6. Adjust the configuration (chapter 5: small server, time zone).
7. Set up start at server boot (4.6).
8. Make a backup plan and run the first restore test (chapter 8).
9. Run the pre-production checks (7.7).

If a problem occurs

• See the GDB-INSTALL entries in QuickStart, chapter 7, and TroubleShooting.

Learn more

• For reinitialization and upgrade, see chapter 3. For configuration, see chapter 5.
• PostgreSQL 17 documentation: Creating a database cluster, Server account, Connection settings, and trust authentication