워드프레스 데이터베이스 연결 오류: 무슨 뜻이고 어떻게 고치나

사이트를 열면 프런트엔드든 wp-admin이든 모든 페이지가 한 줄짜리 회색 문장으로 바뀌어 있습니다. 데이터베이스 연결을 설정하는 중 오류가 발생했습니다. 아무것도 렌더링되지 않습니다. 될 수가 없으니까요. WordPress는 페이지를 만드는 데까지도 가지 못했습니다.

빠르게 고치게 해 주는 개념은 이렇습니다. WordPress는 글, 페이지, 설정, 사용자 등 모든 콘텐츠를 파일이 아니라 MySQL 데이터베이스에 보관합니다. 요청이 올 때마다 wp-config.php에서 네 가지 로그인 정보를 읽어 그 데이터베이스에 연결하고 필요한 것을 꺼내 옵니다. 이 오류는 그 연결이 시도되었고 거부되었다는 뜻입니다. 해결책은 왜 거부되었는지 알아내는 것이고, 가능성은 세 가지뿐입니다.

가능성이 높은 순서로, 세 가지 원인

1. wp-config.php의 잘못된 접속 정보 — 대개 호스팅을 옮긴 결과입니다.
2. 데이터베이스 서버가 죽었거나 과부하 상태 — 대개 당신 쪽에서 아무것도 바꾸지 않았는데 생깁니다.
3. 데이터베이스 손상 — 덜 흔하고, 드러나는 방식도 다릅니다.

이 순서대로 확인해 나가세요.

1단계: 네 가지 접속 정보를 확인한다

SFTP나 호스팅의 파일 관리자로 사이트 루트의 wp-config.php를 엽니다. 연결을 정의하는 건 다음 네 줄입니다.

define( 'DB_NAME', 'your_database_name' );
define( 'DB_USER', 'your_database_user' );
define( 'DB_PASSWORD', 'your_database_password' );
define( 'DB_HOST', 'localhost' );

이 값들은 모두 호스팅이 배정한 것과 정확히 일치해야 합니다. 호스팅 제어판의 데이터베이스 항목(cPanel에서는 「MySQL Databases」)을 열고 한 글자씩 대조하세요.

• DB_NAME — 호스팅은 cpaneluser_wpdb처럼 이름 앞에 계정명을 접두어로 붙이는 경우가 많습니다. 이 접두어도 이름의 일부입니다.
• DB_USER — 같은 접두어가 붙고, 그 사용자는 그냥 존재하는 게 아니라 해당 데이터베이스에 배정되어 있어야 합니다.
• DB_PASSWORD — 가장 흔한 범인입니다. 확신이 없으면 제어판에서 재설정하고 새 값을 붙여 넣으세요. 끝에 붙은 공백이나 자동 변환된 따옴표를 조심하세요.
• DB_HOST — localhost라고 넘겨짚지 마세요. 많은 호스팅이 mysql.yourhost.com 같은 주소(때로는 :port 포함)의 전용 데이터베이스 서버를 씁니다. 올바른 값은 제어판에 나와 있습니다.

이 네 값이 놓이는 곳이 바로 이 파일이므로, 따옴표까지 올바르게 정리된 wp-config.php를 다시 만드는 가장 안전한 방법은 wp-config.php 생성기입니다. 데이터베이스 네 칸을 채우고, 나온 결과를 예전 블록 위에 붙여 넣으세요.

거의 모든 이전에서 이 단계 하나로 오류가 해결됩니다. 예전 호스팅에서 맞던 접속 정보가 새 호스팅에서는 틀리기 때문입니다.

2단계: 데이터베이스 서버가 실제로 살아 있는지 확인한다

접속 정보가 맞는데도 오류가 계속된다면 — 특히 당신이 아무것도 바꾸지 않았는데 저절로 나타났다면 — 데이터베이스 서버 자체가 용의자입니다.

공용 호스팅에서는 흔한 일이고 대개 일시적입니다. 트래픽이 몰릴 때 MySQL 서비스가 감당하지 못하거나 계정별 연결 수 한도에 걸려 새 연결을 거부하기 시작합니다. 보통 몇 분 안에 회복됩니다. 과감한 조치에 나서기 전에 잠시 기다렸다가 새로고침하세요.

WordPress와 무관하게 접속 정보가 유효한지 확인하려면, wp-config.php 옆에 작은 스크립트를 하나 놓습니다.

<?php
$link = mysqli_connect('localhost', 'your_database_user', 'your_database_password');
if (!$link) {
    die('Connection failed: ' . mysqli_connect_error());
}
echo 'Connected — the server and credentials are fine.';

