Atoms 雲資料庫會儲存並管理您的 app 所依賴的結構化資料，包括產品、預約、訂單、表單提交內容，以及使用者產生的內容。在資料庫模組中，您可以檢視環境與資料表、搜尋及編輯記錄、檢查資料表結構，並使用 CSV 檔案匯入或匯出資料。

本指南涵蓋內建於 Atoms 雲 的資料庫。如果您的專案使用 Supabase，請改為參閱 Supabase 整合。

開啟資料庫

在開啟資料庫之前，請先將您的專案連接到 Atoms 雲。如果尚未連接，請依照 Atoms 雲 中的連接步驟操作。

1. 在桌面裝置上開啟您的專案。
2. 在與 App 預覽 所在相同的工作區工具列中，選取 Atoms 雲。
3. 在 Atoms 雲側邊欄中選取 資料庫。
4. 在 Databases 下，選取您想檢查的資料庫。當專案可用時，會顯示 Development 與 Production 資料庫卡片。

每張資料庫卡片都會顯示目前已使用的儲存空間與可用總量。建置與測試您的 app 時，請使用 Development。在 Production 中所做的變更可能會影響正式上線 app 的資料，因此在進行變更前，請務必確認您目前所在的環境。

選擇 Development 或 Production 資料庫。

瀏覽與篩選資料表資料

1. 依您想操作的環境，選取 Development 或 Production 資料庫卡片。
2. 使用 Search tables 尋找資料表，或直接從清單中選取。每張資料表卡片都會顯示其資料列數，以及是否為唯讀。
3. 使用 Search rows 在目前資料表內搜尋，或選取 Filter 以使用一個或多個欄位縮小結果範圍。
4. 使用資料表下方的頁面箭頭控制項來檢視更多資料列。
5. 若要檢查資料表結構，請開啟 ••• 選單並選取 Schema。

Schema 檢視會顯示每個欄位的名稱、資料類型、鍵狀態、需求、限制條件與預設值。選取 Copy 可複製顯示中的結構描述。

新增、編輯或刪除資料列

當您找到想要變更的資料庫後，可以使用以下操作：

操作	操作方式
新增資料列	開啟 ... 並選取 Add Row。輸入符合可用欄位的值，然後提交該資料列。
編輯資料列	按兩下儲存格並輸入新值。選取 Commit Changes 以儲存所有待處理編輯，或選取 Discard 以移除它們。
刪除資料列	選取一列或多列資料，選取 Delete，然後確認。資料列刪除後無法復原。

新增資料列或確認刪除時，變更會立即套用到所選資料庫。只有行內儲存格編輯需要您選取 Commit Changes 或 Discard。如果您有任何待處理編輯，請先提交或捨棄它們，再新增資料列、匯入或匯出 CSV 檔案、變更搜尋或篩選條件，或導覽至其他頁面。

如果專案位於工作區中，只有 Editors 與 workspace owner 可以編輯可寫入資料表中的資料列。如果 Atoms 無法偵測資料表的主鍵，您將無法編輯或刪除其資料列，因為 Atoms 無法可靠地識別個別記錄。

檢查待處理的資料列編輯，然後提交或捨棄變更。

建立資料表或變更結構描述

開啟您想更新的資料庫環境，然後依照您想進行的變更說明操作：

操作	操作方式
建立資料表	在資料表清單中，按一下 ...，然後選取 Create table。輸入有效的資料表名稱與初始欄位，然後提交請求。等待智能體完成後，重新開啟 資料庫 並確認資料表。
變更結構描述	按一下您想變更的資料表，然後按一下 ...，再選取 Schema. 使用 Add Field 建立欄位，或選取符合條件的欄位進行編輯。您可以變更其名稱、類型、預設值、必填狀態或唯一性。您也可以將非鍵欄位標記為刪除。選取 Submit Changes 將請求送交智能體，或選取 Discard 清除待處理變更。

只有 workspace owner 可以建立資料表或變更資料表的結構描述。

提交結構描述請求並不代表遷移已完成。請等待智能體完成，在 資料庫 中確認結果，並於之後測試您的 app。主鍵欄位與唯讀資料表無法透過此方式修改。

在 Add Field 中輸入新欄位的詳細資料。

