破壞客戶端 API 的變更

本頁簡要介紹了所有可能破壞客戶端程式碼的 API 變更。

SQLite JavaScript API 致力於維持與 C API 相同的強大向後相容性保證，但 JS API 的早期版本明確標示為「測試版」/「技術預覽」版本，可能會有所變更。

正式版本之間引入的 API 可能會以多種方式變更，但一旦 API 透過正式版本發佈，我們將盡一切努力保留它，但極少數情況下，最終發現 API 存在嚴重缺陷（例如 sqlite3_js_vfs_create_file()）則例外。然而，JS API 採用新的語義（例如新的參數組合和類型）的同時也保留其自身的語義，這並不罕見。

以下是已知重大變更的列表，最新變更排在最前面...

2022-12-25

• 傳遞給 sqlite3_exec() 的 JS 函式的簽章已簡化，移除了對 JS 多餘的參數。「完整」形式可以透過手動安裝回呼函式，並將其指標（而非函式物件）傳遞給 sqlite3_exec() 來從 JS 使用。

2022-12-14

• oo1.DB.exec() 的 rowMode 選項 之前接受 "$X"、"@X" 或 ":X" 形式的欄位名稱參考。後兩種已被移除，因為它們是多餘的，而且不必要的變化可能會造成混淆。

2012-12-09

• 重新命名了 sqlite3.wasm 命名空間 的幾個常用方法，但保留了舊名稱作為別名。

  • setMemValue() → poke()
  • setPtrValue() → pokePtr()
  • getMemValue() → peek()
  • getPtrValue() → peekPtr()
    peek 和 poke 的名稱在維基百科上有詳細的說明。peekPtr() 和 pokePtr() 只是少了一個參數的便利形式。

• wasm.poke() 和 wasm.pokePtr() 的回傳語義已更改。它們現在回傳 this 而不是回傳函式本身。它們現在也接受位址陣列，但這不是一個潛在的破壞性變更。

2022-12-06

• 為了保持一致性，sqlite3.wasm.cstringToJs() 已重新命名為 cstrToJs()。

2022-11-30

• sqlite3.wasm.alloc() 現在代理 sqlite3_malloc()（以前是 malloc()），而 sqlite3.wasm.dealloc() 現在代理 sqlite3_free()（以前是 free()）。除非客戶端將 sqlite3.wasm 連結到更大的應用程式中，否則預計不會有任何客戶端受到此影響。此變更消除了 JS 端 WASM 記憶體管理方式的一些客戶端不一致性，最明顯的是透過 sqlite3_deserialize() 和虛擬表格介面的一部分。

2022-11-29

• 為了與其他 oo1.DB 子類別保持一致，sqlite3.opfs.OpfsDb 已重新命名為 sqlite3.oo1.OpfsDb。舊名稱將在短時間內可用，但將在 3.41 版本中移除。（更新：已於 2022-12-06 移除。）