هویت کاری در برابر متن لغوی برای حل رگرسیون SQL

تصور کنید یک بازبین کد در روز سه‌شنبه با سه نسخه مختلف از یک کوئری گزارش‌گیری روبه‌روست که هر سه توسط یک عامل هوش مصنوعی بازنویسی شده‌اند؛ هر کدام فرمت متفاوتی دارند و مقادیر متفاوتی را جایگذاری کرده‌اند. متن تفاضل (diff) نویزی به نظر می‌رسد، گراف اتصال‌ها (join graph) بدون تغییر است و بازبین تنها دوازده دقیقه پیش از بسته شدن پنجره تغییرات (freeze window) فرصت دارد. هیچ‌یک از کاندیدها روی عملیات نوشتن (writes) اثر نمی‌گذارند، اما یکی از بازنویسی‌ها، فیلتر تاریخ را از orders.created_at به یک ستون snapshot دنورمالیزه منتقل کرده است. در اینجا سؤال واقعی این نیست که کدام دستیار SQL را پیش‌نویس کرده است، بلکه این است که کدام گیت رگرسیون باید باعث شکست (fail) درخواست ادغام (pull request) شود.

بسیاری از تیم‌های توسعه با SQL مانند یک رشته متنی ثابت برخورد می‌کنند، اما عامل‌های هوش مصنوعی (AI Agents) — شبیه دستیارهایی که دستورات را می‌فهمند اما هر بار با لحنی متفاوت می‌نویسند — به‌ندرت از یک فرمت استاندارد (canonical) پیروی می‌کنند. حتی وقتی منطق برنامه (logical plan) ثابت است، این عامل‌ها مکرراً نام مستعارها (Alias)، برچسب‌های CTE و فرمت مقادیر لغوی (literal formatting) را تغییر می‌دهند. این وضعیت باعث ایجاد تضاد بین دو فلسفه اعتبارسنجی متضاد می‌شود: «اثرانگشت‌گذاری» (Fingerprinting) و «تفاضل لغوی» (Literal Diffing).

چرا SQL تولید شده توسط عامل‌ها، گیت‌های ساده را می‌شکند

SQLهای نوشته شده توسط عامل‌ها به‌ندرت به صورت یک رشته استاندارد واحد ارائه می‌شوند. در حالی که گراف اتصال‌ها و گزاره‌ها (predicates) معادل باقی می‌مانند، مواردی چون فاصله‌های خالی (whitespace)، نام مستعارها، فرمت لغوی و برچسب‌های CTE تغییر می‌کنند. این امر منجر به چندین حالت شکست می‌شود:

• گیت‌های متنی خام (Raw Text Gates): این گیت‌ها روی تغییرات استایل بی‌ضرر شکست می‌خورند و می‌توانند تنها گزاره‌ای را که واقعاً جابه‌جا شده است، زیر لایه‌ای از نویز متنی دفن کنند.
• گیت‌های اثرانگشت (Fingerprint Gates): این‌ها می‌توانند مقداری لغوی را پنهان کنند که اکنون یک بازه تاریخی نامحدود یا یک لیست IN بدون پارامتر را اسکن می‌کند.
• تست‌های صرفاً زمان اجرا (Runtime-only Tests): عامل‌های بازبین از تست‌هایی که فقط تأیید می‌کنند «کوئری هنوز اجرا می‌شود» فراتر می‌روند. موفقیت در زمان اجرا ثابت نمی‌کند که رشته پذیرفته شده، همان حجم کاری (workload) است که تیم قصد داشت حفظ کند.

ترکیب این روش‌ها بدون یک قانون مشخص، هم منجر به بیلد‌های قرمز کاذب (false red builds) می‌شود و هم باعث رانش خاموش برنامه (silent plan drift).

رویکرد الف: نرمال‌سازی به اثرانگشت و سپس مقایسه

طرفداران اردوگاه اثرانگشت استدلال می‌کنند که بازبین‌ها باید هویت حجم کاری را تأیید کنند، نه یک رشته متنی زیبا. در این روش، مقادیر لغوی، کامنت‌ها و فاصله‌های قابل چشم‌پوشی حذف یا جایگزین می‌شوند و سپس یک عصاره (digest) با یک نسخه طلایی (golden) ثبت شده مقایسه می‌شود. استایل‌های معادل، وضعیت سبز را حفظ می‌کنند؛ اما تغییر در اتصال (join)، فیلتر یا تصویر (projection)، عصاره را تغییر داده و باعث شکست CI می‌شود.

