عميل مزامنة ee-database - توثيق Entity Enricher

عميل مزامنة ee-database

عميل التطبيق مفتوح المصدر لـقواعد بيانات المخطط. شغّله بجانب قاعدة PostgreSQL الخاصة بك، واقترن مرة واحدة، وسيبقي تلك القاعدة متقاربة مع عمليات الإثراء لديك — بدءًا بالتمهيد من لقطة، ثم تطبيق تغذية دلتا حية عبر اتصال WebSocket صادر واحد. لا تغادر سلسلة اتصالك جهازك أبدًا.

كل عبارة محمية بالمراجعة، لذا تتقارب الدفعة المعاد تسليمها نحو الصفوف نفسها. يؤدي خطأ SQL إلى التراجع عن الدفعة وإيقافها — ولا يتم أبدًا تخطي دلتا مسمومة بصمت.

يسحب العميل الحالة لا العمليات: تحمل كل دلتا الصف (الصفوف) الحالي كاملًا لكيان متغيّر على هيئة INSERT … ON CONFLICT … DO UPDATE عديمة التأثير التكراري، بحيث يتقارب الهدف حتى لو فُقِدت دفعة.

لماذا عميل المزامنة؟

يمكن استهلاك قواعد بيانات المخطط بعدة طرق — n8n وMake.com وMCP وخطافات الويب الخام أو تغذية دلتا عبر REST. أما عميل المزامنة فهو المسار المؤتمت بالكامل: الأقل بناءً والأقل تسريبًا.

لا حاجة لبناء أي سير عمل

لا سيناريو n8n، ولا cron، ولا كود ربط. اقترن مرة واحدة، فيبدأ التمهيد من اللقطة، ثم يطبّق كل دلتا فور وصولها.

لا يغادر DSN الخاص بك جهازك أبدًا

تُمرَّر سلسلة الاتصال عبر سطر الأوامر أو تُخزَّن محليًا بصلاحيات mode-600 — ولا تُرسَل أبدًا إلى Entity Enricher. يتصل العميل للخارج فقط.

آمن لإعادة التشغيل بحكم تصميمه

كل دلتا عبارة عن عملية إدراج أو تحديث (upsert) خاملة (idempotent) ومحمية بالمراجعة. إذا توقف العميل في منتصف الدفعة، يُعاد تسليم الدفعة بعد انتهاء صلاحية عقد الإيجار الخاص بها، وتؤدي إعادة التطبيق إلى التقارب نحو الصفوف نفسها.

يفشل بصوت عالٍ، وليس بصمت أبدًا

يؤدي خطأ SQL إلى التراجع عن الدفعة، والإبلاغ عن الفرق الفاشل في صفحة قواعد البيانات، والخروج بقيمة غير صفرية — فلا يمكن أبدًا تخطّي فرق ضار بصمت.

بدء سريع

سجّل قاعدة بيانات على schema أولًا، ثم اقترن عميلًا وشغّله بجانب قاعدة بياناتك.

1
تسجيل قاعدة بيانات
في صفحة قواعد البيانات، سجّل قاعدة بيانات على schema الذي تريد عكسه وراجع مفاتيح قاعدة بياناته. راجع قواعد البيانات للاطلاع على النموذج الكامل. تعلن هذه الخطوة عن لهجة الهدف التي سيطبّقها العميل.
2
ثبِّت العميل
نزّل ملفًا ثنائيًا موقّعًا من الإصدارات، أو ابنِ من المصدر (Go ≥ 1.23).
```
go build -o ee-database .
```
يتوفّر الكود المصدري والإصدارات الموقّعة على TOT-Concept/ee-database (MIT).
3
الإقران عبر متصفحك
شغّل ee-database pair. تُفتح علامة تبويب في المتصفح على /database/connect برمز قصير — أكّده، واختر أي قاعدة بيانات ينبغي لهذا العميل مزامنتها.
```
ee-database pair --server https://entityenricher.ai

Open this URL in your browser to confirm pairing:
   https://entityenricher.ai/database/connect?code=7QX-KP2

  Code: 7QX-KP2

Waiting for confirmation...
```
تفضّل رمزًا مميزًا؟ أصدر واحدًا في صفحة قواعد البيانات (عميل المزامنة ← اقتران عميل) ومرّره مباشرة: ee-database pair --server … <refresh-token>.
4
شغّله بجانب قاعدة بياناتك
في التشغيل الأول، يجلب العميل لقطة .sql ويطبّقها، ثم يتصل ويبثّ عمليات الدلتا. يخزّن --save-dsn سلسلة الاتصال محليًا بحيث لا تحتاج عمليات التشغيل اللاحقة إلى أي وسائط.
```
ee-database run --dsn "postgres://user:pass@localhost:5432/mydb" --save-dsn
```
«بالقرب من» تعني قريبًا على مستوى الشبكة، وليس على خادم قاعدة البيانات: أي جهاز أو حاوية يمكنها الوصول إلى DSN تفي بالغرض — بما في ذلك PostgreSQL المُدارة سحابيًا (Azure وOVHcloud وAWS RDS…)، والتي تفرض عادةً TLS: …/mydb?sslmode=require.

كيفية عمل التسليم: الإيجار والإقرار

تغادر الفروق Entity Enricher عبر صندوق صادر صارم من نوع FIFO لكل قاعدة بيانات. يقوم الخادم باستئجار النافذة المرئية لمدة 120 ثانية ويدفعها كدفعة واحدة؛ ويطبّق العميل الدفعة كاملةً في معاملة واحدة ويردّ ack ، ما يقدّم المؤشر ويطلق النافذة التالية فورًا. أما العميل الذي يتعطّل في منتصف الدفعة فيغطّيه انتهاء الإيجار وإعادة دفع من جانب الخادم — فلا يُفقد شيء ولا يُلتزَم به مرتين.