在選取 Submit Changes 之前，先檢查待處理的結構描述變更。

匯入或匯出 CSV 資料

選取您想操作的資料表，然後依照相關操作的說明進行：

操作	操作方式
匯入 CSV	按一下 ... 並選取 Import CSV。選擇一個不超過 10 MB 的 .csv 檔案，然後在確認前檢查檔名、預估資料列數、所選資料表與環境。CSV 欄位必須符合資料表結構描述。匯入的資料列會立即新增，且無法自動復原，因此建議您先匯出現有資料。
匯出 CSV	按一下 ... 並選取 Export CSV。如果搜尋或篩選條件已啟用，則只會匯出符合條件的資料列。否則，會匯出目前資料表中的所有資料。

只有 workspace owner 可以匯入或匯出 CSV 檔案。對於唯讀資料表， Export CSV 是唯一可用的選項。

權限與受保護資料表

操作	可執行者	其他要求
新增、編輯或刪除資料列	Editor 或 workspace owner	資料表必須可寫入。編輯與刪除資料列也需要主鍵資訊。
建立資料表或變更結構描述	Workspace owner	主鍵欄位與唯讀資料表無法修改。
匯入或匯出 CSV 檔案	Workspace owner	CSV 檔案無法匯入唯讀資料表。

受保護的系統或使用者資料表可能會顯示 Read-only 標記。您可以檢視其資料，並在可用時檢查其結構描述，但無法從此頁面修改其資料列或結構。

修正常見資料庫問題

「No databases found」或「No tables found」

請確認 Atoms 雲 已連接至專案。如果已經連接，請確認您的 app 包含會儲存持久性資料的功能。如有需要，請要求智能體新增以資料庫為基礎的功能。待智能體完成後，重新開啟 資料庫 或選取 Refresh。

資料庫操作遺失或無法使用

請檢查資料表是否有 Read-only 標記，然後查看上方權限說明，以確認您的工作區角色允許執行該操作。編輯與刪除資料列也需要主鍵資訊。

待處理的資料列編輯可能會阻止其他操作。在新增資料列、匯入或匯出 CSV 檔案、變更搜尋或篩選條件，或移動到其他頁面之前，請先選取 Commit Changes 或 Discard。

如果完成這些檢查後該操作仍無法使用，請聯絡 Support，並附上專案或 Chat 連結、環境、資料表、工作區角色、嘗試執行的操作，以及完整的錯誤文字。

CSV 檔案無法匯入

只有 workspace owner 可以匯入資料，而且目標資料表必須可寫入。請確認：

• 檔案使用 .csv 格式。
• 檔案大小不超過 10 MB。
• 其欄位與資料與目標資料表的結構描述相容。
• 您已提交或捨棄所有待處理的資料列編輯。

如果匯入仍然失敗，請聯絡 Support，並附上專案或 Chat 連結、環境、目標資料表、工作區角色、檔名與大小、嘗試執行的操作，以及完整的錯誤文字。

常見問題

我的正式環境資料庫沒有同步。我該怎麼做？

如果 Development 運作正常，但正式網站（Production）顯示缺少資料表、欄位或遷移錯誤：

重要：請勿自行重建或覆寫正式環境資料庫。

需要提供的資訊：

• Chat 連結與正式網址
• 完整 SQL 錯誤訊息
• 缺少的資料表／欄位名稱
• 最近一次資料庫結構描述變更
• 最後一個正常運作的正式版本
• 是否必須保留正式環境資料
• 您是想完整同步 Development 資料，還是只補齊缺少的結構

請將這些資訊提供給支援團隊，以便我們在進行變更前比較 Development／Production 版本、遷移狀態與結構描述差異。

為什麼我的開發資料與正式資料不同？

如果您已發佈多次，但 Production 仍顯示舊資料，而程式碼更新運作正常：

在聯絡支援之前，請先確認：

1. 目前的正式環境資料是否必須保留？

2. 您想以目前的 Development 資料完整覆寫，還是只補齊缺少的記錄？

3. 您是否已經有備份？

4. 您可接受的維護時段為何？

在確認資料處理目標之前，我們不會覆寫或重建正式環境資料。請提供 Development／Production 網址，以及可顯示差異的範例記錄 ID 或數量。