ServBay에서 PostgreSQL 업그레이드 및 마이그레이션 방법

웹 개발자에게 로컬 개발 환경에서 데이터베이스 버전을 관리하는 일은 매우 중요합니다. PostgreSQL을 업그레이드하거나 버전을 전환하는 것은 최신 기능 활용, 보안 업데이트 적용 또는 프로젝트별 데이터베이스 버전 호환성을 맞추기 위해 반드시 필요할 때가 많습니다. ServBay는 강력한 로컬 웹 개발 도구로서, 여러 PostgreSQL 버전을 손쉽게 설치·관리하고 그 사이를 유연하게 전환할 수 있게 해줍니다.

이 글에서는 ServBay 환경에서 PostgreSQL 기본 버전을 안전하고 효율적으로 변경하는 방법을 단계별로 안내합니다. PostgreSQL 10에서 PostgreSQL 16으로 마이그레이션하는 예시와 함께 설명하지만, 본 문서의 절차는 ServBay가 지원하는 모든 PostgreSQL 버전 간의 전환에 적용할 수 있습니다.

개요

PostgreSQL 버전을 전환하는 핵심 절차는 기존 데이터베이스 백업, 새 버전 설치, ServBay에서 기본 버전 설정, 그리고 백업된 데이터 복원 순서로 이루어집니다. 각 단계를 올바르게 수행하면 데이터 손실이나 호환성 문제의 위험을 최소화할 수 있습니다.

주요 활용 사례

• 최신 버전으로 업그레이드: 성능 향상, 신규 기능, 보안 패치 적용 등.
• 호환성 테스트: 실 서비스 환경 업그레이드 전에 로컬에서 애플리케이션과 신규 PostgreSQL 버전 간의 호환성 점검.
• 프로젝트별 요구사항 충족: 일부 프로젝트가 특정 PostgreSQL 버전을 필요로 할 경우.
• 버전 롤백: 호환성 문제 발생 시 과거 버전으로 되돌릴 필요가 있을 때.

사전 준비 사항

시작하기 전에 다음 조건을 충족하는지 확인하세요.

1. ServBay가 설치되어 실행 중인지 확인합니다.
2. ServBay의 패키지 관리 기능과 설정 패널에 대해 기본적인 이해가 필요합니다.
3. ServBay 관리 권한을 보유하고 있어야 합니다.
4. 기본적인 커맨드라인(터미널) 조작 능력이 필요합니다.
5. 데이터베이스 전체 백업 파일을 저장할 수 있을 만큼 충분한 디스크 공간을 확보합니다.

절차 안내

다음은 ServBay에서 PostgreSQL 기본 버전을 전환하는 상세 절차입니다.

1. 기존 버전 데이터베이스 백업

버전 변경 전, 반드시 현재 PostgreSQL 데이터베이스를 전부 백업할 것을 강력히 권장합니다. 이는 데이터 손실을 막는 데 가장 중요한 단계입니다. pg_dumpall 명령어를 사용하면 PostgreSQL 서버의 모든 데이터베이스(시스템 및 사용자 데이터베이스 포함)를 한 번에 백업할 수 있습니다.

터미널을 열고 다음 명령을 실행하세요.

pg_dumpall -U postgres -f postgresql_backup.sql

• -U postgres: PostgreSQL의 기본 슈퍼유저인 postgres 계정으로 연결합니다.
• -f postgresql_backup.sql: 백업 데이터를 현재 디렉토리 내의 postgresql_backup.sql 파일로 저장합니다.

명령 실행 시, PostgreSQL postgres 계정 비밀번호를 물어봅니다. 정확히 입력하면 백업이 시작됩니다. 완료 후 현재 디렉토리에 postgresql_backup.sql 파일이 생성됩니다. 이 백업 파일은 안전한 곳에 보관하세요.

2. ServBay를 통해 새 버전 설치

ServBay의 그래픽 사용자 인터페이스(GUI)에서 소프트웨어 패키지 패널(과거에는 "서비스 패널"로 표기될 수 있음)을 엽니다.

좌측 내비게이션 바에서 데이터베이스를 클릭한 후 PostgreSQL을 선택하세요. ServBay가 지원하는 다양한 PostgreSQL 버전 목록이 나옵니다. 전환하려는 새 버전(예: PostgreSQL 16) 옆의 "설치" 버튼을 클릭합니다.

