المزامنة مع قاعدة بياناتك

زامن بيانات Dodo Payments مع قاعدة بياناتك الخاصة لإجراء التحليلات وإعداد التقارير وعمليات التكامل. يعمل محرك المزامنة على نسخ المدفوعات والعملاء والاشتراكات والتراخيص تلقائيًا إلى MongoDB أو PostgreSQL أو MySQL أو ClickHouse.

الحزمة: dodo-sync على npm | المصدر: GitHub

ماذا يمكنك مزامنته؟

اختر أي مجموعة من هذه الكيانات:

Payments

جميع معاملات الدفع، بما في ذلك المدفوعات لمرة واحدة والمبالغ المستردة وتحديثات الحالة.

Customers

ملفات تعريف العملاء ومعلومات الاتصال والبيانات الوصفية.

Subscriptions

بيانات الاشتراكات ودورات الفوترة وتغييرات الحالة.

Licenses

مفاتيح التراخيص وعمليات التفعيل وتحديثات الحالة.

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

دعم قاعدة البيانات

يدعم Dodo Sync قواعد بيانات MongoDB وPostgreSQL وMySQL الإصدار 8.0.20 أو الإصدارات الأحدث، وClickHouse. ويجري حاليًا تطوير دعم Snowflake وقواعد البيانات الأخرى وخطوط أنابيب ETL والمزامنة الآنية. للمساهمة بإضافة تكامل جديد مع قاعدة بيانات، أرسل طلب سحب إلى مستودع GitHub.

البدء

استخدم Dodo Sync عبر CLI للإعداد السريع، أو برمجيًا ضمن التعليمات البرمجية لديك لدمجه في تطبيقك. توفر كلتا الطريقتين الوظائف نفسها.

استخدام CLI

ثبّت CLI بشكل عام لتتمكن من تشغيله من أي مكان:

npm install -g dodo-sync

bun add -g dodo-sync

تشغيل CLI

يدعم CLI وضعين: التفاعلي للإعداد الموجّه، واليدوي للإعداد المباشر. الوضع التفاعلي: شغّله من دون وسيطات لبدء معالج الإعداد.

dodo-sync

الوضع اليدوي: مرّر الوسيطات مباشرة لتخطي المعالج.

dodo-sync -i [interval] -d [database] -u [database_uri] --scopes [scopes] --api-key [api_key] --env [environment]

أمثلة:

# MongoDB
dodo-sync -i 600 -d mongodb -u mongodb://mymongodb.url --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode

# PostgreSQL
dodo-sync -i 600 -d postgres -u postgresql://user:password@localhost:5432/mydb --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode

# MySQL
dodo-sync -i 600 -d mysql -u mysql://user:password@localhost:3306/mydb --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode

# ClickHouse
dodo-sync -i 600 -d clickhouse -u http://localhost:8123 --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode

وسيطات CLI

number

مطلوب

الفاصل الزمني للمزامنة بالثواني. يعمل CLI باستمرار وفق هذا الفاصل الزمني. لإجراء مزامنة لمرة واحدة، استخدم .run() في التعليمات البرمجية.

string

مطلوب

نوع قاعدة البيانات: "mongodb" أو "postgres" أو "mysql" أو "clickhouse".

string

مطلوب

URI الاتصال بقاعدة بياناتك:

MongoDB: mongodb://localhost:27017 أو mongodb+srv://user:pass@cluster.mongodb.net/
PostgreSQL: postgresql://user:password@localhost:5432/mydb
MySQL: mysql://user:password@localhost:3306/mydb
ClickHouse: http://localhost:8123

string

مطلوب

قائمة مفصولة بفواصل بالكيانات المراد مزامنتها: licences وpayments وcustomers وsubscriptions. مثال: "payments,customers".

string

مطلوب

مفتاح Dodo Payments API الخاص بك من Developer → API Keys. استخدم مفتاحًا من الوضع نفسه مثل --env.