• مزیت: این روش «نویز» را حذف می‌کند. قوی‌ترین شواهد برای این رویکرد در SQLهای گزارش‌گیری با تغییرات زیاد (high-churn) است، جایی که عامل‌ها مکرراً نام مستعارها را تغییر داده و CTEها را بازچیدمان می‌کنند.
• ارتباط با PostgreSQL: این روش مشابه نحوه استفاده PostgreSQL از pg_stat_statements.queryid برای ردیابی حجم‌های کاری فارغ از مقادیر bind خاص است؛ به گونه‌ای که متون مشابه را ادغام می‌کند تا اپراتورها بتوانند یک حجم کاری را ردیابی کنند نه یک فایل را.
• ریسک: از دست رفتن اطلاعات. دو کوئری می‌توانند شکل اثرانگشت یکسانی داشته باشند در حالی که یکی یک روز و دیگری یک دهه را bind می‌کند. کامنت‌هایی که محدودیت‌های ترتیب قفل (lock-order) را مستند می‌کنند، ناپدید می‌شوند. رشته‌های dollar-quoted، مقادیر لغوی INTERVAL و سازنده‌های آرایه در نرمال‌سازهای دست‌ساز به‌راحتی اشتباه مدیریت می‌شوند و تداخلاتی (collisions) ایجاد می‌کنند که گیت متوجه آن‌ها نخواهد شد.

رویکرد ب: حفظ تفاضل‌های متنی لغوی و الزام به بازبینی انسانی

تفاضل لغوی با SQL به عنوان یک اثر حسابرسی (audit artifact) برخورد می‌کند. هر کاراکتر تغییر یافته، فرصتی برای معرفی یک جدول جدید، یک گزاره گسترده‌تر یا تابعی با نوسان (volatility) متفاوت است. اجرای git diff روی خروجی sqlfmt ساده است، برای بخش‌های انطباق (compliance) قابل توضیح است و به نرمال‌سازی که تیم باید نگهداری کند، وابسته نیست.

• مزیت: امنیت بالا. شواهد برای این رویکرد در DMLهای دارای سطح دسترسی بالا، مسیرهای security-definer و کوئری‌هایی که ثابت‌های تجاری را در خود جای داده‌اند، قوی‌تر است. اثرانگشتی که 'pending' و 'closed' را با ? جایگزین می‌کند، نمی‌تواند یک فیلتر وضعیت را از یک اسکن تصادفی بین-وضعیت تشخیص دهد.
• ریسک: خستگی بازبین. عامل‌ها فرمت‌کننده‌های متفاوتی، کلمات کلیدی اختیاری AS و نام‌های CTE ناپایدار تولید می‌کنند. تحت فشار زمانی، بازبین‌ها شروع به تأیید سریع (rubber-stamping) تغییرات استایل می‌کنند و آن یک ستونی را که جابه‌جا شده است، از دست می‌دهند. گیت‌های لغوی همچنین با استایل پارامترهای bind می‌جنگند، زیرا '2026-09-17' و $1 متون متفاوتی هستند، حتی اگر در زمان اجرا برنامه یکسانی داشته باشند.

پیاده‌سازی یک ساختار دو-گیت (Dual-Gate Fixture)

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

مکانیزم:

• نرمال‌سازی: اسکریپت از regex برای حذف کامنت‌ها و جایگزینی مقادیر لغوی با ? استفاده می‌کند. همچنین نام مستعارها را نرمال می‌کند (مثلاً AS alias به AS _a تبدیل می‌شود).
• اثرانگشت‌گذاری: یک هش SHA-256 از متن نرمال‌شده تولید می‌کند که به ۱۶ کاراکتر کوتاه شده است.
• اجرا: fixture روی یک نسخه Read-only اجرا می‌شود. برای تضمین ایمنی، باید با یک timeout دستور و یک نقش read-only جفت شود. یک توالی تمرینی شامل موارد زیر است:
  • SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY;
  • SET lock_timeout = '2s';
  • SET statement_timeout = '5s';

کدهای خروجی:

• 0: موفق (OK)
• 10: عدم تطابق اثرانگشت (Fingerprint miss)
• 11: عدم تطابق لغوی (Literal miss)
• 12: ساختار درست اما متن تغییر کرده (Shape-ok but text drifted)

