pglayers: ترکیب افزونه‌های PostgreSQL بدون نیاز به کامپایل کدهای منبع

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

تا پیش از این، توسعه‌دهندگان برای شخصی‌سازی یک نمونه از PostgreSQL دو راه دشوار داشتند: یا باید از ایمیج‌های حجیم و bloated شخص ثالث استفاده می‌کردند که امنیت آن‌ها گواهی‌نشده بود، یا خودشان ساعت‌ها زمان صرف کامپایل افزونه‌ها از کد منبع می‌کردند. طبق مستندات منتشرشده در گیت‌هاب در ۱ ژوئیه ۲۰۲۶، پروژه pglayers این دوگانگی را با تبدیل افزونه‌های پایگاه‌داده به لایه‌های ترکیب‌پذیر داکر (Docker layers) به کل تغییر داده است.

برای برنامه‌نویسان، افزودن ابزارهایی مثل pgvector یا pg_cron معمولاً به معنای نصب وابستگی‌های ساخت پیچیده و مدیریت کامپایلرها در داخل کانتینر است. این مسیر نه‌تنها مستعد خطا است، بلکه حجم ایمیج نهایی را به‌شدت افزایش می‌دهد. با انتقال بخش سنگین کار به مرحله‌ی پیش‌ساخت (pre-build)، pglayers اجازه می‌دهد محیط‌های بهینه شده‌ی پایگاه‌داده در چند ثانیه اسمبل شوند. شما دیگر نیازی ندارید که بفهمید چگونه افزونه‌های PostgreSQL را بسازید، وابستگی‌ها را نصب کنید یا کامپایلرها را به‌صورت دستی پیکربندی نمایید. همان‌طور که در تحلیل‌های قبلی ما درباره‌ی استقرار زیرساخت‌های ابری اشاره کردیم، کاهش اصطکاک در لایه‌ی ابزاری، سرعت نوآوری در سطح محصول را به‌شدت بالا می‌برد.

مکانیسم لایه‌بندی

در هسته‌ی pglayers استراتژی استفاده از ایمیج‌های FROM scratch قرار دارد. این‌ها کانتینرهای قابل اجرا نیستند. در عوض، آن‌ها ایمیج‌های مینیمالی هستند که فقط آرتیفکت‌های افزونه را در مسیرهای مشخص فایل‌سیستم نگه می‌دارند. برای مثال، مسیرهای زیر در این لایه‌ها قرار دارند:

• /usr/lib/postgresql/17/lib/vector.so
• /usr/share/postgresql/17/extension/vector.control
• /usr/share/postgresql/17/extension/vector--0.8.3.sql

شما می‌توانید با استفاده از دستور COPY --from در داکرفایل، یک ایمیج سفارشی بسازید. برای افزودن قابلیت جست‌وجوی برداری، زمان‌بندی وظایف و تحلیل‌های مکانی به PostgreSQL 17، کافی است برای هر افزونه یک خط اضافه کنید:

FROM postgres:17
COPY --from=ghcr.io/pglayers/pgx-pgvector:17 / /
COPY --from=ghcr.io/pglayers/pgx-pg_cron:17 / /
COPY --from=ghcr.io/pglayers/pgx-postgis:17 / /

داکر این لایه‌های پیش‌ساخته را از ریجستری کانتینرهای گیت‌هاب (GHCR) می‌کشد و مستقیماً روی ایمیج رسمی postgres قرار می‌دهد. در این فرآیند هیچ کامپیلاسیونی رخ نمی‌دهد. نتیجه، یک ایمیج واحد است که لایه به لایه با ابزارهای انتخابی شما ساخته شده است.

اکوسیستم افزونه‌ها و نسخه‌بندی

به گزارش مستندات pglayers، این پروژه در حال حاضر از ۵۳ افزونه در سه نسخه‌ی اصلی PostgreSQL پشتیبانی می‌کند. نسخه‌های ۱۷ و ۱۸ به عنوان نسخه‌های پایدار (Stable) علامت‌گذاری شده‌اند، در حالی که نسخه ۱۹ در حال حاضر در مرحله‌ی بتای آزمایشی (Experimental Beta) قرار دارد. پشتیبانی از PG 19 تا زمان رسیدن به نسخه نهایی (General Availability یا GA) به‌صورت «بیشترین تلاش ممکن» (Best-effort) است، زیرا برخی افزونه‌ها ممکن است هنوز با این نسخه سازگار نباشند.

