4. Start, check, and stop

By the end of this chapter: You start GritDB, confirm that it is normal, try registering a first table, and stop GritDB.

Time: 30 min | Prerequisite: chapter 3

4.1 Start

~/gritdb1/bin/gritdb-start

Expected output:

============================================================================
GritDB Start (installed at /home/gritdb/gritdb1)
============================================================================
[INFO] Starting GritAdmin...
============================================================================
GritDB started successfully!
============================================================================
[INFO] GritAdmin: running (PID: <PID>)

Instance ID:         <instance ID>
PG port:             5432 (from postgresql.conf)
Log directory:       /home/gritdb/gritdb1/log
PostgreSQL connect:  /home/gritdb/gritdb1/bin/psql -p 5432 -d postgres
Stop:                /home/gritdb/gritdb1/bin/gritdb-stop
============================================================================

4.2 Confirm that it accepts connections

started successfully means that GritDB is ready to accept connections. Confirm it once more with the command below.

~/gritdb1/bin/pg_isready -p 5432

Expected output:

/tmp:5432 - accepting connections

If you see rejecting connections or no response, run the command again after 5 seconds. If the result is the same after 1 minute, see GDB-BOOT-005.

4.3 Confirm normal operation

GritDB is normal when all three checks pass.

1. Four processes are running.

   ps -o pid,comm -p "$(cut -d: -f2 ~/gritdb1/run/grit_admin.pid | paste -sd,)"
   

   Expected output (a header line and 4 lines, in any order):

       PID COMMAND
     <PID> GritAdmin
     <PID> postgres
     <PID> GritCatalog
     <PID> GritSurfer
   

2. gritsurfer is preloaded.

   ~/gritdb1/bin/psql -p 5432 -d postgres -Atc "SHOW shared_preload_libraries;"
   

   Expected output:

   gritsurfer
   

3. The gritsurfer extension is installed.

   ~/gritdb1/bin/psql -p 5432 -d postgres -Atc "SELECT extname FROM pg_extension WHERE extname = 'gritsurfer';"
   

   Expected output:

   gritsurfer
   

4.4 Register a first table

GritDB manages only registered tables. The registration condition is that the table has REPLICA IDENTITY FULL.

~/gritdb1/bin/psql -p 5432 -d postgres

Run the following in psql.

CREATE TABLE public.quickstart_check (id integer PRIMARY KEY, memo text);
ALTER TABLE public.quickstart_check REPLICA IDENTITY FULL;
SELECT register_gritsurfer_table('public', 'quickstart_check');
INSERT INTO public.quickstart_check VALUES (1, 'hello'), (2, 'gritdb');
SELECT * FROM public.quickstart_check ORDER BY id;
SELECT table_name FROM get_gritsurfer_tables() WHERE table_name = 'quickstart_check';

Expected output:

CREATE TABLE
ALTER TABLE
 register_gritsurfer_table
---------------------------

(1 row)

INSERT 0 2
 id |  memo
----+--------
  1 | hello
  2 | gritdb
(2 rows)

    table_name
------------------
 quickstart_check
(1 row)

• register_gritsurfer_table returns no value, so one empty row is normal.
• During registration and unregistration, INFO: GritSurfer: … and NOTICE: GritSurfer: … lines also appear. These lines record the registration and unregistration, and they are normal.
• If the last query shows quickstart_check, the registration is complete.
• Without REPLICA IDENTITY FULL, the registration is rejected (GDB-RUNTIME-001).

Clean up the check table. Unregister it first, then drop it.

SELECT unregister_gritsurfer_table('public', 'quickstart_check');
DROP TABLE public.quickstart_check;
\q

Expected output:

 unregister_gritsurfer_table
-----------------------------

(1 row)

DROP TABLE

4.5 Stop

~/gritdb1/bin/gritdb-stop

Expected output:

============================================================================
GritDB Stop (installed at /home/gritdb/gritdb1)
============================================================================
[INFO] GritAdmin is running (PID: <PID>)
[INFO] Sending: grit_admin_client stop
[INFO] Stop command accepted: OK stopped
[INFO] GritAdmin stopped
============================================================================
GritDB stopped.
============================================================================

Confirm the stop. If the command below shows no output, all processes have stopped.

pgrep -u gritdb -l -x 'GritAdmin|GritSurfer|GritCatalog|postgres'

• gritdb-stop performs a normal stop. If open sessions remain, it switches to a quick stop, and the next start runs recovery. So end the connected applications first (GDB-SHUTDOWN-002).
• gritdb-stop --quick performs a quick stop. It cuts off work in progress, and the next start runs recovery. Use it only when it is urgent. It can leave a GritDB engine core file (tens of GB), so check the free disk space.
• ⚠ Do not kill the processes one by one with kill (chapter 6).

4.6 Restart

~/gritdb1/bin/gritdb-stop
~/gritdb1/bin/gritdb-start

If a problem occurs

• If GritDB does not start, see GDB-BOOT-001 to 006.
• If table registration is rejected, see GDB-RUNTIME-001.
• If warnings remain after the stop or the stop takes a long time, see GDB-SHUTDOWN-001 and 002.

Learn more

• For start options, quick stop, and restart after a crash, see Admin, chapter 4.
• For all functions to register, unregister, and list tables, and for the analytics session, see Admin, chapter 6. The analytics session sends queries that read only registered tables to the GritDB engine.