برای تأیید بیشتر، یک پروب دوم ثبت می‌کند که آیا برنامه‌ریز (planner) هنوز گره‌های مورد انتظار را پس از تطابق اثرانگشت می‌بیند یا خیر، و این کار را با استفاده از EXPLAIN (COSTS OFF, VERBOSE FALSE) انجام می‌دهد. هزینه‌ها (Costs) خاموش می‌شوند زیرا با کش و autovacuum تغییر می‌کنند و نباید هویت کوئری باشند.

ماتریس تصمیم‌گیری برای کلاس‌های کوئری

همه SQLها یکسان نیستند. این چارچوب یک پاسخ لایه‌بندی شده بر اساس هدف کوئری پیشنهاد می‌کند:

• گزارش‌های Read-only (بدون گزاره‌های امنیت ردیفی): از هر دو گیت استفاده کنید؛ در مورد رانش متن هشدار دهید اما تطابق‌های صرفاً اثرانگشتی را برای تغییرات استایل Alias و CTE با گره‌های EXPLAIN یکسان، مجاز بدانید.
• جست‌وجوی پارامتریک OLTP: از اثرانگشت به همراه بررسی تعداد پارامترهای bind استفاده کنید. در صورت تغییر تعداد جایگاه‌ها (placeholders)، درخواست را رد کنید.
• DMLهای دارای سطح دسترسی (UPDATE/DELETE): تطابق متنی لغوی را الزامی کنید. هر تغییر توکن باید توسط انسان تأیید شود؛ هرگز تطابق‌های صرفاً اثرانگشتی را مجاز نکنید.
• کوئری‌های دارای مقادیر لغوی وضعیت یا Tenant ID: از تطابق لغوی روی لیست گزاره‌ها استفاده کنید. اگر یک مقدار لغوی در نسخه طلایی با ? جایگزین شده است، این یک شکست است زیرا آن مقادیر لغوی همان قرارداد (contract) هستند.
• SQLهای حساس به security-definer یا search_path: تطابق لغوی و نام‌های کاملاً واجد شرایط (fully qualified names) را الزامی کنید. اگر نام‌های رابطه بدون پیشوند ظاهر شدند، درخواست را رد کنید.

قوانین شماره‌گذاری شده برای ربات‌های بازبین

1. ابتدا طبقه‌بندی کنید: فایل را از روی مسیر و اولین فعل دستور، پیش از آنکه به خروجی هر مدلی اعتماد کنید، طبقه‌بندی کنید. پوشه‌های dml/ و security/ به طور پیش‌فرض لغوی هستند؛ reports/ ممکن است از اثرانگشت استفاده کنند.
2. بودجه‌بندی اجرا: نسخه replica را با READ ONLY ،lock_timeout و statement_timeout اجرا کنید تا یک کاندید بد نتواند بدون بودجه، منتظر یک قفل بماند یا اسکن انجام دهد. این رویکرد برای جلوگیری از حوادثی است که در آن حلقه‌های تکرار نامحدود عامل‌های کدنویسی منجر به هزینه‌های ابری سنگین شدند.
3. نگاشت کدهای خروجی: نتیجه اثرانگشت و لغوی را به عنوان کدهای خروجی مجزا محاسبه کنید، سپس آن‌ها را از طریق جدول تصمیم نگاشت کنید، نه یک مقدار boolean واحد.
4. مداخله انسانی: اگر اثرانگشت مطابقت داشت و متن لغوی تغییر کرد، تنها زمانی مداخله انسانی را بخواهید که کلاس کوئری دارای سطح دسترسی بالا یا حساس به لغوی باشد.
5. رد کردن عدم تطابق اثرانگشت: اگر اثرانگشت مطابقت نداشت، حتی زمانی که EXPLAIN هنوز Index Scan را نشان می‌دهد، درخواست را رد کنید؛ زیرا یک گزاره جابه‌جا شده می‌تواند نوع گره را ثابت نگه دارد اما تعداد ردیف‌های بازیافت شده (cardinality) را تغییر دهد.
6. ذخیره‌سازی دوگانه: نسخه‌های طلایی را هم به صورت golden.sql و هم golden.fp ذخیره کنید تا باگ‌های نرمال‌ساز به جای تداخل خاموش، به صورت عدم تطابق دوگانه قابل مشاهده باشند.

