خطای Cannot add or update a child row در MySQL؛ چرا کلید خارجی اجازه درج نمی‌دهد؟

بار اول که این خطا را در یک پروژه فروشگاهی دیدم، در مرحله ثبت سفارش بود؛ کاربر روی دکمه پرداخت می‌زد و سرور با پیام Cannot add or update a child row: a foreign key constraint fails پاسخ می‌داد. آن روز ابتدا به سمت کد PHP رفتم، ولی وقتی ساختار جدول‌ها را بررسی کردم، فهمیدم ریشه در جای دیگری است: جدول سفارش‌ها به جدول کاربران کلید خارجی داشت و در آن لحظه، رکورد کاربر به‌دلیل یک فرآیند پاک‌سازی حذف شده بود. از آن روز، هر بار این خطا را می‌بینم، پیش از هر چیز سراغ روابط کلید خارجی می‌روم، نه سراغ کوئری.

خطای Cannot add or update a child row دقیقاً چیست؟

خطای Cannot add or update a child row: a foreign key constraint fails یکی از پیام‌های استاندارد MySQL است که زمانی ظاهر می‌شود که شما می‌خواهید رکوردی را در جدول فرزند (child) درج یا به‌روزرسانی کنید، ولی مقدار کلید خارجی (foreign key) آن، در جدول والد (parent) وجود ندارد. به بیان ساده، MySQL به شما می‌گوید: «این رکورد، به یک والد ارجاع می‌دهد که در جدول والد پیدا نشد.»

این خطا در مستندات رسمی MySQL در دسته خطاهای SQLSTATE 23000 و با کد 1452 قرار می‌گیرد. پیام کامل آن معمولاً به‌شکل زیر است:

ERROR 1452 (23000): Cannot add or update a child row: a foreign key constraint fails
(`dbname`.`child_table`, CONSTRAINT `fk_parent_child` FOREIGN KEY (`parent_id`)
REFERENCES `parent_table` (`id`))

نکته مهمی که در تجربه من بیش از همه به آن برخورده‌ام این است که توسعه‌دهندگان تصور می‌کنند این خطا از کد PHP یا Python می‌آید. در واقع، این خطا در لایه دیتابیس رخ می‌دهد؛ یعنی کوئری شما به MySQL رسیده، ولی MySQL آن را نپذیرفته. همین تفکیک، مسیر دیباگ را کاملاً تغییر می‌دهد: شما باید سراغ ساختار جداول و روابط کلید خارجی بروید، نه سراغ کد اپلیکیشن.

کلید خارجی یک قانون دیتابیس است، نه یک توصیه؛ وقتی این قانون نقض شود، MySQL از درج یا به‌روزرسانی جلوگیری می‌کند.

اگر با خانواده خطاهای MySQL آشنایی کامل ندارید، پیشنهاد می‌کنم ابتدا مرور جامعی روی ساختار آن داشته باشید؛ مقاله «آموزش mysql از صفر» نقطه شروع مناسبی است.

یک نکته ظریف دیگر این است که این خطا بسته به بافت، پیام‌های نزدیک به خود را دارد. مثلاً اگر مشکل از سمت حذف والد باشد، پیام متفاوتی مثل Cannot delete or update a parent row ظاهر می‌شود که ریشه‌اش کاملاً متفاوت است. برای درک دقیق‌تر این تفاوت، مرور «خطای Cannot add or update a child row» توصیه می‌شود؛ چون مرز بین این دو خطا، یکی از پرتکرارترین موارد سردرگمی در دیباگ است.

کلید خارجی و یکپارچگی ارجاعی در InnoDB

برای این‌که بتوانید این خطا را در ریشه رفع کنید، باید مکانیزم پایین‌دستی آن را بلد باشید. کلید خارجی در MySQL، تنها در موتور InnoDB پشتیبانی می‌شود و یکی از مفاهیم اصلی یکپارچگی ارجاعی است. این مفهوم می‌گوید هر رکورد در جدول فرزند، باید به یک رکورد معتبر در جدول والد ارجاع بدهد.

وقتی یک کلید خارجی تعریف می‌شود، InnoDB سه قانون را به‌طور خودکار اجرا می‌کند:

قانون درج: هر رکورد جدید در جدول فرزند، باید مقدار کلید خارجی‌اش در جدول والد وجود داشته باشد.
قانون به‌روزرسانی: اگر مقدار کلید خارجی در جدول فرزند تغییر کند، مقدار جدید باید در جدول والد موجود باشد.
قانون حذف: اگر رکورد والد حذف شود و در جدول فرزند ارجاعی به آن باشد، InnoDB از حذف جلوگیری می‌کند (مگر اینکه ON DELETE CASCADE تعریف شده باشد).