تمامی ایمیج‌ها چند-معماری (multi-architecture) هستند و از هر دو پلتفرم linux/amd64 و linux/arm64 پشتیبانی می‌کنند. داکر به‌طور خودکار معماری صحیح را متناسب با پلتفرم شما می‌کشد. کاربران می‌توانند بین دو فرمت تگ انتخاب کنند:

• آخرین بیلد: استفاده از تگ‌هایی مانند pgx-pgvector:17.
• نسخه‌ی پین‌شده: برای بازتولید دقیق‌تر محیط، استفاده از تگ‌هایی مانند pgx-pgvector:17-v0.8.3.

کاتالوگ تفصیلی افزونه‌ها

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

هوش مصنوعی و جست‌وجو

• pgvector (v0.8.3): جست‌وجوی شباهت برداری برای AI و Embedding (نسخه‌های ۱۷، ۱۸ و ۱۹).
• pg_bigm (v1.2): جست‌وجوی تمام‌متن 2-gram، بهینه شده برای زبان‌های CJK (نسخه‌های ۱۷ و ۱۸).
• pg_textsearch (v1.3.1): جست‌وجوی تمام‌متن با رتبه‌بندی مرتبط BM25 (نسخه‌های ۱۷ و ۱۸).
• rum (v1.3.15): ایندکسی شبیه GIN با قابلیت ترتیب برای جست‌وجوی تمام‌متن (نسخه‌های ۱۷ و ۱۸).

تحلیل داده و موتورهای تخصصی

• timescaledb (v2.28.1): هایپرتول‌های سری زمانی، فشرده‌سازی و Aggregateهای مداوم (نسخه‌های ۱۷ و ۱۸).
• pg_duckdb (v1.1.1): موتور تحلیل ستونی DuckDB به‌صورت تعبیه شده (نسخه‌های ۱۷ و ۱۸).
• Apache AGE (v1.7.0-rc0): پایگاه‌داده گرافی با زبان پرس‌وجوی openCypher (نسخه‌های ۱۷ و ۱۸).
• documentdb (v0.113-0): موتور سازگار با MongoDB با تایپ‌های BSON و APIهای CRUD (نسخه‌های ۱۷ و ۱۸).
• tdigest (v1.4.3): استفاده از T-digest برای تخمین کوانتایل و پرسنتایل (نسخه‌های ۱۷، ۱۸ و ۱۹).
• hll (v2.21): شمارش متمایز احتمالی HyperLogLog (نسخه‌های ۱۷، ۱۸ و ۱۹).

داده‌های جغرافیایی و شبکه

• PostGIS (v3.6.4): پشتیبانی جامع مکانی شامل هندسه، جغرافیا، رستر و MVT (نسخه‌های ۱۷، ۱۸ و ۱۹).
• pgrouting (v4.0.1): مسیریابی مکانی و تحلیل شبکه روی PostGIS (نسخه‌های ۱۷، ۱۸ و ۱۹).
• h3-pg (v4.2.3): ایندکس‌گذاری مکانی شش‌ضلحه‌ای Uber H3 (نسخه‌های ۱۷ و ۱۸).
• ip4r (v2.4.3): تایپ‌های داده‌ای محدوده IPv4/IPv6 با ایندکس‌گذاری GiST (نسخه‌های ۱۷، ۱۸ و ۱۹).
• prefix (v1.2.11): تایپ داده‌ای محدوده پیشوند برای جست‌وجوهای مسیریابی تلفنی (نسخه‌های ۱۷، ۱۸ و ۱۹).

مدیریت و عملکرد

• pg_cron (v1.6.7): یک زمان‌بند برای وظایف دوره‌ای داخل پایگاه‌داده (نسخه‌های ۱۷ و ۱۸).
• pgaudit (v17.1): ثبت لاگ‌های حسابرسی در سطح نشست و شیء (نسخه‌های ۱۷ و ۱۸).
• pg_partman (v5.4.3): مدیریت خودکار پارتیشن‌بندی جداول (نسخه‌های ۱۷، ۱۸ و ۱۹).
• pg_repack (v1.5.3): بازسازماندهی آنلاین جداول بدون قفل‌های سنگین (نسخه‌های ۱۷، ۱۸ و ۱۹).
• pg_squeeze (v1.9.3): حذف فضای استفاده نشده از جداول بدون قفل‌های سنگین (نسخه‌های ۱۷، ۱۸ و ۱۹).
• pg_hint_plan (v1.7.1): اصلاح طرح‌های اجرا با استفاده از Hintها در کامنت‌های SQL (نسخه‌های ۱۷ و ۱۸).
• pg_stat_monitor (v2.3.2): آمار پیشرفته پرس‌وجوها با هیستوگرام‌ها و باکت‌ها (نسخه‌های ۱۷ و ۱۸).
• pg_wait_sampling (v1.1.9): آمارهای مبتنی بر نمونه‌برداری از رویدادهای انتظار (نسخه‌های ۱۷، ۱۸ و ۱۹).
• plprofiler (v4.2.5): پروفایلر عملکرد برای توابع PL/pgSQL (نسخه‌های ۱۷ و ۱۸).
• hypopg (v1.4.3): ایجاد ایندکس‌های فرضی برای تحلیل‌های What-if (نسخه‌های ۱۷، ۱۸ و ۱۹).

