Sửa lỗi PostgreSQL 'insert or update violates foreign key constraint'

TL;DR

Bạn đang chèn hoặc cập nhật một hàng có giá trị khóa ngoại không tồn tại trong bảng được tham chiếu. Bản ghi cha bị thiếu, bạn đang truyền sai ID, hoặc thứ tự chèn không đúng. Cách sửa: đảm bảo hàng cha tồn tại trước, sau đó thử lại.

Lỗi

ERROR: insert or update on table "orders" violates foreign key constraint "orders_customer_id_fkey"
DETAIL: Key (customer_id)=(999) is not present in table "customers".

Đọc kỹ dòng DETAIL — nó giúp bạn debug một nửa vấn đề. Ở đây nó cho biết customer_id = 999 không có hàng tương ứng trong bảng customers. Đó chính xác là vấn đề của bạn.

Nguyên nhân gốc rễ

PostgreSQL kiểm tra tính toàn vẹn tham chiếu tại thời điểm ghi. Mọi giá trị bạn đưa vào cột khóa ngoại phải đã tồn tại trong bảng cha. Không có ngoại lệ — lệnh chèn sẽ bị từ chối ngay nếu hàng cha bị thiếu.

Điều này thường xảy ra do một trong các nguyên nhân sau:

• Bản ghi cha chưa bao giờ được tạo (khách hàng chưa đăng ký trước khi đặt hàng)
• Truyền sai ID — lỗi lệch một đơn vị, giá trị cache cũ, hoặc bug trong logic ứng dụng
• Chèn hàng loạt theo thứ tự sai — hàng con được chèn trước hàng cha
• Script migration hoặc seed bỏ qua bảng cha hoàn toàn
• Hàng cha bị xóa mà không có ON DELETE CASCADE hoặc ON DELETE SET NULL, để lại các hàng con mồ côi

Bước 1: Xác nhận hàng cha bị thiếu

Trước khi làm bất cứ điều gì, hãy xác minh rằng ID được tham chiếu có thực sự tồn tại:

-- Customer 999 có tồn tại không?
SELECT * FROM customers WHERE id = 999;

Không có hàng nào trả về? Đó là vấn đề của bạn. Bản ghi cha đã bị xóa — hoặc chưa bao giờ được tạo.

Để xem chính xác ràng buộc được định nghĩa như thế nào, hãy kiểm tra trực tiếp:

-- Cách nhanh trong psql
\d orders

-- Hoặc truy vấn system catalog
SELECT
  conname AS constraint_name,
  conrelid::regclass AS table_name,
  a.attname AS column_name,
  confrelid::regclass AS referenced_table,
  af.attname AS referenced_column
FROM pg_constraint c
JOIN pg_attribute a ON a.attnum = ANY(c.conkey) AND a.attrelid = c.conrelid
JOIN pg_attribute af ON af.attnum = ANY(c.confkey) AND af.attrelid = c.confrelid
WHERE c.contype = 'f'
  AND c.conrelid = 'orders'::regclass;

Các cách sửa

Cách 1: Chèn hàng cha trước

Chín trong mười trường hợp, đây là cách sửa. Tạo bản ghi cha còn thiếu, sau đó thử lại lệnh chèn con:

-- Tạo customer trước
INSERT INTO customers (id, name, email)
VALUES (999, 'Alice', 'alice@example.com');

-- Bây giờ lệnh chèn order sẽ thành công
INSERT INTO orders (id, customer_id, total)
VALUES (1, 999, 150.00);

Cách 2: Dùng ID hiện có đúng

Đôi khi bản ghi cha tồn tại — bạn chỉ đang truyền sai ID. Hãy tra cứu trước:

-- Tìm ID thực sự của Alice
SELECT id FROM customers WHERE email = 'alice@example.com';
-- Trả về: 42

-- Dùng 42, không phải 999
INSERT INTO orders (customer_id, total)
VALUES (42, 150.00);

Đừng bao giờ hardcode ID giữa các môi trường. Một customer được chèn ở production gần như chắc chắn sẽ có ID khác so với ở staging.

Cách 3: Bọc trong transaction (cho chèn hàng loạt)