خطای Cannot add or update a child row دقیقاً زمانی رخ می‌دهد که قانون اول یا دوم نقض شود. یعنی شما می‌خواهید در جدول فرزند رکوردی درج یا به‌روزرسانی کنید، ولی مقدار کلید خارجی آن، در جدول والد وجود ندارد.

نکته ظریف این است که InnoDB برای اجرای این قوانین، به یک ایندکس روی کلید خارجی در جدول فرزند نیاز دارد. اگر این ایندکس نباشد، InnoDB به‌طور خودکار آن را می‌سازد. ولی اگر ایندکس وجود داشته باشد و با ساختار کلید هم‌خوان نباشد، ممکن است رفتار غیرمنتظره رخ دهد. به همین دلیل، در طراحی جداول، همیشه باید از تطابق نوع داده و ایندکس بین کلید خارجی و کلید اصلی والد مطمئن شد.

برای درک عمیق‌تر این مفاهیم در بافت طراحی دیتابیس، مرور «طراحی دیتابیس در mysql» و «دستورات پرکاربرد mysql» توصیه می‌شود؛ چون این دو مقاله، پیش‌نیاز درک دقیق خطاهای کلید خارجی هستند.

تفاوت با خطای حذف والد و سایر خطاهای کلید خارجی

یکی از پرتکرارترین سؤالاتی که در جلسات بازبینی کد زیاد می‌شنوم این است: تفاوت Cannot add or update a child row با Cannot delete or update a parent row چیست؟ پاسخ در ظاهر ساده است ولی در عمل مهم: اولی در سمت درج و به‌روزرسانی فرزند رخ می‌دهد، دومی در سمت حذف یا به‌روزرسانی والد.

برای این‌که در پروژه‌های چندخطایی بتوانید سریع تشخیص دهید کدام خطای کلید خارجی را پیش رو دارید، بد نیست اعضای پرتکرار این خانواده را کنار هم ببینید:

پیام	سمت خطا	معنای دقیق
`Cannot add or update a child row`	سمت فرزند	رکورد فرزند به والد ناموجود ارجاع می‌دهد
`Cannot delete or update a parent row`	سمت والد	رکورد والد حذف یا به‌روزرسانی می‌شود ولی فرزند وابسته دارد
`Incorrect string value`	لایه charset	کاراکتر با charset ستون هم‌خوان نیست
`Duplicate entry`	لایه ایندکس یکتا	مقدار تکراری در ستون یکتا
`Table doesn't exist`	لایه وجود جدول	جدول مقصد در دیتابیس وجود ندارد

تفاوت کلیدی بین خطای درج فرزند و خطای حذف والد در این است که اولی از سمت عملیات روی جدول فرزند می‌آید و دومی از سمت عملیات روی جدول والد. به همین دلیل، مسیر تشخیص این دو خطا متفاوت است. در خطای درج فرزند، سؤال اصلی این است: «چرا مقدار کلید خارجی در جدول والد وجود ندارد؟» در خطای حذف والد، سؤال اصلی این است: «چرا رکورد فرزند وابسته هنوز حذف نشده است؟».

در تجربه من، پرونده‌های Cannot add or update a child row در پنج کلاس اصلی جای می‌گیرند: درج رکورد فرزند قبل از والد؛ عدم تطابق نوع داده بین کلید خارجی و کلید اصلی؛ حذف والد بدون پاک‌سازی فرزند؛ ساختار جدول قدیمی که با داده جدید هم‌خوان نیست؛ و مهاجرت دیتابیس که در آن ترتیب import رعایت نشده است.

در لایه charset، خطای مشابهی وجود دارد که در نگاه اول شبیه خطای کلید خارجی به نظر می‌رسد ولی ماهیتش کاملاً متفاوت است. برای درک دقیق‌تر این تفاوت، مرور «خطای Incorrect string value در MySQL» توصیه می‌شود؛ چون این دو خطا در بافت پروژه‌های فارسی‌زبان، بیشترین شباهت ظاهری را دارند.

هشت سناریوی واقعی که این خطا را فعال می‌کنند

در پرونده‌هایی که به من رسیده، تعداد الگوهایی که به این خطا منتهی می‌شوند بیشتر از آن‌چه انتظار می‌رود است. هشت سناریوی زیر، تقریباً همه پرونده‌های عملی را پوشش می‌دهند.

سناریو اول: درج رکورد فرزند قبل از والد

شایع‌ترین حالت. کد شما سفارش را قبل از کاربر درج می‌کند، در حالی که کلید خارجی user_id به جدول کاربران ارجاع می‌دهد. راه‌حل، اطمینان از ترتیب درست درج است: ابتدا والد، سپس فرزند.

سناریو دوم: عدم تطابق نوع داده

