서버의 데이터베이스는 서버 자체의 루프백 주소에서만 연결을 수신하므로, TablePlus, Sequel Ace, DBeaver, MySQL Workbench 같은 데스크톱 도구는 여기에 직접 접속할 수 없습니다. SSH 터널을 사용하면 이러한 도구에 데이터베이스로 전달되는 로컬 포트를 제공하므로, MySQL을 인터넷에 노출하지 않고도 데이터에 제대로 된 GUI로 접근할 수 있습니다.
터널이 필요한 이유
웹사이트를 열고 사이트를 클릭한 다음 데이터베이스를 클릭하세요. 연결 정보 카드에는 호스트가 127.0.0.1로, 포트가 3306로 표시됩니다. 이것은 임시 값이 아닙니다. 데이터베이스는 실제로 자신이 실행되는 머신에서 오는 연결만 허용합니다. 공인 인터넷상의 어떤 것도 포트 3306에 접근할 수 없으며, 이는 공격의 한 범주 전체를 제거해줍니다.
SSH 터널은 이 틈을 안전하게 메워줍니다. SSH 클라이언트가 노트북에서 포트를 열고, 거기로 보내는 모든 데이터를 암호화한 다음, 마치 로컬 프로세스가 연결한 것처럼 서버 내부에서 데이터베이스로 전달합니다.
먼저 준비해야 할 것
터널은 SSH 연결이므로, 이 모든 작업이 동작하려면 먼저 해당 사이트에 SSH 키가 등록되어 있어야 합니다. 먼저 사이트에 SSH 키 추가하기를 따라 진행한 다음 이 문서로 돌아오세요.
다음 네 가지를 준비하세요.
- SSH 호스트, 포트, 사용자 이름: 설정에서 SSH 키로 이동한 뒤 연결 정보 카드에서 확인합니다.
- 데이터베이스 이름, 사용자 이름, 비밀번호: 데이터베이스에서 확인합니다. 눈 모양 아이콘을 클릭해 비밀번호를 표시하고, 복사 아이콘을 클릭해 클립보드에 복사할 수 있습니다.
데이터베이스 탭에 이 사이트 유형에는 프로비저닝된 데이터베이스가 없습니다라고 표시되면, 해당 사이트에는 데이터베이스가 없는 것입니다. 정적 사이트와 일부 Node.js 사이트는 데이터베이스 없이 생성됩니다.
터미널에서 터널 열기
기본 형태는 로컬 포트를 SSH 연결 반대편(서버 쪽)의 127.0.0.1:3306으로 전달하는 것입니다.
ssh -N -L 3307:127.0.0.1:3306 <ssh-username>@<ssh-host> -p <ssh-port>
-L 3307:127.0.0.1:3306은 사용자의 머신에서 포트 3307을 열고, 이를 서버의 루프백 인터페이스상의 포트 3306으로 전달합니다.-N는 셸을 실행하지 말고 터널만 열어두라는 의미입니다.- 해당 사이트의 키가 기본 키가 아니라면
-i /path/to/key을 추가하세요.
해당 터미널 창은 계속 실행한 상태로 두세요. 창이 열려 있는 동안, 노트북에서의 127.0.0.1:3307은 곧 해당 사이트의 데이터베이스입니다.
로컬에서는 3306 대신 3307을 사용하세요. 본인 머신에 이미 MySQL이나 MariaDB가 설치되어 있다면 이미 3306 포트를 사용 중일 것이며, 이 경우 터널은 "address already in use" 오류와 함께 바인딩에 실패합니다. 비어 있는 로컬 포트라면 어떤 것이든 사용할 수 있습니다.
데이터베이스 클라이언트를 터널로 연결하기
GUI 클라이언트에서 다음 값으로 일반 MySQL 연결을 만드세요.
| 항목 | 값 |
|---|---|
| 호스트 | 127.0.0.1 |
| 포트 | 3307 (전달한 로컬 포트 번호) |
| 사용자 | 데이터베이스 탭의 사용자 이름 |
| 비밀번호 | 데이터베이스 탭의 비밀번호 |
| 데이터베이스 | 데이터베이스 탭의 데이터베이스 이름 |
호스트 필드에는 SSH 호스트를 입력하지 마세요. 클라이언트 입장에서는 본인 머신에 있는 데이터베이스와 통신하는 것으로 간주됩니다.
내장 SSH 탭이 있는 클라이언트
TablePlus, Sequel Ace, DBeaver, MySQL Workbench는 모두 터널을 자체적으로 관리할 수 있어, 터미널을 계속 열어둘 필요가 없습니다. 두 그룹의 항목을 입력하세요.
- SSH 섹션: SSH 키 페이지의 호스트, 포트, 사용자 이름, 개인 키 파일.
- 데이터베이스 섹션: 호스트
127.0.0.1, 포트3306, 그리고 데이터베이스 탭의 데이터베이스 이름, 사용자, 비밀번호.
클라이언트가 터널을 생성할 때는 로컬 전달 포트가 아니라 데이터베이스 섹션에서 3306을 사용하세요. 클라이언트는 서버 관점에서 연결하므로 실제 포트를 그대로 인식합니다.
대신 phpMyAdmin 사용하기
테이블을 잠깐 확인하기만 하면 된다면 굳이 터널이 필요하지 않습니다. 데이터베이스 탭에는 phpMyAdmin 카드와 phpMyAdmin 열기 버튼이 있습니다. 이는 KPanel을 통해 자동으로 로그인되므로 별도의 비밀번호를 기억할 필요가 없으며, 새 탭에서 이미 해당 사이트의 데이터베이스를 가리킨 상태로 열립니다.
phpMyAdmin은 데이터를 훑어보거나 일회성 쿼리를 실행하거나 값을 확인할 때 더 빠른 방법입니다. 대량 내보내기, 스키마 작업, 스크립트로 자동화하고 싶은 작업에는 터널을 이용한 데스크톱 클라이언트가 더 적합합니다. 브라우저 방식에 대해서는 phpMyAdmin 사용하기를 참고하세요.
터널을 통해 쿼리와 덤프 실행하기
터널이 열려 있는 상태에서는 표준 명령줄 도구들을 로컬 전달 포트로 지정해 평소처럼 사용할 수 있습니다.
mysql -h 127.0.0.1 -P 3307 -u <db-user> -p <db-name>
mysqldump -h 127.0.0.1 -P 3307 -u <db-user> -p <db-name> > backup.sql
수동 덤프는 백업 전략이 아니라 편의용 사본일 뿐입니다. 실행한 그 순간의 데이터만 담고 있으며, 실행한 노트북에만 저장됩니다. KapsuleHost는 이미 사이트에 대해 매일 자동 백업을 수행하며 30일간 보관합니다. 로컬 .sql 파일에 의존하기 전에 백업하기를 확인하세요.
문제 해결
터널을 열 때 "Address already in use" 오류가 발생하는 경우. 본인 머신에서 이미 해당 로컬 포트를 사용 중입니다. 다른 포트, 예를 들어 -L 3399:127.0.0.1:3306을 선택하고 클라이언트의 포트 설정도 이에 맞춰 변경하세요.
데이터베이스 클라이언트에서 "Connection refused"가 발생하는 경우. 터널이 열려 있지 않은 상태입니다. SSH 터미널이 여전히 실행 중이고 오류가 출력되지 않았는지 확인하고, 클라이언트의 포트가 -L 인자의 로컬 포트와 일치하는지 확인하세요.
SSH는 연결되지만 클라이언트가 계속 시간 초과되는 경우. 공개 호스트 이름이 아니라 127.0.0.1:3306으로 전달했는지 확인하세요. 공개 이름으로 전달하면 서버에 인터넷을 통해 데이터베이스에 접근하라고 요청하는 것이 되는데, 이는 정확히 차단되어 있는 방식입니다.
"Access denied for user" 오류가 발생하는 경우. SSH 로그인은 성공했지만 MySQL 자격 증명이 잘못된 것입니다. 사용자 이름과 비밀번호를 직접 입력하지 말고 데이터베이스 탭의 복사 아이콘을 이용해 다시 복사하고, 올바른 데이터베이스 이름에 연결하고 있는지 확인하세요.
MySQL에 도달하기도 전에 "Permission denied (publickey)" 오류가 발생하는 경우. 이는 데이터베이스 계층이 아니라 SSH 계층의 문제입니다. 사이트에 SSH 키 추가하기의 문제 해결 섹션을 참고해 진행하세요.
다음으로 볼 만한 문서
- SFTP로 파일 업로드하기는 파일 전송에 동일한 SSH 자격 증명을 사용합니다.
- phpMyAdmin 사용하기: 브라우저 기반 데이터베이스 작업용입니다.
- 백업에서 복원하기: 쿼리가 의도한 것보다 더 많은 영향을 끼쳤을 때 참고하세요.