# PostgreSQL Export Integration

Treasure Dataからジョブ結果を既存のPostgreSQLインスタンスにエクスポートできます。PostgreSQLデータのインポートについては、[PostgreSQL Import Integration](http://docs.treasuredata.com/display/INT/PostgreSQL+Import+Integration)を参照してください。

このトピックには以下が含まれます:

## 前提条件

- [TD Toolbelt](https://toolbelt.treasuredata.com/)を含む、Treasure Dataの基本的な知識。
- **PostgreSQLインスタンス**。


## Treasure Data Integration の静的 IP アドレス

セキュリティポリシーで IP ホワイトリストが必要な場合は、接続を成功させるために Treasure Data の IP アドレスを許可リストに追加する必要があります。

リージョンごとに整理された静的 IP アドレスの完全なリストは、次のリンクにあります:
[https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/](https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/)

## TD Consoleを使用した接続の作成

### 新しい接続の作成

1. 新しい接続を作成するために、以下のフィールド値を設定します。
![](/assets/postgresql-export-integration-2024-07-26.55b61de5bfe82f4f7a3cac20923331fca9118744d7cff08100fc6a21535a4ade.272a20fd.png)


- **Host**: ソースデータベースのホスト情報（IPアドレスなど）。
- **User**: ソースデータベースに接続するためのユーザー名。
- **Password**: ソースデータベースに接続するためのパスワード。
- **Use SSL**: SSLを使用して接続する場合はこのボックスにチェックを入れます
  - **Require a valid SSL certificate?:** 接続時に有効なSSL証明書の提示を要求します。


### PostgreSQLインスタンスへの結果エクスポートの設定

Treasure Dataからのエクスポートはクエリを使用します。クエリは新規作成することも、既存のものを再利用することもできます。クエリ内でデータ接続を設定します。

1. [Creating a Destination Integration](https://docs.treasuredata.com/display/PD/Creating+a+Destination+Integration)の手順を完了します。
2. **Data Workbench > Queries**に移動します。
3. データをエクスポートしたいクエリを選択します。
4. クエリを実行して結果セットを検証します。
5. **Export Results**を選択します。
6. 既存の統合認証を選択します。
![](/assets/postgresql-export-integration-2024-08-13-1.976a84340b2212cab5deded4fdbd2313767ee9357fc1800030b207f9fc1a3afd.272a20fd.png)
7. 追加のExport Resultsの詳細を定義します。エクスポート統合の内容で、統合パラメータを確認してください。
例えば、Export Results画面が異なる場合や、入力する追加の詳細がない場合があります:
![](/assets/postgresql-export-integration-2024-08-13-2.cb87c5dd29a338e49ba6b46f2d4046dc95f4cd912a038417158d84f305510c64.272a20fd.png)
8. **Done**を選択します。
9. クエリを実行します。
10. 指定した宛先にデータが移動したことを検証します。


### Export Resultパラメータの設定

![](/assets/postgresql-export-integration-2024-07-26-1.169ea3b63d2f08e8e6288aff3e9c8723312703e71198ea92889ee6ea3510be19.272a20fd.png)

- **Database name**: データを転送するデータベースの名前。(例: `your_database_name`)
- **Table**: データをエクスポートしたいテーブル。
- **Output mode**: データをアップロードするための異なる方法。
  - **Append** (デフォルト): **append**モードは、URLにモードオプションが指定されていない場合に使用される**デフォルト**モードです。このモードでは、クエリ結果がテーブルに追加されます。テーブルが存在しない場合は作成されます。このモードはアトミックです。
  - **Replace**: **replace**モードは、既存のテーブルの全コンテンツをクエリの結果出力で置き換えます。テーブルがまだ存在しない場合は、新しいテーブルが作成されます。replaceモードは、以下の3つのステップを**単一のトランザクション**で実行することで**アトミック性**（テーブルの消費者が常に一貫したデータを持つこと）を実現します:
    1. 一時テーブルを作成する
    2. 一時テーブルに書き込む
    3. ALTER TABLE RENAMEを使用して既存のテーブルを一時テーブルで置き換える
    - **Truncate:** システムはまず既存のテーブルをtruncateし、その後クエリ結果を挿入します。テーブルがまだ存在しない場合は、新しいテーブルが作成されます。このモードはアトミックです。
    - **Update:** "unique"パラメータで指定された列に重複値が発生しない限り、行が挿入されます。重複する場合は、代わりに更新が実行されます。updateモードを使用する場合、"unique"パラメータが必要です。このモードはアトミックです。
    - **Insert Method**: このオプションは、データがPostgresテーブルにどのように書き込まれるかを制御します。デフォルトの方法は**copy**で、ほとんどの状況で推奨されます。
    - **Copy**(デフォルト): データはまずサーバー上の一時ファイルに保存され、その後[COPY](http://www.postgresql.org/docs/8.1/static/sql-copy.md)トランザクションを使用してPostgresに書き込まれます。この方法はINSERTよりも高速なので、大量のデータを処理する際に便利です。
    - **Insert**: データは'INSERT'ステートメントを使用してPostgresに書き込まれます。これは最も信頼性が高く互換性のある方法で、ほとんどの状況で推奨されます。
    - **Schema**: ターゲットテーブルが配置されているスキーマを定義します。指定されていない場合は、デフォルトのスキーマが使用されます。デフォルトのスキーマはユーザーの"search_path"設定によりますが、通常は"public"です。
    - **Foreign Data Wrapper**: このオプションは、データの保存にデータラッパーを使用するかどうかを制御します。デフォルトはnoneで、ほとんどのインスタンスで機能するはずです。
    - **None** (デフォルト) - foreign-data wrapperなし。
    - **Cstore** - 宛先テーブルでカラムナストレージが必要/有効になっている場合に使用されます。


### (オプション) Query Export ジョブをスケジュールする

Scheduled Jobs と Result Export を使用して、指定したターゲット宛先に出力結果を定期的に書き込むことができます。

Treasure Data のスケジューラー機能は、高可用性を実現するために定期的なクエリ実行をサポートしています。

2 つの仕様が競合するスケジュール仕様を提供する場合、より頻繁に実行するよう要求する仕様が優先され、もう一方のスケジュール仕様は無視されます。

例えば、cron スケジュールが `'0 0 1 * 1'` の場合、「月の日」の仕様と「週の曜日」が矛盾します。前者の仕様は毎月 1 日の午前 0 時 (00:00) に実行することを要求し、後者の仕様は毎週月曜日の午前 0 時 (00:00) に実行することを要求するためです。後者の仕様が優先されます。

#### TD Console を使用してジョブをスケジュールする

1. **Data Workbench > Queries** に移動します
2. 新しいクエリを作成するか、既存のクエリを選択します。
3. **Schedule** の横にある None を選択します。
![](/assets/image2021-1-15_17-28-51.f1b242f6ecc7666a0097fdf37edd1682786ec11ef80eff68c66f091bc405c371.0f87d8d4.png)
4. ドロップダウンで、次のスケジュールオプションのいずれかを選択します:
![](/assets/image2021-1-15_17-29-47.45289a1c99256f125f4d887e501e204ed61f02223fde0927af5f425a89ace0c0.0f87d8d4.png)
| ドロップダウン値 | 説明 |
|  --- | --- |
| Custom cron... | [Custom cron... の詳細](#custom-cron-details)を参照してください。 |
| @daily (midnight) | 指定されたタイムゾーンで 1 日 1 回午前 0 時 (00:00 am) に実行します。 |
| @hourly (:00) | 毎時 00 分に実行します。 |
| None | スケジュールなし。 |


#### Custom cron... の詳細

![](/assets/image2021-1-15_17-30-23.0f94a8aa5f75ea03e3fec0c25b0640cd59ee48d1804a83701e5f2372deae466c.0f87d8d4.png)

| **Cron 値** | **説明** |
|  --- | --- |
| `0 * * * *` | 1 時間に 1 回実行します。 |
| `0 0 * * *` | 1 日 1 回午前 0 時に実行します。 |
| `0 0 1 * *` | 毎月 1 日の午前 0 時に 1 回実行します。 |
| "" | スケジュールされた実行時刻のないジョブを作成します。 |



```
 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- day of week (0 - 6) (Sunday=0)
 |    |    |    +---------- month (1 - 12)
 |    |    +--------------- day of month (1 - 31)
 |    +-------------------- hour (0 - 23)
 +------------------------- min (0 - 59)
```

次の名前付きエントリを使用できます:

- Day of Week: sun, mon, tue, wed, thu, fri, sat.
- Month: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec.


各フィールド間には単一のスペースが必要です。各フィールドの値は、次のもので構成できます:

| フィールド値  | 例  | 例の説明  |
|  --- | --- | --- |
| 各フィールドに対して上記で表示された制限内の単一の値。 |  |  |
| フィールドに基づく制限がないことを示すワイルドカード
`'*'`。 | `'0 0 1 * *'` | 毎月 1 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| 範囲 `'2-5'`
フィールドの許可される値の範囲を示します。 | `'0 0 1-10 * *'` | 毎月 1 日から 10 日までの午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| カンマ区切りの値のリスト `'2,3,4,5'`
フィールドの許可される値のリストを示します。 | `0 0 1,11,21 * *'` | 毎月 1 日、11 日、21 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| 周期性インジケータ `'*/5'`
フィールドの有効な値の範囲に基づいて、
スケジュールが実行を許可される頻度を表現します。 | `'30 */2 1 * *'` | 毎月 1 日、00:30 から 2 時間ごとに実行するようにスケジュールを設定します。
`'0 0 */5 * *'` は、毎月 5 日から 5 日ごとに午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| `'*'`
ワイルドカードを除く上記の
いずれかのカンマ区切りリストもサポートされています
`'2,*/5,8-10'` | `'0 0 5,*/10,25 * *'` | 毎月 5 日、10 日、20 日、25 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |


1. (オプション) Delay execution を有効にすることで、クエリの開始時刻を遅延させることができます。


### クエリを実行する

クエリに名前を付けて保存して実行するか、単にクエリを実行します。クエリが正常に完了すると、クエリ結果は指定された宛先に自動的にエクスポートされます。

設定エラーにより継続的に失敗するスケジュールジョブは、複数回通知された後、システム側で無効化される場合があります。

(オプション) Delay execution を有効にすることで、クエリの開始時刻を遅延させることができます。

## Audience Studio で Segment をアクティベートする

Audience Studio で activation を作成することで、segment データをターゲットプラットフォームに送信することもできます。

1. **Audience Studio** に移動します。
2. parent segment を選択します。
3. ターゲット segment を開き、右クリックして、**Create Activation** を選択します。
4. **Details** パネルで、Activation 名を入力し、前述の Configuration Parameters のセクションに従って activation を設定します。
5. **Output Mapping** パネルで activation 出力をカスタマイズします。


![](/assets/ouput.b2c7f1d909c4f98ed10f5300df858a4b19f71a3b0834df952f5fb24018a5ea78.8ebdf569.png)

- Attribute Columns
  - **Export All Columns** を選択すると、変更を加えずにすべての列をエクスポートできます。
  - **+ Add Columns** を選択して、エクスポート用の特定の列を追加します。Output Column Name には、Source 列名と同じ名前があらかじめ入力されます。Output Column Name を更新できます。**+ Add Columns** を選択し続けて、activation 出力用の新しい列を追加します。
- String Builder
  - **+ Add string** を選択して、エクスポート用の文字列を作成します。次の値から選択します:
    - String: 任意の値を選択します。テキストを使用してカスタム値を作成します。
    - Timestamp: エクスポートの日時。
    - Segment Id: segment ID 番号。
    - Segment Name: segment 名。
    - Audience Id: parent segment 番号。


1. **Schedule** を設定します。


![](/assets/snippet-output-connector-on-audience-studio-2024-08-28.a99525173709da1eb537f839019fa7876ffae95045154c8f2941b030022f792c.8ebdf569.png)

- スケジュールを定義する値を選択し、オプションでメール通知を含めます。


1. **Create** を選択します。


batch journey の activation を作成する必要がある場合は、[Creating a Batch Journey Activation](/products/customer-data-platform/journey-orchestration/batch/creating-a-batch-journey-activation) を参照してください。

## (オプション) CLIを使用したエクスポート統合

TD Consoleが利用できない場合、またはニーズを満たさない場合は、CLIを使用してクエリを発行し、結果を出力できます。以下の手順では、CLIを使用してクエリ出力結果をフォーマットする方法を示します。

### td query コマンドの使用方法

単一クエリの結果を Postgres サーバーに出力するには、`td query` コマンドに `--result` オプションを追加します。ジョブが完了すると、結果がデータベースに書き込まれます:


```bash
td query -w -d testdb \
--result 'postgresql://user:password@host/database/table' \
"SELECT code, COUNT(1) FROM www_access GROUP BY code"
```

出力が体系的に Postgres に書き込まれるスケジュールクエリを作成するには、td sched:create コマンドでスケジュールを作成する際に `--result` オプションを追加します:


```bash
td sched:create hourly_count_example "0 * * * *" \
-d testdb \
--result 'postgresql://user:password@host/database/table' \
"SELECT COUNT(*) FROM www_access"
```

### 結果出力 URL フォーマット

結果出力先は、次のフォーマットの URL で表されます:

`postgresql:``//username:password@hostname:port/database/table`

各項目の説明:

- **postgresql** は Postgres への結果出力を識別します
- **username** と **password** は Postgres サーバーへの認証情報です
- **hostname** は Postgres サーバーのホスト名です
- **port** は Postgres サーバーにアクセスするためのポート番号です。「:」はオプションであり、デフォルトでは 5432 と見なされます
- **database** は宛先データベースの名前です
- **table** は上記のデータベース内のテーブル名です。クエリ出力が実行される時点で存在しない場合は、指定された名前のテーブルがユーザーのために作成されます


### オプション

Postgres への結果出力は、オプションの URL パラメータとして指定できる様々なオプションをサポートしています。これらのオプションは互いに互換性があり、組み合わせることができます。該当する場合、デフォルトの動作が示されています。

### SSL オプション

**ssl** オプションは、Postgres サーバーへの接続に SSL を使用するかどうかを決定します。

Treasure Data から Postgres サーバーへの接続に SSL を使用します。Postgres サーバーは [SSL 接続を受け入れるように設定されている](http://www.postgresql.org/docs/current/static/ssl-tcp.md) 必要があります。

`postgresql://user:password@host/database/table?ssl=true`

Treasure Data から Postgres サーバーへの接続に SSL を使用しません。

`postgresql://user:password@host/database/table?ssl=false`

### Schema オプション

対象テーブルが配置されているスキーマを制御します。指定されていない場合は、デフォルトのスキーマが使用されます。デフォルトのスキーマはユーザーの「search_path」設定に依存しますが、通常は「public」です。

`postgresql://user:password@host/database/table?schema=target_schema`

### Update Mode オプション

データベースデータを変更する様々な方法を制御します。サポートされている 4 つのモードはすべて**アトミック**です。これは、宛先テーブルの変更を試みる前に、一時テーブルを使用して受信データを保存するためです:

- Append
- Replace
- Truncate
- Update


#### mode=append (デフォルト)

**append** モードはデフォルトで、URL にモードオプションが指定されていない場合に使用されます。このモードでは、クエリ結果がテーブルに追加されます。テーブルが存在しない場合は、テーブルが作成されます。

`mode=append` がデフォルトの動作であるため、次の 2 つの URL は同等です:

- postgresql://user:password@host/database/table
- postgresql://user:password@host/database/table?mode=append


#### mode=replace

**replace** モードは、既存のテーブルの内容全体をクエリの出力結果で置き換えます。テーブルがまだ存在しない場合は、新しいテーブルが作成されます。replace モードは、**単一トランザクション**内で以下の3つのステップを実行することにより、**原子性**を実現します(テーブルの利用者が常に一貫したデータを持つことを保証します)。

1. 一時テーブルを作成します。
2. 一時テーブルに書き込みます。
3. ALTER TABLE RENAME を使用して、既存のテーブルを一時テーブルで置き換えます。


例:

- `postgresql://user:password@host/database/table?mode=replace`


#### mode=truncate

**truncate** モードでは、システムはまず既存のテーブルをトランケートし、その後クエリ結果を挿入します。テーブルがまだ存在しない場合は、新しいテーブルが作成されます。

例:

`postgresql://user:password@host/database/table?mode=truncate`

replace とは異なり、truncate モードではテーブルのインデックスが保持されます。

#### mode=update

**update** モードでは、挿入される行が "unique" パラメータで指定された列に重複する値を引き起こす場合を除き、行が挿入されます。そのような場合は、挿入の代わりに行の更新が実行されます。update モードを使用する場合は、"unique" パラメータが必要です。

例:

1. `postgresql://...?mode=update&unique=col1`        # 単一のユニーク列
2. `postgresql://...?mode=update&unique=[col1,col2]` # 複数のユニーク列


### Write method オプション

**method** オプションは、データが Postgres テーブルに書き込まれる方法を制御します。以下を使用できます:

- method=insert
- method=copy


デフォルトのメソッドは **insert** で、ほとんどの状況で推奨される方法です。

#### method=insert (デフォルト)

**insert** メソッドでは、データは 'INSERT' ステートメントを使用して Postgres に書き込まれ、最も信頼性が高く互換性のある方法です。

`method=insert` はデフォルトの動作であるため、以下の2つの URL は同等です:

1. `postgresql://user:password@host/database/table`
2. `postgresql://user:password@host/database/table?method=insert`


#### method=copy

**copy** メソッドを使用すると、データはまずサーバー上の一時ファイルに保存され、その後 [COPY](http://www.postgresql.org/docs/8.1/static/sql-copy.md) トランザクションを使用して Postgres に書き込まれます。このメソッドは INSERT よりも高速であるため、大量のデータを処理する場合に便利です。

例:

`postgresql://user:password@host/database/table?method=copy`

## (オプション) ワークフローでのエクスポート結果の設定

Treasure Workflow 内で、このデータコネクタを使用してデータを出力することを指定できます。


```yaml
timezone: UTC

_export:
  td:
    database: sample_datasets

+td-result-output-postgresql:
  td>: queries/sample.sql
  result_connection: your_connections_name
  result_settings:
   database: database_name
   table: table_name
   mode: append
   set_role: new_role
```

[ワークフロー内でデータコネクタを使用してデータをエクスポートする方法](http://docs.treasuredata.com/display/PD/About+Using+Workflows+to+Export+Data+with+TD+Toolbelt)についてお読みください。[ワークフローの例](https://github.com/treasure-data/workflow-examples/tree/master/td/postgresql)をご覧ください。