یکپارچه‌سازی داده و تایپ‌ها

• pglogical (v2.4.7): تکثیر منطقی استریمینگ با استفاده از pub/sub (نسخه‌های ۱۷، ۱۸ و ۱۹).
• wal2json (v2.6): پلاگین خروجی JSON برای تکثیر منطقی و CDC (نسخه‌های ۱۷ و ۱۸).
• tds_fdw (v2.0.5): Wrapper داده‌های خارجی برای SQL Server و Sybase (نسخه‌های ۱۷، ۱۸ و ۱۹).
• wrappers (v0.6.2): فریمورک FDW برای Stripe, S3, Firebase و غیره (نسخه‌های ۱۷ و ۱۸).
• postgres_protobuf (v0.3.2): پشتیبانی از Protocol Buffer برای تبدیل پرس‌وجو و JSON (نسخه‌های ۱۷، ۱۸ و ۱۹).
• pg_uuidv7 (v1.7.0): شناسه‌های منحصربه‌فرد قابل مرتب‌سازی زمانی (نسخه‌های ۱۷، ۱۸ و ۱۹).
• semver (v0.41.0): تایپ داده‌ای نسخه‌بندی معنایی (نسخه‌های ۱۷، ۱۸ و ۱۹).

امنیت و API

• pgsodium (v3.1.11): رمزنگاری مدرن با استفاده از libsodium (نسخه‌های ۱۷، ۱۸ و ۱۹).
• pgjwt (master): تولید و اعتبارسنجی JSON Web Token (نسخه‌های ۱۷، ۱۸ و ۱۹).
• anon (v3.1.1): ناشناس‌سازی و ماسک‌گذاری داده‌ها (نسخه‌های ۱۷ و ۱۸).
• credcheck (v5.0): بررسی اعتبار هنگام ایجاد کاربر یا تغییر رمز عبور (نسخه‌های ۱۷، ۱۸ و ۱۹).
• pg_graphql (v1.6.1): پشتیبانی از GraphQL برای PostgreSQL (نسخه‌های ۱۷ و ۱۸).
• http (v1.7.1): کلاینت HTTP برای درخواست‌های وب از طریق SQL (نسخه‌های ۱۷، ۱۸ و ۱۹).
• pg_net (v0.20.3): درخواست‌های HTTP/HTTPS غیرمسدودکننده و async (نسخه‌های ۱۷، ۱۸ و ۱۹).

توسعه و سازگاری

• pgtap (v1.3.4): فریمورک تست واحد (Unit Testing) برای PostgreSQL (نسخه‌های ۱۷، ۱۸ و ۱۹).
• plpgsql_check (v2.9.1): لینتر و اعتبارسنج PL/pgSQL (نسخه‌های ۱۷ و ۱۸).
• plv8 (v3.2.4): زبان رویه‌ای JavaScript (V8) (نسخه‌های ۱۷ و ۱۸).
• orafce (v4.16.7): توابع و پکیج‌های سازگار با Oracle (نسخه‌های ۱۷ و ۱۸).
• pgtt (v4.5): جداول موقت جهانی به سبک Oracle (نسخه‌های ۱۷، ۱۸ و ۱۹).

پروفایل‌های آماده‌-به‌کار

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

• پروفایل Full: ایمیج ghcr.io/pglayers/pglayers-full:17 تمام ۵۳ افزونه پشتیبانی شده را در خود جای داده است.
• پروفایل Azure: پروفایل ghcr.io/pglayers/pglayers-azure:17 شامل ۲۸ افزونه است که تقریباً مشابه Azure Database for PostgreSQL Flexible Server می‌باشد.

این پروفایل‌ها برای نسخه‌های ۱۷، ۱۸ و ۱۹ منتشر شده‌اند. پروژه هشدار می‌دهد که پروفایل‌های венدور (Vendor) تخمین‌هایی برای توسعه محلی هستند و جایگزین سرویس‌های مدیریت‌شده نمی‌شوند، زیرا پیش‌فرض‌های پیکربندی و رفتارهای خاص هر پلتفرم ممکن است متفاوت باشد.