محدودیت‌های فنی

هیچ گیت خودکاری کامل نیست. نرمال‌سازهای دست‌ساز، پارسر PostgreSQL نیستند. Dollar quotes، escapeهای E'' ،WITH ORDINALITY و مقادیر لغوی jsonb می‌توانند دو رشته متفاوت را در یک عصاره ادغام کنند. در حالی که pg_stat_statements.queryid ایمن‌تر از regex است، اما نیاز به اجرا روی یک موتور واقعی دارد و همچنان نادیده می‌گیرد که آیا یک بازه bound شده یک روز است یا ده سال.

علاوه بر این، EXPLAIN بدون ANALYZE نمی‌تواند یک Sequential Scan را که تنها پس از تأخیر در autovacuum ظاهر می‌شود، شناسایی کند. تفاضل‌های لغوی کوئری‌ای را که از نظر منطقی یکسان است اما به دلیل تغییر آمار از یک ایندکس جزئی (partial index) به یک ایندکس کامل سوئیچ کرده است، تشخیص نمی‌دهند. هیچ‌یک از گیت‌ها امنیت سطح ردیف (RLS) را ثابت نمی‌کنند، زیرا RLS به SET ROLE و متغیرهای نشست وابسته است که در فایل موجود نیستند. در نهایت، اسکریپت دو-گیت فرض می‌کند در هر فایل یک دستور وجود دارد؛ عامل‌هایی که دسته‌ای از دستورات یا CREATE INDEX CONCURRENTLY تولید می‌کنند، به تمرین متفاوتی نیاز دارند.

چه کسانی نباید از این رویکرد استفاده کنند

• کمبود زیرساخت: اگر تیم نمی‌تواند یک نرمال‌ساز با کیفیت پارسر نگهداری کند یا نمی‌تواند PostgreSQL را در CI اجرا کند، از اثرانگشت‌های طلایی صرف‌نظر کند.
• فرسودگی بازبین: اگر صف بازبینی در حال حاضر با نویز فرمت‌کننده‌ها اشباع شده و بازبین‌ها خواندن diffها را متوقف کرده‌اند، از گیت‌های صرفاً لغوی صرف‌نظر کنید.
• طرح‌های پویا (Dynamic Schemas): اگر به عامل اجازه داده شده است که جداول را به صورت پویا از یک کاتالوگ زنده بدون یک قرارداد منجمد انتخاب کند، از هر دو روش صرف‌نظر کنید.
• عدم تطابق محیط: تیم‌هایی که نسخه replica آن‌ها با اکستنشن‌ها، collationها و search_path محیط تولید مطابقت ندارد، نباید یک گیت محلی سبز را به عنوان دلیل ارتقاء (promotion) در نظر بگیرند.

این رویکرد بحث را از «کدام هوش مصنوعی بهتر است» به «کدام قانون ادغام صریح است» تغییر می‌دهد. با ذخیره هم‌زمان golden.sql و golden.fp ،تیم‌ها می‌توانند باگ‌های نرمال‌ساز را شناسایی کنند. برای تیم‌هایی که این روش را پیاده می‌کنند، پیشنهاد می‌شود از گزینه سرور رایگان MonkeyCode برای تمرین این حلقه‌ها روی نسخه‌های replica یک‌بارمصرف، پیش از متصل کردن عامل‌ها به پایگاه‌داده‌های اصلی استفاده کنند. این کار رگرسیون SQL را به یک مسئله طبقه‌بندی تبدیل می‌کند که در آن پروفایل ریسک کوئری، سخت‌گیری گیت را تعیین می‌کند.

گام بعدی شما

• بررسی کنید آیا در خط لوله CI/CD خود تفاوتی بین تغییرات ظاهری SQL و تغییرات منطقی قائل می‌شوید یا خیر.
• برای کوئری‌های حساس (DML)، گیت تطابق لغوی (Literal Match) را جایگزین تأییدات دستی سریع کنید.
• از دستور EXPLAIN برای اعتبارسنجی ساختار اجرای کوئری‌های تولیدشده توسط عامل‌ها استفاده کنید.

اما مدیریت این کوئری‌ها تنها بخشی از ماجراست؛ برای درک چگونگی بهینه‌سازی هزینه استنتاج این عامل‌ها، تحلیل ما درباره تراشه‌های Blackwell را بخوانید.