与您的数据库同步

将您的 Dodo Payments 数据同步到自己的数据库，以用于分析、报告和集成。同步引擎会自动将 payments、customers、subscriptions 和 licenses 复制到 MongoDB、PostgreSQL、MySQL 或 ClickHouse。

Package：npm 上的 dodo-sync | Source：GitHub

您可以同步什么？

选择这些实体的任意组合：

Payments

所有支付交易，包括一次性支付、退款和状态更新。

Customers

客户资料、联系信息和元数据。

Subscriptions

订阅数据、计费周期和状态变更。

Licenses

许可证密钥、激活信息和状态更新。

使用 scopes 参数指定要同步的实体。每次运行都会获取所选范围内的每条记录，并按 ID 写入，因此现有行会就地更新，而不会产生重复项。每一页记录都会以单个批次写入您的数据库。

数据库支持

Dodo Sync 支持 MongoDB、PostgreSQL、MySQL 8.0.20 或更高版本，以及 ClickHouse。Snowflake 和其他数据库、ETL 管道以及实时同步功能正在开发中。如要贡献新的数据库集成，请向 GitHub repository 提交 pull request。

开始使用

您可以通过 CLI 使用 Dodo Sync 进行快速设置，也可以在代码中以编程方式使用，以便集成到您的应用程序中。两种方式提供相同的功能。

使用 CLI

全局安装 CLI，以便从任意位置运行：

npm install -g dodo-sync

bun add -g dodo-sync

运行 CLI

CLI 支持两种模式：用于引导设置的 interactive，以及用于直接配置的 manual。 Interactive mode：不带参数运行，以启动设置向导。

dodo-sync

Manual mode：直接传入参数以跳过向导。

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 key，位于 Developer → API Keys。请使用与 --env 相同模式的 key。

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

使用 .start() 时，必须提供 interval 选项。同步会按照指定间隔持续运行，直到进程停止。

手动同步

按需触发同步操作，例如从 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 或类似平台上：

在 finally 块中调用 .disconnect()，如上面的示例所示，这样连接不会在调用之间保持打开状态。
使用 Node.js runtime。Edge runtimes 无法打开数据库连接。
延长函数超时时间。大型同步可能需要比默认限制更长的时间。在 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 key
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、Payments、Licenses、Customers）会创建在连接 URI 指定的数据库中。数据以 JSONB 格式存储。MySQL：需要 MySQL 8.0.20 或更高版本。表（Subscriptions、Payments、Licenses、Customers）会创建在连接 URI 指定的数据库中。数据以 JSON 格式存储。ClickHouse：表（Subscriptions、Payments、Licenses、Customers）使用 ReplacingMergeTree 引擎创建。查询时，使用 FINAL 关键字，以确保获得去重后的结果。

从 0.x 升级

版本 1.0 更改了 MongoDB 数据的存储方式，并提高了 MySQL 的版本要求。升级前：

MongoDB：删除现有的 licences 集合。现在，许可证文档按许可证 id 而不是 subscription_id 存储，下次同步时会重新填充该集合。
MongoDB：检查连接 URI。现在，数据会写入 URI 指定的数据库，而不总是写入 dodopayments_sync。若要继续使用现有数据，请在 URI 中加入 dodopayments_sync，或不指定数据库。
MySQL：升级到 MySQL 8.0.20 或更高版本。

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

​您可以同步什么？

Payments

Customers

Subscriptions

Licenses

​数据库支持

​开始使用

​使用 CLI

​运行 CLI

​CLI 参数

​在代码中使用

​自动同步（基于间隔）

​手动同步

​在 Serverless 环境中运行

​PostgreSQL 示例

​MySQL 示例

​ClickHouse 示例

​构造函数选项

​重要信息

​从 0.x 升级

​其他资源

GitHub Repository

npm Package

您可以同步什么？

数据库支持

开始使用

使用 CLI

运行 CLI

CLI 参数

在代码中使用

自动同步（基于间隔）

手动同步

在 Serverless 环境中运行

PostgreSQL 示例

MySQL 示例

ClickHouse 示例

构造函数选项

重要信息

从 0.x 升级

其他资源