string

مطلوب

البيئة: "live_mode" أو "test_mode".

number

حد معدل الطلبات بالطلبات في الثانية. يتحكم في سرعة إجراء محرك المزامنة لطلبات API. القيمة الافتراضية هي 10؛ وتؤدي القيم التي تساوي 100 أو تزيد عليها إلى إيقاف تحديد المعدل.

الاستخدام في التعليمات البرمجية

ادمج ميزة المزامنة مباشرةً في تطبيقك. ثبّتها باعتبارها تبعية:

npm install dodo-sync

bun add dodo-sync

المزامنة التلقائية (المستندة إلى فاصل زمني)

شغّل المزامنة باستمرار وفق فواصل زمنية منتظمة:

import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60, // Sync every 60 seconds
  database: 'mongodb',
  databaseURI: process.env.MONGODB_URI, // e.g., 'mongodb://localhost:27017'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode' // or 'live_mode'
  }
});

// Initialize connection
await syncDodoPayments.init();

// Start the sync loop
syncDodoPayments.start();

يكون الخيار interval مطلوبًا عند استخدام .start(). تعمل المزامنة باستمرار وفق الفاصل الزمني المحدد حتى تتوقف العملية.

المزامنة اليدوية

شغّل عمليات المزامنة عند الطلب، مثلًا من مهمة cron أو نقطة نهاية API أو دالة serverless:

import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  database: 'mongodb',
  databaseURI: process.env.MONGODB_URI,
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

try {
  // Initialize connection
  await syncDodoPayments.init();

  // Trigger a single sync operation
  await syncDodoPayments.run();
} finally {
  // Close the database connection
  await syncDodoPayments.disconnect();
}

الخيار interval غير مطلوب للمزامنة اليدوية. استدعِ .run() كلما احتجت إلى المزامنة. لا يُكتمل .run() إلا بعد انتهاء كل عمليات الكتابة في قاعدة البيانات. .close() هو اسم مستعار لـ .disconnect().

التشغيل على Serverless

على Vercel أو AWS Lambda أو المنصات المشابهة:

استدعِ .disconnect() داخل كتلة finally، كما في المثال أعلاه، حتى لا تبقى الاتصالات مفتوحة بين عمليات الاستدعاء.
استخدم بيئة تشغيل Node.js. لا تستطيع بيئات تشغيل Edge فتح اتصالات بقاعدة البيانات.
ارفع مهلة الدالة. قد تستغرق المزامنة الكبيرة وقتًا أطول من الحد الافتراضي. على Vercel، اضبط export const maxDuration = 60;.
زامن عددًا أقل من النطاقات في كل عملية استدعاء، مثل scopes: ['payments']، للحفاظ على قِصر مدة كل عملية تشغيل.

مثال على PostgreSQL

import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60,
  database: 'postgres',
  databaseURI: process.env.POSTGRES_URI, // e.g., 'postgresql://user:password@localhost:5432/mydb'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

await syncDodoPayments.init();
syncDodoPayments.start();

مثال على MySQL

import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60,
  database: 'mysql',
  databaseURI: process.env.MYSQL_URI, // e.g., 'mysql://user:password@localhost:3306/mydb'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

await syncDodoPayments.init();
syncDodoPayments.start();

مثال على ClickHouse

import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60,
  database: 'clickhouse',
  databaseURI: process.env.CLICKHOUSE_URI, // e.g., 'http://localhost:8123'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

await syncDodoPayments.init();
syncDodoPayments.start();

خيارات المُنشئ

string

مطلوب

نوع قاعدة البيانات: "mongodb" أو "postgres" أو "mysql" أو "clickhouse".

string

مطلوب

سلسلة الاتصال بقاعدة بياناتك:

MongoDB: mongodb://localhost:27017 أو mongodb+srv://...
PostgreSQL: postgresql://user:password@localhost:5432/mydb
MySQL: mysql://user:password@localhost:3306/mydb
ClickHouse: http://localhost:8123

