docs(solana-rpc): expand agave and geyser runbook

doc/step-003-geyser-plugin-postgres.txt

@@ -0,0 +1,122 @@
+Step 003: Geyser plugin -> PostgreSQL (Agave) na prywatnym RPC node
+
+Cel:
+- Wlaczyc Geyser plugin zapisujacy eventy do Postgresa.
+- Na poczatek: dzialajace end-to-end (plugin laduje sie w validatorze + dane wpadaja do DB).
+
+Wazne ryzyka:
+- Pisanie wszystkiego do Postgresa na mainnet generuje OGROMNY write load.
+  Jezeli DB bedzie na tym samym hoście co validator, latwo o IO contention i spadek performance sync.
+- Rekomendacja: startuj od selektorow (filtrow), np. tylko programy ktore bot potrzebuje.
+
+0) Preconditions
+- Agave dziala pod systemd:
+  - doc/step-002b-agave-validator-systemd.txt
+- Masz pinned Agave release (tag) i go nie zmieniasz "w locie":
+  - doc/step-002f-agave-build-from-source-latest.txt
+
+1) Postgres (lokalnie, minimalny setup)
+  sudo apt-get update
+  sudo apt-get install -y postgresql postgresql-contrib
+  sudo systemctl enable --now postgresql
+
+  # DB + user (dostosuj haslo; nie commituj do repo)
+  sudo -u postgres psql -v ON_ERROR_STOP=1 <<'SQL'
+  DO $$
+  BEGIN
+    IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'geyser') THEN
+      CREATE ROLE geyser LOGIN PASSWORD 'CHANGE_ME';
+    END IF;
+  END $$;
+
+  CREATE DATABASE geyser OWNER geyser;
+  SQL
+
+2) Build plugin ze zrodel (Anza Agave plugin Postgres)
+  # Repo:
+  #   https://github.com/anza-xyz/agave-geyser-plugin-postgres
+  #
+  # Uwaga: plugin i validator musza byc kompatybilne wersjami interfejsu.
+  # Najbezpieczniej: build pluginu po update Agave i test "plugin loaded".
+  #
+  # Opcjonalnie: pin plugin do tagu/commit (np. pod ten sam release co Agave).
+  # PLUGIN_REF="main"   # albo tag/commit
+
+  sudo install -d -o root -g root -m 0755 /opt/solana/plugins
+  sudo install -d -o solana -g solana -m 0750 /var/lib/solana/src
+
+  PLUGIN_SRC_DIR="/var/lib/solana/src/agave-geyser-plugin-postgres"
+
+  sudo -u solana -H bash -lc "
+    set -euo pipefail
+    export PATH=/var/lib/solana/.cargo/bin:\$PATH
+    rm -rf \"${PLUGIN_SRC_DIR}\"
+    git clone https://github.com/anza-xyz/agave-geyser-plugin-postgres.git \"${PLUGIN_SRC_DIR}\"
+    cd \"${PLUGIN_SRC_DIR}\"
+    if [ \"${PLUGIN_REF:-main}\" != \"main\" ]; then git checkout \"${PLUGIN_REF}\"; fi
+    cargo build --release
+  "
+
+  # Typowa nazwa .so (sprawdz `ls target/release/*.so`):
+  sudo cp -a "${PLUGIN_SRC_DIR}"/target/release/*.so /opt/solana/plugins/
+  sudo chmod 0755 /opt/solana/plugins/*.so
+
+3) Schema w Postgres
+  # Plugin repo ma SQL do stworzenia schematu. Najpierw znajdz plik:
+  sudo -u solana -H bash -lc '
+    cd /var/lib/solana/src/agave-geyser-plugin-postgres
+    find . -maxdepth 3 -type f -iname \"*schema*.sql\" -o -type f -iname \"create*.sql\" | sort
+  '
+
+  # Potem wykonaj jako postgres na DB geyser (podmien sciezke na znaleziony plik):
+  # sudo -u postgres psql -d geyser -f /var/lib/solana/src/agave-geyser-plugin-postgres/scripts/create_schema.sql
+
+4) Konfig pluginu (JSON)
+  # Najbezpieczniej: skopiuj example config z repo pluginu i zmien tylko:
+  # - sciezke do .so
+  # - connection string
+  # - selektory (na poczatek mozesz dac \"*\" tylko na smoke test, potem zawęz)
+  #
+  # Znajdz przyklad w repo:
+  sudo -u solana -H bash -lc '
+    cd /var/lib/solana/src/agave-geyser-plugin-postgres
+    find . -maxdepth 4 -type f -iname \"*.json\" | sort
+    rg -n \"connection_str|libpath|accounts_selector|transaction_selector|selector\" -S . || true
+  '
+
+  sudo install -d -o root -g root -m 0755 /etc/solana
+
+  # Start od skopiowania example (podmien sciezke jesli repo ma inna nazwe pliku):
+  # sudo cp -a /var/lib/solana/src/agave-geyser-plugin-postgres/config.json /etc/solana/geyser-postgres.json
+
+  # Uprawnienia: config zawiera haslo, ale validator (User=solana) musi go czytac.
+  if [ -f /etc/solana/geyser-postgres.json ]; then
+    sudo chown root:solana /etc/solana/geyser-postgres.json
+    sudo chmod 0640 /etc/solana/geyser-postgres.json
+  fi
+
+5) Wlaczenie pluginu w agave-validator (systemd)
+  # Sprawdz, jak na Twojej wersji nazywa sie flaga:
+  /opt/solana/bin/agave-validator --help | rg -n \"geyser|plugin\" || true
+
+  # Docelowo (w unit file) dopisz:
+  #   --geyser-plugin-config /etc/solana/geyser-postgres.json
+  #
+  # Nastepnie:
+  sudo systemctl daemon-reload
+  sudo systemctl restart agave-validator
+
+6) Weryfikacja
+  sudo journalctl -u agave-validator -n 200 --no-pager | rg -i \"geyser|plugin|postgres\" || true
+
+  # Czy w DB pojawiaja sie tabele (zalezy od schema.sql):
+  sudo -u postgres psql -d geyser -c \"\\dt\" | head
+
+  # Czy rosną inserty (przyklad - dostosuj nazwy tabel):
+  # sudo -u postgres psql -d geyser -c 'select count(*) from account;'
+
+7) Performance (minimum sanity)
+- Jezeli validator zacznie znacząco odstawać, zacznij od:
+  - zawężenia selektorow (unikaj \"*\" po smoke tescie)
+  - zmniejszenia batch/threads
+  - przeniesienia DB na osobny host (lub przynajmniej na osobny NVMe)