> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 데이터베이스와 동기화

> 분석, 보고 및 통합을 위해 Dodo Payments 데이터를 자동으로 자신의 데이터베이스에 동기화합니다.

Dodo Payments는 결제 데이터를 자동으로 자신의 데이터베이스와 동기화하는 내장 데이터베이스 동기화 기능을 제공합니다. **결제**, **고객**, **구독**, 및 **라이센스**를 동기화하여 분석, 보고 또는 다른 시스템과의 통합을 위한 데이터의 로컬 복사본을 유지할 수 있습니다.

<Info>
  **구현**: [npm 패키지](https://www.npmjs.com/package/dodo-sync)를 통해 제공됩니다 | **소스 코드**: [GitHub](https://github.com/dodopayments/dodo-sync)
</Info>

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

우리의 데이터베이스 동기화 기능은 다음 Dodo Payments 엔티티를 데이터베이스에 동기화하는 것을 지원합니다:

<CardGroup cols={2}>
  <Card title="Payments" icon="credit-card">
    일회성 결제, 환불 및 결제 상태 업데이트를 포함한 모든 결제 거래를 동기화합니다.
  </Card>

  <Card title="Customers" icon="users">
    고객 프로필, 연락처 정보, 메타데이터를 포함해 고객 데이터를 동기화 상태로 유지합니다.
  </Card>

  <Card title="Subscriptions" icon="repeat">
    활성 구독, 청구 주기, 구독 상태 변경을 포함한 구독 데이터를 동기화합니다.
  </Card>

  <Card title="Licenses" icon="key">
    라이선스 키, 활성화 및 라이선스 상태 업데이트를 포함한 라이선스 정보를 동기화합니다.
  </Card>
</CardGroup>

`scopes` 매개변수에 이러한 엔터티 중 원하는 조합을 지정하여 동기화할 수 있습니다. 모든 동기화 작업은 증분 방식이며 최적의 성능을 위해 새롭거나 업데이트된 레코드만 전송합니다.

## 데이터베이스 지원

현재 **MongoDB**, **PostgreSQL**, **MySQL**, 및 **ClickHouse**를 지원합니다.

우리는 다음에 대한 지원을 확장하기 위해 적극적으로 작업하고 있습니다:

* **데이터베이스**: Snowflake 및 기타.
* **파이프라인**: ETL 파이프라인, 실시간 동기화.

<Tip>
  데이터베이스 지원은 지속적으로 확대 중입니다. 새로운 데이터베이스 통합을 기여하고자 한다면 [GitHub 저장소](https://github.com/dodopayments/dodo-sync)에 Pull Request를 제출해 주세요.
</Tip>

## 시작하기

**CLI**를 통해 또는 **코드**에서 프로그래밍 방식으로 데이터베이스 동기화 기능을 사용할 수 있습니다. 두 방법 모두 동일한 기능을 제공하므로, 작업 흐름에 가장 적합한 방법을 선택하세요.

### CLI 사용하기

CLI 도구는 데이터베이스 동기화를 설정하고 실행하는 빠른 방법을 제공합니다. 어디서나 사용할 수 있도록 전역적으로 설치하세요:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g dodo-sync
  ```

  ```bash bun theme={null}
  bun add -g dodo-sync
  ```
</CodeGroup>

#### CLI 실행하기

CLI는 두 가지 모드를 지원합니다: **대화형 모드**는 안내 설정을 위한 것이고, **수동 모드**는 직접 구성을 위한 것입니다.

**대화형 모드**: 인수 없이 명령을 실행하여 대화형 설정 마법사를 시작하세요.

```bash theme={null}
dodo-sync
```

**수동 모드**: 마법사를 건너뛰기 위해 인수를 직접 전달하세요.

```bash theme={null}
dodo-sync -i [interval] -d [database] -u [database_uri] --scopes [scopes] --api-key [api_key] --env [environment]
```

**예시:**

```bash theme={null}
# 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 인수

<ParamField path="--interval" type="number" alias="-i">
  초 단위 동기화 간격입니다. 동기화 작업이 실행되는 빈도를 결정합니다. 이 옵션을 제공하지 않으면 동기화는 한 번 실행된 후 종료됩니다.
</ParamField>

<ParamField path="--database" type="string" alias="-d" required>
  사용할 데이터베이스 유형입니다. 지원되는 값: `"mongodb"`, `"postgres"`, `"mysql"` 또는 `"clickhouse"`.
</ParamField>

<ParamField path="--database-uri" type="string" alias="-u" required>
  데이터베이스 연결 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`
</ParamField>

<ParamField path="--scopes" type="string" required>
  동기화할 데이터 엔터티를 쉼표로 구분하여 나열합니다. 가능한 범위: `licences`, `payments`, `customers`, `subscriptions`. 예시: `"payments,customers"`.
</ParamField>

<ParamField path="--api-key" type="string" required>
  Dodo Payments API 키입니다. 라이브 모드는 `dp_live_`로 시작해야 하고 테스트 모드는 `dp_test_`로 시작해야 합니다.
</ParamField>

<ParamField path="--env" type="string" required>
  환경 대상입니다. `"live_mode"` 또는 `"test_mode"` 중 하나여야 합니다. 이 설정은 어떤 Dodo Payments 환경에서 동기화를 수행할지를 결정합니다.
</ParamField>

<ParamField path="--rate-limit" type="number" alias="--rl">
  초당 요청 제한입니다. Dodo Payments API에 과도한 요청이 전송되지 않도록 동기화 엔진이 API 요청을 수행하는 속도를 제어합니다.
</ParamField>

### 코드에서 사용하기

프로그래밍 방식으로 제어하려면, 동기화 기능을 애플리케이션에 직접 통합하세요. 프로젝트에 종속성으로 설치하세요:

<CodeGroup>
  ```bash npm theme={null}
  npm install dodo-sync
  ```

  ```bash bun theme={null}
  bun add dodo-sync
  ```
</CodeGroup>

#### 자동 동기화 (간격 기반)

정기적으로 동기화가 지속적으로 실행되도록 하려면 자동 동기화를 사용하세요:

```typescript theme={null}
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();
```

<Tip>
  자동 동기화를 위해 `.start()`을 사용할 경우 `interval` 옵션이 필요합니다. 지정된 간격동안 프로세스를 중지할 때까지 동기화가 계속 실행됩니다.
</Tip>

#### 수동 동기화

수동 동기화는 필요할 때 동기화 작업을 트리거하려는 경우에 사용하세요 (예: 크론 작업 또는 API 엔드포인트에서):

```typescript theme={null}
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'
  }
});

