1. 설치 계획

이 장을 마치면: 구성 방식과 서버 사양, OS 설정, 디스크 배치, 반입물을 정한다.

1.1 구성 방식

• 한 데이터베이스 구성에서는 등록 테이블에 쓸 때마다 GritDB 엔진이 받았다는 확인을 기다린다. 그래서 운영 업무의 쓰기 부하에는 권하지 않는다.
• 분석계 구성에서는 운영 DB 쪽에도 할 일이 있다. wal_level, publication, 복제 계정, pg_hba.conf, 방화벽, 운영 DB pg_wal 여유, max_slot_wal_keep_size는 6.4.1과 6.4.3을 본다. 감시는 7.5를 본다.
• 분석계 GritDB를 멈춰 둔 동안 운영 DB의 복제 슬롯이 WAL을 붙잡는다. 그래서 멈춰 둘 수 있는 시간과 운영 DB 디스크 여유를 미리 정한다(4.7).
• 운영 DB의 물리 복제(스트리밍 대기 서버)로는 받지 않는다. 분석계는 PostgreSQL 논리 복제, CDC 또는 ETL로 받는다(6.4).
• 1.1에 없는 구성은 GritDB 이중화(standby, HA), 다중 노드, 이미 쓰는 PostgreSQL에 GritDB 붙이기다. 설치 스크립트가 initdb로 데이터 디렉토리를 새로 만들므로 기존 PostgreSQL에는 붙일 수 없다. 자세한 것은 10.6을 본다.

1.2 지원 플랫폼

• 지원 OS는 Ubuntu 24.04 LTS 하나다. 그 밖의 OS와 컨테이너는 지원 환경 밖이다. 설치와 기동이 되어도 보증하지 않는다.
• RHEL 9와 Rocky Linux 9는 glibc가 min_glibc보다 낮아 설치 점검(QuickStart 2.4 점검표 4)에서 막힌다.
• 설치 스크립트는 glibc나 CPU 명령어가 모자라도 경고만 내고 설치를 이어 간다. 아래 경고가 보이면 설치를 멈추고 QuickStart 2.4 점검표 3과 4로 돌아간다.
  • [WARN] Host glibc <판> is older than required <판>; binaries may not start.
  • [WARN] CPU may lack required flags (cx16, sse4.2); startup guard will refuse if so.
• 컨테이너에서는 GritDB 엔진이 메모리와 vCPU를 호스트 값으로 잡는다. 컨테이너 한도를 보지 않는다. 한도에 걸리면 OS가 GritDB 프로세스를 강제로 끝내고, GritDB 전체가 멈춘다(4.3).

설치 전에 공유 라이브러리를 점검한다. 압축을 푼 디렉토리에서 실행한다.

cd ~/pkg/gritdb-*/
ldd bin/postgres bin/grit_admin bin/grit_surfer_process bin/grit_catalog_process | grep 'not found'

출력이 없으면 정상이다. 빠진 라이브러리가 있으면 설치는 끝나도 기동에서 멈춘다. 이때는 그 라이브러리를 OS 패키지로 설치한 뒤 다시 점검한다.

1.3 사양 산정

• 이름이 8 GB인 서버는 보통 total이 8192보다 작게 보인다. 커널과 펌웨어 예약분이 빠지기 때문이다. 그래서 하한에 모자란다.
• 1.1에는 GritDB가 쓰는 vCPU와 메모리를 줄이는 설정이 없다. GritDB는 서버(가상 서버) 크기만큼 쓴다. 그래서 크기는 서버를 고를 때 정한다.

메모리 나눔:

디스크 나눔:

등록 테이블에 한 트랜잭션으로 쓰는 행 수(한 트랜잭션 크기)에는 상한이 있다. 상한은 서버 메모리에 따라 다르고, 바꾸는 설정은 없다. 설치한 뒤 6.8로 확인한다.

• 분석계로 큰 테이블을 받거나 운영 DB에 큰 배치가 있으면 서버를 고르기 전에 지원 문의(0장)를 한다.