اگر کلید اصلی والد از نوع BIGINT UNSIGNED باشد و کلید خارجی فرزند از نوع INT SIGNED، InnoDB نمی‌تواند مقادیر را تطابق دهد و خطا رخ می‌دهد. راه‌حل، اطمینان از تطابق کامل نوع داده است:

-- والد
CREATE TABLE parent (
  id BIGINT UNSIGNED NOT NULL PRIMARY KEY
);

-- فرزند
CREATE TABLE child (
  parent_id BIGINT UNSIGNED NOT NULL,
  FOREIGN KEY (parent_id) REFERENCES parent(id)
);

سناریو سوم: عدم تطابق charset و collation

اگر کلید اصلی والد با charset utf8mb4 و کلید خارجی فرزند با charset utf8 باشد، InnoDB مقادیر را متفاوت می‌بیند و خطا رخ می‌دهد. راه‌حل، هم‌خوانی charset در دو طرف است.

سناریو چهارم: حذف والد بدون پاک‌سازی فرزند

در بعضی فرآیندها، والد حذف می‌شود ولی فرزندها باقی می‌مانند. سپس در درج یا به‌روزرسانی فرزند، چون والد وجود ندارد، خطا رخ می‌دهد. راه‌حل، استفاده از ON DELETE CASCADE یا پاک‌سازی دستی فرزند پیش از حذف والد است.

سناریو پنجم: مهاجرت دیتابیس با ترتیب اشتباه

در مهاجرت دیتابیس، اگر جدول فرزند قبل از جدول والد import شود، داده فرزند نمی‌تواند والد خود را پیدا کند و خطا رخ می‌دهد. راه‌حل، غیرفعال کردن موقت بررسی کلید خارجی در حین import است:

SET FOREIGN_KEY_CHECKS = 0;
-- import tables
SET FOREIGN_KEY_CHECKS = 1;

توجه: این روش فقط برای import داده‌های معتبر توصیه می‌شود و باید بعد از اتمام کار، بررسی کلید خارجی دوباره فعال شود.

سناریو ششم: استفاده از ایندکس اشتباه

در بعضی موارد، کلید خارجی روی ستونی تعریف شده که با کلید اصلی والد هم‌خوان نیست. مثلاً کلید اصلی والد روی ستون id است ولی کلید خارجی فرزند به ستون code ارجاع می‌دهد که یکتای جهانی نیست. راه‌حل، اطمینان از ارجاع کلید خارجی به یک ستون یکتا در والد است.

سناریو هفتم: تغییر ساختار جدول بدون هم‌راستایی داده

اگر ستون کلید اصلی والد از نوع INT به BIGINT تغییر کند و ستون کلید خارجی فرزند تغییر نکند، خطا رخ می‌دهد. راه‌حل، تغییر هم‌زمان هر دو ستون است.

سناریو هشتم: داده خراب در والد یا فرزند

در بعضی پروژه‌ها، داده‌ای که از منابع خارجی آمده، شامل مقادیر نامعتبر است. مثلاً والد شامل id = NULL باشد، ولی فرزند به آن ارجاع دهد. راه‌حل، اعتبارسنجی داده پیش از درج است.

در همه هشت سناریو، یک نکته مشترک وجود دارد: جایی در زنجیره، هم‌خوانی بین والد و فرزند نقض شده است.

دام اختصاصی وردپرس و ووکامرس

در تجربه من، بخش بزرگی از پرونده‌های Cannot add or update a child row مربوط به پروژه‌های وردپرسی و ووکامرسی است. دلیلش روشن است: این سیستم‌ها اغلب از جداول اختصاصی با روابط کلید خارجی استفاده می‌کنند و در نسخه‌های قدیمی، بعضی افزونه‌ها جداول خود را بدون کلید خارجی معتبر می‌سازند.

ریشه تاریخی در وردپرس

وردپرس به‌طور پیش‌فرض از کلید خارجی در جداول خود استفاده نمی‌کند. یعنی روابط بین wp_posts و wp_postmeta به‌شکل کلید خارجی تعریف نشده است. ولی در بعضی افزونه‌ها و در ووکامرس، این روابط با کلید خارجی تعریف می‌شوند. به همین دلیل، خطاهای کلید خارجی در پروژه‌های وردپرسی معمولاً از افزونه‌ها می‌آید، نه از خود وردپرس.

بررسی وضعیت کلیدهای خارجی در وردپرس

برای بررسی وضعیت کلیدهای خارجی در دیتابیس وردپرس، می‌توانید از کوئری زیر استفاده کنید:

SELECT
  table_name,
  constraint_name,
  column_name,
  referenced_table_name,
  referenced_column_name
FROM information_schema.KEY_COLUMN_USAGE
WHERE table_schema = 'your_wp_database'
  AND referenced_table_name IS NOT NULL;

