Postgres.js 4.0: بازنویسی کامل زیر API
خلاصهٔ کاملتر
Postgres.js نسخه 4.0 رو منتشر کرده و طبق یادداشت انتشار، همه چیز زیر API عمومی از نو نوشته شده: pool اتصالها، خود اتصال، پروتکل، شروع ارتباط و لایه socket. کوئریها، تراکنشها، cursorها، COPY و subscribe مثل نسخه 3.4.9 کار میکنن، به جز تغییراتی که پایین اومده.
دو مشکل امنیتی بسته شده که تو v3 هم پچ شدن. اول اینکه اگه کاراکتر NUL داخل مقدار database یا user بود، میشد پارامترهای اضافه به اتصال تزریق کرد. یعنی اپی که ورودی کاربر رو اونجا میذاشت (مثلاً یه دیتابیس برای هر tenant) ممکن بود با کاربر دیگهای لاگین کنه. حالا هر NUL توی رشتههای پروتکل با خطای NUL_CHARACTER رد میشه. دوم اینکه ستونی به اسم proto دیگه prototype ردیف رو عوض نمیکنه و یه property معمولی هست.
مهمترین تغییر برای ارتقا اینه که حالا سرور نوع هر پارامتر رو تعیین میکنه (infer: false پیشفرضه)، مثل libpq. تو v3 مثلاً یه Date همیشه timestamptz فرستاده میشد. حالا اگه بیرون از UTC هستید، Dateی که با ستون timestamp یا date مقایسه میشه بهعنوان UTC حساب میشه. جاهایی که کوئری خودش نوع رو مشخص نمیکنه هم باید cast بذارید. با infer: true رفتار قبلی برمیگرده. Node.js 20 به بالا، Bun و Cloudflare Workers پشتیبانی میشن و نسخه CommonJS حذف شده.
چند تغییر رفتاری دیگه: sql.array() حذف شده و آرایه رو مستقیم با cast میفرستید. اگه سرور جواب COMMIT رو با ROLLBACK بده، sql.begin با TRANSACTION_ROLLED_BACK رد میشه، در حالی که v3 اونو commit حساب میکرد. کوئری روی اتصالی که release شده هم دیگه اجرا نمیشه و BEGIN ناامن بیرون از sql.begin هم rollback میشه.
قابلیت جدید اصلی یه scheduler هست؛ یعنی وقتی همه اتصالها مشغولن، کوئری روی اتصالی صف میشه که زودتر آزاد میشه و کوئریهای کند کنار هم نگه داشته میشن. طبق یادداشت انتشار، یه lookup یک میلیثانیهای دیگه پشت یه گزارش سنگین منتظر نمیمونه و p99.9 از ۷۹۲ به ۵ میلیثانیه رسیده. چیزای دیگه: queue_timeout، لغو کوئری با .signal()، savepoint برای sql.begin تودرتو، using برای بستن خودکار، channel binding روی TLS و tracing channel برای OpenTelemetry.
تو بخش رفع اشکال، ۳۳ باگ درستی هر کدوم با تست رگرسیون درست شدن؛ مثلاً جوابها دیگه به کوئری اشتباه نمیرسن و helperها با clause درست کار میکنن. از نظر کارایی هم کوئریای که نوع همه پارامترهاش معلومه تو یه رفتوبرگشت آماده و اجرا میشه. بعد از ۱۶ ردیف با یه شکل، ردیفها با یه تابع مخصوص اون شکل ساخته میشن که تو ۲۰ ستون حدوداً نصف CPU مصرف میکنه.
نکات کلیدی:
- v4 همه لایههای زیر API رو بازنویسی کرده؛ API عمومی تقریباً مثل 3.4.9 مونده.
- پیشفرض infer: false هست و سرور نوع پارامترها رو تعیین میکنه؛ Date بیرون از UTC ممکنه رفتار متفاوت داشته باشه.
- دو مشکل امنیتی (NUL در پارامتر اتصال و ستون proto) تو v3 و v4 بسته شدن.
- scheduler جدید p99.9 یه کوئری سریع رو روی pool شلوغ از ۷۹۲ به ۵ میلیثانیه رسونده.
- نیازمندیها: Node.js 20 به بالا، Bun یا Cloudflare Workers؛ CommonJS و sql.array() حذف شدن.




