WOrmPostgresql

WOrmPostgresql

new WOrmPostgresql(optopt) → {Object}

Description:

  • 操作資料庫(PostgreSQL)

    本套件之主鍵欄位由opt.pk指定，預設為time，select以外之五函數皆以此欄位認定主鍵。 因主鍵得為承載業務語義之欄位(如時序資料之觀測時間)，insert與save於輸入未帶有效主鍵值時不自動補值， 一律以reject回報；del亦不補值，該筆回ok:0與err。

Source:
Parameters:
Name Type Attributes Default Description
opt Object <optional>
 {}

輸入設定物件，預設{}

Properties
Name Type Attributes Default Description
url String <optional>
 'postgresql://127.0.0.1:5432'

輸入連接資料庫字串，預設'postgresql://127.0.0.1:5432'
db String <optional>
 'worm'

輸入使用資料庫名稱字串，預設'worm'
cl String <optional>
 'test'

輸入使用資料表名稱字串，預設'test'
pk String <optional>
 'time'

輸入主鍵欄位名字串，預設'time'
useCache Boolean <optional>
 false

輸入是否使用select快取，適用於單程序操作，預設false
Returns:

回傳操作資料庫物件，各事件功能詳見說明

Type
Object

Methods

(async, static) createTable(cl, pkopt, arr) → {Promise}

Description:

  • 創建資料表 註: pk未給時採建構時之opt.pk。因insert與save倚賴主鍵之唯一約束達成原子性， 若給予與opt.pk不同之欄位，將建出其餘函數無法正確操作之資料表，故一般應留空或給予相同值

Source:
Parameters:
Name Type Attributes Default Description
cl String

輸入資料表名字串
pk String <optional>
 opt.pk

輸入主鍵欄位名字串，預設為建構時之opt.pk
arr Array | Object

輸入數據物件陣列或數據物件
Returns:

回傳Promise，resolve回傳成功訊息，reject回傳錯誤訊息

Type
Promise

(async, static) del(data) → {Promise}

Description:

  • 刪除數據

    回傳陣列恆與輸入等長，各筆之n與nDeleted皆為主鍵命中筆數，值為0或1，未命中為0且屬正常結果。 判斷某筆是否真的被刪除一律以nDeleted為準。 未帶有效主鍵值者為該筆之輸入問題，回ok:0與err且不送查詢，不中斷其餘筆數， 以此與[主鍵未命中]之ok:1區辨。

Source:
Parameters:
Name Type Description
data Object | Array

輸入數據物件或陣列
Returns:

回傳Promise，resolve回傳刪除結果陣列[{n,nDeleted,ok}]，reject回傳錯誤訊息

Type
Promise

(async, static) delAll(findopt) → {Promise}

Description:

  • 刪除全部數據，需與del分開，避免未傳數據導致直接刪除全表

    n與nDeleted皆為實際刪除筆數，不取全表筆數。find未給或為空物件時刪除全部數據， 條件無命中時回{n:0,nDeleted:0,ok:1}，不視為錯誤。

Source:
Parameters:
Name Type Attributes Default Description
find Object <optional>
 {}

輸入刪除條件物件
Returns:

回傳Promise，resolve回傳刪除結果物件{n,nDeleted,ok}，reject回傳錯誤訊息

Type
Promise

(async, static) insert(data, optionopt) → {Promise}

Description:

  • 插入數據，僅於主鍵不存在時寫入，已存在者跳過且不覆寫

    預設回傳單一聚合物件，n為輸入筆數即本次嘗試插入之基準；nInserted為實際插入筆數， 全數已存在而nInserted為0屬正常結果，不視為錯誤。同批含重複主鍵時僅首筆計入nInserted。 因主鍵得承載業務語義，未帶有效主鍵值時不自動補值，一律以reject回報。

    option.returnList為true時改回傳與輸入等長且保序之逐筆陣列，令呼叫端得知[是哪幾筆]為新數據， 而非僅知[有幾筆]。各元素之n恆為1、ok恆為1，因insert之任何錯誤皆屬整批性錯誤而reject， 故逐筆元素不出現ok:0與err；同批含重複主鍵者以首次出現者之nInserted為1，其餘為0。 兩種取值下之不變式為陣列長度等於輸入筆數，且nInserted為1者之筆數等於聚合模式之nInserted。