ServBay가 자동으로 선택한 PostgreSQL 버전을 다운로드하고 설치합니다. 진행이 끝날 때까지 기다립니다.

3. ServBay에서 기존 PostgreSQL 버전 비활성화

신규 버전을 설치한 뒤, 포트 충돌이나 시스템이 구버전을 잘못 참조하는 일을 방지하기 위해 이전에 사용 중이던 PostgreSQL 서비스를 비활성화하는 것이 좋습니다.

ServBay 소프트웨어 패키지 패널 → 데이터베이스 → PostgreSQL 목록에서 현재 실행 중인 구버전(예: PostgreSQL 10)을 찾으세요. 그 옆에 있는 토글 스위치(보통 활성화 시 녹색, 클릭 시 회색으로 변함)를 클릭해 비활성화합니다.

서비스 상태가 "비활성화됨"으로 표시되는지 확인하세요.

4. ServBay에서 새 버전 PostgreSQL 활성화

기존 버전을 비활성화한 후, 방금 설치한 새로운 PostgreSQL 버전을 활성화하세요.

ServBay의 소프트웨어 패키지 패널 → 데이터베이스 → PostgreSQL 목록에서 새 버전(예: PostgreSQL 16)을 찾고, 옆의 토글 스위치를 클릭해 활성화(녹색) 하세요.

잠시 기다린 후, 서비스 상태가 실행중(녹색)으로 변하는지 확인합니다.

5. ServBay 설정에서 PostgreSQL 기본 버전 전환

ServBay는 “기본” PostgreSQL 버전을 지정할 수 있습니다. 이 기본값은 터미널에서 psql 등 명령어 실행 시 참조할 PostgreSQL 실행 파일 버전을 결정합니다.

ServBay 설정 패널을 엽니다. 데이터베이스 or PostgreSQL 관련 설정 항목을 찾아, ServBay가 어느 버전을 시스템 기본값으로 지정할지 선택합니다.

방금 활성화한 새 버전(예: PostgreSQL 16)을 선택한 뒤, 하단의 Apply 버튼을 눌러 변경 사항을 적용하세요.

6. 소프트웨어 패키지 패널에서 기본 버전 전환 확인

다시 ServBay 소프트웨어 패키지 패널 → 데이터베이스 → PostgreSQL 목록으로 가서 새 버전(예: PostgreSQL 16) 옆에 “기본” 또는 기타 표시가 있는지 확인하세요. 정상적으로 기본값으로 설정되었다는 안내가 나와야 합니다.

7. 커맨드라인에서 기본 버전 확인

ServBay GUI에서 기본값을 확인할 수 있지만, 커맨드라인에서 검사하면 시스템 환경(PAH 환경변수 등)이 제대로 갱신되었는지 확실히 알 수 있습니다.

새 터미널 창을 열거나, source ~/.zshrc, source ~/.bash_profile 등 본인의 쉘 설정에 따라 환경변수를 재로딩하세요. 그런 뒤 다음 명령을 실행합니다.

psql --version

출력 결과로 새 버전(PostgreSQL 16.x.x 등)이 나오면 정상 변경된 것입니다.

여전히 구버전이 나오면, ServBay 앱을 완전히 종료 후 재실행하거나 터미널 환경변수 설정을 직접 수정해야 할 수 있습니다.

8. 데이터베이스 복원

이제 앞서 백업한 데이터를 새 버전 PostgreSQL에 복원해야 합니다. 새 버전의 서비스가 실행 중인지 먼저 확인하세요.

백업 파일(postgresql_backup.sql)이 있는 폴더에서 터미널로 다음 명령을 실행합니다.

psql -U postgres -f postgresql_backup.sql

• -U postgres: 새 버전 PostgreSQL의 postgres 계정으로 접속.
• -f postgresql_backup.sql: postgresql_backup.sql 파일 내 SQL 명령을 실행.

다시 비밀번호 입력을 요구하며, 입력 이후 데이터 복원이 시작됩니다. 백업 파일 크기에 따라 시간 소요가 다릅니다.

주의: 백업 파일 내에 데이터베이스 생성 명령이 포함되어 있고, 동일 이름의 데이터베이스가 이미 새 버전에 있다면 오류가 날 수 있습니다. 이런 경우, 복원 전에 대상 데이터베이스를 먼저 삭제해야 합니다. 속한 데이터베이스가 반드시 삭제해도 괜찮은 것인지 두 번 확인하세요(혹은 추가 백업 필수). 삭제는 DROP DATABASE dbname; 명령으로 할 수 있습니다.

