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 批量添加操作
進行批量操作的主要原因有兩個:
- 你希望操作是原子的——即它們要麼完全發生,要麼完全不發生。
- 你想要加速大量的添加操作。在常見問題解答中反覆出現的一個主題是如何優化速度,這既是可能的,也是推薦的。批量操作可以大大加快多次添加的速度。
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 讀取數據庫數據
從數據庫中讀取數據有幾種不同的方式:
- 依次讀取一條記錄。
- 使用類似'WHERE'的子句讀取一條記錄。
- 使用類似WHERE的子句(例如,Name like %,其中%是通配符)讀取一系列記錄。
- 讀取一系列記錄和相關記錄。
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
過程中從數據庫中檢索孩子的信息以及他們的父母信息。這樣的查詢可以更高效地獲取相關數據,而不是對每個孩子單獨執行查詢。