Đang chèn một loạt hàng liên quan? Bọc tất cả trong một transaction và đặt hàng cha lên trước:

BEGIN;

INSERT INTO customers (id, name) VALUES (100, 'Bob');
INSERT INTO orders (id, customer_id, total) VALUES (1, 100, 75.00);

COMMIT;

Nếu bất kỳ lệnh chèn nào thất bại, toàn bộ transaction sẽ rollback. Không có hàng mồ côi, không có trạng thái dở dang.

Cách 4: Tạm thời trì hoãn ràng buộc (chỉ dùng cho migration)

Migration hàng loạt đôi khi khiến việc sắp xếp thứ tự chèn không khả thi. Nếu ràng buộc được tạo với DEFERRABLE, bạn có thể đẩy việc kiểm tra sang cuối transaction:

-- Chỉ hoạt động nếu ràng buộc là DEFERRABLE
BEGIN;
SET CONSTRAINTS orders_customer_id_fkey DEFERRED;

-- Chèn theo bất kỳ thứ tự nào trong transaction này
INSERT INTO orders (id, customer_id, total) VALUES (1, 100, 75.00);
INSERT INTO customers (id, name) VALUES (100, 'Bob');

COMMIT;  -- Kiểm tra FK xảy ra ở đây

Nếu ràng buộc của bạn chưa deferrable, hãy tạo lại nó:

ALTER TABLE orders
  DROP CONSTRAINT orders_customer_id_fkey,
  ADD CONSTRAINT orders_customer_id_fkey
    FOREIGN KEY (customer_id) REFERENCES customers(id)
    DEFERRABLE INITIALLY IMMEDIATE;

Cách 5: Vô hiệu hóa ràng buộc (phương án cuối cùng, chỉ cho migration)

Chỉ dùng cách này trong các migration có kiểm soát. Không bao giờ dùng trong code ứng dụng production:

-- Vô hiệu hóa kiểm tra FK
ALTER TABLE orders DISABLE TRIGGER ALL;

-- ... chèn hàng loạt ...

-- Bật lại
ALTER TABLE orders ENABLE TRIGGER ALL;

-- Sau đó ngay lập tức kiểm tra hàng mồ côi
SELECT o.id, o.customer_id
FROM orders o
LEFT JOIN customers c ON c.id = o.customer_id
WHERE c.id IS NULL;

Luôn chạy lệnh kiểm tra hàng mồ côi sau khi bật lại. Bỏ qua bước này và bạn sẽ gặp các vấn đề toàn vẹn dữ liệu âm thầm xuất hiện vào thời điểm tệ nhất có thể.

Xác minh

Thử lại lệnh chèn và xác nhận dữ liệu đã được ghi đúng:

-- Thử lại
INSERT INTO orders (id, customer_id, total)
VALUES (1, 999, 150.00);

-- Xác minh bằng join
SELECT o.id, o.total, c.name AS customer_name
FROM orders o
JOIN customers c ON c.id = o.customer_id
WHERE o.id = 1;

Kết quả join rõ ràng có nghĩa là tính toàn vẹn tham chiếu đang hoạt động tốt.

Phòng ngừa

Một vài thói quen giúp tránh lỗi này vĩnh viễn:

• Chèn theo thứ tự phụ thuộc trong seed script và migration — cha luôn trước con.
• Định nghĩa ON DELETE CASCADE hoặc ON DELETE SET NULL khi việc xóa hàng cha là điều được kỳ vọng, để hàng con được xử lý tự động thay vì trở thành mồ côi.
• Dùng RETURNING id khi chèn hàng cha — lấy ID thực sự được tạo ra và truyền trực tiếp cho lệnh chèn con.
• Trong ORM (SQLAlchemy, Hibernate, ActiveRecord), cấu hình tùy chọn cascade ở cấp model thay vì tự xử lý ID thủ công.

-- Lấy ID được tạo ra với RETURNING
INSERT INTO customers (name, email)
VALUES ('Carol', 'carol@example.com')
RETURNING id;
-- Trả về: id = 43

-- Dùng ngay lập tức
INSERT INTO orders (customer_id, total)
VALUES (43, 200.00);