Source:
Parameters:
Name Type Attributes Default Description
data Object | Array

輸入數據物件或陣列
option Object <optional>
 {}

輸入設定物件，預設為{}

Properties
Name Type Attributes Default Description
returnList Boolean <optional>
 false

輸入是否改回傳逐筆結果陣列，預設為false
Returns:

回傳Promise，resolve於returnList為false時回傳插入結果物件{n,nInserted,ok}， 為true時回傳逐筆結果陣列[{n,nInserted,ok}]，reject回傳錯誤訊息

Type
Promise

(async, static) insertBulk(data) → {Promise}

Description:

  • 批次插入數據，全批視為一個單位，全部插入成功或一筆都不寫入

    本函數非insert之加速版，兩者衝突政策不同：insert於主鍵已存在時跳過該筆且整批ok為1， 本函數則於任一筆之主鍵已存在時整批reject且不寫入任何一筆，同批含重複主鍵者亦視為衝突。 n為輸入筆數，nInserted為實際插入筆數且成功時恆等於n。 不提供逐筆結果，故不出現ok:0與err，需要逐筆處置者改用insert。 因主鍵得承載業務語義，未帶有效主鍵值時不自動補值，一律以reject回報， 且主鍵檢查於任何寫入之前一次完成，故整批reject時同批之有效筆數亦不會被寫入。

Source:
Parameters:
Name Type Description
data Object | Array

輸入數據物件或陣列
Returns:

回傳Promise，resolve回傳插入結果物件{n,nInserted,ok}，reject回傳錯誤訊息

Type
Promise

(async, static) save(data, optionopt) → {Promise}

Description:

  • 儲存數據，以主鍵為準更新既有數據，未給之欄位保留

    回傳陣列恆與輸入等長，輸入單一物件亦回傳長度1之陣列。 各筆之n為主鍵命中筆數，值為0或1，命中(不論內容有無變更)或經插入而產生皆為1； nInserted與nModified恆同時出現，無對應行為時填0。 [內容相同]之判定基準為待寫入物件合併進現值後與現值相同，非待寫入物件與現值全等， 故只給部份欄位且該些欄位值皆與現值相同時，合併結果等於現值，nModified為0， 令nModified忠實反映資料庫端是否真的寫入。 因主鍵得承載業務語義，未帶有效主鍵值時不自動補值，一律以reject回報。

Source:
Parameters:
Name Type Attributes Default Description
data Object | Array

輸入數據物件或陣列
option Object <optional>
 {}

輸入設定物件，預設為{}

Properties
Name Type Attributes Default Description
autoInsert boolean <optional>
 true

輸入是否於儲存時發現原本無數據，則自動改以插入處理，預設為true
Returns:

回傳Promise，resolve回傳儲存結果陣列[{n,nInserted,nModified,ok}]，reject回傳錯誤訊息

Type
Promise

(async, static) select(findopt, orderopt) → {Promise}

Description:

  • 查詢數據

Source:
Parameters:
Name Type Attributes Default Description
find Object <optional>
 {}

輸入查詢條件物件
order Object <optional>
 {}

輸入排序條件物件
Returns:

回傳Promise，resolve回傳數據，reject回傳錯誤訊息

Type
Promise

(async, static) selectByPk(pk) → {Promise}

Description:

  • 由主鍵查詢單筆數據，因直接由資料表主鍵索引取值，不需如select提取數據至前端再處理，故數據量大時效能較佳 註: 本套件之主鍵欄位由建構時之opt.pk指定，預設為time

    主鍵未命中或主鍵值無效皆回傳null而不reject，命中之判定基準與insert、save、del內對既有數據之認定一致。 主鍵值之型別與欄位不符時PostgreSQL回報22P02或22007，亦屬主鍵值無效而回傳null。

Source:
Parameters:
Name Type Description
pk String | Number | Date

輸入主鍵值，即數據之主鍵欄位值
Returns:

回傳Promise，resolve回傳數據物件，若無此主鍵則回傳null，reject回傳錯誤訊息

Type
Promise