LỗiBạn đang cố gắng kích hoạt một tính năng phổ biến của PostgreSQL như uuid-ossp cho các mã định danh duy nhất hoặc pg_trgm để tìm kiếm mờ (fuzzy searching). Thay vì nhận được thông báo thành công, bảng điều khiển SQL của bạn lại hiển thị một loạt văn bản màu đỏ:
ERROR: extension "uuid-ossp" does not exist
Điều này xảy ra vì PostgreSQL giữ cho nhân hệ điều hành của nó tinh gọn. Mặc dù nhiều extension là "tiêu chuẩn", các tệp vật lý của chúng thường nằm trong một gói riêng biệt không được cài đặt mặc định. Nếu các tệp .so hoặc .control bị thiếu trong thư mục thư viện của máy chủ (thường là /usr/lib/postgresql/<version>/lib/), Postgres sẽ không biết chúng tồn tại.
Tại sao lỗi này xảy raCác extension của PostgreSQL cần ba điều kiện để hoạt động: các tệp vật lý trên đĩa, quyền superuser để đăng ký chúng và ngữ cảnh cơ sở dữ liệu chính xác. Bạn thường sẽ gặp lỗi này vì một trong những lý do sau:
- Thiếu gói Contrib: Các module "contrib" — một tập hợp các công cụ bổ sung — đã bị bỏ qua trong quá trình cài đặt cơ sở dữ liệu ban đầu.- Sai cơ sở dữ liệu: Bạn đang kết nối với cơ sở dữ liệu bảo trì
postgresthay vì cơ sở dữ liệu ứng dụng thực tế của mình.- Không khớp phiên bản: Bạn đã cài đặt gói contrib cho PostgreSQL 14, nhưng máy chủ của bạn thực tế đang chạy phiên bản 16.## Cách khắc phục từng bước### Bước 1: Cài đặt các module PostgreSQL ContribHầu hết các bản phân phối Linux đều chia PostgreSQL thành nhiều gói. Để khắc phục việc thiếu tệp, bạn phải cài đặt gói contrib cụ thể cho phiên bản của mình.
Trên Ubuntu hoặc Debian:Trước tiên hãy kiểm tra phiên bản của bạn bằng lệnh psql --version. Nếu bạn đang chạy phiên bản 15, hãy chạy:
sudo apt-get update
sudo apt-get install postgresql-contrib-15
Trên RHEL, CentOS, hoặc AlmaLinux:Sử dụng dnf hoặc yum để tải gói tương ứng:
# Cho PostgreSQL 16
sudo dnf install postgresql16-contrib
Bạn không cần phải khởi động lại toàn bộ dịch vụ cơ sở dữ liệu sau việc này, mặc dù việc xác minh cài đặt ngay lập tức là một thói quen tốt.
Bước 2: Xác minh Extension đã sẵn sàngTrước khi chạy lại lệnh cài đặt, hãy kiểm tra xem PostgreSQL hiện đã có thể thấy các tệp hay chưa. Chạy truy vấn này trong terminal của bạn:
SELECT name, default_version, installed_version
FROM pg_available_extensions
WHERE name = 'uuid-ossp';
Nếu cột default_version có dữ liệu (ví dụ: 1.1), các tệp đã sẵn sàng. Nếu installed_version là null, extension đã có sẵn nhưng chưa được kích hoạt trong cơ sở dữ liệu cụ thể này.
Bước 3: Kích hoạt ExtensionCác extension mang tính đặc thù cho từng cơ sở dữ liệu. Nếu bạn bật uuid-ossp trong test_db, nó sẽ không tự động hoạt động trong production_db. Hãy chuyển sang cơ sở dữ liệu mục tiêu của bạn và chạy lệnh tạo:
-- Kết nối với cơ sở dữ liệu ứng dụng cụ thể của bạn
\c my_app_db
-- Đăng ký extension
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
Bước 4: Xử lý trong môi trường DockerImage Docker postgres chính thức thường bao gồm các module contrib theo mặc định. Tuy nhiên, nếu bạn đang sử dụng thẻ -slim hoặc -alpine, chúng có thể bị thiếu. Thêm dòng này vào Dockerfile của bạn để đảm bảo chúng luôn hiện diện:
FROM postgres:16
RUN apt-get update && apt-get install -y postgresql-contrib-16 && rm -rf /var/lib/apt/lists/*
Khắc phục cho môi trường Cloud (AWS RDS / Azure)Bạn không thể cài đặt các gói ở cấp độ hệ điều hành trên các dịch vụ được quản lý như AWS RDS. May mắn thay, AWS đã bao gồm sẵn các tệp này. Nếu bạn gặp lỗi này trên RDS, đó thường là vấn đề về quyền hạn. Hãy đảm bảo người dùng của bạn có vai trò rds_superuser. Đối với một số extension cụ thể (như pg_partman), bạn cũng có thể cần thêm tên extension vào danh sách shared_preload_libraries trong RDS Parameter Group và khởi động lại instance.
Xác minh: Kiểm tra việc khắc phụcXác nhận mọi thứ đang hoạt động bằng cách tạo một UUID phiên bản 4:
SELECT uuid_generate_v4();
Kết quả thành công sẽ trông như thế này: f47ac10b-58cc-4372-a567-0e02b2c3d479. Nếu bạn thấy chuỗi 36 ký tự đó, bạn đã hoàn tất.