في دليل Supabase على سيرفرك شغلنا أحد عشر Container خلف بوابة واحدة، واستهلكت قرابة 1.2 جيجابايت من الذاكرة RAM دون أي ضغط، وحجم ال Images قرابة 9 جيجابايت، وهذا ثمن معقول لمنصة فيها PostgreSQL كاملة. لكن لنفرض أن مشروعك أصغر من ذلك بكثير: تطبيق داخلي لفريق من عشرين شخصاً، أو نموذج أولي Prototype لعميل، أو تطبيق جوال لمتجر صغير، وكل ما تريده هو تسجيل دخول وجداول بصلاحيات ورفع ملفات وتحديث فوري، على VPS بذاكرة 1 جيجابايت. هنا يظهر PocketBase، وهو خلفية Backend كاملة في ملف تنفيذي واحد مكتوب بلغة Go، يحفظ كل شيء في قاعدة SQLite داخل مجلد واحد، وتنسخه إلى السيرفر وتشغله.
وفكرة ال Backend as a Service نفسها، ولماذا يكلم التطبيق قاعدة البيانات Database مباشرة فتصبح قواعد الوصول هي الحارس الوحيد، شرحناها في ما هو Backend as a Service؟ فلن نعيدها هنا. وسوف نناقش في هذا المقال ما يلي:
- ما الذي يعمل داخل الملف الواحد، ولماذا انتقل مستودع المشروع من GitHub إلى نطاق صاحبه.
- التثبيت داخل Docker بالإصدار v0.42.3، وزمن التشغيل والذاكرة كما قسناها.
- المجموعات Collections والحقول Fields من ملف ترحيل Migration بدل الضغط في اللوحة.
- قواعد الوصول API Rules، والفرق الخطير بين القاعدة الفارغة والقاعدة غير الموجودة.
- تطبيق مهام صغير كامل بمكتبة JavaScript: مستخدمان وملف محمي وتحديث فوري ومسار خاص.
- كيف يعمل التحديث الفوري Realtime من الداخل، وماذا حدث عندما فتحنا 200 اشتراك.
- الدوال الخاصة Hooks بلغة JavaScript والمهام المجدولة، والخطأ الذي يقع فيه الجميع أول مرة.
- النسخ الاحتياطي Backup والاستعادة، ثم حدود PocketBase بصراحة ومتى يناسبك ومتى لا.
لماذا يوجد PocketBase؟
الحل البسيط لمشروع صغير هو أن تكتب سيرفراً صغيراً بنفسك، ب Express أو Flask، فوق ملف SQLite، وتضيف إليه تسجيل الدخول ورفع الملفات، وقد تبدو العملية من الوهلة الأولى بسيطة، لكن في الواقع فهي غير كذلك، فبعد أسبوعين ستجد أنك كتبت تسجيلاً وتوكنات Token واستعادة كلمة المرور Password Reset وتحققاً من المدخلات Validation وصلاحيات لكل جدول ورفع ملفات بأحجام وأنواع محددة ولوحة إدارة بسيطة، وكل جزء من هذه الأجزاء مكان محتمل لثغرة. والحل الثاني هو منصة كاملة مثل Supabase أو Appwrite، وهذا يعطيك كل الأجزاء مختبرة، لكن مقابل عشرة Containers أو أكثر وذاكرة تقاس بالجيجابايت وتحديثات لعدة مشاريع معاً.
وPocketBase يقف بين الحلين، فهو يعطيك الأجزاء نفسها، أي المصادقة Authentication وقاعدة البيانات والصلاحيات Permissions والملفات والتحديث الفوري ولوحة الإدارة Admin Console، لكن داخل عملية Process واحدة، والسبب أنه مبني على SQLite المدمجة داخل البرنامج نفسه وليس على سيرفر قاعدة بيانات مستقل. ولذلك فالسؤال الذي يجب أن تسأله قبل أن تختاره ليس «هل هو قوي بما يكفي؟»، وإنما «هل يكفيني سيرفر واحد؟»، وسوف نعود إلى هذا السؤال في آخر المقال.
ما الذي يعمل داخل الملف الواحد؟
الملف التنفيذي Executable الذي نزلناه حجمه 33.5 ميجابايت، وعند تشغيله يفتح منفذاً واحداً، ومن خلاله يقدم الواجهة البرمجية REST API ولوحة الإدارة على المسار /_/ والتحديث الفوري، ويحفظ كل حالته في مجلد اسمه pb_data بجانبه. والصورة التالية تبين الأجزاء:

- قاعدة البيانات SQLite: مدمجة في الملف التنفيذي نفسه، والبيانات والمستخدمون في
data.db، والسجلات Logs في ملف منفصل اسمهauxiliary.dbحتى لا تزاحم السجلات بياناتك، ويعمل الملفان بنمط WAL الذي يسمح بالقراءة أثناء الكتابة. وطريقة تخزين القاعدة لبياناتها على القرص شرحناها في كيف تخزن قاعدة البيانات بياناتك من الداخل. - المصادقة: مجموعة المستخدمين
usersمن نوع خاص اسمه Auth Collection، وكلمات المرور محفوظة بخوارزمية bcrypt، والدخول يعطي توكن JWT، وفكرة التوكن والجلسة في الجلسات وملفات تعريف الارتباط وJWT. - التحديث الفوري Realtime: عبر Server-Sent Events، واختصاراً SSE، وليس WebSocket، والفرق بينهما في التواصل اللحظي: Polling وSSE وWebSockets.
- الدوال الخاصة Hooks: محرك JavaScript مدمج اسمه goja، وهو ليس Node.js، كما سوف نرى.
- الملفات: في مجلد
storageمحلياً، أو في تخزين متوافق مع S3 إذا ضبطته.
والترخيص MIT، والمشروع يكتبه ويصونه مطور واحد بشكل أساسي، وهذه نقطة تحسبها عند الاختيار، فقد أعلن المشروع في الإصدار v0.41.0 أنه نقل وحدة Go من GitHub إلى نطاق صاحبه ganigeorgiev.com، وأصبح المستودع القديم على GitHub مؤرشفاً وأول سطر فيه يقول إن المستودع انتقل، وآخر إصدار نشر هناك هو v0.40.6 بتاريخ 23 أكتوبر 2026، أما ما بعده فينزل من الموقع الجديد. وهذا يعني عملياً أمرين: إذا كنت تعتمد على صفحة إصدارات GitHub في سكربت أو Dockerfile فلن تجد الإصدارات الجديدة هناك، والرابط الثابت الجديد للتنزيل هو المذكور في سجل التغييرات Changelog، والأمر الثاني أن المشروع ما زال قبل الإصدار 1.0، والملف README نفسه يحذر من أن التوافق مع الإصدارات السابقة غير مضمون قبله، فاقرأ سجل التغييرات قبل كل تحديث.
التثبيت داخل Docker
لا يوجد Docker Image رسمي لـ PocketBase، والتوثيق في صفحة Going to production يعطي Dockerfile صغيراً كمثال، وقد استخدمناه كما هو مع إضافة ملفات الترحيل والدوال الخاصة، وثبتنا الإصدار حتى لا يتغير البناء من يوم لآخر:
# PocketBase has no official Docker image; this follows the minimal Dockerfile in the "Going to production" docs
FROM alpine:3.22
ARG PB_VERSION=0.42.3
RUN apk add --no-cache unzip ca-certificates
ADD https://ganigeorgiev.com/meta/pocketbase/pocketbase/download/v${PB_VERSION}/pocketbase_${PB_VERSION}_linux_amd64.zip /tmp/pb.zip
RUN unzip /tmp/pb.zip -d /pb/ && rm /tmp/pb.zip
COPY ./pb_migrations /pb/pb_migrations
COPY ./pb_hooks /pb/pb_hooks
EXPOSE 8090
CMD ["/pb/pocketbase", "serve", "--http=0.0.0.0:8090"]في الإعداد أعلاه لاحظ التالي:
- رابط التنزيل يمر عبر المسار
/meta/.../download/الذي يحول إلى الملف الفعلي، وهو الرابط الثابت الذي ذكره سجل التغييرات للإصدار v0.41.0 لمن يبني Docker Image، فلا تقم بنسخ رابط الملف الذي يظهر بعد التحويل، والسبب أنه رابط داخلي قد يتغير. - الحزمة
ca-certificatesضرورية إذا كان PocketBase سيتصل بسيرفر بريد أو بتخزين S3 أو بمزود دخول OAuth عبر HTTPS، وسجل تغييرات v0.40.6 نفسه ينصح بتحديثها مع كل تحديث لل Image. - المجلد
pb_dataغير موجود في ال Image، ويجب أن يكون Volume، وإلا فكل بياناتك تختفي عند حذف ال Container، كما شرحنا في Volumes وBind Mounts.
الآن نقوم بالبناء والتشغيل، ونقيس الزمن من أمر التشغيل حتى يرد مسار الصحة /api/health:
docker build -t sc5-pocketbase:0.42.3 .
docker volume create sc5-pb-data
t0=$(date +%s%N)
docker run -d --name sc5-pb -p 127.0.0.1:28090:8090 -v sc5-pb-data:/pb/pb_data sc5-pocketbase:0.42.3
until curl -sf http://127.0.0.1:28090/api/health >/dev/null; do sleep 0.05; done
echo "ready after $(( ($(date +%s%N)-t0)/1000000 )) ms"
docker logs sc5-pbوالمخرج سوف يكون كما يلي:
ready after 1230 ms
2026/11/19 20:53:08 Server started at http://0.0.0.0:8090
> Dashboard: http://0.0.0.0:8090/_/
> REST API: http://0.0.0.0:8090/api/
(!) Launch the URL below in the browser if it hasn't been open already to create your first superuser account:
http://0.0.0.0:8090/_/#/pbinstall/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2xs…
(you can also create your first superuser by running: /pb/pocketbase superuser upsert EMAIL PASS)واستغرق البناء 11 ثانية، وحجم ال Image الناتجة 86.8 ميجابايت، منها 33.5 للملف التنفيذي، والباقي Alpine وطبقة الملف المضغوط. والجاهزية بعد 1.2 ثانية من أمر docker run بما فيها إنشاء ال Container، وعندما أوقفناه وشغلناه ثلاث مرات كانت الأرقام 1093 و942 و1477 مللي ثانية.
ولاحظ الرابط الذي يبدأ ب pbinstall، فهو توكن مؤقت يسمح لمن يفتحه بإنشاء أول مشرف Superuser للنظام، أي أن أول من يفتح هذا الرابط يملك السيرفر، ولهذا ربطنا المنفذ على 127.0.0.1 فقط، والأفضل ألا تعتمد على الرابط أصلاً، وإنما تنشئ المشرف من سطر الأوامر قبل أن تفتح المنفذ للعالم:
docker exec sc5-pb /pb/pocketbase superuser upsert [email protected] 'Lab-Admin-2026!'Successfully saved superuser "[email protected]"!/pb/pocketbase يتحول إلى C:/Program Files/Git/pb/pocketbase ويفشل الأمر بخطأ no such file or directory، والسبب أن Git Bash يحول المسارات التي تبدأ بشرطة مائلة، والحل أن تضبط MSYS_NO_PATHCONV=1 قبل الأمر، وقد وقعنا في هذا الخطأ أول مرة.ما الذي يوجد في pb_data؟
docker exec sc5-pb ls -la /pb/pb_datadrwxr-xr-x 2 root root 4096 Nov 19 20:53 .notify
-rw-r--r-- 1 root root 4096 Nov 19 20:53 auxiliary.db
-rw-r--r-- 1 root root 32768 Nov 19 20:53 auxiliary.db-shm
-rw-r--r-- 1 root root 45352 Nov 19 20:53 auxiliary.db-wal
-rw-r--r-- 1 root root 4096 Nov 19 20:53 data.db
-rw-r--r-- 1 root root 32768 Nov 19 20:53 data.db-shm
-rw-r--r-- 1 root root 280192 Nov 19 20:53 data.db-wal
-rw-r--r-- 1 root root 803467 Nov 19 20:53 types.d.tsوالملفات التي تنتهي ب -wal و-shm جزء من قاعدة البيانات وليست ملفات مؤقتة، فالكتابات الجديدة تذهب أولاً إلى ملف ال WAL ثم تنقل إلى الملف الرئيسي على دفعات، ولذلك لا تقم بنسخ data.db وحده بأمر cp والسيرفر يعمل، والسبب أن النسخة قد تفقد آخر الكتابات أو تخرج تالفة، والطرق الصحيحة للنسخ في قسم النسخ الاحتياطي. أما types.d.ts فهو ملف تعريفات TypeScript يولده PocketBase ليكمل محرر الكود أسماء الدوال عند كتابة ال Hooks.
المجموعات والحقول من ملف ترحيل Migration
المجموعة Collection في PocketBase هي جدول في SQLite مع وصف لحقوله وقواعد الوصول إليه، وتستطيع أن تنشئها من اللوحة بالضغط، وهذا مريح في التجربة الأولى، لكنه غير مناسب لمشروع حقيقي، والسبب أن ما تفعله في اللوحة على جهازك لا ينتقل إلى السيرفر إلا إذا كررته يدوياً، فتختلف البيئتان مع الوقت. والحل الأنسب هو ملفات الترحيل في المجلد pb_migrations، فينفذها PocketBase عند التشغيل بالترتيب ويسجل ما نفذه، كما في توثيق الترحيل بلغة JavaScript، وتحفظها في Git مع بقية الكود. والملف التالي ينشئ مجموعة المهام لتطبيقنا:
/// <reference path="../pb_data/types.d.ts" />
// todos: every record belongs to the signed-in user who created it
migrate((app) => {
const users = app.findCollectionByNameOrId("users")
const todos = new Collection({
type: "base",
name: "todos",
listRule: "owner = @request.auth.id",
viewRule: "owner = @request.auth.id",
createRule: "@request.auth.id != '' && owner = @request.auth.id",
updateRule: "owner = @request.auth.id && (@request.body.owner:isset = false || @request.body.owner = @request.auth.id)",
deleteRule: "owner = @request.auth.id",
fields: [
{ type: "text", name: "title", required: true, min: 1, max: 200 },
{ type: "bool", name: "done" },
{ type: "relation", name: "owner", required: true, collectionId: users.id, maxSelect: 1, cascadeDelete: true },
{ type: "file", name: "attachment", maxSelect: 1, maxSize: 5242880, mimeTypes: ["text/plain", "image/png", "image/jpeg", "application/pdf"], protected: true },
{ type: "autodate", name: "created", onCreate: true },
{ type: "autodate", name: "updated", onCreate: true, onUpdate: true },
],
indexes: ["CREATE INDEX idx_todos_owner ON todos (owner)"],
})
app.save(todos)
}, (app) => {
app.delete(app.findCollectionByNameOrId("todos"))
})في الإعداد أعلاه لاحظ التالي:
- الدالة
migrateتأخذ دالتين، الأولى للتطبيق والثانية للتراجع Rollback، فإذا احتجت أن تعود عن الترحيل يعرف PocketBase كيف يحذف ما أنشأه. - الحقل
ownerعلاقة Relation بمجموعة المستخدمين، ومعهcascadeDelete، فإذا حذف مستخدم حذفت مهامه معه، وهذا ما تريده غالباً في تطبيق شخصي، ولا تريده في سجل فواتير مثلاً. - حقل الملف
attachmentمحدد بالحجم 5 ميجابايت وبأنواع محددة، وprotected: trueيعني أن الملف لا يفتح برابطه المباشر، وإنما يحتاج توكن ملف قصير المدة، كما سنرى في التطبيق. - الفهرس Index على
ownerمهم لأن كل قاعدة وصول عندنا تبحث بهذا الحقل، فبدونه تفحص SQLite الجدول كله مع كل طلب.
وعند التشغيل الأول نفذ PocketBase الملف، ونستطيع أن نرى النتيجة في القاعدة نفسها:
docker exec sc5-pb sqlite3 /pb/pb_data/data.db "select name,type from _collections order by created"_mfas|base
_otps|base
_externalAuths|base
_authOrigins|base
_superusers|auth
users|auth
todos|baseوالمجموعات التي تبدأ بشرطة سفلية مجموعات النظام، وفيها المشرفون والتوكنات المؤقتة OTP وربط الحسابات الخارجية، والمجموعة users تأتي جاهزة مع كل تثبيت جديد. والصورة التالية من لوحة الإدارة بعد تشغيل التطبيق في القسم التالي:

قواعد الوصول API Rules
لكل مجموعة خمس قواعد: للقائمة List، ولعرض سجل واحد View، وللإنشاء Create، وللتعديل Update، وللحذف Delete. والقاعدة جملة شرط بصيغة فلاتر PocketBase، وتشير إلى الطلب بالمتغير @request، وإلى حقول السجل بأسمائها، كما في توثيق القواعد والفلاتر. والقاعدة owner = @request.auth.id مثلاً لا ترفض الطلب، وإنما تضاف شرطاً إلى استعلام SQLite نفسه، فلا يعود من القاعدة إلا ما يملكه صاحب التوكن، وهذه الفكرة نفسها التي تقوم عليها سياسات الصفوف Row-Level Security في PostgreSQL، لكن مكتوبة في الواجهة بدل قاعدة البيانات.

ولاحظ قاعدة التعديل، فالشرط الأول يكفي ليمنع عمر من تعديل مهمة سارة، لكنه لا يمنع سارة من أن تنقل مهمتها إلى عمر بتغيير الحقل owner، فتظهر في قائمته مهمة لم ينشئها، ولذلك أضفنا الشرط الثاني: إما ألا يرسل الطلب حقل owner أصلاً، وإما أن يرسله بقيمة صاحب التوكن نفسه. وهذا النوع من الثغرات لا يظهر في التطبيق أبداً، لأن الواجهة لا تعرض حقل المالك للتعديل، لكن أي شخص يستطيع أن يرسل الطلب بنفسه خارج الواجهة.
القاعدة الفارغة ليست القاعدة غير الموجودة
هذه أهم نقطة في القسم كله. فللقاعدة ثلاث حالات: null أي لا توجد قاعدة، وهذا يعني أن المشرفين فقط يستطيعون العملية، وهي القيمة التي يضعها زر «Set superusers only»، والنص الفارغ "" ويعني أن العملية مسموحة للجميع بلا أي شرط، حتى الزائر غير المسجل، والحالة الثالثة شرط مثل الذي كتبناه. والفرق بين الأولى والثانية علامتا تنصيص فقط، والنتيجة عكسها تماماً، فلنجرب ذلك على مجموعة المهام بعد أن أضاف التطبيق ثلاث مهام لمستخدمين اثنين، ونطلب القائمة دون أي توكن:
B=http://127.0.0.1:28090
# T = a superuser token from /api/collections/_superusers/auth-with-password
curl -s -X PATCH $B/api/collections/todos -H "Authorization: $T" -H 'content-type: application/json' -d '{"listRule":null}'
curl -s "$B/api/collections/todos/records"
curl -s -X PATCH $B/api/collections/todos -H "Authorization: $T" -H 'content-type: application/json' -d '{"listRule":""}'
curl -s "$B/api/collections/todos/records?fields=title,owner"والمخرج سوف يكون كما يلي:
--- rule = null (superusers only)
{"data":{},"message":"Only superusers can perform this action.","status":403}
--- rule = "" (everyone)
{"items":[{"owner":"u8cxrj92l285ywj","title":"خطة الإطلاق"},{"title":"موردون","owner":"u8cxrj92l285ywj"},{"owner":"kx29k9gbcoffrfo","title":"ملاحظة عمر"}],"page":1,"perPage":30,"totalItems":3,"totalPages":1}فمع القاعدة الفارغة حصل زائر مجهول على مهام المستخدمين جميعاً ومعرفاتهم، دون أي تسجيل دخول، والصورة التالية تلخص الحالات الثلاث كما ظهرت في المختبر:

لغة القواعد أبعد من مقارنة المالك
القاعدة التي استخدمناها أبسط ما يمكن، لكن لغة الفلاتر تسمح بأكثر من ذلك بكثير، وهذا ما تحتاجه عندما يكبر التطبيق من «كل مستخدم يرى بياناته» إلى «أعضاء الفريق يرون بيانات فريقهم». ففي القاعدة تستطيع أن تشير إلى أربعة مصادر: حقول السجل نفسه بأسمائها، وطلب المستخدم عبر @request.auth للمستخدم الحالي و@request.body لما أرسله و@request.query لمعاملات الرابط و@request.headers للترويسات، ومجموعة أخرى كاملة عبر @collection.اسم_المجموعة، وحقول السجلات المرتبطة عبر النقطة، مثل project.members.id. والعمليات المتاحة هي المقارنات المعروفة، ومعها ~ للبحث بجزء من النص، والعمليات التي تبدأ بعلامة الاستفهام مثل ?= وتعني «أي عنصر في القائمة يساوي»، وهذه هي المفيدة مع حقول العلاقات المتعددة. ولنأخذ مثالاً: لو كانت كل مهمة تتبع مشروعاً، ولكل مشروع قائمة أعضاء، فقاعدة القائمة تصبح:
project.members.id ?= @request.auth.idأي أن المستخدم يرى المهمة إذا كان أحد أعضاء مشروعها، وهذا الشرط يتحول عند التنفيذ إلى ربط Join بين الجداول في SQLite، فضع فهرساً على حقل العلاقة كما فعلنا مع owner. ولاحظ أن @request.body لا يكون موثوقاً إلا في قواعد الإنشاء والتعديل، لأنه ما أرسله المستخدم نفسه، ولذلك استخدمناه لمنع تغيير المالك وليس لتحديده، والمعدل :isset يفرق بين حقل لم يرسل أصلاً وحقل أرسل فارغاً. وقاعدة واحدة طويلة يصعب اختبارها، فإذا وجدت نفسك تكتب سطراً من ثلاثة شروط مركبة، فانقل جزءاً من المنطق إلى دالة خاصة في pb_hooks واجعل القاعدة بسيطة.
تطبيق صغير كامل: المصادقة والقواعد والملف والتحديث الفوري
الآن سوف نبني تطبيق مهام صغيراً بمكتبة PocketBase JavaScript SDK بالإصدار 0.29.0، ونشغله ب Node.js 22 داخل Container على الشبكة نفسها، وهو يمثل ما يفعله تطبيق الويب أو الجوال تماماً، فلا يحمل أي مفتاح سري، وإنما يسجل كل مستخدم دخوله ويعمل بتوكنه:
// A small todo app against our PocketBase: auth, API rules, realtime, a protected file, a hook and a custom route
import PocketBase from 'pocketbase'
const URL = process.env.PB_URL ?? 'http://127.0.0.1:28090'
const sleep = (ms) => new Promise(r => setTimeout(r, ms))
const err = (e) => `${e.status} ${e.response?.message ?? e.message}`
// 1) two users sign up, then sign in; each client keeps its own token
const sara = new PocketBase(URL), omar = new PocketBase(URL)
for (const [pb, email] of [[sara, '[email protected]'], [omar, '[email protected]']]) {
await pb.collection('users').create({ email, password: 'Lab-Pass-2026!', passwordConfirm: 'Lab-Pass-2026!' })
await pb.collection('users').authWithPassword(email, 'Lab-Pass-2026!')
}
const saraId = sara.authStore.record.id, omarId = omar.authStore.record.id
console.log('signup sara:', saraId, ' omar:', omarId)
// 2) realtime: omar subscribes to every change on todos
const events = []
await omar.collection('todos').subscribe('*', (e) => events.push(`${e.action} ${e.record.title}`))
console.log('realtime omar subscribed, clientId:', omar.realtime.clientId)
// 3) each user writes todos; sara attaches a file to hers
await sara.collection('todos').create({ title: ' خطة الإطلاق ', owner: saraId,
attachment: new File(['نراجع الخطة يوم الأحد'], 'plan.txt', { type: 'text/plain' }) })
await sara.collection('todos').create({ title: 'موردون', owner: saraId })
await omar.collection('todos').create({ title: 'ملاحظة عمر', owner: omarId })
await sleep(800)
const sTodos = await sara.collection('todos').getFullList({ sort: 'created' })
const oTodos = await omar.collection('todos').getFullList()
console.log('list sara sees:', sTodos.map(t => t.title))
console.log('list omar sees:', oTodos.map(t => t.title))
console.log('realtime omar received:', events)
// 4) omar tries sara's todo, then tries to write as sara, an anonymous visitor lists, and an empty title
const target = sTodos[0].id
await omar.collection('todos').update(target, { title: 'hacked' }).catch(e => console.log('update omar on sara todo ->', err(e)))
await omar.collection('todos').create({ title: 'forged', owner: saraId }).catch(e => console.log('create omar as sara ->', err(e)))
const anon = await new PocketBase(URL).collection('todos').getList(1, 20)
console.log('list anonymous ->', anon.totalItems, 'items')
await sara.collection('todos').create({ title: ' ', owner: saraId }).catch(e => console.log('create empty title ->', err(e)))
// 5) the protected file: a short-lived file token for sara, nothing for omar
const rec = sTodos[0]
const plain = sara.files.getURL(rec, rec.attachment)
console.log('file without token ->', (await fetch(plain)).status)
const token = await sara.files.getToken()
const res = await fetch(sara.files.getURL(rec, rec.attachment, { token }))
console.log('file sara with token ->', res.status, await res.text())
const otoken = await omar.files.getToken()
console.log('file omar with his token ->', (await fetch(omar.files.getURL(rec, rec.attachment, { token: otoken }))).status)
// 6) the custom route from pb_hooks
console.log('route sara /api/my-stats ->', await sara.send('/api/my-stats', {}))
const r = await fetch(`${URL}/api/my-stats`)
console.log('route without login ->', r.status)
await omar.collection('todos').unsubscribe()
process.exit(0)docker run --rm --network sc5-net -v "$PWD/client:/app" -w /app node:22-alpine \
sh -c 'npm i --silent; PB_URL=http://sc5-pb:8090 node --experimental-eventsource app.mjs'والمخرج سوف يكون كما يلي:
signup sara: u8cxrj92l285ywj omar: kx29k9gbcoffrfo
(node:1) [UNDICI-ES] Warning: EventSource is experimental, expect them to change at any time.
realtime omar subscribed, clientId: 2DI0Tk6nOYQHKlgwf5vLwP0dyAysrp3zRWXNktt9
list sara sees: [ 'خطة الإطلاق', 'موردون' ]
list omar sees: [ 'ملاحظة عمر' ]
realtime omar received: [ 'create ملاحظة عمر' ]
update omar on sara todo -> 404 The requested resource wasn't found.
create omar as sara -> 400 Failed to create record.
list anonymous -> 0 items
create empty title -> 400 Title is empty.
file without token -> 404
file sara with token -> 200 نراجع الخطة يوم الأحد
file omar with his token -> 404
route sara /api/my-stats -> { user: '[email protected]', todos: 2, done: 0 }
route without login -> 401في المخرج أعلاه لاحظ التالي:
- الاستعلام
getFullList()لا يحمل أي شرط، ومع ذلك رأى كل مستخدم مهامه فقط، فالشرط في قاعدة القائمة على السيرفر، وهذا هو المعنى العملي لكون القاعدة جزءاً من الاستعلام. - محاولة عمر تعديل مهمة سارة ردت ب 404 وليس 403، والسبب أن قاعدة التعديل تخفي السجل عنه أصلاً، فلا يعرف حتى أنه موجود، وهذا أفضل من رد يؤكد له وجود المعرف.
- محاولة الإنشاء باسم سارة ردت ب 400 مع رسالة عامة، فقاعدة الإنشاء رفضت أن يكون
ownerغير صاحب التوكن. - العنوان
' خطة الإطلاق 'حفظ دون المسافات، والعنوان المكون من مسافات فقط رفض برسالةTitle is empty.، وكلاهما من الدالة الخاصة التي سنشرحها بعد قليل وليس من التطبيق. - Node.js 22 يحتاج الخيار
--experimental-eventsourceلأن المكتبة تستخدم EventSource للتحديث الفوري، ويظهر معه تحذير في السطر الثاني، أما المتصفح فيملك EventSource أصلاً، وفي React Native تحتاج مكتبة تضيفه، كما يذكر ملف README للمكتبة.
الملف المحمي Protected File والتوكن قصير المدة
الرابط المباشر للملف المحمي رد ب 404، ومعنى ذلك أن من ينسخ الرابط من التطبيق ويرسله لغيره لا يفتح شيئاً، والطريقة الصحيحة أن يطلب التطبيق توكن ملف File Token من files.getToken() ثم يضيفه إلى الرابط، وهذا التوكن قصير المدة ومرتبط بصاحبه، فعندما استخدم عمر توكنه هو على ملف سارة رد السيرفر ب 404، لأن قاعدة العرض View Rule للمجموعة تطبق على الملف أيضاً. ولا تقم بجعل حقل الملف غير محمي في تطبيق فيه مستندات خاصة، والسبب أن أسماء الملفات في PocketBase عشوائية لكنها تظهر في الرد وفي سجلات المتصفح، وأي رابط يتسرب يبقى صالحاً للأبد.
المصادقة: ما الذي يقدمه غير كلمة المرور؟
مجموعة المستخدمين في PocketBase تدعم من الإعدادات نفسها عدة طرق للدخول، كما في توثيق المصادقة: البريد وكلمة المرور كما فعلنا، ورمز مؤقت بالبريد One-Time Password، والمصادقة متعددة العوامل Multi-Factor Authentication التي تطلب طريقتين معاً، والدخول بحسابات خارجية عبر OAuth2 مثل Google وApple وGitHub، وفكرة هذا البروتوكول في شرح OAuth وOpenID Connect. والتوكن الذي يعود من الدخول توكن JWT موقع بسر خاص بالمجموعة، وفي المختبر كان صالحاً خمسة أيام بحسب الحقل exp فيه، والمكتبة تجدده بالطلب authRefresh() قبل أن ينتهي. وقد يتساءل البعض: إذا سرق توكن، فكيف أبطله قبل انتهائه؟ والإجابة أن تغيير كلمة مرور المستخدم يغير مفتاح التوكن الخاص به فتبطل كل توكناته القديمة، ومنذ الإصدار v0.42.0 أضاف المشروع طبقة عامة ترفض ب 401 أي ترويسة Authorization منتهية أو غير معروفة، فيعرف التطبيق فوراً أن الجلسة انتهت بدل أن يكمل كزائر. والمصادقة متعددة العوامل عند المشرفين أولى منها عند المستخدمين، لأن توكن مشرف واحد يتجاوز كل القواعد، وفكرتها في المصادقة الثنائية 2FA وMFA.
التحديث الفوري من الداخل: SSE واشتراك بالتوكن
عمر اشترك في كل تغيير على مجموعة المهام، ومع ذلك وصله حدث مهمته فقط، فكيف عرف السيرفر ذلك؟ والإجابة في توثيق Realtime API، ونستطيع أن نراها بأمر curl دون أي مكتبة. أولاً نفتح اتصال SSE، فيرد السيرفر بمعرف للعميل Client ID، ثم نرسل طلب الاشتراك ومعه هذا المعرف وتوكن المستخدم، ثم ننشئ مهمة بتوكن عمر:
B=http://127.0.0.1:28090
curl -sN --max-time 6 $B/api/realtime > /tmp/sse.txt &
# CID from the first event, TOK and OID from auth-with-password for omar
curl -s -X POST $B/api/realtime -H "Authorization: $TOK" -H 'content-type: application/json' \
-d "{\"clientId\":\"$CID\",\"subscriptions\":[\"todos\"]}" -w "subscribe %{http_code}\n"
curl -s -X POST $B/api/collections/todos/records -H "Authorization: $TOK" -H 'content-type: application/json' \
-d "{\"title\":\"from curl\",\"owner\":\"$OID\"}" -o /dev/null -w "create %{http_code}\n"
cat /tmp/sse.txtsubscribe 204
create 200
id:le1zTKcQifJ9sfuVqDwEGbmH6XFon5ga5vHOgXz2
event:PB_CONNECT
data:{"clientId":"le1zTKcQifJ9sfuVqDwEGbmH6XFon5ga5vHOgXz2"}
id:le1zTKcQifJ9sfuVqDwEGbmH6XFon5ga5vHOgXz2
event:todos
data:{"record":{"attachment":"","collectionId":"pbc_113564862","collectionName":"todos","created":"2026-11-19 21:12:41.983Z","done":false,"id":"kkswvv08vkc7wuk","owner":"kx29k9gbcoffrfo","title":"from curl","updated":"2026-11-19 21:12:41.983Z"},"action":"create"}فالاتصال المفتوح نفسه لا يحمل أي توكن، والتوكن يأتي مع طلب الاشتراك، وهنا يربط السيرفر هذا العميل بمستخدم معين، ثم عند كل تغيير في المجموعة يطبق قاعدة القائمة والعرض على كل مشترك على حدة، ويكتب الحدث في اتصال من يسمح له فقط، والصورة التالية تبين الخطوات:

ويذكر سجل التغييرات أن اتصالات Realtime أصبحت منذ الإصدار v0.38.2 تنتهي بعد 30 دقيقة على الأكثر حتى لو كانت نشطة، فيتغير معرف العميل عند إعادة الاتصال، والمكتبة تعيد الاتصال والاشتراك بنفسها، لكن إذا كتبت عميلاً خاصاً بلغة أخرى فعليك أن تعالج ذلك. ولا تقم بالاعتماد على التحديث الفوري وحده لبيانات لا تحتمل الضياع، والسبب أن الحدث الذي يقع أثناء انقطاع الاتصال لا يعاد إرساله، فاقرأ القائمة من الواجهة البرمجية عند فتح الشاشة وعند عودة الاتصال، واجعل الأحداث لتحديث الشاشة بينهما.
ماذا يحدث مع 200 مشترك؟
بما أن كل حدث يمر على كل مشترك، فقد أردنا أن نعرف كلفة ذلك بالأرقام، فكتبنا سكربتاً يفتح عدداً من الاشتراكات للمستخدمة نفسها، ثم يضيف 2,000 مهمة على دفعات من 20 طلباً متوازياً:
// Light load: SUBS realtime subscribers (default 200) for one user, then 2,000 todo creates (20 at a time)
import PocketBase from "pocketbase"
const SUBS = Number(process.env.SUBS ?? 200)
const URL = process.env.PB_URL
const subs = []
for (let i = 0; i < Math.max(SUBS, 1); i++) {
const pb = new PocketBase(URL)
await pb.collection('users').authWithPassword('[email protected]', 'Lab-Pass-2026!')
if (SUBS > 0) await pb.collection("todos").subscribe("*", () => {})
subs.push(pb)
}
const pb = subs[0], owner = pb.authStore.record.id
pb.autoCancellation(false) // the SDK cancels a pending request when the same one starts again; parallel creates need this off
const t0 = Date.now()
for (let i = 0; i < 2000; i += 20)
await Promise.all(Array.from({ length: 20 }, (_, j) => pb.collection('todos').create({ title: `todo ${i + j}`, owner })))
console.log(SUBS, "subscribers, 2000 creates in", Date.now() - t0, 'ms')
await new Promise(r => setTimeout(r, Number(process.env.HOLD ?? 0)))
process.exit(0)وفي التشغيل الأول لم يكن السطر autoCancellation(false) موجوداً، فتوقف السكربت في أول دفعة بهذا الخطأ:
ClientResponseError 0: The request was aborted (most likely autocancelled; you can find more info in https://ganigeorgiev.com/pocketbase/js-sdk#auto-cancellation).والسبب أن المكتبة تلغي تلقائياً الطلب المعلق إذا بدأ طلب مطابق له من النسخة نفسها، وهذا مفيد في واجهة يكتب فيها المستخدم في مربع بحث فتتابع الطلبات، لكنه يلغي الطلبات المتوازية المقصودة، فإذا كان كودك يرسل عدة طلبات متشابهة معاً فأوقف هذه الميزة للنسخة كلها، أو أعط كل طلب مفتاحاً خاصاً requestKey. وبعد الإصلاح شغلنا السكربت مرتين:
0 subscribers, 2000 creates in 7672 ms
mem 110.3MiB / 31.29GiB
200 subscribers, 2000 creates in 66715 ms
mem 141.5MiB / 31.29GiB
فبدون مشتركين أضاف PocketBase قرابة 260 مهمة في الثانية، ومع 200 مشترك نزل الرقم إلى قرابة 30، وارتفع استخدام المعالج CPU في docker stats إلى ما بين 270% و340% طوال التجربة. ولاحظ أن القياس على Docker Desktop مع WSL2 في جهاز تطوير، فلا تعتبر الأرقام سقفاً لسيرفر حقيقي، لكن النسبة بين الحالتين هي الدرس: تصميم التطبيق بحيث يشترك كل مستخدم فيما يخصه فقط، أي في سجل محدد أو بفلتر، أرخص بكثير من اشتراك الجميع في المجموعة كلها ثم ترك السيرفر يفرز. والتوثيق نفسه في صفحة الإنتاج ينبه إلى رفع حد الملفات المفتوحة Open Files إذا كثرت الاتصالات، لأن كل اتصال SSE ملف مفتوح في نظام التشغيل.
الدوال الخاصة Hooks بلغة JavaScript
القواعد تكفي للصلاحيات، لكن كل تطبيق يحتاج منطقاً لا يعبر عنه شرط: تنظيف مدخل، أو إرسال إشعار بعد حدث، أو مسار خاص يحسب شيئاً. وفي PocketBase تكتب ذلك في ملفات تنتهي ب .pb.js داخل المجلد pb_hooks، كما في نظرة عامة على JavaScript، والملف التالي هو الذي عمل مع التطبيق:
/// <reference path="../pb_data/types.d.ts" />
// 1) before a todo is saved from the API: trim the title and refuse a title that is only spaces
onRecordCreateRequest((e) => {
const title = (e.record.get("title") || "").trim()
if (!title) throw new BadRequestError("title is empty")
e.record.set("title", title)
e.next()
}, "todos")
// 2) after a todo is created: write one line to the app log
onRecordAfterCreateSuccess((e) => {
e.app.logger().info("todo created", "id", e.record.id, "owner", e.record.get("owner"))
e.next()
}, "todos")
// 3) a custom route: the caller's own counts, signed-in users only
routerAdd("GET", "/api/my-stats", (e) => {
const uid = e.auth.id
const all = $app.countRecords("todos", $dbx.hashExp({ owner: uid }))
const done = $app.countRecords("todos", $dbx.hashExp({ owner: uid, done: true }))
return e.json(200, { user: e.auth.get("email"), todos: all, done: done })
}, $apis.requireAuth())
// 4) a scheduled job: every day at 03:00 delete finished todos older than 30 days
cronAdd("purge-done", "0 3 * * *", () => {
const old = $app.findRecordsByFilter("todos", "done = true && updated < {:limit}", "", 500, 0,
{ limit: new DateTime().addDate(0, 0, -30).string() })
old.forEach((r) => $app.delete(r))
$app.logger().info("purge-done", "deleted", old.length)
})في الإعداد أعلاه لاحظ التالي:
onRecordCreateRequestيعمل قبل الحفظ ولطلبات الواجهة البرمجية فقط، فإذا أنشأت سجلاً من دالة أخرى أو من ترحيل لا يمر به، أماonRecordAfterCreateSuccessفيعمل بعد نجاح الحفظ فعلاً، وهو المكان المناسب للإشعارات، والسبب أن الحدث قبل الحفظ قد يفشل بعده الحفظ نفسه.- كل دالة تنادي
e.next()، ونسيانه يوقف السلسلة فلا يحفظ السجل ولا يعمل ما بعدها. $apis.requireAuth()يرفض الطلب دون توكن قبل أن يصل إلى الدالة، ولذلك رد المسار ب 401 للزائر في مخرج التطبيق.- العد في المسار الخاص يمر عبر
$appمباشرة، أي بصلاحيات النظام وليس بقواعد المجموعة، فالشرطowner: uidهنا هو الحماية الوحيدة، ولا تقم بأخذ معرف المستخدم من معاملات الطلب في مثل هذه الدوال، وإنما منe.authفقط. - عند تعديل أي ملف في
pb_hooksيعيد PocketBase تشغيل نفسه تلقائياً على Linux، وقد رأينا ذلك في السجل، وهذا مريح في التطوير، لكن في الإنتاج يعني أن رفع ملف بخطأ يوقف الخدمة لحظة.
والسجل الذي كتبته الدالة الثانية نقرؤه من قاعدة السجلات:
docker exec sc5-pb sqlite3 /pb/pb_data/auxiliary.db \
"select level, message, json_extract(data,'$.id') from _logs where message like 'todo%' order by created"0|todo created|oab9e00149szhoa
0|todo created|zrx6ukxr5n0pbwx
0|todo created|yb1g8k7yvpl8v4oالخطأ الذي يقع فيه الجميع أول مرة
المحرك المدمج goja ليس Node.js ولا متصفحاً، فلا توجد فيه وحدات fs وfetch وBuffer، وتستبدلها دوال PocketBase مثل $http.send و$os، والوحدات الخارجية تحمل ب require بصيغة CommonJS فقط. والفرق الأهم أن كل دالة تعمل في سياق معزول، فالمتغير الذي تعرفه خارجها غير موجود داخلها، ولنجرب ذلك بملف صغير:
const greeting = "hello"
routerAdd("GET", "/api/scope-test", (e) => {
return e.json(200, { msg: greeting })
})curl -s http://127.0.0.1:28090/api/scope-test
docker exec sc5-pb sqlite3 /pb/pb_data/auxiliary.db \
"select level, message, json_extract(data,'$.error') from _logs where json_extract(data,'$.url') like '%scope%'"{"data":{},"message":"Something went wrong while processing your request.","status":400}
8|GET /api/scope-test|ReferenceError: greeting is not defined at /pb.js:2:29(5)فالمستخدم يرى رسالة عامة، والسبب الحقيقي في السجل فقط: ReferenceError. والحل كما يذكر التوثيق أن تضع القيم المشتركة في ملف مستقل وتحمله داخل الدالة ب require(`${__hooks}/config.js`). ويذكر التوثيق أيضاً أن الملف التنفيذي يجهز مسبقاً 15 نسخة من المحرك ليبقى الأداء قريباً من كود Go، وإذا احتجت أكثر من ذلك، كمكتبة تشفير لا يوفرها المحرك، فالخيار هو استخدام PocketBase كإطار عمل Framework بلغة Go وبناء ملفك التنفيذي بنفسك.
المهام المجدولة Cron
الدالة cronAdd سجلت مهمة يومية تحذف المهام المنتهية الأقدم من 30 يوماً، وصيغة الجدولة هي صيغة Cron المعروفة، كما في توثيق الجدولة، ومعناها مشروح في المهام المجدولة: Cron أم systemd timers. والصورة التالية من صفحة Crons في اللوحة، وفيها مهمتنا بجانب مهام النظام نفسه، ومنها تنظيف السجلات كل ست ساعات:

ولاحظ أن المهام المجدولة تعمل داخل العملية نفسها، فإذا كان السيرفر متوقفاً في الثالثة فجراً فلن تعمل المهمة حتى اليوم التالي، ولا توجد طابور Queue يعيد المحاولة، فاجعل المهمة قابلة للتكرار دون ضرر، كما فعلنا بالحذف بشرط التاريخ.
رسالة الخطأ التي ظهرت في السجلات
عندما فتحنا صفحة السجلات في اللوحة وجدنا تحذيراً يتكرر مع كل دخول للمشرف:
![صفحة Logs في PocketBase وفيها تحذير WARN بالرسالة [recordAuthResponse] Failed to send login alert مع error: exit status 1، بجانب طلبات POST /api/collections/_superusers/auth-with-password](https://arabroot.io/content/images/2026/11/pocketbase-07-login-alert-log.webp)
والسبب أن PocketBase يرسل تنبيهاً بالبريد عند الدخول من مكان جديد، ويستخدم افتراضياً الأمر sendmail في نظام التشغيل، وهذا الأمر غير موجود في Alpine أصلاً، فيفشل بالرمز 1، والأمر نفسه سوف يحدث لرسائل استعادة كلمة المرور وتأكيد البريد، وقد رأيناه في مقال الانتقال من Firebase عندما طلبنا رابط استعادة لمستخدم مستورد. وصفحة الإنتاج في التوثيق تضع ضبط سيرفر SMTP في أول التوصيات، والسبب أن sendmail حتى لو وجد فرسائله تذهب غالباً إلى البريد المزعج Spam. فاضبطه من Settings ثم Mail settings قبل أن يعتمد عليه أي مستخدم، وإذا لم يكن عندك سيرفر بريد فقد شرحنا البريد التفاعلي Transactional Email والإرسال عبر Amazon SES.
النسخ الاحتياطي والاستعادة
النسخ الاحتياطي هنا أبسط منه في أي منصة أخرى، فكل الحالة في مجلد واحد، ومع ذلك فيه ثلاث طرق، ولكل منها مكانها.
الطريقة الأولى هي النسخ المدمج، من اللوحة أو من الواجهة البرمجية، وهو ينشئ ملف ZIP فيه قاعدة البيانات وقاعدة السجلات والملفات المرفوعة محلياً:
curl -s -X POST $B/api/backups -H "Authorization: $T" -H 'content-type: application/json' -d '{"name":"lab_before_change.zip"}' -w "%{http_code}\n"
curl -s $B/api/backups -H "Authorization: $T"
docker exec sc5-pb unzip -l /pb/pb_data/backups/lab_before_change.zip204
[{"modified":"2026-11-19 20:55:24.978Z","key":"lab_before_change.zip","size":232268}]
Archive: /pb/pb_data/backups/lab_before_change.zip
Length Date Time Name
--------- ---------- ----- ----
172032 2026-11-19 20:55 data.db
36864 2026-11-19 20:55 auxiliary.db
39 2026-11-19 20:54 storage/pbc_113564862/oab9e00149szhoa/plan_z0lbo4ey7e.txt
239 2026-11-19 20:54 storage/pbc_113564862/oab9e00149szhoa/plan_z0lbo4ey7e.txt.attrs
803467 2026-11-19 20:53 types.d.ts
--------- -------
1012641 5 filesثم افتعلنا خطأ عن قصد، فحذفنا كل المهام مباشرة من SQLite كما لو أن سكربتاً خاطئاً عمل على القاعدة، ثم استعدنا النسخة من الواجهة البرمجية:
docker exec sc5-pb sqlite3 /pb/pb_data/data.db "delete from todos; select count(*) from todos;"
curl -s -X POST $B/api/backups/lab_before_change.zip/restore -H "Authorization: $T" -w "%{http_code}\n"
docker exec sc5-pb sqlite3 /pb/pb_data/data.db "select count(*) from todos;"0
204
3ولاحظ أن الاستعادة أعادت تشغيل PocketBase نفسه داخل ال Container، فظهر في السجل سطر Server started جديد بينما بقي ال Container يعمل دون إعادة تشغيل، أي أن هناك انقطاعاً لثوان، فلا تقم بالاستعادة على سيرفر الإنتاج والمستخدمون يعملون إلا وأنت تعرف أن كل ما كتب بعد النسخة سيضيع. والصورة التالية من صفحة النسخ في اللوحة:

والطريقة الثانية هي أمر .backup في SQLite، وهو يأخذ نسخة متسقة من قاعدة تعمل دون إيقافها:
docker exec sc5-pb sh -c 'sqlite3 /pb/pb_data/data.db ".backup /tmp/data-copy.db" && sqlite3 /tmp/data-copy.db "pragma integrity_check; select count(*) from todos; select count(*) from users;"'ok
3
2والطريقة الثالثة هي نسخ المجلد كاملاً بعد إيقاف الخدمة، وهي أبسطها وأضمنها لكنها تحتاج نافذة توقف. ويذكر التوثيق أن النسخ المدمج يبطئ الطلبات أثناء عمله، وأنه قد يصبح بطيئاً جداً مع مجلد بيانات أكبر من 5 جيجابايت، وينصح عندها بالطريقة الثانية مع rsync للملفات. وأياً كانت الطريقة فالنسخة على القرص نفسه ليست نسخة احتياطية، فارفعها إلى مكان آخر، وخيار S3 في Backup options يفعل ذلك تلقائياً، والقاعدة العامة والاختبار الدوري للاستعادة في النسخ الاحتياطي بقاعدة 3-2-1 والنسخة خارج السيرفر.
دون Docker: خدمة systemd وأمر التحديث
شغلنا PocketBase في Docker لأن كل مختبراتنا هكذا، لكن الملف التنفيذي لا يحتاج Docker أصلاً، والتوثيق نفسه يقترح أن ترفعه إلى السيرفر وتشغله خدمة systemd، فتحصل على إعادة التشغيل التلقائية والسجلات من مكان واحد. والملف التالي مبني على مثال صفحة الإنتاج، مع مستخدم خاص بالخدمة بدل root، ومنفذ داخلي خلف Reverse Proxy:
[Unit]
Description=pocketbase
After=network-online.target
[Service]
Type=simple
User=pocketbase
Group=pocketbase
LimitNOFILE=4096
Restart=always
RestartSec=5s
WorkingDirectory=/opt/pocketbase
ExecStart=/opt/pocketbase/pocketbase serve --http=127.0.0.1:8090
[Install]
WantedBy=multi-user.targetفي الإعداد أعلاه لاحظ التالي:
- المستخدم
pocketbaseيملك المجلد/opt/pocketbaseفقط، فإذا وجد مهاجم ثغرة في الخدمة لم يملك السيرفر كله، ومثال التوثيق يعمل ب root ليستطيع أن يفتح المنفذين 80 و443 ويصدر شهادة Let's Encrypt بنفسه، وهذا خيار مريح لكنه أوسع صلاحية مما تحتاجه خلف Caddy. LimitNOFILEيرفع حد الملفات المفتوحة، وهو المهم مع اتصالات SSE كما رأينا.- السجلات تذهب إلى journald، وتقرؤها ب
journalctl -u pocketbase، كما شرحنا في الخدمات والسجلات مع systemd.
ولاحظ أن في الملف التنفيذي أمراً اسمه update ينزل آخر إصدار ويستبدل نفسه، وقد غير الإصدار v0.40.6 مصدر هذا الأمر من GitHub إلى الموقع الجديد. والأمر مريح، لكن مع مشروع قبل 1.0 لا تقم بتشغيله على سيرفر الإنتاج دون أن تقرأ سجل التغييرات وتأخذ نسخة احتياطية، والأفضل أن تثبت الإصدار كما فعلنا في Dockerfile، وتجرب الإصدار الجديد على نسخة من pb_data أولاً، لأن ملفات الترحيل في الإصدار الجديد قد تغير بنية الجداول ولا تعود عنها.
الذاكرة والزمن: ما قسناه في المختبر
| القياس | القيمة | ملاحظة |
|---|---|---|
| حجم الملف التنفيذي | 33.5 ميجابايت | للإصدار v0.42.3 على linux_amd64 |
| حجم Docker Image | 86.8 ميجابايت | Alpine 3.22 مع الملف والطبقة المضغوطة |
| البناء | 11 ثانية | تنزيل 12.8 ميجابايت وفك الضغط |
| من التشغيل حتى الجاهزية | 0.9 إلى 1.5 ثانية | أربع محاولات |
| الذاكرة دون ضغط | 19 إلى 26 ميجابايت | من docker stats |
| الذاكرة بعد 200 مشترك و4,000 إضافة | قرابة 140 ميجابايت | لم تعد إلى البداية فوراً |
| 2,000 إضافة دون مشتركين | 7.7 ثانية | قرابة 260 في الثانية |
| 2,000 إضافة مع 200 مشترك | 66.7 ثانية | قرابة 30 في الثانية |
وللمقارنة، استهلك Supabase المستضاف في دليله قرابة 1.2 جيجابايت للخدمات الإحدى عشرة دون ضغط، أي أن PocketBase أخف منه بقرابة خمسين مرة في الذاكرة، وهذا الفرق هو سبب وجوده، والمقارنة الكاملة بين الثلاثة بالتطبيق نفسه في مقال المقارنة ضمن هذه المرحلة.
حدود PocketBase بصراحة
كل ما سبق يبدو مغرياً، لكن الخفة لها ثمن، وهذه الحدود يجب أن تعرفها قبل أن تبني عليه:
- سيرفر واحد فقط: لا يوجد توسع أفقي Horizontal Scaling، فلا تستطيع أن تشغل نسختين خلف موزع حمل Load Balancer على قاعدة واحدة، والسبب أن SQLite ملف على قرص محلي، والتوسع الوحيد هو سيرفر أكبر.
- كاتب واحد في كل لحظة: SQLite تسمح بقراءات كثيرة متزامنة لكن بكتابة واحدة في كل لحظة، وهذا يكفي آلاف المستخدمين في تطبيق أغلبه قراءة، ولا يكفي تطبيقاً يكتب باستمرار من مصادر كثيرة.
- قبل الإصدار 1.0: التوافق غير مضمون بين الإصدارات، والانتقال من v0.22 إلى v0.23 مثلاً غير شكل ال Hooks كلها، ولهذا ما زال المشروع يصدر تحديثات أمنية لسلسلة v0.22 بجانب السلسلة الحالية.
- لا يوجد استيراد لكلمات مرور Firebase: PocketBase يحفظ كلمات المرور ب bcrypt فقط، فمن ينتقل من Firebase يحتاج أن يعيد مستخدموه تعيين كلمات مرورهم، وهذا ما اختبرناه في مقال الانتقال.
- التحديث الفوري يكلف مع كل مشترك: كما رأينا في الأرقام.
- الدوال ليست Node.js: مكتبات npm التي تعتمد على Node لا تعمل داخل ال Hooks.
- مشروع يعتمد على شخص واحد: وهذا ليس عيباً في الكود، لكنه خطر تشغيلي تحسبه، فإذا توقف التطوير يبقى عندك ملف تنفيذي يعمل وكود مفتوح، وبياناتك في SQLite التي تقرؤها أي أداة.
متى تصل إلى حد SQLite فعلاً؟
الحد الذي يذكره الجميع، أي «كاتب واحد في كل لحظة»، يبدو مخيفاً، لكن الرقم الذي قسناه يضعه في حجمه: 260 إضافة في الثانية على جهاز تطوير، مع فحص قاعدة وصول ودالة خاصة وسجل لكل إضافة. وتطبيق فيه عشرة آلاف مستخدم نشط يوماً، يضيف كل منهم عشرين سجلاً في اليوم، يكتب مئتي ألف سجل يومياً، أي أقل من ثلاثة في الثانية في المتوسط، وحتى لو تركزت في ساعتين فهي أقل من ثلاثين في الثانية. فالحد يأتي عادة من مكان آخر: من الاشتراكات الفورية كما رأينا، أو من استعلامات بطيئة بلا فهارس، أو من ملفات كبيرة ترفع وتصغر صورها على السيرفر نفسه. وعندما يأتي الحد فعلاً فخياراتك بالترتيب: فهارس أفضل، ثم سيرفر بمعالج أسرع وقرص NVMe، ثم نقل جزء من العمل كالملفات إلى S3، ثم الانتقال إلى منصة على PostgreSQL، وهذا الأخير هو الأصعب، فإذا كنت تعرف من البداية أن تطبيقك سيكتب كثيراً من مصادر كثيرة فابدأ بغير PocketBase.
متى يناسبك PocketBase، ومتى لا؟
| الحالة | القرار | والسبب |
|---|---|---|
| تطبيق داخلي لفريق أو نموذج أولي أو مشروع جانبي | PocketBase | تشغيل في دقيقة، وذاكرة بعشرات الميجابايت، ونسخ احتياطي بملف واحد |
| تطبيق جوال لمتجر صغير بآلاف المستخدمين وأغلبه قراءة | PocketBase على VPS واحد مع نسخ إلى S3 | SQLite تكفي القراءة الكثيرة، وسيرفر واحد جيد يكفي سنوات |
| بيانات علائقية وتقارير واستعلامات SQL معقدة | Supabase | PostgreSQL كاملة بدل SQLite |
| حاجة إلى توفر عال High Availability أو أكثر من سيرفر | Supabase أو Appwrite | PocketBase لا يعمل إلا على سيرفر واحد |
| انتقال من Firebase مع الحفاظ على كلمات المرور | Supabase أو Appwrite | كلاهما يقبل هاش scrypt الخاص ب Firebase |
| فريق يريد كتابة منطق كثير على السيرفر بمكتبات npm | Appwrite Functions أو سيرفر خاص بجانب PocketBase | ال Hooks تعمل على goja وليس Node.js |
قبل الإنتاج
- ضع PocketBase خلف Reverse Proxy بشهادة HTTPS، كما في تثبيت Caddy، وارفع مهلة القراءة كما في مثال التوثيق حتى لا تنقطع اتصالات SSE، واضبط ترويسات عنوان المستخدم User IP Proxy Headers في الإعدادات حتى تسجل السجلات عنوانه الحقيقي.
- أنشئ المشرف من سطر الأوامر، ولا تترك رابط
pbinstallلأول زائر. - اضبط SMTP قبل الإطلاق، واختبر رسالة استعادة كلمة المرور فعلاً.
- فعل محدد معدل الطلبات Rate Limiter المدمج منذ v0.23.0، والفكرة في تحديد معدل الطلبات.
- قيد دخول المشرفين بعناوين IP محددة، وهي ميزة أضيفت في v0.38.0، وفعل المصادقة متعددة العوامل MFA لمجموعة المشرفين.
- راجع كل قاعدة وصول، وابحث عن أي قاعدة فارغة، واختبر كل مجموعة بطلب دون توكن.
- جدول النسخ الاحتياطي إلى S3، وجرب الاستعادة على سيرفر آخر.
- ثبت رقم الإصدار في Dockerfile، واقرأ سجل التغييرات قبل كل تحديث، والسبب أن المشروع قبل 1.0.
- إذا كثرت الاتصالات فارفع حد الملفات المفتوحة
LimitNOFILEفي خدمة systemd أو في ال Container، وإذا كانت الذاكرة محدودة فاضبطGOMEMLIMITكما يذكر التوثيق.
أخطاء شائعة
- قاعدة فارغة بدل null: علامتا التنصيص تفتحان المجموعة للجميع.
- قاعدة تعديل لا تحمي حقل المالك: فينقل المستخدم سجلاته إلى غيره.
- نسخ data.db بأمر cp والسيرفر يعمل: فتضيع كتابات ال WAL أو تتلف النسخة.
- pb_data داخل ال Container دون Volume: فتضيع البيانات مع أول تحديث لل Image.
- متغير خارج الدالة في pb_hooks: فيظهر للمستخدم خطأ عام والسبب الحقيقي في السجل.
- طلبات متوازية متشابهة من المكتبة: فتلغيها ميزة الإلغاء التلقائي.
- الاعتماد على sendmail: فلا تصل رسائل الاستعادة والتنبيهات.
- اشتراك كل المستخدمين في المجموعة كلها: فيدفع السيرفر فحص القاعدة لكل مشترك مع كل حدث.
حذف المختبر
حذفنا ما أنشأناه فقط، بالاسم:
docker rm -f sc5-pb
docker volume rm sc5-pb-data
docker rmi sc5-pocketbase:0.42.3ولا تقم بتشغيل docker system prune على سيرفر عليه خدمات أخرى، والسبب أنه يحذف كل ما لا يعمل في تلك اللحظة ولو كان لمشروع آخر.
الخلاصة
وصلنا لنهاية الموضوع، وأهم ما فيه:
- PocketBase خلفية كاملة في ملف تنفيذي واحد فوق SQLite، وقسنا له Docker Image بحجم 86.8 ميجابايت وجاهزية في ثانية تقريباً وذاكرة بين 19 و26 ميجابايت دون ضغط.
- المستودع انتقل من GitHub إلى ganigeorgiev.com منذ v0.41.0، فانزل الإصدارات من الرابط الثابت الجديد، وتذكر أن المشروع قبل 1.0.
- القاعدة
nullتعني المشرفين فقط، والقاعدة الفارغة تعني الجميع، والشرط يضاف إلى الاستعلام نفسه، فاختبر كل مجموعة بطلب دون توكن. - الملفات الخاصة تحتاج
protected: trueوتوكن ملف قصير المدة. - التحديث الفوري عبر SSE، والقاعدة تطبق لكل مشترك مع كل حدث، ومع 200 مشترك نزل معدل الإضافة من 260 إلى 30 في الثانية.
- ال Hooks تعمل على goja وليس Node.js، وكل دالة في سياق معزول.
- اضبط SMTP، وانسخ احتياطياً إلى مكان آخر، واعرف أن PocketBase سيرفر واحد لا يتوسع أفقياً.
دليلما هو Backend as a Service؟ وما بديل كل خدمة في Firebaseما الذي يقدمه ال Backend الجاهز لتطبيقك، ولماذا تصبح قواعد الوصول هي الحارس الوحيد لبياناتك، وما البديل المفتوح لكل خدمة في Firebase.
دليلSupabase على سيرفرك: بديل Firebase فوق PostgreSQLكيف تثبت Supabase على سيرفرك وتبني عليه تطبيقاً صغيراً بمستخدمين وصلاحيات وملفات، وما الذي ينقص النسخة المستضافة عن السحابية.
دليلAppwrite على سيرفرك: Backend متكامل للويب والجوالكيف تثبت Appwrite على سيرفرك وتبني عليه جدولاً بصلاحيات على مستوى الصف ومجلد ملفات ودالة وتطبيق ويب، وما الثمن الحقيقي بالذاكرة والقرص.
دليلSupabase أم Appwrite أم PocketBase؟ مقارنة بالأرقامبنينا التطبيق نفسه على الأدوات الثلاث وقسنا الذاكرة والقرص والزمن والصلاحيات، لتختار الخلفية التي تناسب سيرفرك وفريقك.
دليلالانتقال من Firebase: البيانات والمستخدمون وكلمات المروركيف تنقل بيانات Firestore والمستخدمين بكلمات مرورهم القديمة من Firebase إلى Supabase وAppwrite وPocketBase، وتعيد كتابة القواعد دون أن تفتح بياناتك.سجل التحديثات
- 20 نوفمبر 2026: كتابة الدليل، وتنفيذ المختبر على PocketBase v0.42.3 ومكتبة pocketbase 0.29.0 مع Node.js 22.23 على Docker Engine 29.8.0.