mORMot 1.18 第07章 簡單的讀寫操作

海利鸟發表於2024-04-28
ORM

mORMot 1.18 第七章 簡單的讀寫操作

本章描述了典型的資料讀寫操作。首先，我們將注意力集中在資料上，而不是函式。

讀取操作返回一個TID，它是一個32位或64位整數（取決於你的記憶體模型），反映了表的資訊。TID在表中的每一行都是唯一的。

ORM的新手可能會感到驚訝，但通常你不需要建立SQL查詢來過濾請求，而是將其留給ORM來處理。

為什麼呢？原因有很多。

ORM理解你的資料模型，並且可以提出合理請求。ORM可以強制實施安全要求，而這些要求你很難附加到自己的SQL請求中。ORM可以處理資料庫技術中的差異，這些差異你必須瞭解並且進行硬編碼。這些差異使得一個典型的SQL專案很難移植到新的資料庫中，但對於ORM專案來說卻很容易。考慮以下SQL語句：


Firstname := 'Tom'; // 或 TEdit.Text
Database.Query('SELECT * FROM sampledata WHERE name = ?',[Firstname]);

在mORMot中，它將被寫成


Firstname := StringToUTF8( 'Tom'); // 或 TEdit.Text
Rec := TSQLSampleRecord.Create( Database, 'Name=?' ,[firstname]);

StringToUTF8處理適當的內碼表轉換，以正確處理可能在第一個示例中無法正確處理的名稱，例如帶有重音符號、撇號等的名稱。

mORMot會構建一個類似的SQL語句，但也可以新增安全條件、SQL JOIN條件等。

以下是一個完整的示例程式，展示了mORMot的實際應用。我們稍後會對其進行剖析。

program sample1;
{$APPTYPE CONSOLE}
uses
  SysUtils,
  Classes,
  SynCommons,
  mORMot;
type
  TSQLSampleRecord = class(TSQLRecord)
  private
    fQuestion: RawUTF8;
    fName: RawUTF8;
    fTime: TModTime;
  published
    property Time: TModTime read fTime write fTime;
    property Name: RawUTF8 read fName write fName;
    property Question: RawUTF8 read fQuestion write fQuestion;
  end;

var
  Database: TSQLRest;
  Model: TSQLModel;

  procedure ModelCreate;
  begin
    writeln('creating model');
    Model := TSQLModel.Create([TSQLSampleRecord]);
  end;


  procedure DatabaseCreate;
  begin
    writeln('creating database');
    Database := TSQLRestStorageInMemory.Create(TSQLSampleRecord, nil, 'test.db', False);
  end;

  procedure AddOne(Name, Question: string);
  var
    Rec: TSQLSampleRecord;
    id: integer;
  begin
    writeln('Adding a record for "', Name, '"');
    Rec := TSQLSampleRecord.Create;
    try
 // we use explicit StringToUTF8() for conversion below
 Rec.Name := StringToUTF8(Name);
 Rec.Question := StringToUTF8(Question);
 id := Database.Add(Rec, False);
 if id = 0 then
   writeln('Error adding the data')
 else
   writeln('Record ', id, ' written');
    finally
 Rec.Free;
    end;
  end;


  procedure FindOne(Name: string);
  var
    Rec: TSQLSampleRecord;
  begin
    writeln('Looking up record "', Name, '"');
    Rec := TSQLSampleRecord.Create(Database, 'Name=?', [StringToUTF8(Name)]);
    try
 if Rec.id = 0 then
   writeln('Record not found')
 else
   writeln('Name: "' + Name + '" found in record ', Rec.id, ' with question: "', UTF8ToString(Rec.Question), '"');
    finally
 Rec.Free;
    end;
  end;

  procedure Shutdown;
  begin
    Database.Free;
    Model.Free;
  end;


begin

  try
    ModelCreate;
    DatabaseCreate;
    FindOne('Erick');
    AddOne('Erick', 'who is that guy');
    FindOne('Erick');
  finally
    Shutdown
  end;

end.

您的應用程式透過建立TSQLRecord的派生資料物件（如本例中的TSQLSampleRecord）來與資料庫進行互動。


TSQLSampleRecord = class(TSQLRecord)

  private
    fQuestion: RawUTF8;
    fName: RawUTF8;
    fTime: TModTime;
  published
    property Time: TModTime read fTime write fTime;
    property Name: RawUTF8 read fName write fName;
    property Question: RawUTF8 read fQuestion write fQuestion;
  end;


