Đồng bộ với cơ sở dữ liệu của bạn

Tự động đồng bộ dữ liệu Dodo Payments của bạn với cơ sở dữ liệu của riêng bạn để phân tích, báo cáo và tích hợp.

Đồng bộ dữ liệu Dodo Payments với cơ sở dữ liệu riêng của bạn để phục vụ phân tích, báo cáo và tích hợp. Công cụ đồng bộ tự động sao chép payments, customers, subscriptions và licenses vào MongoDB, PostgreSQL, MySQL hoặc ClickHouse.

Package: dodo-sync trên npm | Source: GitHub

​

Bạn có thể đồng bộ những gì?

Chọn bất kỳ tổ hợp nào trong các entity này:

Payments

Tất cả giao dịch thanh toán, bao gồm thanh toán một lần, hoàn tiền và cập nhật trạng thái.

Customers

Hồ sơ khách hàng, thông tin liên hệ và metadata.

Subscriptions

Dữ liệu gói đăng ký, chu kỳ thanh toán và thay đổi trạng thái.

Licenses

License key, lượt kích hoạt và cập nhật trạng thái.

Chỉ định các entity cần đồng bộ bằng parameter scopes. Mỗi lần chạy sẽ lấy mọi record trong các scope đã chọn và ghi theo ID, vì vậy các row hiện có được cập nhật tại chỗ thay vì bị trùng lặp. Mỗi page record được ghi vào database của bạn trong một batch duy nhất.

​

Hỗ trợ cơ sở dữ liệu

Dodo Sync hỗ trợ MongoDB, PostgreSQL, MySQL 8.0.20 trở lên và ClickHouse. Hỗ trợ Snowflake và các database khác, pipeline ETL cũng như đồng bộ realtime đang được phát triển.

Để đóng góp một tích hợp cơ sở dữ liệu mới, hãy gửi pull request đến repository GitHub.

​

Bắt đầu

Sử dụng Dodo Sync thông qua CLI để thiết lập nhanh hoặc tích hợp theo cách lập trình vào code của bạn. Cả hai phương thức đều cung cấp cùng một chức năng.

​

Sử dụng CLI

Cài đặt CLI trên toàn hệ thống để chạy từ bất kỳ đâu:

npm

npm install -g dodo-sync

​

Chạy CLI

CLI hỗ trợ hai chế độ: interactive để được hướng dẫn thiết lập và manual để cấu hình trực tiếp.

Chế độ interactive: Chạy không có đối số để bắt đầu trình hướng dẫn thiết lập.

dodo-sync

Chế độ manual: Truyền trực tiếp các đối số để bỏ qua trình hướng dẫn.

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

Ví dụ:

# 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

​

Đối số CLI

--interval · number · bắt buộc

Khoảng thời gian đồng bộ tính bằng giây. CLI chạy liên tục theo khoảng thời gian này. Để đồng bộ một lần, hãy sử dụng .run() trong code của bạn.

--database · string · bắt buộc

Loại cơ sở dữ liệu: "mongodb", "postgres", "mysql" hoặc "clickhouse".

--database-uri · string · bắt buộc

URI kết nối đến cơ sở dữ liệu của bạn:

• MongoDB: mongodb://localhost:27017 hoặc mongodb+srv://user:[e-mail]/
• PostgreSQL: postgresql://user:password@localhost:5432/mydb
• MySQL: mysql://user:password@localhost:3306/mydb
• ClickHouse: http://localhost:8123

--scopes · string · bắt buộc

Danh sách entity cần đồng bộ, được phân tách bằng dấu phẩy: licences, payments, customers, subscriptions. Ví dụ: "payments,customers".

--api-key · string · bắt buộc

API key Dodo Payments của bạn từ Developer → API Keys. Sử dụng key ở cùng chế độ với --env.

--env · string · bắt buộc

Môi trường: "live_mode" hoặc "test_mode".

--rate-limit · number

Giới hạn tốc độ tính bằng request mỗi giây. Kiểm soát tốc độ công cụ đồng bộ thực hiện request API. Mặc định là 10; giá trị 100 trở lên sẽ tắt throttling.

​

Sử dụng trong Code của bạn

Tích hợp trực tiếp tính năng đồng bộ vào ứng dụng của bạn. Cài đặt dưới dạng dependency:

npm

npm install dodo-sync

​

Đồng bộ tự động (theo khoảng thời gian)

Chạy đồng bộ liên tục theo các khoảng thời gian đều đặn:

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();

Tùy chọn interval là bắt buộc khi sử dụng .start(). Quá trình đồng bộ chạy liên tục theo khoảng thời gian được chỉ định cho đến khi process dừng.