اگر خروجی این کوئری شامل جدول‌های افزونه‌های ناشناخته باشد، احتمال دارد آن افزونه منبع خطا باشد.

دام ووکامرس

در ووکامرس، جداول wp_wc_orders و wp_wc_order_addresses با کلید خارجی به wp_wc_orders ارجاع می‌دهند. اگر در فرآیند ثبت سفارش، رکورد والد (سفارش) قبل از فرزند (آدرس) درج نشود یا درج آن با خطا مواجه شود، خطای Cannot add or update a child row رخ می‌دهد. راه‌حل، اطمینان از ترتیب درست درج و بررسی لاگ خطاهای ووکامرس است. برای مرور دقیق‌تر افزونه‌های استاندارد در ووکامرس، مرور «بهترین افزونه‌های کاربردی برای ووکامرس» توصیه می‌شود؛ چون انتخاب افزونه‌های استاندارد، از بسیاری از این مشکلات جلوگیری می‌کند.

چطور ریشه این خطا را در پروژه ایزوله کنیم؟

فرض کنید همین امروز یک خطای Cannot add or update a child row در محیط تولید ظاهر شده و می‌خواهید ریشه‌اش را پیدا کنید. روشی که در این نوع پرونده‌ها به کار می‌گیرم، شش گام دارد و هر گام، یک شرط را در ذهن من حذف می‌کند.

گام اول: نگاه دقیق به پیام خطا

اولین کاری که می‌کنم، خواندن دقیق پیام خطا است. پیام معمولاً شامل نام جدول فرزند، نام constraint، نام ستون کلید خارجی، نام جدول والد و نام ستون کلید اصلی والد است. با نگاه به این اطلاعات، می‌توانم به‌سرعت تشخیص دهم که کدام رابطه نقض شده است.

گام دوم: بررسی ساختار جدول فرزند

دومین کاری که می‌کنم، بررسی ساختار جدول فرزند است:

SHOW CREATE TABLE your_child_table;

در خروجی این دستور، بخش مربوط به CONSTRAINT و FOREIGN KEY نشان می‌دهد که کلید خارجی به کدام جدول و کدام ستون ارجاع می‌دهد.

گام سوم: بررسی ساختار جدول والد

سومین کاری که می‌کنم، بررسی ساختار جدول والد است:

SHOW CREATE TABLE your_parent_table;

توجه به نوع داده، charset و collation کلید اصلی والد، در این گام بسیار مهم است.

گام چهارم: بررسی داده واقعی

چهارمین کاری که می‌کنم، بررسی داده واقعی است. یک کوئری ساده می‌زنم که مقدار کلید خارجی مورد نظر را در جدول والد جستجو کند:

SELECT * FROM parent_table WHERE id = 'problematic_value';

اگر این کوئری نتیجه‌ای برنگرداند، تأیید می‌شود که مقدار کلید خارجی در والد وجود ندارد.

گام پنجم: بررسی نوع داده و charset

پنجمین کاری که می‌کنم، مقایسه نوع داده و charset بین کلید اصلی والد و کلید خارجی فرزند است. اگر این دو هم‌خوان نباشند، InnoDB نمی‌تواند مقادیر را تطابق دهد.

گام ششم: بررسی ترتیب عملیات در کد

ششمین کاری که می‌کنم، بررسی ترتیب عملیات در کد اپلیکیشن است. اگر کد شما رکورد فرزند را قبل از والد درج می‌کند، باید ترتیب را برعکس کنید. برای مرور دقیق‌تر این لایه در بافت زبان‌های مختلف، مرور «اتصال php به mysql» و «اتصال پایتون به mysql» توصیه می‌شود.

در کنار این شش گام، یک تکنیک عملی مهم وجود دارد: در بافت ORMها مثل Eloquent یا SQLAlchemy، روابط کلید خارجی معمولاً در مدل‌ها تعریف می‌شوند. اگر مدل شما رابطه را به‌درستی تعریف نکرده باشد، ممکن است ORM ترتیب درج را اشتباه تشخیص دهد. توصیه من این است که در همه لایه‌ها، ترتیب عملیات را به‌شکل صریح مدیریت کنید.

راه‌حل‌های امن و ترتیب درست عملیات

بعد از تشخیص، نوبت به رفع است. شش الگوی عملی در پروژه‌ها به کارم آمده که هر کدام، در بافت متفاوتی مناسب است.

الگوی اول: اصلاح ترتیب درج

ساده‌ترین و در بسیاری از پروژه‌ها کافی‌ترین راه‌حل، اصلاح ترتیب درج است. همیشه ابتدا والد، سپس فرزند:

-- مرحله اول: درج والد
INSERT INTO parent_table (id, name) VALUES (1, 'Ali');

-- مرحله دوم: درج فرزند
INSERT INTO child_table (parent_id, name) VALUES (1, 'Order 1');

الگوی دوم: استفاده از تراکنش

در عملیات پیچیده، استفاده از تراکنش، امکان بازگردانی در صورت خطا را فراهم می‌کند:

START TRANSACTION;
INSERT INTO parent_table (id, name) VALUES (1, 'Ali');
INSERT INTO child_table (parent_id, name) VALUES (1, 'Order 1');
COMMIT;

برای درک دقیق‌تر این الگو در بافت پروژه‌های واقعی، مرور «تراکنش ها در mysql» توصیه می‌شود.

الگوی سوم: غیرفعال کردن موقت بررسی کلید خارجی

در سناریوهای مهاجرت داده، می‌توانید به‌طور موقت بررسی کلید خارجی را غیرفعال کنید:

SET FOREIGN_KEY_CHECKS = 0;
-- عملیات import
SET FOREIGN_KEY_CHECKS = 1;

توجه: این روش فقط در بافت import داده‌های معتبر توصیه می‌شود و باید بعد از اتمام کار، بررسی کلید خارجی دوباره فعال شود.

الگوی چهارم: پاک‌سازی داده یتیم

در بعضی پروژه‌ها، داده یتیم در جدول فرزند وجود دارد که به والد ناموجود ارجاع می‌دهد. راه‌حل، پاک‌سازی این داده است:

DELETE FROM child_table
WHERE parent_id NOT IN (SELECT id FROM parent_table);

الگوی پنجم: ON DELETE CASCADE

در بعضی سناریوها، استفاده از ON DELETE CASCADE جلوی خطای والد را می‌گیرد:

ALTER TABLE child_table
ADD CONSTRAINT fk_parent
FOREIGN KEY (parent_id) REFERENCES parent_table(id)
ON DELETE CASCADE;

الگوی ششم: اعتبارسنجی داده پیش از درج

در پروژه‌های جدی، استفاده از یک لایه اعتبارسنجی پیش از درج، خطاهای کلید خارجی را زودتر می‌گیرد:

function ensureParentExists($pdo, $parentId) {
  $stmt = $pdo->prepare("SELECT 1 FROM parent_table WHERE id = ?");
  $stmt->execute([$parentId]);
  if (!$stmt->fetch()) {
    throw new RuntimeException("Parent not found: $parentId");
  }
}

در انتخاب بین این شش الگو، هیچ‌کدام را نباید به‌عنوان نسخه «درست» در نظر گرفت؛ انتخاب، به بافت پروژه و اندازه تیم بستگی دارد. برای مرور جامع‌تر الگوهای مدیریت خطا در بافت دیتابیس، مطالعه «بهینه سازی کوئری های mysql» توصیه می‌شود.

حذف کامل این خطا از سیستم، نتیجه ترکیب چند الگوی طراحی است، نه یک توصیه تک‌خطی.

ON DELETE و ON UPDATE CASCADE: کِی و چگونه

یکی از پرتکرارترین سؤالاتی که در جلسات فنی مطرح می‌شود این است: چه زمانی از ON DELETE CASCADE و ON UPDATE CASCADE استفاده کنیم؟ پاسخ در ظاهر ساده است ولی در عمل مهم: این گزینه‌ها، رفتار پیش‌فرض InnoDB را تغییر می‌دهند. به‌طور پیش‌فرض، InnoDB از حذف والد جلوگیری می‌کند اگر فرزند وابسته داشته باشد. با ON DELETE CASCADE، فرزندها به‌طور خودکار حذف می‌شوند.

سه گزینه اصلی برای ON DELETE و ON UPDATE وجود دارد:

RESTRICT — پیش‌فرض؛ از عملیات جلوگیری می‌کند.
CASCADE — عملیات را روی فرزندها تکرار می‌کند.
SET NULL — کلید خارجی را روی NULL تنظیم می‌کند (نیازمند مجاز بودن NULL).

نکته مهمی که در تجربه من بیش از همه به آن برخورده‌ام این است که انتخاب نادرست این گزینه‌ها می‌تواند منبع خطاهای بعدی باشد. مثلاً استفاده از ON DELETE CASCADE در جدولی که داده‌های آن مستقل هستند، ممکن است باعث حذف ناخواسته شود. توصیه من این است که در طراحی جداول، این گزینه‌ها را با دقت انتخاب کنید و در مستندات پروژه ثبت کنید.

برای درک عمیق‌تر این مفاهیم در بافت طراحی، مرور «طراحی دیتابیس در mysql» و «دستورات پرکاربرد mysql» توصیه می‌شود؛ چون این دو مقاله، پیش‌نیاز درک دقیق رفتار کلید خارجی هستند.

