Docker pgAdmin: Cách thiết lập GUI cho PostgreSQL với Docker Compose

Việc chuyển đổi giữa các phiên, ghi nhớ cú pháp, và cầu mong bạn không gõ sai một truy vấn phá hủy dữ liệu sẽ nhanh chóng trở nên mệt mỏi. Không có kế hoạch truy vấn trực quan, không có trình duyệt schema, và cũng không có cách dễ dàng để sao lưu cơ sở dữ liệu. Vẫn dùng được, nhưng còn xa mới lý tưởng.

pgAdmin 4 khắc phục điều đó với một GUI chạy trên trình duyệt, xây dựng riêng cho PostgreSQL. Và chạy nó trong Docker có nghĩa là không cần cài đặt cục bộ. Bạn chỉ cần khởi động container là xong.

Trong bài viết này, tôi sẽ hướng dẫn bạn thiết lập PostgreSQL và pgAdmin 4 với Docker Compose, kết nối hai container, và sử dụng Query Tool, trình duyệt schema, cùng tính năng sao lưu của pgAdmin.

Để theo dõi, bạn cần cài đặt và chạy Docker trên máy của bạn. Nếu bạn mới dùng Docker Compose, hãy đọc hướng dẫn của chúng tôi để xem nó đơn giản hóa phát triển đa container như thế nào.

pgAdmin 4 là gì?

pgAdmin 4 là nền tảng phát triển và quản trị mã nguồn mở chạy trên trình duyệt dành cho PostgreSQL. Bạn truy cập qua trình duyệt web, nên không cần cài ứng dụng desktop. Nó cung cấp GUI để quản lý cơ sở dữ liệu, chạy truy vấn, kiểm tra schema, và xử lý sao lưu - tất cả mà không cần đụng tới dòng lệnh.

Docker image chính thức là dpage/pgadmin4, do đội ngũ phát triển pgAdmin duy trì.

Chạy pgAdmin 4 trong Docker có vài lợi thế rõ rệt so với cài đặt cục bộ. Đầu tiên là tính di động - toàn bộ môi trường cơ sở dữ liệu của bạn nằm trong một tệp docker-compose.yml mà bạn có thể chia sẻ với đồng đội. Thứ hai, không có xung đột phiên bản - pgAdmin chạy trong container riêng của nó, hoàn toàn tách biệt khỏi mọi thứ khác trên máy bạn. Và khi xong việc, docker compose down sẽ dọn sạch mọi thứ.

pgAdmin 4 so với các GUI PostgreSQL khác

Có vô số công cụ GUI quản lý cơ sở dữ liệu. Đây là cách pgAdmin 4 so sánh với hai lựa chọn phổ biến.

pgAdmin 4 so với các lựa chọn phổ biến

DBeaver và TablePlus đều là công cụ tốt, nhưng không có image Docker chính thức. Nếu phiên bản PostgreSQL của bạn đã chạy trong Docker, pgAdmin 4 là lựa chọn rất phù hợp - bạn chỉ cần thêm một service vào docker-compose.yml và mọi thứ chạy cùng nhau trong cùng một mạng.

Thiết lập môi trường với Docker Compose

Cách nhanh nhất để chạy PostgreSQL và pgAdmin 4 cùng nhau là một tệp docker-compose.yml duy nhất. Nếu bạn mới với chủ đề này, Hướng dẫn Docker Compose của chúng tôi bao quát các kiến thức nền tảng. Ở đây, tôi sẽ tập trung vào cấu hình dành riêng cho pgAdmin.

Dưới đây là tệp hoàn chỉnh bạn có thể sao chép-dán:

services:
  postgres:
    image: postgres:18
    container_name: postgres
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql
    networks:
      - pgnetwork

  pgadmin:
    image: dpage/pgadmin4:9.13
    container_name: pgadmin
    environment:
      PGADMIN_DEFAULT_EMAIL: you@yourdomain.com
      PGADMIN_DEFAULT_PASSWORD: password
      PGADMIN_LISTEN_PORT: 5050 
    ports:
      - "5050:5050"                
    volumes:
      - pgadmin_data:/var/lib/pgadmin
    depends_on:
      - postgres
    networks:
      - pgnetwork

