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

# 連接資料來源

> 新增 PostgreSQL、MySQL、Oracle 或 S3 上的 Parquet 連線，選擇資料表並瀏覽目錄

連線保存一個資料庫或 S3 儲存貯體的主機、資料庫與憑證。儲存後，再選擇哪些資料表要成為
分析資料可讀取的 **原始資料**。只有工作區 **管理員** 可以新增、編輯或刪除連線。

## 開始之前

* **使用唯讀帳號。** 建立一個只能 `SELECT` 你要登錄之資料表的資料庫角色。所有查詢都以這個
  角色執行，並看得到它能讀取的一切。PostgreSQL 可直接沿用
  [從程式碼查詢資料庫](/zh/data/query-from-code) 中建立唯讀使用者的步驟。
* **允許主機。** 分析服務只會連線到部署允許清單上的主機。部署管理員在管理頁面的
  **資料來源主機** 中管理這份清單。
* **確保網路可達。** DataGen 分析服務必須能透過網路連到資料庫（公開端點、VPN、對等互連，
  或在地端部署時位於同一私有網路）。

## 新增連線

<Steps>
  <Step title="開啟連線">
    前往 **資料 -> 連線**，點選 **連接原始資料**。
  </Step>

  <Step title="選擇原始資料類型">
    在 **原始資料類型** 中選擇 **PostgreSQL**、**MySQL / MariaDB**、**Oracle Database**
    或 **Parquet / S3**。（**工作區檔案** 請見[建立分析資料](/zh/data/build-models)。）
  </Step>

  <Step title="命名">
    輸入 **連線名稱**。資料庫連線還有 **SQL 別名**，也就是每個原始資料 SQL 名稱的中間段
    （`data.<別名>.<schema>.<資料表>`）。預設取自名稱，只能使用小寫英文字母、數字與底線，
    在工作區內必須唯一，之後無法變更。
  </Step>

  <Step title="填寫欄位">
    依照提供者填寫欄位（見下方分頁），並選擇 **TLS** 模式。
  </Step>

  <Step title="儲存">
    點選 **儲存連線**。DataGen 會先用這組憑證實際連線再儲存：主機、連接埠或密碼錯誤時，
    會在這一步顯示資料庫的錯誤訊息。
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/datagen/rusBmwP8bd_Srmdm/images/browser-guide/zh/connect-postgres.jpg?fit=max&auto=format&n=rusBmwP8bd_Srmdm&q=85&s=ac540b0b74419a42509d7623a96a1214" alt="新增 PostgreSQL 連線表單；尚未填入或儲存" width="838" height="863" data-path="images/browser-guide/zh/connect-postgres.jpg" />
</Frame>

### 各提供者的欄位

<Tabs>
  <Tab title="PostgreSQL">
    | 欄位 | 說明 |
    | - | - |
    | **主機**、**連接埠** | 連接埠預設 `5432`。 |
    | **資料庫** | 要連線的資料庫。 |
    | **使用者名稱**、**密碼** | 唯讀角色。加密儲存。 |
    | **Schema（以逗號分隔）** | 可登錄資料表的 schema。預設 `public`。 |
    | **TLS** | **驗證憑證與主機名稱**（預設）、**必須使用 TLS**、**可用時使用 TLS（私有網路）**、**不使用 TLS（僅限私有開發環境）**。 |
  </Tab>

  <Tab title="MySQL / MariaDB">
    | 欄位 | 說明 |
    | - | - |
    | **主機**、**連接埠** | 連接埠預設 `3306`。 |
    | **資料庫** | 要連線的資料庫。 |
    | **使用者名稱**、**密碼** | 唯讀帳號。加密儲存。 |
    | **資料庫（以逗號分隔；留空則使用上方的資料庫）** | MySQL 把 schema 稱為資料庫。留空表示只使用上方的資料庫。 |
    | **TLS** | **驗證憑證與主機名稱**（預設）、**必須使用 TLS**、**不使用 TLS（僅限私有開發環境）**。 |
  </Tab>

  <Tab title="Oracle Database">
    | 欄位 | 說明 |
    | - | - |
    | **主機**、**連接埠** | 連接埠預設 `1521`。 |
    | **服務名稱** 或 **SID** | 兩者擇一填寫。 |
    | **使用者名稱**、**密碼** | 唯讀使用者。加密儲存。 |
    | **Schema（以逗號分隔；留空則使用該使用者自己的 Schema）** | 可登錄其資料表的擁有者。 |
    | **TLS** | **驗證憑證與主機名稱**（預設）、**Oracle 原生加密（不需憑證；適用所有版本）**、**不使用 TLS（僅限私有開發環境）**。 |
  </Tab>

  <Tab title="Parquet / S3">
    | 欄位 | 說明 |
    | - | - |
    | **S3 端點** | 相容 S3 的端點 URL。 |
    | **儲存貯體** | 存放 Parquet 檔案的儲存貯體。 |
    | **物件前綴** | 選填，儲存貯體內的資料夾。 |
    | **區域** | 預設 `us-east-1`。 |
    | **存取金鑰 ID**、**秘密存取金鑰** | 能讀取該儲存貯體的金鑰。加密儲存。 |

    Parquet / S3 連線沒有 SQL 別名，其原始資料使用 `data.<id>` 形式的 SQL 名稱。
  </Tab>
