Sửa lỗi PostgreSQL FATAL: database "myapp_production" does not exist

Lỗi Kết Nối

Bạn đang cố gắng kết nối với phiên bản PostgreSQL của mình, có thể là trong quá trình triển khai hoặc khi thiết lập môi trường phát triển cục bộ, và kết nối bị từ chối ngay lập tức với thông báo này:

FATAL: database "myapp_production" does not exist

Lỗi này gây khó chịu vì nghe có vẻ như là vấn đề về quyền truy cập hoặc sự cố cấu hình máy chủ, nhưng thực tế, PostgreSQL chỉ đơn giản là thông báo rằng nó không thể tìm thấy cơ sở dữ liệu có tên chính xác mà bạn đã cung cấp trong danh mục nội bộ của nó. Cho dù bạn đang sử dụng psql, một máy khách Node.js node-postgres, hay database.yml của Rails, nguyên nhân gốc rễ hầu như luôn là sự không khớp giữa mong đợi và thực tế.

Các Tình Huống Thường Gặp

Cơ sở dữ liệu chưa bao giờ được tạo: Bạn đã cài đặt PostgreSQL nhưng chưa chạy lệnh CREATE DATABASE.
Lỗi đánh máy trong Cấu hình: Một lỗi chính tả nhỏ trong tệp .env hoặc cấu hình ứng dụng của bạn.
Phân biệt chữ hoa chữ thường: Bạn đã tạo một cơ sở dữ liệu có chữ hoa (ví dụ: "MyApp") nhưng đang tìm kiếm "myapp".
Hành vi mặc định của người dùng: Chạy psql mà không có đối số sẽ mặc định lấy tên cơ sở dữ liệu khớp với tên người dùng hệ thống của bạn.
Khởi tạo Docker: Container đã khởi động, nhưng các tập lệnh khởi tạo bị lỗi hoặc chưa chạy.

Bước 1: Xác minh các Cơ sở dữ liệu hiện có

Trước khi giả định rằng cơ sở dữ liệu đã tồn tại, hãy kiểm tra danh sách thực tế các cơ sở dữ liệu trên máy chủ. Kết nối với cơ sở dữ liệu mặc định postgres để xem những gì hiện có:

psql -U postgres -d postgres -l

Cờ -l liệt kê tất cả các cơ sở dữ liệu. Nếu bạn đã ở trong một phiên psql, hãy sử dụng lệnh meta:

\l

Hãy nhìn kỹ vào kết quả đầu ra. Nếu "myapp_production" không có trong danh sách, bạn đã xác nhận rằng cơ sở dữ liệu không tồn tại trên phiên bản PostgreSQL cụ thể này.

Bước 2: Tạo Cơ sở dữ liệu còn thiếu

Nếu cơ sở dữ liệu bị thiếu, bạn cần tạo nó. Bạn có thể thực hiện việc này thông qua dòng lệnh hoặc trình nhắc SQL.

Sử dụng Dòng lệnh (Shell)

Tiện ích createdb là một trình bao bọc (wrapper) cho lệnh SQL:

createdb -U postgres myapp_production

Sử dụng SQL

Kết nối với cơ sở dữ liệu postgres và chạy:

CREATE DATABASE myapp_production;

Cảnh báo về phân biệt chữ hoa chữ thường: Nếu bạn sử dụng dấu ngoặc kép như CREATE DATABASE "MyApp";, PostgreSQL sẽ giữ nguyên kiểu chữ. Nếu bạn kết nối sau đó bằng -d myapp, nó sẽ thất bại. Luôn ưu tiên tên chữ thường không có dấu ngoặc kép để đơn giản hóa.

Bước 3: Gỡ lỗi Chuỗi kết nối và Biến môi trường

Nếu cơ sở dữ liệu thực sự tồn tại trong danh sách nhưng ứng dụng của bạn vẫn báo lỗi, hãy kiểm tra cấu trúc chuỗi kết nối của bạn. Một URI điển hình trông như thế này:

postgresql://user:password@localhost:5432/myapp_production

Đảm bảo không có khoảng trắng thừa hoặc ký tự ẩn trong tệp .env của bạn. Ví dụ, trong môi trường Bash hoặc Docker, một khoảng trắng thừa trong biến môi trường có thể bị hiểu là một phần của chuỗi:

# Sai
DB_NAME=myapp_production 

# Đúng
DB_NAME=myapp_production

Bước 4: Xử lý Bẫy "Người dùng Mặc định"

Một trong những cách phổ biến nhất khiến lỗi này xuất hiện là khi chạy psql một mình. Theo mặc định, PostgreSQL cố gắng kết nối với một cơ sở dữ liệu được đặt tên theo tên người dùng hệ điều hành hiện tại của bạn. Nếu người dùng của bạn là ubuntu, việc chạy psql tương đương với:

psql -d ubuntu

Nếu bạn chưa tạo cơ sở dữ liệu có tên ubuntu, bạn sẽ nhận được lỗi FATAL: database "ubuntu" does not exist. Để tránh điều này, hãy luôn chỉ định tên cơ sở dữ liệu một cách rõ ràng:

psql -d postgres

Bước 5: Các bản sửa lỗi dành riêng cho Docker

Nếu bạn đang sử dụng hình ảnh Docker PostgreSQL chính thức, hãy đảm bảo biến môi trường POSTGRES_DB khớp với những gì ứng dụng của bạn đang tìm kiếm. Nếu bạn thay đổi biến này sau khi container đã được khởi tạo (nghĩa là sau khi thư mục /var/lib/postgresql/data được tạo), nó sẽ không có tác dụng.

Để khắc phục điều này trong Docker, bạn phải thực hiện một trong hai cách:

Xóa volume và khởi động lại (Lưu ý: Thao tác này sẽ xóa tất cả dữ liệu): docker-compose down -v
Kết nối với container đang chạy và tạo cơ sở dữ liệu theo cách thủ công:

docker exec -it my_postgres_container psql -U postgres -c "CREATE DATABASE myapp_production;"

Xác minh

Khi bạn tin rằng bản sửa lỗi đã được áp dụng, hãy xác minh nó bằng bài kiểm tra kết nối trực tiếp. Chạy lệnh này từ máy nơi ứng dụng được lưu trữ:

psql -h localhost -U your_user -d myapp_production -c "SELECT 1;"

Nếu bạn thấy một bảng với một số 1 duy nhất, kết nối đã thành công. Nếu bạn vẫn thấy lỗi FATAL, hãy kiểm tra kỹ xem bạn có đang kết nối với đúng máy chủ và cổng không (ví dụ: bạn có thể đang kết nối với một phiên bản Postgres cục bộ thay vì một phiên bản RDS hoặc Docker từ xa).

Bài học kinh nghiệm

Tên cơ sở dữ liệu trong PostgreSQL được kiểm tra nghiêm ngặt. Để ngăn chặn lỗi này trong tương lai:

Bao gồm bước tạo cơ sở dữ liệu trong quy trình CI/CD hoặc các tập lệnh thiết lập của bạn.
Luôn sử dụng chữ thường cho tên cơ sở dữ liệu để tránh những rắc rối về phân biệt chữ hoa chữ thường.
Xác định rõ ràng biến môi trường PGDATABASE trong shell của bạn nếu bạn sử dụng psql thường xuyên.
Kiểm tra nhật ký (logs) của ứng dụng để biết chuỗi kết nối cụ thể mà nó đang sử dụng khi chạy nhằm phát hiện các lỗi cấu hình động.