الگوهای طراحی برای پیشگیری از این خطا

بعد از تشخیص، نوبت به پیشگیری است. شش الگوی طراحی که در پروژه‌های بالغ دیده‌ام، این کلاس خطا را از یک خطر پنهان به یک ابزار قابل کنترل تبدیل می‌کند.

الگوی اول: تعریف صریح کلید خارجی

در طراحی جداول، کلیدهای خارجی را به‌شکل صریح تعریف کنید، نه با اتکا به منطق اپلیکیشن. این کار، یکپارچگی داده را در سطح دیتابیس تضمین می‌کند:

ALTER TABLE child_table
ADD CONSTRAINT fk_parent
FOREIGN KEY (parent_id) REFERENCES parent_table(id);

الگوی دوم: تطابق کامل نوع داده

همیشه از تطابق کامل نوع داده، charset و collation بین کلید اصلی والد و کلید خارجی فرزند مطمئن شوید. این کار، از خطاهای ظریف جلوگیری می‌کند.

الگوی سوم: مدیریت ترتیب عملیات در کد

در کد اپلیکیشن، ترتیب عملیات را به‌شکل صریح مدیریت کنید. یعنی همیشه ابتدا والد، سپس فرزند. این ترتیب، ساده‌ترین راه پیشگیری از خطا است.

الگوی چهارم: استفاده از تراکنش برای عملیات پیچیده

در عملیاتی که چند جدول را درگیر می‌کند، استفاده از تراکنش، امکان بازگردانی را فراهم می‌کند و از داده نیمه‌کاره جلوگیری می‌کند.

الگوی پنجم: اعتبارسنجی داده در مرزهای سیستم

در پروژه‌های مدرن، به‌جای تکرار اعتبارسنجی در همه نقاط، از یک لایه اعتبارسنجی در مرزهای سیستم استفاده کنید. این لایه، پیش از درج، داده را بررسی می‌کند.

الگوی ششم: پایش و alerting

در پروژه‌های بالغ، خطاهای کلید خارجی در سمت سرور و کلاینت ثبت می‌شوند و در صورت افزایش نرخ خطا، هشدار به تیم فنی ارسال می‌شود. این لایه، جلوی بسیاری از خطاهای بحرانی را در تولید می‌گیرد.

در انتخاب بین این شش الگو، هیچ‌کدام را نباید به‌عنوان نسخه «درست» در نظر گرفت؛ انتخاب، به بافت پروژه و اندازه تیم بستگی دارد. برای مرور جامع‌تر الگوهای مدیریت خطا در بافت دیتابیس، مطالعه «بهینه‌سازی جداول MySQL برای سرعت بیشتر» توصیه می‌شود.

اشتباهات رایجی که این خطا را تشدید می‌کنند

در بررسی پرونده‌های این خطا، هفت اشتباه تکراری دیده‌ام که هر کدام، به‌جای رفع مشکل، آن را پیچیده‌تر می‌کند.

غیرفعال کردن دائمی بررسی کلید خارجی. بعضی تیم‌ها برای «رفع سریع» خطا، بررسی کلید خارجی را به‌طور دائمی غیرفعال می‌کنند. این کار، یکپارچگی داده را از بین می‌برد و در بلندمدت به داده یتیم منتهی می‌شود.
نادیده گرفتن ترتیب درج. اگر کد شما فرزند را قبل از والد درج کند، همیشه خطا رخ می‌دهد. ترتیب درست را در طراحی کد لحاظ کنید.
استفاده از SET NULL بدون مجاز بودن NULL. اگر ستون کلید خارجی NOT NULL باشد، استفاده از SET NULL خطا می‌دهد. همیشه ساختار ستون را بررسی کنید.
نادیده گرفتن charset و collation. اگر والد و فرزند charset متفاوت داشته باشند، کلید خارجی نمی‌تواند مقادیر را تطابق دهد.
حذف داده یتیم بدون بررسی. حذف داده یتیم بدون بررسی ریشه، ممکن است داده‌های معتبر را از بین ببرد. همیشه قبل از حذف، ریشه یتیم شدن را بررسی کنید.
عدم مستندسازی کلیدهای خارجی. اگر تیم فنی نداند که کدام جدول به کدام جدول ارجاع می‌دهد، به‌سرعت فرض‌های اشتباه شکل می‌گیرد.
نادیده گرفتن خطا در لاگ. اگر سیستم لاگ شما خطاهای کلید خارجی را ثبت نمی‌کند، ممکن است خرابی داده در سکوت رخ دهد.

