Xử Lý Sự Cố: Database

Sửa các vấn đề kết nối và query database phổ biến.

Connection Refused

Lỗi: ECONNREFUSED 127.0.0.1:5432 hoặc connect ECONNREFUSED 127.0.0.1:27017

Lỗi này nghĩa là 1DevTool đã kết nối đến host và port trong connection string, nhưng không có gì đang lắng nghe ở đó. Database server có thể chưa chạy hoặc đang lắng nghe trên port khác.

Cách sửa:

  • Kiểm tra database có đang chạy không. Cho PostgreSQL: chạy pg_ctl status trong terminal. Cho MySQL: mysqladmin status. Cho Redis: redis-cli ping (bạn sẽ nhận PONG). Khởi động service nếu nó đã dừng.
  • Kiểm tra port. Các port mặc định là 5432 (PostgreSQL), 3306 (MySQL/MariaDB), 27017 (MongoDB), và 6379 (Redis). So sánh port trong DATABASE_URL với port database thực sự đang dùng.
  • Docker containers. Nếu database đang chạy trong Docker, kiểm tra container có chạy với docker ps. Nếu không có trong danh sách, khởi động nó với docker start <container-name>. Cũng xác nhận port của container được publish đến host (tìm 0.0.0.0:5432->5432/tcp trong output docker ps).

Authentication Failed

Lỗi: password authentication failed for user "postgres" hoặc Access denied for user 'root'@'localhost'

Username hoặc password trong connection string không khớp với những gì database server mong đợi.

Cách sửa:

  • Kiểm tra kỹ username và password trong DATABASE_URL hoặc connection settings. Dễ nhầm lẫn giữa password tài khoản Supabase với password database — chúng khác nhau. Dùng password hiển thị trong Supabase dashboard dưới Settings → Database.
  • Ký tự đặc biệt trong passwords. Nếu password chứa @, #, /, hoặc :, các ký tự này phải được URL-encoded trong connection string. Ví dụ, @ thành %40 và # thành %23. Password như p@ss#word sẽ viết thành p%40ss%23word trong URL.

SSL/TLS Required

Lỗi: SSL connection has been closed unexpectedly hoặc server requires SSL but client does not support it

Nhiều cloud database providers (Supabase, Neon, Railway, Render) yêu cầu kết nối mã hóa.

Cách sửa: Thêm ?sslmode=require vào cuối connection string PostgreSQL:

postgresql://user:pass@host:5432/db?sslmode=require

Cho MongoDB Atlas, dùng scheme mongodb+srv:// trong connection string — nó tự động bật TLS và không cần parameter thêm.

Query Bị Timeout

Nguyên nhân: query đang quét quá nhiều dữ liệu, hoặc kết nối mạng giữa 1DevTool và database bị đứt giữa chừng.

Cách sửa:

  • Thêm mệnh đề LIMIT vào query khi khám phá dữ liệu. Ví dụ: SELECT * FROM orders LIMIT 100.
  • Nếu query cụ thể luôn chậm, kiểm tra xem các cột trong mệnh đề WHERE có indexes không. Chạy EXPLAIN ANALYZE <query của bạn> trong SQL editor sẽ hiển thị query plan.
  • Nếu timeout xảy ra không liên tục, kiểm tra mạng. Kết nối VPN đặc biệt có thể gây kết nối database không ổn định.

MongoDB: Ký Tự Đặc Biệt Trong Password

Nếu password MongoDB chứa @, /, :, hoặc #, bạn phải URL-encode các ký tự đó trong connection string. Các ký tự này có ý nghĩa đặc biệt trong URL và sẽ phá vỡ parsing nếu dùng nguyên bản.

Các encoding phổ biến: @ → %40, # → %23, / → %2F, : → %3A.

Ví dụ: password my@secret#pass thành my%40secret%23pass trong connection string.

Không Thể Kết Nối Đến Docker Container

Nếu database đang chạy trong Docker container và bạn đang cố kết nối từ 1DevTool (chạy trên máy host), đừng dùng localhost trong connection string. Từ host, localhost đề cập đến chính máy host — không phải container.

Dùng host.docker.internal thay thế:

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

Hostname đặc biệt này luôn phân giải đến máy host từ bên trong Docker, và đến loopback interface chính xác từ phía host.