// Initialize connection
await syncDodoPayments.init();

// Trigger a single sync operation
await syncDodoPayments.run();
```

<Tip>
  수동 동기화를 사용하는 경우 `interval` 옵션은 필요하지 않습니다. 동기화 작업이 필요할 때마다 `.run()`를 호출하면 됩니다.
</Tip>

#### PostgreSQL 예시

다음은 PostgreSQL에서 `dodo-sync`를 사용하는 방법입니다:

```typescript theme={null}
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 예시

다음은 MySQL에서 `dodo-sync`를 사용하는 방법입니다:

```typescript theme={null}
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 예시

다음은 ClickHouse에서 `dodo-sync`를 사용하는 방법입니다:

```typescript theme={null}
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();
```

#### 생성자 옵션

<ParamField body="database" type="string" required>
  사용할 데이터베이스 이름입니다. 지원되는 값: `"mongodb"`, `"postgres"`, `"mysql"` 또는 `"clickhouse"`.
</ParamField>

<ParamField body="databaseURI" type="string" required>
  데이터베이스 연결 문자열:

  * **MongoDB**: `mongodb://localhost:27017` 또는 `mongodb+srv://...`
  * **PostgreSQL**: `postgresql://user:password@localhost:5432/mydb`
  * **MySQL**: `mysql://user:password@localhost:3306/mydb`
  * **ClickHouse**: `http://localhost:8123`
</ParamField>

<ParamField body="scopes" type="string[]" required>
  동기화할 엔터티 배열입니다. 가능한 옵션: `"licences"`, `"payments"`, `"customers"`, `"subscriptions"`. 이들을 원하는 조합으로 포함할 수 있습니다.
</ParamField>

<ParamField body="dodoPaymentsOptions" type="object" required>
  인증 및 환경 선택을 위한 Dodo Payments API 구성입니다. 전체 옵션은 [TypeScript SDK 타입](https://github.com/dodopayments/dodopayments-typescript/blob/main/src/client.ts)을 참조하세요.

  **필수 속성:**

  * `bearerToken`: Dodo Payments API 키
  * `environment`: `"test_mode"` 또는 `"live_mode"` 중 하나
</ParamField>

<ParamField body="interval" type="number">
  자동 동기화에 `.start()`을 사용하는 경우 필요한 초 단위 간격입니다. 수동 동기화를 위해 `.run()`을 사용하는 경우에는 선택 사항입니다.
</ParamField>

<ParamField body="rateLimit" type="number">
  초당 요청 수입니다. Dodo Payments API에 과도한 요청을 보내지 않도록 동기화 엔진이 API 요청을 수행하는 속도를 제어합니다.
</ParamField>

## 중요 정보

<Warning>
  **MongoDB**: `dodopayments_sync`이라는 이름의 데이터베이스가 자동으로 생성되며, 모든 동기화 데이터는 해당 서버에 저장됩니다. 이 데이터베이스 이름은 현재 고정되어 있으며 변경할 수 없습니다.

  **PostgreSQL**: 연결 URI에 지정된 데이터베이스에 테이블 (`Subscriptions`, `Payments`, `Licenses`, `Customers`)이 생성됩니다. 데이터는 JSONB로 저장됩니다.

  **MySQL**: 연결 URI에 지정된 데이터베이스에 테이블 (`Subscriptions`, `Payments`, `Licenses`, `Customers`)이 생성됩니다. 데이터는 JSON으로 저장됩니다.

  **ClickHouse**: ReplacingMergeTree 엔진을 사용하여 테이블 (`Subscriptions`, `Payments`, `Licenses`, `Customers`)이 생성됩니다. 중복 없는 결과를 얻으려면 쿼리 시 `FINAL` 키워드를 사용하세요.
</Warning>

<Info>
  동기화 엔진은 변경 사항을 추적하여 새롭거나 업데이트된 레코드만 동기화하므로 대용량 데이터셋에서도 이후 동기화가 효율적입니다.
</Info>

## 추가 리소스

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodo-sync">
    소스 코드를 확인하거나 이슈를 신고하거나 개선 사항에 기여하세요
  </Card>

  <Card title="npm Package" icon="box-open" href="https://www.npmjs.com/package/dodo-sync">
    패키지 상세 정보와 설치 지침을 확인하세요
  </Card>
</CardGroup>