실제 DB_HOST, DB_USER, DB_PASSWORD를 사용하세요. Connected가 출력되면 로그인 정보는 정상이고 문제는 다른 곳(데이터베이스 손상, 3단계)에 있습니다. 연결 오류가 출력되면 메시지가 어느 쪽인지 알려 줍니다. 「Access denied」는 사용자나 비밀번호가 틀렸다는 뜻이고, 「Can’t connect to MySQL server」는 호스트가 틀렸거나 서비스가 실제로 죽었다는 뜻이니 호스팅에 연락할 때입니다. 끝나는 즉시 스크립트를 삭제하세요.

3단계: 손상된 데이터베이스를 복구한다

손상과 연결 문제를 가르는 단서가 하나 있습니다. 프런트엔드는 열리는데 wp-admin에서는 오류가 나거나, 그 반대인 경우입니다. 연결이 정말로 거부된 거라면 양쪽 다 죽어 있어야 합니다. 이렇게 갈린다는 건 테이블이 손상됐다는 신호입니다.

WordPress에는 복구 도구가 내장돼 있습니다. wp-config.php의 「편집 중단」 주석 위에 한 줄을 추가하세요.

define( 'WP_ALLOW_REPAIR', true );

그런 다음 브라우저에서 이 URL을 직접 엽니다.

https://yoursite.com/wp-admin/maint/repair.php

이 화면은 로그인 없이 열립니다 — 당신이 잠겨서 못 들어갈 수 있으니 그게 요점입니다 — 그리고 「Repair Database」와 「Repair and Optimize Database」를 제공합니다. 실행하세요.

그런 다음 곧바로 wp-config.php에서 그 줄을 삭제하세요. 그 줄이 있는 동안에는 인터넷의 누구든 그 URL로 들어와 당신의 데이터베이스에 복구를 실행할 수 있습니다. 이건 선택적인 뒷정리가 아니라, 방금 열어 놓은 구멍을 막는 일입니다.

4단계: 복구 화면조차 연결되지 않을 때

복구 페이지 자체가 연결 오류를 띄운다면 복구할 것이 없습니다 — 데이터베이스에 아예 도달하지 못하는 것이므로 1단계나 2단계로 돌아갑니다. 이 지점에서 확실한 선택은 호스팅의 가장 최근 백업에서 데이터베이스를 복원하는 것입니다. 대부분의 제어판은 매일 자동으로 데이터베이스 스냅샷을 남깁니다. 연결조차 안 되는 손상을 뒤쫓는 것보다, 어젯밤 상태에서 복원하는 편이 거의 언제나 더 빠르고 안전합니다.

무시해도 되는 조언

「그냥 WordPress를 다시 설치하세요.」 이 오류는 데이터베이스 연결에 관한 것이지 코어 파일과는 무관합니다. 재설치는 멀쩡히 잘 돌아가는 바로 그 파일들을 갈아 끼울 뿐, 망가진 부분은 건드리지 않습니다.

「PHP 메모리 한도를 늘리세요.」 메모리 부족은 메시지가 다른 별개의 오류입니다. 한도를 올려도 거부된 데이터베이스 연결에는 아무 효과가 없고, 접속 정보를 확인하지 않았다는 사실만 가릴 뿐입니다.

「캐시를 지우세요.」 이 실패는 어떤 캐시가 페이지를 내보내기도 전에 PHP 안에서 일어납니다. 연결이 거부되는 동안에는 캐시를 지워도 아무것도 바뀌지 않습니다. 캐시 삭제가 의미 있는 건 사이트가 돌아온 뒤뿐입니다.

「데이터베이스를 직접 고치세요.」 연결이 되는지도 확인하기 전에 phpMyAdmin으로 테이블을 손수 편집하는 것은, 일시적인 장애를 영구적인 데이터 손실로 바꾸는 지름길입니다. 연결부터 확인하고, 데이터는 맨 마지막에, 그것도 백업에서만 손대세요.

그래도 안 되면

테스트 스크립트로 접속 정보가 확인되고, 서버도 살아 있고, 복구도 연결되어 오류가 없다고 나오는데도 사이트에 여전히 이 메시지가 뜬다면, 남은 용의자는 자기만의 연결로 데이터베이스와 통신하는 플러그인 — 오래된 호스트 정보를 저장해 둔 캐싱이나 데이터베이스 플러그인 — 입니다. SFTP로 wp-content/plugins를 plugins-off로 이름을 바꿔 배제해 보세요. 오류가 사라지면 플러그인을 하나씩 되돌리며 다시 나타날 때까지 확인하세요.