계산 예:

• 디스크 하한은 하한일 뿐이다. cold file의 크기는 부하에 따라 다르므로 운영 초기부터 추이를 잰다(7.4).

1.4 OS 설정

① 파일 열기 한도 — root가 /etc/security/limits.conf에 두 줄을 더한다.

cat >> /etc/security/limits.conf <<'EOF'
gritdb soft nofile 65536
gritdb hard nofile 65536
EOF

• 새로 로그인한 gritdb 셸에서 ulimit -n과 ulimit -Hn을 다시 실행해 둘 다 65536 이상인지 확인한다.
• QuickStart 2.1(계정 만들기)이 같은 두 줄을 넣는다. 그대로 설치했으면 이미 올라가 있으므로 확인만 한다.
• 서버 부팅 때 서비스로 띄우면 이 파일이 적용되지 않는다. 이때는 4.6의 LimitNOFILE을 본다.

② core 파일 — GritDB 엔진은 core 크기 한도를 hard 값까지 올린다. 즉시 정지나 비정상 종료 때 core 1개가 수십 GB일 수 있다(9.6).

• core를 남길지와 어디에 둘지를 정한다. 설정할 것은 hard 한도(/etc/security/limits.conf의 core 줄)와 kernel.core_pattern의 자리다.
• kernel.core_pattern이 |로 시작하면(Ubuntu 기본) OS의 core 수집 프로그램이 core를 받는다. 이때는 그 프로그램의 자리와 설정을 먼저 본다(9.6).
• 자리는 데이터 볼륨이 아니면서 core 여러 개를 둘 공간이 있는 곳이다(1.5).

③ clocksource — tsc가 아니면 GritDB는 기동하지만 log/grit_admin_main.log에 kernel clocksource is 경고가 남는다. 바꾸기는 root가 한다.

cat /sys/devices/system/clocksource/clocksource0/available_clocksource
echo tsc > /sys/devices/system/clocksource/clocksource0/current_clocksource

• 첫 줄 출력에 tsc가 있을 때만 바꾼다. 없으면 지원 문의(0장)를 한다.
• 다시 부팅해도 남기려면 커널 명령줄에 clocksource=tsc를 더한다.

④ 임시 디렉토리(TMPDIR)

• 설치 때는 설치 스크립트가 임시 디렉토리에 단계별 스크립트를 만들어 실행한다. /tmp가 noexec이면 모든 단계가 실패할 수 있다. 이때는 실행할 수 있는 디렉토리를 준다.

  mkdir -p ~/tmp
  cd ~/pkg/gritdb-*/
  TMPDIR=~/tmp ./install_gritdb.sh
  

• 실행 중에는 GritDB 엔진이 정리 작업 임시 파일(__tkidx_spill_*.tmp)을 쓴다. 쓰는 곳은 기동한 셸의 TMPDIR(없으면 /tmp)이다. /tmp가 tmpfs이거나 작으면 데이터 볼륨 안 디렉토리를 주고 기동한다. 이 디렉토리는 datafiles/ 밖에 두고, 기동할 때마다 같은 값을 준다.

  TMPDIR=<데이터 볼륨 안 디렉토리> ~/gritdb1/bin/gritdb-start
  

• 비정상 종료 뒤 남은 임시 파일은 GritDB를 정지한 상태(4.5)에서 지운다. 자세한 것은 7.6을 본다. <임시 디렉토리>는 기동 때 준 TMPDIR이고, 주지 않았으면 /tmp다.

  ls -l <임시 디렉토리>/__tkidx_spill_*.tmp
  rm -f <임시 디렉토리>/__tkidx_spill_*.tmp
  

  • 설치본이 여럿이고 같은 임시 디렉토리를 쓰면 모든 설치본을 정지한 뒤 지운다(2.9).