​

Đồng bộ thủ công

Kích hoạt các thao tác đồng bộ theo yêu cầu, chẳng hạn từ cron job, API endpoint hoặc serverless function:

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();
}

Tùy chọn interval không bắt buộc đối với đồng bộ thủ công. Gọi .run() bất cứ khi nào bạn cần đồng bộ. .run() chỉ hoàn tất sau khi mọi thao tác ghi vào database đã hoàn thành. .close() là alias của .disconnect().

​

Chạy trên Serverless

Trên Vercel, AWS Lambda hoặc các nền tảng tương tự:

• Gọi .disconnect() trong block finally, như trong ví dụ trên, để các connection không duy trì mở giữa các lần invocation.
• Sử dụng runtime Node.js. Edge runtime không thể mở các connection đến database.
• Tăng timeout của function. Một lần đồng bộ lớn có thể mất nhiều thời gian hơn giới hạn mặc định. Trên Vercel, đặt export const maxDuration = 60;.
• Đồng bộ ít scope hơn trong mỗi invocation, chẳng hạn scopes: ['payments'], để mỗi lần chạy có thời lượng ngắn.

​

Ví dụ 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();

​

Ví dụ 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();

​

Ví dụ 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();

​

Các tùy chọn Constructor

database · string · bắt buộc

Loại database: "mongodb", "postgres", "mysql" hoặc "clickhouse".

databaseURI · string · bắt buộc

Connection string cho database của bạn:

• MongoDB: mongodb://localhost:27017 hoặc mongodb+srv://...
• PostgreSQL: postgresql://user:password@localhost:5432/mydb
• MySQL: mysql://user:password@localhost:3306/mydb
• ClickHouse: http://localhost:8123

scopes · string[] · bắt buộc

Mảng entity cần đồng bộ: "licences", "payments", "customers", "subscriptions". Có thể bao gồm bất kỳ tổ hợp nào.

dodoPaymentsOptions · object · bắt buộc

Cấu hình Dodo Payments API. Xem các type của TypeScript SDK để biết đầy đủ các tùy chọn.

Các property bắt buộc:

• bearerToken: API key Dodo Payments của bạn
• environment: "test_mode" hoặc "live_mode"

interval · number

Thời gian tính bằng giây giữa các lần đồng bộ tự động. Bắt buộc đối với .start(), tùy chọn đối với .run().

rateLimit · number

Giới hạn tốc độ tính bằng request mỗi giây. Mặc định là 10; các giá trị từ 100 trở lên sẽ tắt throttling.

​

Thông tin quan trọng

MongoDB: Các collection (subscriptions, payments, licences, customers) được tạo trong database có tên được nêu trong connection URI của bạn, chẳng hạn mongodb://localhost:27017/my_database. Nếu URI không nêu database, Dodo Sync sẽ sử dụng dodopayments_sync.

PostgreSQL: Các table (Subscriptions, Payments, Licenses, Customers) được tạo trong database được chỉ định trong connection URI của bạn. Dữ liệu được lưu dưới dạng JSONB.

MySQL: Yêu cầu MySQL 8.0.20 trở lên. Các table (Subscriptions, Payments, Licenses, Customers) được tạo trong database được chỉ định trong connection URI của bạn. Dữ liệu được lưu dưới dạng JSON.

ClickHouse: Các table (Subscriptions, Payments, Licenses, Customers) được tạo bằng engine ReplacingMergeTree. Khi query, hãy sử dụng keyword FINAL để đảm bảo kết quả không bị trùng lặp.

​

Nâng cấp từ 0.x

Version 1.0 thay đổi cách lưu trữ dữ liệu MongoDB và nâng yêu cầu đối với MySQL. Trước khi nâng cấp:

• MongoDB: Xóa collection licences hiện có. Các license document hiện được lưu theo license id thay vì subscription_id, và lần đồng bộ tiếp theo sẽ tạo lại collection.
• MongoDB: Kiểm tra connection URI của bạn. Dữ liệu hiện được ghi vào database mà URI chỉ định, không phải luôn là dodopayments_sync. Để tiếp tục sử dụng dữ liệu hiện có, hãy thêm dodopayments_sync vào URI hoặc bỏ database khỏi URI.
• MySQL: Nâng cấp lên MySQL 8.0.20 trở lên.

​

Tài nguyên bổ sung

GitHub Repository

Xem mã nguồn, báo cáo issue hoặc đóng góp cải tiến

npm Package

Xem thông tin package và hướng dẫn cài đặt