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)