⑤ RemoveIPC — Ubuntu에서 systemd는 기본으로 일반 계정의 마지막 로그인 세션이 끝날 때 그 계정의 공유 메모리를 지운다. useradd -m으로 만든 서비스 계정(QuickStart 2.1)은 일반 계정이다. 그래서 gritdb로 로그인했다 나가면 실행 중인 GritDB의 공유 메모리(/dev/shm, 1.4 표)가 지워진다. root가 아래처럼 끈다.

mkdir -p /etc/systemd/logind.conf.d
printf '[Login]\nRemoveIPC=no\n' > /etc/systemd/logind.conf.d/gritdb.conf
systemctl restart systemd-logind

• 위 표의 확인 명령을 실행해 RemoveIPC=no가 나오는지 확인한다.
• QuickStart 2.1(계정 만들기)이 같은 세 줄을 실행한다. 그대로 설치했으면 이미 꺼져 있으므로 확인만 한다.
• 서비스 계정을 시스템 계정(useradd -r)으로 만들었으면 지워지지 않는다. 근거는 systemd RemoveIPC에 있다.

큰 페이지 설정인 PostgreSQL huge_pages는 기본값(try) 그대로 둔다. GritDB 엔진은 큰 페이지를 따로 잡지 않는다.

1.5 디스크 배치

데이터 전용 볼륨을 두고 datafiles/를 통째로 그 볼륨에 두기를 권한다(2.4의 --datafiles). datafiles/는 한 묶음이므로 일부만 다른 볼륨에 두지 않는다.

~/gritdb1/                    설치 경로 (OS 볼륨)
├── bin/ · lib/ · share/ …    설치 파일
├── config/                   GritDB 엔진 설정
├── log/                      로그
├── run/                      실행 중 상태 파일
└── datafiles → /data/gritdb/datafiles  심링크

/data/                        데이터 전용 볼륨 (mount 지점 · root 소유)
└── gritdb/                   서비스 계정 소유 (재초기화 · 복원이 이 안에서 이름을 바꾼다)
    └── datafiles/
        ├── pgdata/           PostgreSQL 데이터 · WAL
        ├── checkpoint/       unify checkpoint (GritDB 엔진이 영구 반영을 마친 WAL 위치 · PostgreSQL checkpoint 와 다르다)
        ├── queue/            GritDB 엔진 대기열
        ├── buffer_spill/     메모리가 모자랄 때 밀어낸 데이터
        └── cold_file/        cold file

⚠ 설치한 뒤 datafiles/의 실경로(재배치 대상과 mount 지점 포함)를 바꾸지 않는다

• 이유: 바꾼 채 기동하면 cold file을 잃는다. 되돌릴 수 없다.
• 대신: 처음 설치 때 데이터 볼륨을 정한다(2.4). 디스크가 모자라면 경로를 그대로 두고 볼륨만 늘린다. 복구도 같은 실경로로 한다(8.1과 10.5).

• --datafiles에는 mount 지점 자체가 아니라 그 아래 디렉토리를 준다(2.4). 예: /data가 mount 지점이면 서비스 계정 소유의 /data/gritdb를 만들고 /data/gritdb/datafiles를 준다. 그러면 재초기화와 복원이 같은 볼륨 안, 서비스 계정이 쓸 수 있는 자리에서 이름만 바꾼다. mount 지점 자체를 주면 재초기화가 옛 데이터를 상위 파일시스템으로 옮기므로 그 파일시스템이 찰 수 있다(3.1).
• log/는 설치 경로 아래에 있고 옮기는 옵션이 없다. 그래서 설치 경로 볼륨에 로그 자리를 둔다. postgresql.log는 회전을 설정하지 않으면 계속 커진다(9.4).
• core 파일은 kernel.core_pattern이 정한 자리에 쌓이므로 그 자리를 데이터 볼륨이 아닌 곳으로 정한다(1.4와 9.6).
• 디스크를 늘릴 때는 경로를 그대로 두고 볼륨만 늘린다(위 경고).

1.6 포트 · 네트워크