کاربران همچنین می‌توانند پروفایل‌های سفارشی خود را با افزودن یک فایل متنی به دایرکتوری profiles/ بسازند. در این فایل باید نام هر افزونه در یک خط و به‌صورت الفبایی مرتب شده باشد. کامنت‌ها (#) و خطوط خالی نادیده گرفته می‌شوند. این قابلیت به تیم‌ها اجازه می‌دهد زیرمجموعه خاصی از ابزارها را گلچین کرده و با دستور make image PROFILE=myprofile یک ایمیج ترکیبی بسازند.

نکات اجرایی و ظرافت‌های پیاده‌سازی

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

کتابخانه‌های پیش‌بارگذاری مشترک (Shared Preload Libraries)
بسیاری از افزونه‌ها باید هنگام استارت‌آپ بارگذاری شوند. این‌ها شامل موارد زیر هستند:

• age ،anon ،credcheck
• pg_cron ،pg_duckdb ،pg_durable ،pg_failover_slots
• pg_hint_plan ،pg_net ،pg_partman (به عنوان pg_partman_bgw)
• pg_qualstats ،pg_squeeze ،pg_stat_monitor
• pg_textsearch ،pg_wait_sampling ،pgaudit ،pglogical
• pgsodium ،pgtt ،plprofiler ،timescaledb

پروژه pglayers توصیه می‌کند این موارد را از طریق دستور RUN echo در داکرفایل به فایل postgresql.conf.sample اضافه کنید. برای مثال:
RUN echo "shared_preload_libraries = 'pg_cron,pgaudit,pg_partman_bgw'" >> /usr/share/postgresql/postgresql.conf.sample

فعال‌سازی پایگاه‌داده
افزونه‌ها باید در هر پایگاه‌داده‌ای که مورد نیاز هستند، ایجاد شوند. این کار با کپی کردن یک اسکریپت SQL در مسیر /docker-entrypoint-initdb.d/ خودکار می‌شود. برای مثال، فایلی به نام 10-extensions.sql حاوی دستور CREATE EXTENSION IF NOT EXISTS vector; در اولین استارت کانتینر (زمانی که دایرکتوری داده‌ها در حال مقداردهی اولیه است) اجرا خواهد شد.

مورد خاص: PostGIS
ایمیج PostGIS خودکفا است و کتابخانه‌های مشترک زمان اجرا از جمله libgeos, libproj, libgdal, libjson-c, libprotobuf-c و فایل‌های داده‌ای PROJ/GDAL را شامل می‌شود. برای فعال‌سازی درایورهای فرمت رستر GDAL (مانند GeoTIFF و PNG)، کاربران باید متغیر محیطی POSTGIS_GDAL_ENABLED_DRIVERS=ENABLE_ALL را تنظیم کنند. به‌طور پیش‌فرض، این درایورها به دلایل امنیتی غیرفعال هستند که با رفتار ایمیج رسمی داکر PostGIS مطابقت دارد.

مورد خاص: DocumentDB
پایگاه‌داده DocumentDB یک موتور سازگار با MongoDB را فراهم می‌کند و به فرآیند نصب دو مرحله‌ای نیاز دارد:
۱. هسته (Core): ابتدا باید documentdb_core نصب شود. این بخش تایپ‌های داده‌ای BSON و عملیات‌های اصلی را فراهم می‌کند و به‌تنهایی کار می‌کند.
۲. API کامل: سپس افزونه documentdb نصب می‌شود. این افزونه APIهای کامل CRUD را ارائه می‌دهد اما به documentdb_core, pg_cron, pgvector, postgis و tsm_system_rows وابسته است.

تضمین کیفیت و لایسنسینگ

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

• شناسایی تداخل (Collision Detection): هر جفت از افزونه‌ها با هم مقایسه می‌شوند تا اطمینان حاصل شود هیچ فایل مشترکی ندارند. دستور COPY --from در داکر فایل‌ها را به‌طور بی‌صدا بازنویسی (Overwrite) می‌کند که می‌تواند باعث خرابی افزونه‌ها شود؛ این بررسی مانع از آن می‌شود.
• حفاظت از ایمیج پایه: اطمینان از اینکه افزونه‌ها فایل‌های ایمیج رسمی postgres:XX را جایگزین نمی‌کنند.
• تأیید وابستگی‌ها: اجرای دستور ldd روی هر فایل .so در ایمیج ترکیبی برای شناسایی وابستگی‌های گم‌شده کتابخانه‌های مشترک.
• اعتبارسنجی عملکردی: هر افزونه با یک پرس‌وجوی واقعی آزمایش می‌شود تا رفتار زمان اجرا تأیید گردد.
• تست یکپارچه‌سازی: اجرای فایل‌های test.sql با تأییدیه‌های PASS/FAIL.

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

• لایسنس‌های سهل‌گیرانه: MIT, Apache 2.0, BSD, ISC (مانند pgvector و pg_cron).
• کپی‌لفت ضعیف (Weak Copyleft): MPL-2.0 (مانند pg_uuidv7).
• GPL-2.0: PostGIS و pgRouting گنجانده شده‌اند چون در زمان اجرا از طریق dlopen() بارگذاری می‌شوند. جامعه PostgreSQL و سرویس‌های مدیریت‌شده‌ای مانند AWS RDS, Azure, Google Cloud SQL, Neon و Supabase این مورد را به عنوان «تجمیع صرف» (Mere Aggregation) تلقی می‌کنند.

موارد به‌طور صریح حذف شده‌اند:

• GPL-3.0: مانند login_hook یا session_variable به دلیل شرایط سخت‌تر کپی‌لفت.
• AGPL-3.0: مانند topn.
• تجارتی/منبع-در دسترس: لایسنس‌های BSL, SSPL, ELv2, FSL.
• وابستگی‌های تجاری: افزونه‌هایی مثل oracle_fdw که نیاز به Oracle Instant Client دارند.

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

برای مشارکت‌کنندگان و کاربران پیشرفته، pglayers یک رابط Makefile جامع فراهم کرده است:

• کشف: لیست افزونه‌ها با make list یا پروفایل‌ها با make list-profiles.
• ساخت: ساخت یک افزونه خاص با make build EXT=pgvector PG=17 یا تمامی افزونه‌ها برای یک نسخه با make build-all PG=17.
• پشتیبانی بتا: برای PG 19 از اورراید استفاده کنید: make build EXT=pgvector PG=19 PG_TAG=19beta1.
• توزیع: ارسال ایمیج‌ها به ریجستری با make push یا استفاده از ریجستری جایگزین با REGISTRY=ghcr.io/myorg.
• دیباگ: چاپ داکرفایل یک افزونه با make dockerfile EXT=pg_cron.

برخی افزونه‌ها در فایل extension.conf با علامت CI_SKIP=1 مشخص شده‌اند. این مورد برای ابزارهایی با زمان ساخت بسیار طولانی است؛ مانند plv8 که کامپایل موتور V8 آن از زمان-بندی CI در شبیه‌ساز arm64 فراتر می‌رود، هرچند که همچنان برای بیلد‌های محلی کار می‌کنند.

برای تأیید وضعیت کانتینر در حال اجرا، کاربران می‌توانند لاگ‌ها را برای عبارت "database system is ready to accept connections" چک کنند یا دستور docker exec -it <id> psql -U postgres -c "SELECT version();" را اجرا نمایند. تداخل پورت‌ها با مپ کردن پورت‌های میزبان (مثلاً -p 5433:5432) مدیریت می‌شود، در حالی که کانتینر داخلی همچنان روی پورت ۵۴۳۲ گوش می‌دهد.

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

گام بعدی شما

• اگر از ایمیج‌های حجیم شخص ثالث برای PostgreSQL استفاده می‌کنید، داکرفایل خود را با ساختار COPY --from بازنویسی کنید تا حجم و امنیت ایمیجتان بهبود یابد.
• برای پروژه‌های AI، ترکیب pgvector و pg_cron را در یک ایمیج مینیمال تست کنید تا مدیریت داده‌های برداری خودکار شود.
• بررسی کنید کدام افزونه‌های مورد نیاز شما در لیست ۵۳ مورد pglayers هستند تا فرآیند کامپایل دستی را متوقف کنید.

اما لایه‌بندی فقط مختص پایگاه‌داده نیست؛ تأثیر این رویکرد بر مدیریت وضعیت (State) در کانتینرهای پیچیده را در تحلیل ما درباره‌ی استراتژی‌های ذخیره‌سازی داده در داکر بررسی کنید. این موضوع مشابه چالش‌های استقرار سرویس‌های توزیع شده است، مانند آنچه در راهنمای استقرار سرور شخصی Bluesky بر بستر Cloudflare Workers برای مدیریت داده‌ها در محیط‌های Serverless مشاهده کردیم.