데이터베이스와 동기화

분석, 보고 및 통합을 위해 Dodo Payments 데이터를 자체 데이터베이스로 동기화하세요. sync engine은 payments, customers, subscriptions, licenses를 MongoDB, PostgreSQL, MySQL 또는 ClickHouse에 자동으로 복제합니다.

Package: npm의 dodo-sync | Source: GitHub

무엇을 동기화할 수 있나요?

다음 entity를 원하는 조합으로 선택하세요:

Payments

일회성 결제, 환불 및 상태 업데이트를 포함한 모든 결제 거래입니다.

Customers

고객 프로필, 연락처 정보 및 메타데이터입니다.

Subscriptions

구독 데이터, 결제 주기 및 상태 변경입니다.

Licenses

라이선스 키, 활성화 및 상태 업데이트입니다.

scopes 매개변수를 사용하여 동기화할 엔터티를 지정합니다. 실행할 때마다 선택한 범위의 모든 레코드를 가져와 ID별로 기록하므로 기존 행이 중복되지 않고 제자리에서 업데이트됩니다. 각 레코드 페이지는 단일 배치로 데이터베이스에 기록됩니다.

데이터베이스 지원

Dodo Sync는 MongoDB, PostgreSQL, 8.0.20 이상 버전의 MySQL, ClickHouse를 지원합니다. Snowflake 및 기타 데이터베이스, ETL 파이프라인, 실시간 sync에 대한 지원은 개발 중입니다. 새로운 데이터베이스 통합을 추가하려면 GitHub repository에 pull request를 제출하세요.

시작하기

빠르게 설정하려면 CLI를 통해 Dodo Sync를 사용하고, 애플리케이션에 통합하려면 코드에서 programmatically 사용하세요. 두 방법 모두 동일한 기능을 제공합니다.

CLI 사용

어디서나 실행할 수 있도록 CLI를 전역으로 설치하세요:

npm install -g dodo-sync

bun add -g dodo-sync

CLI 실행

CLI는 두 가지 모드를 지원합니다. 안내에 따른 설정을 위한 interactive 모드와 직접 구성을 위한 manual 모드입니다. Interactive mode: 인수 없이 실행하여 설정 wizard를 시작합니다.

dodo-sync

Manual mode: wizard를 건너뛰고 인수를 직접 전달합니다.

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

필수

초 단위의 sync interval입니다. CLI는 이 interval로 계속 실행됩니다. 일회성 sync를 수행하려면 코드에서 .run()를 사용하세요.

string

필수

데이터베이스 type: "mongodb", "postgres", "mysql" 또는 "clickhouse"입니다.

string

필수

데이터베이스의 connection 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

필수

동기화할 entity의 쉼표로 구분된 목록입니다: licences, payments, customers, subscriptions. 예시: "payments,customers".

string

필수

Developer → API Keys에서 확인할 수 있는 Dodo Payments API key입니다. --env와 동일한 mode의 key를 사용하세요.

string

필수

Environment: "live_mode" 또는 "test_mode"입니다.

number

초당 requests 단위의 rate limit입니다. sync engine이 API requests를 수행하는 속도를 제어합니다. 기본값은 10이며, 100 이상의 값은 throttling을 해제합니다.

코드에서 사용

sync 기능을 애플리케이션에 직접 통합합니다. dependency로 설치하세요:

npm install dodo-sync

bun add dodo-sync

Automatic Sync (Interval-based)

일정한 interval로 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 option이 필요합니다. process가 중지될 때까지 지정된 interval로 sync가 계속 실행됩니다.

Manual Sync

cron job, API endpoint 또는 serverless function 등에서 필요할 때 sync 작업을 트리거합니다:

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

수동 sync에는 interval 옵션이 필요하지 않습니다. sync가 필요할 때마다 .run()을 호출합니다. .run()은 모든 데이터베이스 쓰기 작업이 완료된 후에만 resolve됩니다. .close()는 .disconnect()의 alias입니다.

Serverless에서 실행

Vercel, AWS Lambda 또는 유사한 플랫폼에서:

위 예시와 같이 .disconnect()을 finally 블록에서 호출하여 invocation 간에 connection이 열린 상태로 유지되지 않도록 합니다.
Node.js runtime을 사용합니다. Edge runtime에서는 database connection을 열 수 없습니다.
function timeout을 늘립니다. 대규모 sync는 기본 제한 시간보다 오래 걸릴 수 있습니다. Vercel에서는 export const maxDuration = 60;을 설정합니다.
각 실행 시간을 짧게 유지하려면 scopes: ['payments']과 같이 invocation당 sync하는 scope 수를 줄입니다.

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

Constructor 옵션

string

필수

데이터베이스 유형: "mongodb", "postgres", "mysql" 또는 "clickhouse".

string

필수

데이터베이스의 connection 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 configuration입니다. 전체 옵션은 TypeScript SDK types를 참조하세요.필수 properties:

bearerToken: Dodo Payments API key
environment: "test_mode" 또는 "live_mode"

number

automatic sync 간의 간격(초)입니다. .start()에는 필수이며, .run()에는 선택 사항입니다.

number

초당 요청 수에 대한 rate limit입니다. 기본값은 10이며, 100 이상의 값은 throttling을 해제합니다.

중요 정보

MongoDB: Collections (subscriptions, payments, licences, customers)은 mongodb://localhost:27017/my_database와 같이 connection URI에 지정된 데이터베이스에 생성됩니다. URI에 데이터베이스가 지정되지 않은 경우 Dodo Sync는 dodopayments_sync을 사용합니다.PostgreSQL: Tables (Subscriptions, Payments, Licenses, Customers)은 connection URI에 지정된 데이터베이스에 생성됩니다. 데이터는 JSONB로 저장됩니다.MySQL: MySQL 8.0.20 이상이 필요합니다. Tables (Subscriptions, Payments, Licenses, Customers)은 connection URI에 지정된 데이터베이스에 생성됩니다. 데이터는 JSON으로 저장됩니다.ClickHouse: Tables (Subscriptions, Payments, Licenses, Customers)은 ReplacingMergeTree engine을 사용하여 생성됩니다. 쿼리할 때는 중복 제거된 결과를 보장하기 위해 FINAL keyword를 사용합니다.

0.x에서 업그레이드

Version 1.0에서는 MongoDB 데이터 저장 방식이 변경되고 MySQL 요구 사항이 상향되었습니다. 업그레이드하기 전에 다음을 수행하세요:

MongoDB: 기존 licences collection을 삭제합니다. License documents는 이제 subscription_id 대신 license id별로 저장되며, 다음 sync에서 collection이 다시 채워집니다.
MongoDB: connection URI를 확인합니다. 이제 데이터는 항상 dodopayments_sync이 아니라 URI에 지정된 데이터베이스에 기록됩니다. 기존 데이터를 계속 사용하려면 URI에 dodopayments_sync을 입력하거나 데이터베이스를 생략합니다.
MySQL: MySQL 8.0.20 이상으로 업그레이드합니다.

추가 리소스

GitHub Repository

소스 코드를 확인하거나, issue를 신고하거나, 개선 사항에 기여

npm Package

package 세부 정보 및 설치 지침 확인

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

무엇을 동기화할 수 있나요?

Payments

Customers

Subscriptions

Licenses

데이터베이스 지원

시작하기

CLI 사용

CLI 실행

CLI 인수

코드에서 사용

Automatic Sync (Interval-based)

Manual Sync

Serverless에서 실행

PostgreSQL 예시

MySQL 예시

ClickHouse 예시

Constructor 옵션

중요 정보

0.x에서 업그레이드

추가 리소스

GitHub Repository

npm Package