今天我們開始來熟悉一下EdgeDB的基本知識，而EdgeDB在各作業系統的安裝方法可以參考官方文件。

Scalar type

scalar type包含了如str、bool、int64等primitive以及array、tuple及range等作為容器的collection type。

object type

object type則為自定義的型態。每一個object type可以包含property或使用link與其它object type連接。

property則像是primitive的wrapper，在其上加上一些預設值或是限制。

link就像一種relationship，可以透過它來連接其它的object type。

required vs optional

所有property與link預設為optional，可以省略不寫。如果為必須提供的，需要加上required。

single vs multi

所有property與link預設為single，可以省略不寫。如果property可包含一個以上的scalar type（需為同一型別）又或是link可包含一個以上的object type（需為同一型別），就需要加上multi。

Types, not tables

schema是EdgeDB的核心，包含了許多object type（schema不只有object type，還有如function及alias等其它東西），類似於傳統database中的table。

type Person {
  required name: str;
}

type Movie {
  required title: str;
  multi actors: Person;
}

舉例來說，上面這個schema內定義了：

• Person object type

  • 內含一個名為「"name"」的property，且為required及single，即每次insert時都要提供一個str型態。

• Movie object type

  • 內含一個名為「"title"」的property，且為required及single，即每次insert時都要提供一個str型態。
  • 內含一個名為「"actors"」的link，且為optional及multi，即每次insert時不一定要提供；但如果有提供的話，可以包含一個以上的Person object。

Objects, not rows

EdgeQL（EdgeDB SQL）讓我們可以使用更簡潔的語法來針對所選取的object進行操作。每一個object，類似於傳統database中的row。

select Movie {
  title,
  actors: {
    name
  }
}
filter .title = "The Matrix"

舉例來說，上面這個EdgeQL選取了所有title property為「"The Matrix"」的Movie object，並顯示出title property及actors link中的name property。

EdgeDB cli基礎語法

這裡我們介紹如何使用cli與EdgeDB互動。

1. 首先利用edgedb project init，建立專案資料夾，過程中會詢問instance名字及使用的版本。接著EdgeDB會幫忙建立instance，並建立一個dbschema資料夾，裡面有一個default.esdl，我們可以將schema全部置於其內的default module（註1）。此外dbschema資料夾還有一個空的migrations資料夾，用來存放每次migration的指令。

2. 定義好schema後，執行edgedb migration create，會於dbschema/migrations中建立副檔名為.edgeql的檔案，用來記錄每次migration的變化。

3. 執行edgedb migrate後，將會正式執行dbschema/migrations內的每一次migration。

4. 接著於專案資料夾輸入EdgeDB，即可進入到該instance REPL。此時可以使用EdgeQL與instace互動。

5. 如果想刪除所有的object，可以依照下面步驟執行：
   5.1 執行edgedb branch wipe main並鍵入Yes來刪除所有的object。

   5.2 執行edgedb migrate。

6. 如果想要重置main branch時，可以依照下面步驟執行：

   6.1 執行edgedb branch wipe main並鍵入Yes來刪除所有的object。

   6.2 刪除dbschema/migrations中的所有*.edgeql檔案。

   6.3 重新編寫新的schema至default.esdl。預設的default.esdl應該只有：

   module default {}
   

   6.4 執行edgedb migration create及edgedb migrate。

7. 如果您需要一直測試schema，而需要反覆重置main branch時，可以將步驟簡化為：
   7.1 修改default.esdl。

   7.2 刪除dbschema/migrations中的所有*.edgeql檔案。

   7.3 執行edgedb branch wipe main --non-interactive && edgedb migration create && edgedb migrate。其中的--non-interactive是告知EdgeDB可以直接刪除data，不需詢問。

8. 如果是想刪除instance時，可以執行edgedb instance destroy -I xxx --force，其中xxx為此instance名字。

9. 如果每次重開機後，EdgeDB並未自己啟動或啟動失敗時，可以執行edgedb instance start -I xxx，其中xxx為此instance名字。依我在Windows11上使用的情況來看，此指令偶爾會失敗，需要執行兩次才能成功。

值得一提的是，edgedb開頭的指令亦可於REPL中執行，只需要在指令前加上\，且不用鍵入edgedb。例如於命令列中輸入edgedb migration create，即相當於在REPL中輸入\migration create。

EdgeDB cli備份與讀回

EdgeDB提供edgedb dump的指令執行備份與edgedb restore的指令執行讀回。

我們假設現在位於main branch且當前default.esdl內schema為：

module default {
 type User;
}

1. 執行edgedb migration create並執行edgedb migrate。

2. 執行edgedb query "insert User;"建立一個User object。

3. 執行edgedb dump --all --format=dir first_dump"將所有branch寫入到資料夾first_dump。

4. 執行edgedb branch wipe main並鍵入Yes來模擬刪除main branch中所有object。

5. 執行edgedb query "select User;"可以確認回傳的為空EdgeDBSet。

6. 執行edgedb restore --all first_dump將備份資料由first_dump資料夾讀回。

7. 執行edgedb query "select User;"可以確認原先建立的User object已被讀回。

這邊需要注意，成功地讀回除了需要edgedb dump出的資料夾外，原先migrations下的所有*.edgeql也都必須保留。由於每個*.edgeql的檔名及檔案內部都有特別的識別碼來辨別migraiton的順序，將會於edgedb restore時進行檢查。如果EdgeDB發現migrations資料夾有前後無法匹配的情況（例如識別碼不一致或遺失檔案等），將無法成功讀回。

EdgeDB ui

如果操作環境有安裝瀏覽器的話，可以於命令列中輸入edgedb ui，將會於瀏覽器中開啟一個漂亮的dashboard。

參考資料

本日內容大多整理自EdgeDB GitHub repo README及get-started/quickstart。

備註

註1：一個EdgeDB可以有多個instance，每個instance可以有多個branch（預設為main branch）。此外，雖然EdgeDB允許使用多個module，但將所有schema統一置於default module是一個常見的作法。因此本系列文若無特別說明，皆是將所有schema置於default.esdl中的default module。