در کنار این هفت اشتباه، یک هشتمین نکته هم وجود دارد که در تیم‌های بزرگ زیاد دیده‌ام: نداشتن استاندارد برای طراحی جداول. وقتی تیم فنی نداند که چه استانداردی برای کلید خارجی وجود دارد، هر توسعه‌دهنده ممکن است به سلیقه خود عمل کند و این عدم یک‌دستی، در بلندمدت منبع خطاهای تکراری می‌شود.

ماتریس تست یکپارچگی داده

چیزی که در پروژه‌های بالغ به‌شکل منظم دیده‌ام، تست‌های اختصاصی برای یکپارچگی داده است. ماتریسی که در پروژه‌ها استفاده می‌کنم، این شکلی است:

سناریو	ورودی	خروجی مورد انتظار
درج والد سپس فرزند	رکورد والد معتبر	ذخیره موفق
درج فرزند بدون والد	رکورد فرزند نامعتبر	Cannot add or update a child row
درج فرزند با والد ناموجود	`parent_id = 999`	Cannot add or update a child row
به‌روزرسانی کلید خارجی به ناموجود	`parent_id = 999`	Cannot add or update a child row
حذف والد با فرزند وابسته	والد با فرزند	Cannot delete or update a parent row
حذف والد با ON DELETE CASCADE	والد با فرزند	حذف موفق والد و فرزند
charset متفاوت	والد utf8mb4، فرزند utf8	Cannot add or update a child row
نوع داده متفاوت	والد BIGINT، فرزند INT	Cannot add or update a child row

هر ردیف از این ماتریس، یک سناریوی واقعی را پوشش می‌دهد. اگر این تست‌ها را در پروژه خود بگذارید، نه‌فقط خطاهای زمان اجرا را زودتر می‌گیرید، بلکه وقتی تیم شما بزرگ‌تر می‌شود، رفتار برنامه در برابر تغییرات، قابل پیش‌بینی می‌ماند.

یک تذکر مهم: در تست‌های یکپارچگی داده، مطمئن شوید که همه لایه‌ها (ساختار جدول، نوع داده، charset) با هم‌خوانی یکسان تست می‌شوند. اگر فقط یک لایه تست شود، ممکن است خطا در محیط واقعی رخ دهد.

پرسش‌های پرتکرار درباره Cannot add or update a child row

در این بخش، پرسش‌هایی که بیشترین تکرار را در تیم‌های فنی، تیکت‌های پشتیبانی و جلسات بازبینی داشته‌اند، پاسخ می‌دهم. هدف این است که بتوانید به‌سرعت به پاسخ برسید، بدون اینکه لازم باشد کل مقاله را دوباره مرور کنید.

این خطا از کد می‌آید یا از دیتابیس؟

این خطا در لایه دیتابیس رخ می‌دهد. یعنی کوئری شما به MySQL رسیده، ولی MySQL آن را نپذیرفته. ریشه می‌تواند در کد اپلیکیشن باشد (ترتیب درج) یا در ساختار دیتابیس (عدم تطابق نوع داده).

تفاوت این خطا با Cannot delete or update a parent row چیست؟

اولی در سمت درج و به‌روزرسانی فرزند رخ می‌دهد، دومی در سمت حذف یا به‌روزرسانی والد. برای بررسی دقیق‌تر، مرور «خطای Cannot add or update a child row» توصیه می‌شود.

آیا می‌توانم بررسی کلید خارجی را غیرفعال کنم؟

بله، ولی فقط به‌طور موقت و در بافت import داده‌های معتبر. غیرفعال کردن دائمی، یکپارچگی داده را از بین می‌برد.

چرا والد وجود ندارد ولی کوئری من آن را ساخته است؟

احتمالاً ترتیب عملیات در کد شما اشتباه است. یعنی فرزند را قبل از والد درج می‌کنید. ترتیب را برعکس کنید.

آیا در ووکامرس هم این خطا رخ می‌دهد؟

بله. جداول wp_wc_orders و wp_wc_order_addresses در ووکامرس با کلید خارجی به هم ارجاع می‌دهند. اگر در فرآیند ثبت سفارش، ترتیب درج رعایت نشود، این خطا رخ می‌دهد.

چطور بفهمم کدام کلید خارجی نقض شده است؟

پیام خطا معمولاً نام constraint و نام جدول والد را نشان می‌دهد. با کوئری زیر می‌توانید همه کلیدهای خارجی را بررسی کنید:

SELECT * FROM information_schema.KEY_COLUMN_USAGE
WHERE table_schema = 'your_database'
  AND referenced_table_name IS NOT NULL;

آیا استفاده از ON DELETE CASCADE امن است؟

در بعضی سناریوها بله، در بعضی خیر. اگر داده فرزند مستقل باشد، حذف خودکار آن ممکن است ناخواسته باشد. همیشه با دقت انتخاب کنید.