9. 데이터베이스 복구 확인

복원 완료 후, 새 버전 PostgreSQL 서버에 접속해 데이터베이스와 데이터까지 제대로 이전되었는지 점검하세요.

터미널에서 아래 명령을 입력합니다.

psql -U postgres

비밀번호 입력 후 로그인에 성공하면, 다음 명령으로 데이터베이스 목록을 확인합니다.

\l

특정 데이터베이스로 이동(예: \c your_database_name)한 다음, 테이블 구조와 샘플 데이터를 조회해 점검하세요 (\d your_table_name, SELECT COUNT(*) FROM your_table_name; 등).

\c servbay_demo_db -- 샘플 데이터베이스 접속
\d              -- 모든 테이블 목록 확인
SELECT * FROM your_table_name LIMIT 10; -- 일부 데이터 조회

중요한 데이터가 모두 잘 복구되었는지 확인했다면, 이제 새 버전의 PostgreSQL 환경에서 개발을 시작할 수 있습니다.

유의사항

• 데이터 호환성: PostgreSQL는 버전 간 호환성을 잘 유지하지만, 주요 버전 간 마이그레이션일 경우 일부 데이터 포맷이나 기능에 호환성 문제가 발생할 수 있습니다. 업그레이드 전 관련 공식 문서를 반드시 참고하세요.
• 애플리케이션 호환성: 애플리케이션 코드, 데이터베이스 드라이버, ORM 등도 새 PostgreSQL 버전 완벽 호환이 필요한 경우가 많습니다. 버전 변경 후 반드시 충분한 애플리케이션 테스트를 하세요.
• 비밀번호 관리: 과정 중 PostgreSQL postgres 계정 비밀번호 입력이 필요하므로 반드시 기억해두세요. 비밀번호를 잊었다면, ServBay의 root 비밀번호 초기화 기능을 활용할 수 있습니다.
• 백업 검증: 단순 복원 절차만 따라가지 말고, 중요한 업그레이드라면 외부 테스트 환경에 미리 복원을 시도하여 백업 파일 완전성을 점검해두면 좋습니다.

자주 묻는 질문 (FAQ)

• Q: 복원할 때 데이터베이스가 이미 존재한다고 오류가 나오면 어떻게 하나요?
  • A: 백업 파일에 CREATE DATABASE 문이 포함되어 있으면서 동일 이름의 데이터베이스가 새 버전에 이미 있으면 복원이 실패합니다. 직접 생성해두지 않은 데이터베이스라면, 새 버전 PostgreSQL에 접속(psql -U postgres)하여 DROP DATABASE dbname;으로 충돌 나는 데이터베이스를 삭제한 뒤 복원 명령을 재실행하세요. 꼭 삭제 전에 백업이 충분한지, 삭제해도 괜찮은 DB인지 확인하십시오.
• Q: ServBay에 PostgreSQL 여러 버전을 설치했는데, psql --version 명령 결과가 내가 설정한 기본 버전과 다르게 나와요.
  • A: 이는 환경변수 미갱신 문제일 수 있습니다. 터미널을 완전히 새로 열거나, source ~/.zshrc(혹은 자신 설정 파일) 명령을 실행하세요. 여전히 문제면 ServBay를 완전히 종료했다가 재실행해 보십시오.
• Q: 버전 전환 후, 내 애플리케이션이 데이터베이스 연결에 실패합니다.
  • A: 애플리케이션이 연결하려는 포트(일반적으로 5432)가 신규 PostgreSQL에서 제대로 열려있는지 확인하고, 데이터베이스 드라이버 또는 ORM이 해당 버전과 호환되는지 확인하세요.

결론

본 매뉴얼에 안내된 절차를 따르면, ServBay 환경에서 PostgreSQL 기본 버전을 안전하게 그리고 원활하게 전환할 수 있습니다. 가장 중요한 것은 반드시 사전에 전체 데이터 백업을 하고, ServBay 내 패키지 및 default 설정을 관리한 뒤, 데이터를 새 버전에 복원하고 검증하는 과정입니다. ServBay의 강력한 패키지 관리 기능을 충분히 활용하면 개발 및 테스트 환경에서 원하는 버전의 데이터베이스를 자유롭게 구성할 수 있습니다. 다양한 프로젝트 요구에 맞춰 로컬 데이터베이스를 유연하게 관리하세요.