string[]

مطلوب

مصفوفة الكيانات المراد مزامنتها: "licences" و"payments" و"customers" و"subscriptions". يمكنك تضمين أي مجموعة منها.

object

مطلوب

إعدادات Dodo Payments API. راجع أنواع TypeScript SDK للاطلاع على الخيارات الكاملة.الخصائص المطلوبة:

bearerToken: مفتاح Dodo Payments API الخاص بك
environment: "test_mode" أو "live_mode"

number

المدة بالثواني بين عمليات المزامنة التلقائية. مطلوبة لـ .start()، واختيارية لـ .run().

number

حد معدل الطلبات في الثانية. القيمة الافتراضية هي 10؛ وتؤدي القيم التي تساوي 100 أو تزيد عليها إلى إيقاف تقييد المعدل.

معلومات مهمة

MongoDB: تُنشأ المجموعات (subscriptions وpayments وlicences وcustomers) في قاعدة البيانات المحددة في URI الاتصال، مثل mongodb://localhost:27017/my_database. إذا لم يحدد URI قاعدة بيانات، يستخدم Dodo Sync dodopayments_sync.PostgreSQL: تُنشأ الجداول (Subscriptions وINLINE_CODE_PLACEHOLDER_692267c1468089c_END وLicenses وCustomers) في قاعدة البيانات المحددة في URI الاتصال. تُخزّن البيانات بصيغة JSONB.MySQL: يتطلب MySQL الإصدار 8.0.20 أو إصدارًا أحدث. تُنشأ الجداول (Subscriptions وINLINE_CODE_PLACEHOLDER_692267c1468089c_END وLicenses وCustomers) في قاعدة البيانات المحددة في URI الاتصال. تُخزّن البيانات بصيغة JSON.ClickHouse: تُنشأ الجداول (Subscriptions وINLINE_CODE_PLACEHOLDER_692267c1468089c_END وLicenses وCustomers) باستخدام محرك ReplacingMergeTree. عند إجراء الاستعلامات، استخدم الكلمة المفتاحية FINAL لضمان الحصول على نتائج منزوعة التكرار.

الترقية من الإصدار 0.x

يغيّر الإصدار 1.0 طريقة تخزين بيانات MongoDB ويرفع متطلبات MySQL. قبل الترقية:

MongoDB: احذف مجموعة licences الموجودة. تُخزّن مستندات التراخيص الآن باستخدام id الخاص بالترخيص بدلًا من subscription_id، وستعيد المزامنة التالية تعبئة المجموعة.
MongoDB: تحقّق من URI الاتصال. تُكتب البيانات الآن إلى قاعدة البيانات التي يحددها URI، وليس دائمًا إلى dodopayments_sync. لمواصلة استخدام بياناتك الحالية، أدرج dodopayments_sync في URI أو اترك قاعدة البيانات غير محددة.
MySQL: قم بالترقية إلى MySQL الإصدار 8.0.20 أو إصدار أحدث.

موارد إضافية

GitHub Repository

عرض الشيفرة المصدرية أو الإبلاغ عن المشكلات أو المساهمة بالتحسينات

npm Package

عرض تفاصيل الحزمة وتعليمات التثبيت

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

المزامنة مع قاعدة بياناتك

ماذا يمكنك مزامنته؟

Payments

Customers

Subscriptions

Licenses

دعم قاعدة البيانات

البدء

استخدام CLI

تشغيل CLI

وسيطات CLI

الاستخدام في التعليمات البرمجية

المزامنة التلقائية (المستندة إلى فاصل زمني)

المزامنة اليدوية

التشغيل على Serverless

مثال على PostgreSQL

مثال على MySQL

مثال على ClickHouse

خيارات المُنشئ

معلومات مهمة

الترقية من الإصدار 0.x

موارد إضافية

GitHub Repository

npm Package