1. GritDB at a glance

By the end of this chapter: You can draw which processes run GritDB and where data and logs accumulate.

Time: 10 min (reading)

1.1 Components

GritDB consists of PostgreSQL 17.11 and the GritDB engine. Four processes start and stop together as one unit.

gritdb-start / gritdb-stop         ← the only start and stop commands an engineer uses
        │
        ▼
grit_admin                         supervisor process: starts the three below in order and watches them
  ├── postgres                     PostgreSQL 17.11 + gritsurfer extension — SQL connection point (port 5432)
  ├── grit_catalog_process         GritDB catalog — reads and writes the information on registered tables and cold files
  └── grit_surfer_process          GritDB engine — applies changes from registered tables · manages cold files

• Start order: grit_admin → postgres → (PostgreSQL ready) → grit_catalog_process → grit_surfer_process
• gritdb-stop alone stops all four.
• Users and applications connect on port 5432, as with regular PostgreSQL.
• You register the tables for GritDB to manage in a separate step (section 4.4).

1.2 Directory map

~/gritdb1/                     installation directory
├── bin/                       commands such as gritdb-start · gritdb-stop · psql · pg_isready
├── datafiles/                 ★ all data — always handle it as one unit
│   ├── pgdata/                PostgreSQL data directory (includes postgresql.conf)
│   ├── checkpoint/            unify checkpoint (the WAL position up to which the GritDB engine has applied changes durably · not the PostgreSQL checkpoint)
│   ├── queue/                 GritDB internal queue
│   └── cold_file/             cold files (files the GritDB engine stores by column for analytic queries)
├── log/                       all logs (including the installation log)
├── run/                       runtime state files (pid · socket · lock)
├── config/                    GritDB engine settings (grit_*.config · Admin, chapter 5)
├── docs/                      release notes
├── etc/ · lib/ · share/       configuration templates · libraries · product information (share/gritdb/manifest.json)
├── include/ · licenses/       public headers · licenses
└── .gritdb_installed          install anchor — do not delete

• State accumulates in datafiles/, log/, and run/. Everything else is installed files.
• ⚠ The directories in datafiles/ depend on each other. If you delete or replace only some of them, GritDB cannot start (chapter 6).

1.3 Mapping for Oracle and Tibero users

1.4 Overall flow

Ch.2 Prepare and check ──▶ Ch.3 Install ──▶ Ch.4 Start, check, stop ──▶ Ch.5 Daily checks
                                                                        │
                        Ch.6 Prohibitions (always follow) ◀─────────────┤
                        Ch.7 When problems occur (as needed) ◀──────────┘