# 로컬 개발자의 Bastion 경유 Cloud SQL 접속

Cloud SQL은 Private IP만 사용하므로, 로컬 개발자는 회사 NAT를 통해 Bastion VM에 SSH 접속한 뒤 SSH Local Port Forwarding으로 Cloud SQL에 연결합니다.

## 네트워크 구성

```text
개발자 로컬 PC
    │
    │ SSH TCP 22
    │ 회사 NAT IP: 27.122.140.10
    ▼
Bastion VM
    │
    │ Cloud SQL Private IP
    ▼
Cloud SQL
```

접속 대상은 `sbscax` 데이터베이스의 `core` 스키마이며, 애플리케이션/개발 접속 사용자는 `db_appuser`입니다. 테이블과 enum에 대한 자세한 내용은 [Database Schema Guide](database-schema.md)를 참고합니다.

## 1. Google Cloud 인증

Google Cloud CLI로 로그인하고 프로젝트를 설정합니다.

```bash
gcloud auth login
gcloud config set project pjt-sbscontentsax-poc
gcloud auth list
```

현재 로그인 계정은 `lgcns.com`으로 끝나는 계정을 사용해야 합니다.

## 2. 로컬 도구 설치

Google Cloud CLI와 PostgreSQL client가 설치되어 있어야 합니다.

```bash
sudo apt-get update
sudo apt-get install -y postgresql-client
```

배포판에 따라 `postgresql-client` 패키지가 없으면 설치 가능한 버전을 확인합니다.

```bash
apt-cache search '^postgresql-client-[0-9]+$'
```

예를 들어 PostgreSQL 15 client가 검색되면 다음과 같이 설치할 수 있습니다.

```bash
sudo apt-get install -y postgresql-client-15
```

Cloud SQL PostgreSQL 16에 접속하더라도 PostgreSQL client 버전이 반드시 16일 필요는 없습니다.

## 3. SSH 터널 생성

PostgreSQL 기본 포트 `5432`를 로컬 포트 `15432`로 전달합니다. `10.126.0.3`은 실제 Terraform output의 Cloud SQL Private IP로 변경합니다.

```bash
gcloud compute ssh vm-an3-sbscax-poc-dbproxy \
  --project=pjt-sbscontentsax-poc \
  --zone=asia-northeast3-a \
  -- -N -L 15432:10.126.0.3:5432
```

주의사항:

- 줄바꿈에 사용하는 `\` 뒤에 공백을 입력하지 않습니다.
- 위 명령은 터널을 유지하므로 실행한 터미널을 종료하지 않습니다.
- 이 구성은 IAP를 사용하지 않으므로 `--tunnel-through-iap` 옵션을 사용하지 않습니다.
- 한 줄로 실행하려면 다음 명령을 사용합니다.

```bash
gcloud compute ssh vm-an3-sbscax-poc-dbproxy --project=pjt-sbscontentsax-poc --zone=asia-northeast3-a -- -N -L 15432:10.126.0.3:5432
```

최초 접속 시 다음과 유사한 host key 메시지가 표시될 수 있습니다. 이는 정상적인 동작입니다.

```text
Warning: Permanently added ...
```

## 4. 터널 연결 확인

터널을 실행한 터미널은 유지하고, 별도 터미널에서 확인합니다.

```bash
nc -vz 127.0.0.1 15432
```

정상적인 경우 다음과 유사한 결과가 표시됩니다.

```text
Connection to 127.0.0.1 15432 port [tcp/*] succeeded
```

## 5. PostgreSQL 접속

`psql`을 실행한 뒤 비밀번호 입력창에 `db_appuser`의 Cloud SQL 비밀번호를 입력합니다.

```bash
psql "host=127.0.0.1 port=15432 dbname=sbscax user=db_appuser"
```

접속 후 `core` 스키마를 확인하거나 명시적으로 사용할 수 있습니다.

```sql
SHOW search_path;
SET search_path TO core;
```

비밀번호를 셸 명령어나 Git 저장소에 저장하지 않습니다. 특히 `PGPASSWORD`를 명령어에 직접 지정하면 셸 history나 프로세스 정보에 노출될 수 있으므로 사용하지 않습니다.

## 6. 접속 종료

PostgreSQL client에서 종료합니다.

```text
\q
```

SSH 터널을 종료하려면 터널이 실행 중인 터미널에서 `Ctrl + C`를 입력합니다.