• 들어오는 TCP 접속을 받는 포트는 PostgreSQL 포트 하나다. 그 밖의 GritDB TCP 포트는 없다.
• 유닉스 소켓은 PostgreSQL /tmp/.s.PGSQL.<포트>(unix_socket_directories)와 감독 프로세스 ~/gritdb1/run/grit_admin.sock이다. 감독 프로세스 소켓은 정지 명령용이다(11.7).
• GritDB는 스스로 바깥으로 통신하지 않는다. 사용권 통신이나 통계 통신이 없다. 바깥으로 나가는 접속은 분석계 subscription이 운영 DB로 여는 것 하나다.
• 설치 기본값으로는 localhost에서만 접속을 받는다. 원격 접속은 11.4를 본다.

1.7 인터넷이 없는 망 반입

• 반입 검수는 QuickStart 2.3 그대로 한다(sha256sum -c SHA256SUMS → install_gritdb.sh --verify-only).
• 설치 스크립트는 SHA256SUMS를 읽지 않으므로 sha256sum -c를 빼먹지 않는다.
• 자동화로 판정할 때는 --verify-only의 종료 코드가 0이면 통과다. 0이 아니면 화면 문구로 가른다.
  • jq is required to read the manifest가 나오면 jq를 반입한다(GDB-INSTALL-002).
  • hash mismatch나 dist verification FAILED가 나오면 반입을 다시 받는다(GDB-INSTALL-003).
• 패치나 업그레이드 때도 새 설치 파일을 같은 절차로 검수한다(3.4).

1.8 문자셋 · 정렬 · 시간대

• 데이터베이스 문자셋은 UTF8이고, 정렬(collation)은 C다. 문자 분류(ctype)는 C.UTF-8이다. 설치가 정하고 바꿀 수 없다. GritDB 엔진과 PostgreSQL의 정렬 결과를 맞추려고 고정했다.

  ~/gritdb1/bin/psql -p 5432 -d postgres -Atc "SELECT datname, pg_encoding_to_char(encoding), datcollate, datctype FROM pg_database;"
  

  모든 데이터베이스가 UTF8|C|C.UTF-8이면 정상이다.

• 정렬 결과는 바이트 순서다. ko_KR이나 en_US 정렬과 다르다. 예: ORDER BY에서 대문자가 먼저 오므로 B가 a보다 앞이다. 한글(완성형)은 가나다 순서로 정렬된다.

• 다른 정렬이나 ICU 정렬로 데이터베이스를 만들지 않는다(10.3).

• 서버 시간대는 설치 때의 OS 시간대다(TimeZone). SHOW timezone;을 실행해 확인한다. 바꾸려면 5.3을 본다.

• 분석 세션의 조회는 세션 시간대(SET timezone)를 쓰지 않는다. 그래서 응용 프로그램의 시간대를 서버 시간대와 맞춘다(10.3). 분석 세션은 OS 시간대로 계산하므로 서버 시간대를 OS 시간대와 같게 둔다(5.3).

1.9 설치 계획 점검표

• 설치 명령은 4, 5, 6, 10번이 모두 기본값이면 QuickStart 3.1 그대로 쓴다. 하나라도 다르면 그 값을 한 명령에 모아 첫 설치 때 준다(2.1의 “같이 쓰는 옵션 예”).

  cd ~/pkg/gritdb-*/
  TMPDIR=<디렉토리> ./install_gritdb.sh --datafiles /data/gritdb/datafiles --pgport 5433
  

  • 설치 경로와 데이터 볼륨은 설치한 뒤 바꿀 수 없다(1.5, 2.2, 2.4).
  • QuickStart 3.2와 3.3으로 확인한다. 경로와 포트만 바꿔 읽는다. 그다음 2.10으로 간다.

문제가 생기면

• 설치가 실패하면 QuickStart 7장의 GDB-INSTALL 계열과 TroubleShooting을 본다.

더 알아보기

• 설치 옵션은 2장, 메모리 설정은 5장, 보안은 11장을 본다.
• PostgreSQL 17 문서: 논리 복제, WAL 설정, 자원 사용, 커널 자원, 정렬