</Tabs>

<Tip>
  在你自行選擇 TLS 模式之前，表單會依輸入的主機建議一個模式。凡是可經由網際網路連到的
  資料庫，請保留 **驗證憑證與主機名稱**。
</Tip>

## 選擇資料表

新的連線還沒有任何原始資料。點選連線卡片上的 **管理資料表** 開啟資料表選擇器。

<Steps>
  <Step title="找到資料表">
    DataGen 會列出帳號在設定的 schema 中看得到的資料表。用 **搜尋資料表…** 依名稱篩選，
    或依 **結構** 篩選。每一列都會顯示該資料表將取得的 SQL 名稱。
  </Step>

  <Step title="選取">
    逐一勾選，或點選 **選取所有符合項目**。每次最多儲存 100 個資料表。
  </Step>

  <Step title="儲存">
    點選 **儲存資料表選取**。選取的資料表會出現在 **資料集 -> 原始資料** 與該連線名稱底下。
  </Step>
</Steps>

從選取中移除資料表只會移除原始資料，不會變更任何資料庫權限。已發布分析資料正在讀取的
原始資料無法移除。

<Note>
  PostgreSQL、MySQL 與 Oracle 連線不需登錄任何資料表，就能給 **原生 SQL** 分析資料使用。
  請參閱[建立分析資料](/zh/data/build-models)。
</Note>

## 瀏覽目錄

**資料集** 是工作區的目錄。左側依 **所有資料集**、**原始資料**、**分析資料** 與各連線分組；
搜尋框會比對名稱與說明。

<Frame>
  <img src="https://mintcdn.com/datagen/rusBmwP8bd_Srmdm/images/browser-guide/zh/data-catalog.jpg?fit=max&auto=format&n=rusBmwP8bd_Srmdm&q=85&s=b2b7e54179f59f34572b658019e35bbf" alt="Neon test 連線的原始資料表清單" width="838" height="863" data-path="images/browser-guide/zh/data-catalog.jpg" />
</Frame>

開啟一個原始資料可以看到：

* **資料**：最多 500 列的預覽，每頁 50 列，直接從資料庫即時讀取。
* **結構**：欄位與型別、**原始資料說明**，以及每個欄位的說明。說明儲存在 DataGen 中，
  資料建構器與 Agent 都看得到。

資料集名稱旁的動作選單中有 **複製 SQL 查詢名稱**。

## 維護連線

| 工作 | 做法 |
| - | - |
| 偵測欄位變更 | 連線卡片上的 **重新整理結構** 會檢查每個已登錄的資料表，回報新增、移除與型別變更的欄位。 |
| 新增或移除資料表 | 再次開啟 **管理資料表**。既有原始資料的 SQL 名稱維持不變。 |
| 變更主機或憑證 | **編輯連線**（鉛筆圖示）。認證欄位留空即可保留已儲存的認證資訊。原始資料類型與 SQL 別名無法變更。 |
| 刪除 | **刪除連線**（垃圾桶圖示）會移除連線及從它匯入的所有原始資料。若有原生 SQL 分析資料在該連線上執行，刪除會被拒絕。 |

## 連線憑證如何儲存

連線憑證（使用者名稱、密碼、存取金鑰）經過加密，與連線一起儲存在 DataGen 中。它們不是
[連線保險庫](/zh/foundation/vault) 中的項目，不會回傳到瀏覽器，也不會放進 Agent 的沙盒：

* 分析服務在預覽、發布或更新分析資料時，用它們讀取原始資料。
* Agent 只讀取發布後的快照，因此完全不需要資料庫憑證。
* 資料建構器 Agent 透過 DataGen 的 SQL 代理（在有部署代理的環境中）查詢 PostgreSQL
  原始資料，憑證由代理保管；其他原始資料則由分析服務代為查詢。

**資料 -> 設定** 中選擇的 **連線保險庫** 是另一回事：它提供憑證給資料建構器 Agent 自己的
工具，而不是給連線使用。

## 下一步

<CardGroup cols={2}>
  <Card title="建立分析資料" icon="hammer" href="/zh/data/build-models">
    把原始資料變成已發布、附說明文件的分析資料。
  </Card>

  <Card title="資料總覽" icon="database" href="/zh/data/overview">
    回顧生命週期、SQL 名稱、角色權限與限制。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.