Skip to content

在 Kotlin/JS 上開始使用 SQLDelight ​

資訊

同步的 sqljs-driver(2.0 之前的版本)已被非同步的 web-worker-driver 取代。 這需要在 Gradle 組建組態中設定 generateAsync。

首先在您的專案中套用 gradle 外掛程式。在建立資料庫時,請確保將 generateAsync 設定為 true。

kotlin
plugins {
  id("app.cash.sqldelight") version "2.4.0"
}

repositories {
  google()
  mavenCentral()
}

sqldelight {
  databases {
    register("Database") {
      packageName.set("com.example")
      generateAsync.set(true)
    }
  }
}
groovy
plugins {
  id "app.cash.sqldelight" version "2.4.0"
}

repositories {
  google()
  mavenCentral()
}

sqldelight {
  databases {
    register("Database") { // 這將是產生的資料庫類別名稱。
      packageName = "com.example"
      generateAsync = true
    }
  }
}

定義架構 ​

將您的 SQL 陳述式撰寫在 src/main/sqldelight 下的 .sq 檔案中。 通常 .sq 檔案中的第一個陳述式會建立一個資料表,但您也可以建立索引或設定預設內容。

src/main/sqldelight/com/example/sqldelight/hockey/data/Player.sq
sql
CREATE TABLE hockeyPlayer (
  player_number INTEGER PRIMARY KEY NOT NULL,
  full_name TEXT NOT NULL
);

CREATE INDEX hockeyPlayer_full_name ON hockeyPlayer(full_name);

INSERT INTO hockeyPlayer (player_number, full_name)
VALUES (15, 'Ryan Getzlaf');

透過這些陳述式,SQLDelight 將會產生一個 Database 類別及其關聯的 Schema 物件,可用於建立您的資料庫並對其執行陳述式。Database 類別是由 generateSqlDelightInterface Gradle 任務所產生的,當您編輯 .sq 檔案時,SQLDelight IDE 外掛程式會自動執行該任務,同時它也會作為一般 Gradle 組建的一部分來執行。

kotlin
kotlin {
  sourceSets.jsMain.dependencies {
    implementation("app.cash.sqldelight:web-worker-driver:2.4.0")
    implementation(devNpm("copy-webpack-plugin", "9.1.0"))
  }
}
groovy
kotlin {
  sourceSets.jsMain.dependencies {
    implementation "app.cash.sqldelight:web-worker-driver:2.4.0"
    implementation devNpm("copy-webpack-plugin", "9.1.0")
  }
}

Web worker 驅動程式允許 SQLDelight 與在 Web Worker 中執行的 SQL 實作進行通訊。這讓所有資料庫操作都能在背景處理序中進行。

資訊

Web worker 驅動程式僅與瀏覽器目標相容。

設定 Web Worker ​

SQLDelight 的 Web worker 驅動程式並不繫結至特定背景工作執行緒的實作。相反地,此驅動程式使用一組標準化的訊息與背景工作執行緒通訊。SQLDelight 提供了一個使用 SQL.js 的背景工作執行緒實作。

請參閱 SQL.js Worker 頁面了解為專案進行設定的細節,或參閱 Custom Workers 頁面了解有關實作自訂背景工作執行緒的細節。

使用 Web Worker ​

建立 Web worker 驅動程式的執行個體時,必須傳遞一個 Web worker 參照,該背景工作執行緒將用於處理所有 SQL 操作。Worker 建構函式接受指向背景工作執行緒指令碼的 URL 物件。

Webpack 具有特殊支援,可透過將 import.meta.url 作為第二個引數傳遞給 URL 建構函式,來參照已安裝 NPM 軟件包中的背景工作執行緒指令碼。Webpack 會在組建階段自動從參照的 NPM 軟件包中打包背景工作執行緒指令碼。下方的範例顯示了從 SQLDelight 的 SQL.js Worker 建立的 Worker。

kotlin
val driver = WebWorkerDriver(
  Worker(
    js("""new URL("@cashapp/sqldelight-sqljs-worker/sqljs.worker.js", import.meta.url)""")
  )
)

警告

為了讓 Webpack 在打包時能正確解析此 URL,您必須完全在 js() 區塊內建構 URL 物件,如上方帶有 import.meta.url 引數的範例所示。

從這裡開始,您可以像使用任何其他 SQLDelight 驅動程式一樣使用此驅動程式。

使用查詢 ​

定義型別安全查詢 ​

SQLDelight 會為 .sq 檔案中任何帶有標籤的 SQL 陳述式產生型別安全函式。

src/main/sqldelight/com/example/sqldelight/hockey/data/Player.sq
sql
selectAll:
SELECT *
FROM hockeyPlayer;

insert:
INSERT INTO hockeyPlayer(player_number, full_name)
VALUES (?, ?);

insertFullPlayerObject:
INSERT INTO hockeyPlayer(player_number, full_name)
VALUES ?;

系統會為每個包含標籤陳述式的 .sq 檔案產生一個「Queries」物件。 例如,系統會為上方所示的 Player.sq 檔案產生一個 PlayerQueries 物件。 此物件可用於呼叫產生的型別安全函式,這些函式將執行實際的 SQL 陳述式。

kotlin
suspend fun doDatabaseThings(driver: SqlDriver) {
  val database = Database(driver)
  val playerQueries: PlayerQueries = database.playerQueries

  println(playerQueries.selectAll().awaitAsList()) 
  // [HockeyPlayer(15, "Ryan Getzlaf")]

  playerQueries.insert(player_number = 10, full_name = "Corey Perry")
  println(playerQueries.selectAll().awaitAsList()) 
  // [HockeyPlayer(15, "Ryan Getzlaf"), HockeyPlayer(10, "Corey Perry")]

  val player = HockeyPlayer(10, "Ronald McDonald")
  playerQueries.insertFullPlayerObject(player)
}

警告

當使用非同步驅動程式時,在執行查詢時請使用暫停式的 awaitAs*() 擴充函式,而非阻塞式的 executeAs*() 函式。

就是這樣!請查看側邊欄中的其他頁面以了解其他功能。