volumes:
  postgres_data:
  pgadmin_data:

networks:
  pgnetwork:

Trường depends_on báo cho Docker Compose khởi động container postgres trước pgadmin. Nếu không, pgAdmin có thể khởi động trước khi PostgreSQL sẵn sàng và không kết nối được. Nó không chờ PostgreSQL ở trạng thái khỏe hoàn toàn - chỉ chờ container khởi động. Vậy là đủ để tránh hầu hết điều kiện tranh chấp.

Biến môi trường của pgAdmin 4

Có hai biến môi trường bắt buộc:

• PGADMIN_DEFAULT_EMAIL - địa chỉ email bạn dùng để đăng nhập vào giao diện web pgAdmin
• PGADMIN_DEFAULT_PASSWORD - mật khẩu cho tài khoản đó

Biến thứ ba là tùy chọn nhưng bạn nên chỉ định:

• PGADMIN_LISTEN_PORT - cổng pgAdmin lắng nghe bên trong container. Mặc định là 80, nhưng đặt thành 5050 sẽ gọn gàng hơn khi bạn ánh xạ cổng.

Tuy vậy, hardcode thông tin đăng nhập trong tệp Compose là ý tưởng tệ, đặc biệt nếu tệp được đưa vào hệ thống quản lý phiên bản. Hãy chuyển chúng vào tệp .env.

Tạo tệp .env trong cùng thư mục với docker-compose.yml của bạn:

POSTGRES_USER=admin
POSTGRES_PASSWORD=secret
POSTGRES_DB=mydb
PGADMIN_DEFAULT_EMAIL=admin@example.com
PGADMIN_DEFAULT_PASSWORD=secret

Sau đó tham chiếu các biến trong tệp Compose của bạn:

# postgres
environment:
  POSTGRES_USER: ${POSTGRES_USER}
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  POSTGRES_DB: ${POSTGRES_DB}
  
# pgadmin
environment:
  PGADMIN_DEFAULT_EMAIL: ${PGADMIN_DEFAULT_EMAIL}
  PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_DEFAULT_PASSWORD}

Docker Compose sẽ tự động đọc tệp .env khi bạn chạy lệnh, nên không cần cấu hình thêm. Chỉ cần nhớ thêm .env vào .gitignore và thông tin đăng nhập của bạn sẽ không vào kho mã.

Volumes và lưu trữ dữ liệu bền vững

Volume ánh xạ tới /var/lib/pgadmin là nơi pgAdmin lưu dữ liệu, như dữ liệu phiên, kết nối máy chủ đã lưu, và cấu hình. Bỏ mục này khỏi tệp compose đồng nghĩa bạn sẽ mất tất cả mỗi lần container khởi động lại.

Trong tệp compose hiện tại, bạn có một named volume do Docker quản lý trên máy host. Dữ liệu sẽ tồn tại qua các lần khởi động lại container, tạo lại, và cập nhật image - miễn là bạn không xóa volume đó bằng docker volume rm.

Khởi động stack và truy cập pgAdmin 4

Khi đã sẵn sàng docker-compose.yml, việc khởi động stack chỉ cần một lệnh:

docker compose up -d

Cờ -d chạy cả hai container ở chế độ tách rời - chúng chạy nền và terminal của bạn vẫn rảnh. Để kiểm tra cả hai container đang chạy:

docker ps

Bạn sẽ thấy cả postgres và pgadmin với trạng thái Up.

Trạng thái container

Nếu có gì đó không ổn, hãy kiểm tra log của pgAdmin:

docker logs pgadmin

Một lần khởi động khỏe mạnh trông như sau:

Log khởi động pgAdmin

Nếu bạn thấy lỗi, rất có thể là một trong ba lỗi này:

• Xác thực mật khẩu thất bại: PGADMIN_DEFAULT_PASSWORD bị thiếu hoặc sai định dạng trong tệp .env

• Cổng đã được sử dụng: có thứ khác đang chạy trên cổng 5050; hãy đổi cổng host trong tệp Compose

• Không có tệp hoặc thư mục như vậy: đường dẫn volume sai hoặc container không có quyền ghi vào đó

Khi cả hai container đã chạy và log sạch, mở trình duyệt và truy cập http://localhost:5050:

Trang đăng nhập pgAdmin

Đăng nhập bằng email và mật khẩu bạn đã đặt trong PGADMIN_DEFAULT_EMAIL và PGADMIN_DEFAULT_PASSWORD. Bạn sẽ vào trang tổng quan của pgAdmin, sẵn sàng đăng ký máy chủ PostgreSQL của mình:

Trang chủ pgAdmin

Kết nối pgAdmin 4 với container PostgreSQL của bạn

Trong thanh bên của pgAdmin, bấm chuột phải Servers - Register - Server. Một hộp thoại mở ra với hai tab bạn cần điền: General và Connection.

Tab General

Đặt cho máy chủ một tên có ý nghĩa - ví dụ local-dev-postgres. Đây chỉ là nhãn bên trong pgAdmin, nên hãy chọn bất cứ thứ gì hợp lý với thiết lập của bạn.

Đăng ký máy chủ - tab General

Tab Connection

Đừng dùng localhost ở đây. 

Bên trong một mạng Docker, localhost ám chỉ chính container đó - không phải máy host của bạn, cũng không phải container PostgreSQL. Docker có DNS nội bộ và nó phân giải tên container dựa trên tên service định nghĩa trong docker-compose.yml. Vậy nên nếu service PostgreSQL của bạn tên là postgres, đó là hostname bạn dùng.

Điền các trường như sau:

• Host name/address: postgres (tên service từ docker-compose.yml)

• Port: 5432

• Maintenance database: giá trị của POSTGRES_DB trong tệp Compose (ví dụ, mydb)

• Username: giá trị của POSTGRES_USER (ví dụ, admin)

• Password: giá trị của POSTGRES_PASSWORD

Bấm Save. 

Đăng ký máy chủ - tab Connection

Nếu mọi thứ chính xác, máy chủ sẽ xuất hiện ở thanh bên và bạn có thể mở rộng để xem các cơ sở dữ liệu:

Đăng ký máy chủ thành công

Điều này có nghĩa là bạn đã kết nối.

Sử dụng Query Tool

Vì bạn đã kết nối, tôi sẽ giới thiệu các thao tác cơ bản với pgAdmin 4 và Postgres nói chung.

Mở Query Tool bằng cách nhấp Tools - Query Tool từ menu trên cùng. Giao diện có ba vùng:

• Editor: nơi bạn viết SQL
• Data Output: nơi hiển thị kết quả sau khi bạn chạy truy vấn
• Messages: nơi PostgreSQL gửi thông báo trạng thái, lỗi, và thông tin thực thi

Query tool

Viết và chạy SQL

Hãy tạo một bảng orders đơn giản và thêm một chút dữ liệu. Bạn có thể chạy từng khối bằng cách bấm nút Play hoặc nhấn F5 là phím tắt.

Chạy lệnh này để tạo bảng:

CREATE TABLE orders (
    order_id SERIAL PRIMARY KEY,
    customer_name VARCHAR(100) NOT NULL,
    product VARCHAR(100) NOT NULL,
    quantity INT NOT NULL,
    order_date DATE DEFAULT CURRENT_DATE
);

Chèn vài dòng dữ liệu:

INSERT INTO orders (customer_name, product, quantity)
VALUES
    ('Alice Johnson', 'Wireless Keyboard', 2),
    ('Bob Smith', 'USB-C Hub', 1),
    ('Carol White', 'Mechanical Keyboard', 3);

Và giờ hãy truy vấn dữ liệu:

SELECT * FROM orders;

Truy vấn dữ liệu

Kết quả xuất hiện ở vùng Data Output dưới dạng bảng. Bạn có thể sắp xếp cột, thay đổi kích thước, và sao chép hàng trực tiếp từ lưới.

Đọc kế hoạch truy vấn trực quan

Để xem những gì diễn ra phía sau khi bạn chạy truy vấn, hãy chạy EXPLAIN ANALYZE trên câu lệnh SELECT của bạn:

EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_name = 'Alice Johnson';

Kết quả Explain Analyze

Vùng Data Output hiển thị đầu ra thô. Nhưng pgAdmin có lựa chọn tốt hơn. Nhấp nút Explain trên thanh công cụ - và pgAdmin sẽ dựng kế hoạch truy vấn dưới dạng đồ thị tương tác.

Kế hoạch truy vấn dạng đồ thị

Với truy vấn này thì đơn giản, nhưng bạn sẽ thu được nhiều thông tin hơn khi join bảng hoặc thực hiện các phép tổng hợp dữ liệu phức tạp.

Điều này quan trọng vì đọc đầu ra thô của EXPLAIN vừa chậm vừa dễ sai. Kế hoạch trực quan giúp bạn thấy ngay khi PostgreSQL đang quét toàn bộ bảng lớn, hoặc khi có index nhưng không được sử dụng.

Quản lý schema cơ sở dữ liệu của bạn

Thanh bên của pgAdmin cung cấp cho bạn cái nhìn đầy đủ về cấu trúc cơ sở dữ liệu - và cho phép bạn chỉnh sửa qua GUI.

Cây thư mục bên đi theo: Servers - tên máy chủ của bạn - Databases - cơ sở dữ liệu của bạn - Schemas - public - Tables. Mở rộng bất kỳ bảng nào, bạn sẽ thấy Columns, Indexes, và Constraints hiển thị dưới dạng nút con. Nhấp vào bất kỳ mục nào để xem chi tiết ở bảng bên phải.

Tạo và chỉnh sửa bảng

Để tạo bảng mới, nhấp chuột phải vào Tables dưới schema của bạn và chọn Create - Table. Một hộp thoại mở ra với vài tab.

Tạo bảng

Tab General là nơi bạn đặt tên bảng. Chuyển sang tab Columns để thêm các cột - mỗi hàng cho phép bạn đặt tên cột, kiểu dữ liệu, độ dài, và có cho phép null hay không. Tab Constraints xử lý khóa chính, khóa ngoại, và ràng buộc duy nhất.

Để thêm index cho một bảng hiện có, mở rộng bảng trong thanh bên, nhấp chuột phải vào Indexes, và chọn Create - Index. Chọn các cột cần lập chỉ mục và kiểu chỉ mục - btree là mặc định và phù hợp với hầu hết trường hợp.

Tạo index

Sao lưu và khôi phục

Để sao lưu cơ sở dữ liệu, vào Tools - Backup. Bạn sẽ cần chọn định dạng:

• Custom: định dạng nhị phân nén; linh hoạt nhất và là lựa chọn tốt cho hầu hết trường hợp vì bạn có thể khôi phục từng bảng riêng lẻ
• Plain: một script SQL thuần bạn có thể mở và đọc bằng bất kỳ trình soạn thảo văn bản nào
• Tar: lưu trữ không nén; ít phổ biến hơn nhưng hữu ích cho một số quy trình khôi phục

Sau khi chọn định dạng và đường dẫn đích, pgAdmin chạy pg_dump ở hậu trường và lưu tệp vào máy cục bộ của bạn.

Tạo bản sao lưu

Để khôi phục, vào Tools - Restore, chọn tệp sao lưu, và trỏ tới cơ sở dữ liệu đích.

Khôi phục từ bản sao lưu

Nếu bạn thắc mắc vì sao điều này hữu ích, hãy tưởng tượng bạn đang thử nghiệm một migration phá hủy trên cơ sở dữ liệu phát triển. Hãy sao lưu trước, chạy migration, và nếu có gì hỏng, khôi phục bản sao lưu để quay về trạng thái đã biết.

