데이터베이스 연결 문자열이 계속 헷갈릴 때

프로젝트가 커질수록 연결 문자열이 계속 문제가 된다. 로컬에서는 sqlite 쓰다가, 스테이징에서는 PostgreSQL, 운영에서는 managed DB... 환경마다 다르다.

처음엔 각 환경에 맞게 조심해서 설정했는데, 세 달 뒤 로컬 개발을 다시 시작할 때 어떻게 설정했더라..? 하고 헷갈렸다.

연결 문자열 기록해두기

각 환경별로 연결 문자열이 정확히 뭔지 문서로 남겨둔다. 특히:

• 호스트: localhost vs example.com
• 포트: 5432 vs 3306 vs 5432
• 데이터베이스 이름: 개발용, 스테이징용, 운영용이 다른지
• 인증: 사용자명, 비밀번호 위치
• 옵션: SSL/TLS 필수인지, 타임아웃 설정 등

환경별 예시

로컬:

psqlqlite:///./test.db

스테이징:

postgresql://user:[email protected]:5432/app_staging

운영:

postgresql://user:[email protected]:5432/app_prod?sslmode=require

보기만 해도 다르다는 걸 알 수 있다. 연결 문자열 포맷 자체가 다른 경우도 있다.

빌드 시점에 확인

배포 전에 실제로 연결되는지 테스트한다.

npm run build
# 빌드 후 실제 데이터베이스에 연결 시도
# 타임아웃, 인증 실패 등의 에러를 먼저 확인

운영 배포는 빌드하고 나서 5분은 기다렸다가 실제로 데이터를 조회해본다. 연결이 느려서 나중에야 에러가 나는 경우도 있다.

비밀번호와 키 관리

연결 문자열에는 보통 비밀번호가 들어간다. 이걸 환경 변수로 관리한다.

• .env 파일: 로컬 개발용, 절대 커밋하지 말기
• .env.example: 템플릿, 커밋해도 됨
• 배포 환경: 별도의 시크릿 관리 시스템 (AWS Secrets, GitHub Secrets 등)

절대로 연결 문자열을 소스 코드에 하드코딩하지 말아야 한다.

실제 확인 순서

새 환경에서 처음 개발할 때:

1. .env.example을 보고 필요한 변수 확인
2. 각 변수의 현재 값을 .env에 적기 (로컬) 또는 환경 변수로 설정 (배포)
3. 앱 시작 전에 "Database connection successful" 같은 로그가 나오는지 확인
4. 간단한 쿼리 날려보기 (SELECT 1 같은)

마지막으로, 연결 문자열 문제는 보이는 게 다다. 외워서 쓰면 절대 안 되고, 매번 확인하고 문서로 남겨야 한다. 그래야 3개월 뒤 누군가 "로컬 DB 설정 어떻게 해"라고 물었을 때 빨리 답할 수 있다.