آیا این خطا در MySQL 8 هم رخ می‌دهد؟

بله. رفتار کلید خارجی در InnoDB در همه نسخه‌های مدرن MySQL یکسان است. فقط پیام‌های خطا ممکن است در جزئیات متفاوت باشد.

آیا ORMها این خطا را مدیریت می‌کنند؟

ORMها معمولاً خطا را به لایه بالاتر منتقل می‌کنند، ولی ریشه را حل نمی‌کنند. باید ساختار داده و ترتیب عملیات را در سطح مدل بررسی کنید.

نگاه معمارانه: یکپارچگی داده به‌عنوان قرارداد

در پروژه‌های بالغ، یکپارچگی داده به‌عنوان یک تصمیم طراحی سراسری مدیریت می‌شود، نه به‌عنوان یک تنظیم محلی. سه تصمیم معمارانه که در تیم‌های حرفه‌ای دیده‌ام، این کلاس خطا را از یک خطر پنهان به یک ابزار قابل کنترل تبدیل می‌کند.

لایه اول: قرارداد صریح برای روابط داده

تیم‌های حرفه‌ای برای هر رابطه بین جداول، یک قرارداد صریح تعریف می‌کنند. یعنی مشخص است که کدام جدول والد است، کدام فرزند، چه گزینه‌هایی برای ON DELETE و ON UPDATE استفاده می‌شود، و چه کسی مسئول نگهداری این رابطه است. با این قرارداد، هیچ‌کس به‌طور تصادفی رابطه را نقض نمی‌کند.

لایه دوم: جداسازی منطق داده از کد اپلیکیشن

در پروژه‌های مدرن، به‌جای تکرار منطق یکپارچگی داده در کد اپلیکیشن، از قوانین دیتابیس استفاده می‌شود. یعنی کلیدهای خارجی در سطح دیتابیس تعریف می‌شوند و کد اپلیکیشن به آن‌ها اعتماد می‌کند. این جداسازی، هم کد را ساده‌تر می‌کند و هم یکپارچگی داده را تضمین می‌کند.

لایه سوم: تست یکپارچگی داده در CI/CD

در پروژه‌های بالغ، یکپارچگی داده در فرآیند CI/CD تست می‌شود. یعنی پیش از استقرار، یک تست ساده اجرا می‌شود که از صحت روابط کلید خارجی مطمئن شود. اگر در آن تست، رابطه‌ای نقض شده بود، استقرار متوقف می‌شود. این لایه، جلوی بسیاری از خطاهای کلید خارجی را در تولید می‌گیرد.

در تمام این سه لایه، یک اصل مشترک وجود دارد: یکپارچگی داده نه به‌عنوان یک تنظیم محلی، بلکه به‌عنوان یک قرارداد سراسری دیده می‌شود. همین دیدگاه است که تفاوت بین تیم‌هایی که از این کلاس خطا رنج می‌برند و تیم‌هایی که آن را به‌عنوان یک فرصت طراحی می‌بینند، ایجاد می‌کند.

وقتی یکپارچگی داده به‌عنوان یک قرارداد سراسری دیده شود، از یک تنظیم محلی به یک تعهد سازمانی تبدیل می‌شود.

یک تصمیم کوچک، یک کلاس خطای ازیادرفته

خطای Cannot add or update a child row در نگاه اول یک خطای کوچک به‌نظر می‌رسد، اما در عمل، آینه‌ای است که نشان می‌دهد لایه یکپارچگی داده پروژه شما چقدر صریح و کنترل‌شده است. اگر این خطا در تولید ظاهر می‌شود، به احتمال زیاد جای دیگری از سیستم هم داده‌ای بدون رابطه معتبر جریان دارد. به همین دلیل، توصیه عملی من سه چیز است: اول، همیشه ترتیب درج را در کد به‌شکل صریح مدیریت کنید؛ دوم، کلیدهای خارجی را در سطح دیتابیس تعریف کنید و از تطابق نوع داده و charset مطمئن شوید؛ سوم، در تست‌های خود ماتریس سناریوهای یکپارچگی داده را بگنجانید تا رفتار برنامه در برابر تغییرات ناخواسته، قابل پیش‌بینی بماند.

اگر خطای مشابهی را در یک پروژه واقعی تجربه کرده‌اید — مخصوصاً جایی که ریشه مشکل از آنچه انتظار داشتید دور بوده — تجربه‌تان را در دیدگاه بنویسید. برای من جالب است بدانم کدام لایه بیشترین زمان را از شما گرفت، و آیا الگویی پیدا کردید که با آنچه در این متن آمده، تفاوت داشت. تجربه‌های واقعی شما، این متن را برای خواننده بعدی دقیق‌تر می‌کند. 🗄️