Thực tiễn tốt nhất khi chạy pgAdmin 4 trong Docker

Chạy được pgAdmin 4 là một chuyện. Nhưng giữ cho nó chạy trơn tru đòi hỏi bạn biết thêm vài điều. Dưới đây là một số mẹo thực tế.

Không để lộ thông tin đăng nhập trong tệp Compose

Nếu docker-compose.yml của bạn được đưa vào hệ thống quản lý phiên bản - thường là vậy - thì mật khẩu hardcode cũng theo vào. Hãy dùng tệp .env cho thông tin đăng nhập và thêm nó vào .gitignore. Với môi trường production, tiến thêm một bước và dùng Docker secrets, nơi các giá trị nhạy cảm được mount dưới dạng tệp thay vì biến môi trường.

Không bao giờ công khai cổng của pgAdmin

Mặc định, Docker bind cổng tới 0.0.0.0, nghĩa là mọi giao diện mạng - bao gồm cả giao diện công khai. Trên máy chủ từ xa, điều đó khiến phiên bản pgAdmin của bạn có thể truy cập từ internet. Hãy bind rõ ràng tới 127.0.0.1 thay vào đó:

ports:
  - "127.0.0.1:5050:5050"

Việc này khiến pgAdmin chỉ truy cập được từ chính máy chủ. Hãy dùng SSH tunnel hoặc reverse proxy nếu bạn cần truy cập từ xa.

Cố định thẻ image

Dùng dpage/pgadmin4:latest sẽ kéo về phiên bản mới lần tới khi ai đó chạy docker compose pull. Phiên bản mới có thể hoạt động khác đi, làm hỏng cấu hình, hoặc mang lại thay đổi ngoài dự kiến. Hãy dùng thẻ cụ thể như dpage/pgadmin4:9.13 để mọi thành viên chạy cùng một phiên bản.

Nạp sẵn kết nối máy chủ với servers.json

Nếu cả nhóm của bạn dùng chung thiết lập Compose, đừng để ai cũng phải đăng ký máy chủ PostgreSQL sau khi khởi động stack. pgAdmin hỗ trợ tệp servers.json để nạp sẵn các kết nối khi khởi động. Mount nó vào container như sau:

volumes:
  - ./servers.json:/pgadmin4/servers.json

Đây là một servers.json tối thiểu trông như thế nào:

{
  "Servers": {
    "1": {
      "Name": "local-dev-postgres",
      "Group": "Servers",
      "Host": "postgres",
      "Port": 5432,
      "MaintenanceDB": "mydb",
      "Username": "admin",
      "SSLMode": "prefer"
    }
  }
}

Máy chủ sẽ xuất hiện khi pgAdmin khởi động - không cần thiết lập thủ công.

Kết luận

Trong bài viết này, tôi đã hướng dẫn bạn thiết lập pgAdmin 4 trong Docker từ đầu. Bạn đã viết tệp Docker Compose để khởi chạy PostgreSQL và pgAdmin 4 cùng nhau, kết nối hai container bằng DNS nội bộ của Docker, và sử dụng các tính năng cốt lõi của pgAdmin - Query Tool, trình duyệt schema, và quy trình sao lưu/khôi phục.

Nguyên tắc cốt lõi ở đây là tính tái lập. 

Một tệp docker-compose.yml, một servers.json, và một tệp .env là tất cả những gì bạn cần để đưa cho đồng đội một môi trường cơ sở dữ liệu được cấu hình đầy đủ. Điều này sẽ đảm bảo vấn đề “chạy được trên máy tôi” không bao giờ xảy ra nữa.

Để đào sâu hơn về Docker và container hóa, hãy xem khóa học Intermediate Docker của chúng tôi. Khóa học chứa đầy mẹo hữu ích về multi-stage builds, mạng, và phần chuyên sâu về Compose.