我們首先定義資料庫模型，即我們將在程式中使用的所有TSQLRecord派生類的列表。這裡只有一個記錄模型，但如果有多個，我們會用逗號將它們分開。

然後我們根據模型建立一個資料庫。資料庫是我們與實際資料庫的連線，我們將使用它來讀取、寫入、刪除和更新資料。

在這個簡單的例子中，我們使用的是全域性變數。


var
  Database: TSQLRest;
  Model: TSQLModel;

procedure ModelCreate;
begin
  writeln(' creating Model ');
  Model := TSQLModel.Create([TSQLSampleRecord]);
end;

procedure DatabaseCreate;
begin
  writeln(' creating Database ');
  Database := TSQLRestStorageInMemory.Create(TSQLSampleRecord, Nil, test.db ', False);
end;

Db.Add() 方法用於向資料庫的指定表中新增記錄。它接受第二個引數，一個布林值，用於確定記錄是否應保持更新模式（完成時需要解鎖）。通常，我們只是讀取資料，所以更新標誌應為 False。Add 方法返回 TID，對於所有成功的操作，該值都大於零。


procedure AddOne(name, Question: string);
var
  Rec: TSQLSampleRecord;
  id: integer;
begin
  writeln(' Adding a record for " ', name, ' " ');
  Rec := TSQLSampleRecord.Create;
  try
    // 我們在下面的轉換中使用顯式的 StringToUTF8()
    Rec.name := StringToUTF8(name);
    Rec.Question := StringToUTF8(Question);
    id := Database.Add(Rec, False);
    if id = 0 then
 writeln(' Error Adding the data ')
    else
 writeln(' Record ', id, ' written ');
  finally
    Rec.Free;
  end;
end;

try/finally 部分確保我們無論成員填充和資料庫新增是否成功，都會釋放 TSQLSampleRecord 物件。

我們可以透過帶引數的查詢來查詢記錄。


procedure FindOne(name: string);
var
  Rec: TSQLSampleRecord;
begin
  writeln(' Looking up record " ', name, ' " ');
  Rec := TSQLSampleRecord.Create(Database, 'Name = ? ', [StringToUTF8(name)]);
  try
    if Rec.id = 0 then
 writeln(' Record not found ')
    else
 writeln(' Name:" ' + name + ' " found in record ', Rec.id, 'with question:" ', UTF8ToString(Rec.question), ' " ');
  finally
    Rec.Free;
  end;
end;

Finally, you need to close the database and release the model.


procedure Shutdown;
begin
  Database.Free;
  Model.Free;
end;

7.1 批次新增操作

進行批次操作的主要原因有兩個：

  1. 你希望操作是原子的——即它們要麼完全發生，要麼完全不發生。
  2. 你想要加速大量的新增操作。在常見問題解答中反覆出現的一個主題是如何最佳化速度，這既是可能的，也是推薦的。批次操作可以大大加快多次新增的速度。
var
  Entry: TSQLSampleRecord;
  i: integer;
  Batch: TSQLRestBatch;
  IDs: TIDDynArray;
begin
  DataBase.BatchStart(TSQLORM);
  Entry := TSQLSampleRecord.Create;
  try
    for i := 1 to 25 do
    begin
 Entry.Name := FormatUTF8('Name % i ', [i]);
 DataBase.BatchAdd(Entry, True);
    end;
  finally
    Entry.Free;
  end;
  if (DataBase.BatchSend(IDs) <> HTML_SUCCESS) then
    writeln(' ERROR adding Batch ');
end;

如上所示，相同的Entry物件在每次新增時都被重複使用，這樣你可以很容易地在迴圈外部設定常量，並且它們將保留其值。

7.2 讀取資料庫資料

從資料庫中讀取資料有幾種不同的方式：

  1. 依次讀取一條記錄。
  2. 使用類似'WHERE'的子句讀取一條記錄。
  3. 使用類似WHERE的子句（例如，Name like %，其中%是萬用字元）讀取一系列記錄。
  4. 讀取一系列記錄和相關記錄。

7.3 依次讀取記錄

通常，你可能想從第一條記錄開始迴圈遍歷資料庫，直到遍歷完所有記錄。使用Database.Retrieve函式，失敗時返回0。你可以將id設定為任何有效值。

var
  parent: TSQLParent;
  id: integer;
begin
  parent := TSQLparents.Create;
  id := 1;
  try
    while True do
    begin
 if Database.Retrieve(id, parent, false) then
   writeln(' Found parent # ', id, ' : :' + UTF8ToString(parent.pnt_name))
 else
   break;
 inc(id);
    end;
  finally
    parent.Free;
  end;
end;

7.4 使用類似WHERE的子句讀取一條記錄

mORMot不需要WHERE，但它確實允許你指定類似WHERE的子句。

var
  kid: TSQLKids;
begin
  kid := TSQLKids.Create(Database, 'kid_name LIKE ? ', [wildcard]);
  try
    if kid.id > 0 then
 writeln(' ID=', kid.id, ' Name= ', kid.kid_name);
  finally
    kid.Free;
  end;
end;

請注意，引數可以包含撇號或任何其他有效的UTF8字元。

7.5 使用類似WHERE的子句讀取一系列記錄

當然，有時你會連續讀取多條記錄，例如所有住在Peterborough的人，或者所有名字以S開頭的孩子（S-萬用字元）。你可以使用一次 CreateAndFillPrepare()，然後對每個記錄使用 FillOne()。

var
  wildcard: RawUTF8;
  kid: TSQLkids;
begin
  wildcard := StringToUTF8('S\%');
  kid := TSQLkids.CreateAndFillPrepare(Database, 'kid_name LIKE ?', [wildcard]);
  if Assigned(kid) then
    try
 while kid.FillOne do
   writeln(' ID=', kid.id, ' Name= ', kid.kid_name);
    finally
 kid.Free;
    end;
end;

要有多個條件，請指定多個?和欄位。

kid := TSQLkids.CreateAndFillPrepare(Database,'kid_name LIKE ? AND kid_age < ? ', [wildcard, 4]);

7.6 更新記錄

通常你會讀取一條記錄，然後更新它。

var
  parent: TSQLparents;
  id: integer;
begin
  parent := TSQLparents.Create;
  id := 1;
  try
    if Database.Retrieve(id, parent, True) then
    begin
 parent.pnt_name := 'Smith';
 Database.Update(parent);
    End;
  finally
    parent.Free;
  end;
end;

7.7 新增或更新

Database.AddOrUpdate()的功能與Add()類似，但如果發現已存在的記錄，它會更新該記錄。

7.8 刪除記錄

一旦你使用上述記錄查詢程式碼定位到記錄的TID，你就可以刪除該記錄。

var
  id: integer;
begin
  id := 25;
  aServer.Delete(TParent, id);
end;

可以在批處理操作中刪除多條記錄，這當然會加快處理速度。

7.9 資料型別

mORMot將原生CPU和複合型別轉換為資料庫資料型別。每種資料庫的型別都略有不同，但此表格顯示了SQL3Lite轉換的示例。

Delphi SQLite3 備註
Byte INTEGER
Word INTEGER
Integer INTEGER
Cardinal N/A 應使用Int64代替
Int64 INTEGER
Boolean INTEGER 0為假，其他值均為真
enumeration INTEGER 儲存列舉項的序數值（例如，第一個元素的序數值從0開始）
Set INTEGER 每一位對應一個列舉項（一個欄位最多可以儲存64個元素）
Single FLOAT
Double FLOAT
Extended FLOAT 儲存為double型別（精度損失）
Currency FLOAT 可安全地與貨幣型別進行相互轉換，具有固定的小數位數，無舍入誤差
RawUTF8 TEXT 這是ORM中儲存一些文字內容的首選欄位型別
WinAnsiString TEXT Delphi中的WinAnsi字符集（內碼表1252）
RawUnicode TEXT Delphi中的UCS2字符集，如AnsiString
WideString TEXT UCS2字符集，如COM BSTR型別（所有版本的Delphi中的Unicode）
SynUnicode TEXT 在Delphi 2009之前為WideString，之後為UnicodeString
String TEXT 不建議在Delphi 2009之前使用（除非您希望在轉換過程中丟失某些資料）-在所有情況下，首選RawUTF8
TDateTime TEXT ISO 8601編碼的日期時間
TTimeLog INTEGER 專有的快速Int64日期時間
TModTime INTEGER 當記錄被修改時，將儲存伺服器日期時間（作為專有的快速Int64）
TCreateTime INTEGER 當記錄被建立時，將儲存伺服器日期時間（作為專有的快速Int64）
TSQLRecord INTEGER 32位RowID指向另一條記錄（警告：欄位值包含pointer(RowID)，而不是有效的物件例項-必須透過其ID使用PtrInt(Field)型別轉換或Field.ID方法，透過後期繫結來檢索記錄內容），或者使用例如CreateJoined() - 在Win64下為64位
TID INTEGER 64位RowID指向另一條記錄，但不包含有關對應表的任何資訊
TSQLRecordMany 無 資料儲存在單獨的透視表中；這是TSQLRecord的一個特殊情況：它不包含pointer(RowID)，而是一個例項
TRecordReference INTEGER 透過在類似於RecordRef的Int64值中儲存ID和TSQLRecord類型別，能夠連線模型中的任何表的任何行，自動重置為0
TPersistent TEXT JSON物件（ObjectToJSON）
TCollection TEXT JSON物件陣列（ObjectToJSON）
TObjectList TEXT JSON物件陣列（ObjectToJSON）-參見TJSONSerializer.RegisterClassForJSON
TStrings TEXT 字串的JSON陣列（ObjectToJSON）
TRawUTF8List TEXT 字串的JSON陣列（ObjectToJSON）
any TObject TEXT 參見TJSONSerializer.RegisterCustomSerializer
TSQLRawBlob BLOB 此型別是RawByteString的別名
dynamic arrays BLOB 採用TDynArray.SaveTo二進位制格式
Variant TEXT JSON中的數字或文字，或用於JSON物件或陣列的TDocVariant自定義變體型別
Record TEXT JSON字串或物件，自Delphi XE5起直接處理，或在先前版本中透過重寫TSQLRecord.InternalRegisterCustomProperties在程式碼中定義
TRecordVersion INTEGER 64位版本號，每次修改物件時都會單調更新，以允許遠端同步

7.10 Joining Data Tables 連線資料表 形成多對多的關係

Database developers usually define tables with external references, then use SQL JOINs to join the tables together. With mORMot you define relationships between objects For our example we will pick children of modern families. Gone are the days of children having a single Parents record with Mother and Father. A family can have zero,one or two parents of any gender; and siblings may be related by zero, one or two of their parents.

IMPORTANT: Mormot does not normally download sub-tables. Rather, it just loads the TID of the specified sub-table. Likewise, when you save a table, you save the TID of the sub-table. Like all good rules, there are exceptions. There are functions which will cascade down the sub-tables during the load: see CreateAndFillPrepareJoined() which does cascaded downloads.

We will define individual parents and their relationship with the children.

資料庫開發者通常會定義帶有外部引用的表，這時使用SQL的JOIN操作將這些表連線起來。在使用mORMot時，你需要定義物件之間的關係。以現代家庭的孩子為例，過去那種孩子只有一條包含父母雙方資訊的記錄的時代已經過去了。在mORMot體系中一個家庭的“父母”可以是 0 個，1個，2個或者任意多個；兄弟姐妹之間可能透過0個、1個或2個父母形成聯絡。

重要提示：mORMot通常不會下載子表。相反，它只會載入指定子表的TID（表識別符號）。同樣，當你儲存一個表時，你儲存的是子表的TID。和所有好的規則一樣，也有例外。有一些函式可以在載入時級聯下載子表：參見執行級聯下載的CreateAndFillPrepareJoined()函式。

我們將定義父母與孩子之間的主從（或父子）資料關係。

（注：TID，即表識別符號，是資料庫中對錶的唯一標識。在mORMot框架中，通常使用TID來引用和運算元據表。）

接下來，我們將繼續翻譯上述Pascal程式碼：

type

  // 定義性別型別

  Tgender = (gMALE, gFEMALE);

  // 父母類

  TSQLparents = class(TSQLRecord)
  private
    fname: RawUTF8; // 名字
    fgender: Tgender; // 性別
  published
    property pnt_name: RawUTF8 read fname write fname; // 名字屬性
    property pnt_gender: Tgender read fgender write fgender; // 性別屬性
  end;

  // 孩子類

  TSQLkids = class(TSQLRecord)
  private
    fname: RawUTF8; // 名字
    fbirthdate: TDateTime; // 出生日期
    fparent1: TSQLparents; // 父親或母親1
    fparent2: TSQLparents; // 父親或母親2
  published
    property kid_name: RawUTF8 read fname write fname; // 孩子名字屬性
    property kid_birthdate: TDateTime read fbirthdate write fbirthdate; // 孩子出生日期屬性
    property kid_parent1: TSQLparents read fparent1 write fparent1; // 孩子父親或母親1屬性
    property kid_parent2: TSQLparents read fparent2 write fparent2; // 孩子父親或母親2屬性
  end;

首先，我們定義並建立了模型和資料庫，然後就可以開始了。

var
  Model: TSQLModel; // SQL模型
  Database: TSQLRest; // 資料庫
Const
  DBFILE = 'Database.db3'; // 資料庫檔案

// 建立示例模型的函式
function CreateSampleModels: TSQLModel;
begin
  result := TSQLModel.Create([TSQLkids, TSQLparents]); // 建立一個包含孩子和父母類的模型
end;

var
  parent1, parent2, parent3: TID; // 父母ID
begin
  try
    Model := CreateSampleModels; // 建立模型
    Database := TSQLRestServerDB.Create(Model, DBFILE); // 建立資料庫
    TSQLRestServerDB(Database).CreateMissingTables; // 建立缺失的表

    // 現在我們可以新增父母資訊了
    parent1 := AddParentData(Database, ' Jenny '); // 新增Jenny
    parent2 := AddParentData(Database, ' Hermann '); // 新增Hermann
    parent3 := AddParentData(Database, ' Karen '); // 新增Karen

    // 新增孩子資訊
    AddKidData(Database, ' Tim ', parent1, parent2); // Tim的父母是Jenny和Hermann
    AddKidData(Database, ' Chris ', parent2, parent3); // Chris的父母是Hermann和Karen
    AddKidData(Database, ' George ', parent3, 0); // George的母親是Karen，沒有父親
  finally
    // ... 後續程式碼
  end;
end.

我相信使用像AddParentData()、AddKidData()等工作函式會使程式更易於閱讀。在這個例子中，Jenny和Hermann是Tim的父母，Hermann和Karen是Chris的父母，而Karen是George的唯一母親。

// 向資料庫中新增父母資料的函式
function AddParentData(Database: TSQLRest; parentname: string): TID;
var
  parent: TSQLparents; // 父母物件
begin
  parent := TSQLparents.Create; // 建立父母物件
  try
    parent.pnt_name := parentname; // 設定父母名字
    result := Database.Add(parent, True); // 將父母物件新增到資料庫，並返回其ID
    if result = 0 then // 如果新增失敗（返回ID為0）
      writeln(' ERROR: 新增父母失敗:', parentname) // 輸出錯誤資訊
    else
      writeln(' SUCCESS: 新增父母成功:', parentname); // 輸出成功資訊
  finally
    parent.Free; // 釋放父母物件
  end;
end;

function AddKidData(Database: TSQLRest; kidname: string; parent1, parent2: TID): TID;

var
  kid: TSQLkids;
  parentA, parentB: TSQLParents;
begin
  kid := TSQLkids.Create;
  try
    kid.kid_name := StringToUTF8(kidname);

    parentA := TSQLParents.Create(Database, parent1);
    kid.kid_parent1 := TSQLParents(parentA);

    parentB := TSQLParents.Create(Database, parent2);
    kid.kid_parent2 := TSQLParents(parentB);

    result := Database.Add(kid, True);
    if result = 0 then
      writeln('錯誤：新增孩子失敗：', kidname)
    else
      writeln('成功：新增孩子：', kidname);
  finally
    kid.Free;
    parentA.Free;
    parentB.Free;
  end;
end;

如您所見，這是可讀性很高的程式碼，很難出錯。

一旦新增了資料，就該讀取它們了。


procedure ShowChildrenManyJoined(Database: TSQLRest);

var
  kid: TSQLkids;
  wildcard: RawUTF8;
begin
  writeln('聯接表');
  writeln('================');

  wildcard := StringToUTF8('%');

  // kid.CreateJoined( Database, kid.kid_parent1);

  kid := TSQLkids.CreateAndFillPrepare(Database, 'SELECT k.* FROM kids k JOIN parents p1 ON k.kid_parent1=p1.id JOIN parents p2 ON k.kid_parent2=p2.id WHERE k.kid_name LIKE ?', [], [wildcard]);

  if Assigned(kid) then
    try
      while kid.FillOne do
        writeln('ID=', kid.ID, ' 姓名=', kid.kid_name, ' 父親=', kid.kid_parent1.pnt_name, ', 母親=', kid.kid_parent2.pnt_name);
      kid.FillClose;
    finally
      kid.Free;
    end;

end;

注意：與前面的翻譯相比，這裡的翻譯和修改更加精確，並且已經糾正了原始程式碼中的錯誤（如將parent更正為parentB等）。同時，也根據中文語境調整了輸出文字。此外，在SQL查詢語句中，我增加了一個完整的聯接查詢示例，用於在ShowChildrenManyJoined過程中從資料庫中檢索孩子的資訊以及他們的父母資訊。這樣的查詢可以更高效地獲取相關資料，而不是對每個孩子單獨執行查詢。

相關文章