اللقطة = دلتا من الصفر

تتشارك التهيئة الأولية والحالة المستقرة مسار كود واحد. تخطَّ التهيئة الأولية عبر --skip-bootstrap إذا كانت قاعدة بياناتك مُهيّأة بالبيانات مسبقًا.

محمي بالمراجعة

يحمل كل بيان قيمة _sync_revision بحيث لا يستبدل صف أقدم صفًا أحدث أبدًا، حتى لو وصل خارج الترتيب.

الإيقاف عند الفشل

يخزّن خطأ SQL معرّف الفرق الفاشل في صفحة قواعد البيانات ← بطاقة عميل المزامنة، وتخرج العملية بقيمة غير صفرية ليعيد المشرف تشغيلها.

قواعد البيانات واللهجات

تُحدَّد اللهجة الهدف من خلال تسجيل قاعدة بيانات المخطط في Entity Enricher — ويطبّق العميل أي SQL يُصيّره الخادم. PostgreSQL هي اللهجة عند الإطلاق؛ أما مشغّلا MySQL وSQLite فهما مضمَّنان بالفعل استعدادًا لإطلاق مصيِّرات SQL الخاصة بهما. ويُعالَج تطبيق العبارات المتعددة حسب كل مشغّل (بروتوكول pgx البسيط، وmultiStatements في MySQL، وSQLite الخالي من CGO).

الأمان

صادر فقط

يبدأ العميل اتصال WebSocket عبر ‎:443/wss‎. ولا يقبل مضيف قاعدة بياناتك أي اتصالات واردة إطلاقًا — لا منافذ لفتحها ولا حركة دخول لتهيئتها.

بيان اعتماد واحد، قاعدة بيانات واحدة، عميل واحد

يرتبط بيان الاعتماد بقاعدة بيانات مخطط واحدة. تؤدي إعادة الإقران إلى تدويره وطرد الاتصال النشط السابق فورًا.

رموز وصول قصيرة الأمد

يُستبدَل رمز التحديث ذو 365 يومًا (المخزَّن بصلاحيات mode-600) برموز وصول مدتها 15 دقيقة تُصادق على اتصال WebSocket. ويؤدي الإبطال من الواجهة إلى فصل العميل النشط خلال ثانية واحدة تقريبًا.

يُوصى بأقل الامتيازات

شغّل العميل مقابل دور قاعدة بيانات مخصّص محصور في المخطط المتزامن، بحيث لا يستطيع أي رمز مخترَق الوصول إلى أي شيء آخر.

مرجع واجهة سطر الأوامر

الأمر	ماذا يفعل
ee-database pair --server URL	إقران برمز جهاز مؤكَّد عبر المتصفح. اختر قاعدة البيانات المراد مزامنتها.
ee-database pair --server URL <token>	اقترن برمز مميز صادر في صفحة قواعد البيانات (مناسب للتشغيل دون واجهة).
ee-database run --dsn DSN [--save-dsn] [--skip-bootstrap]	نفّذ التهيئة الأولية من اللقطة (ما لم تُتخطَّ)، ثم اتصل وطبّق الفروق.
ee-database run … --create-missing	أنشئ قاعدة البيانات الهدف أولاً في حال عدم وجودها، باستخدام بيانات اعتماد DSN نفسها (يتطلب postgres صلاحية CREATEDB، ويتطلب mysql صلاحية CREATE؛ أما ملفات sqlite فيتم إنشاؤها تلقائياً على أي حال).
ee-database run … --create-missing --admin-dsn DSN	تهيئة كل ما يسمّيه DSN الهدف عبر اتصال مسؤول: الدور/المستخدم المفقود (بكلمة مرور DSN) وقاعدة البيانات المملوكة له. عندئذٍ لا يحتاج DSN الهدف إلى أي صلاحيات إنشاء؛ ولا يُخزَّن DSN المسؤول أبدًا.
ee-database run --all	مزامنة كل قاعدة بيانات مقترنة بشكل متزامن من عملية واحدة (يحتاج كلٌّ منها إلى DSN محفوظ).
ee-database status	عرض حالة الإقران وعنوان URL للخادم وقواعد البيانات المقترنة.
ee-database disconnect	نسيان بيانات الاعتماد المحلية لأحد الاقترانات. قم بالإلغاء من جانب الخادم عبر واجهة المستخدم.
ee-database version	نسخة للطباعة.

تُخزَّن بيانات الاعتماد بوضع mode-600، ملف تعريف واحد لكل قاعدة بيانات مقترنة، ضمن ~/.config/ee-database/profiles/ — قم بالإقران مرة واحدة لكل قاعدة بيانات، ويتيح --database NAME اختيار واحدة عند اقتران عدة قواعد. أتفضّل عدم استخدام أي أتمتة إطلاقًا؟ التدفق نفسه متاح كـ REST بسيط: GET /api/databases//changes ثم POST /api/databases//ack — راجع قواعد البيانات.

مفتوح المصدر

العميل مرخّص بموجب MIT ويوجد في مستودع عام حتى يتمكّن أي شخص من تدقيق ما يُشغَّل تحديدًا مقابل قاعدة بياناته.

المصدر: github.com/TOT-Concept/ee-database

الإصدارات: github.com/TOT-Concept/ee-database/releases — يُوقَّع كل ملف ثنائي قبل النشر.