SqlDBHowto/zh CN

From Lazarus wiki
Jump to navigationJump to search

Deutsch (de) English (en) español (es) français (fr) 日本語 (ja) Nederlands (nl) polski (pl) 中文(中国大陆)‎ (zh_CN)

介绍

本页面翻译自 SqlDBHowto/nl,最初荷兰语领先,不过,现在两篇文章已经同步。

本文选择从'如何'做为开始。我想通过,一个问题一个答案的方式来解释如何使用不同类。像这样,一个接一个,形成教程以介绍如何使用它。

我会尽力阐明它,以便清楚的说明如何在 Lazarus 和 FreePascal 中使用。但这些例子是 FreePascal 中的(即控制台应用程序)。

在哪里可以找到官方文档

请参阅官方 SQLDB 文档

如何连接到数据库服务器

SqlDB 无法直接连接到数据库服务器,但可以使用数据库服务器客户端连接。SqlDB 发送命令到客户端;客户端连接到数据库并传输命令。这意味着电脑上必须安装数据库客户端才能与数据库连接。Windows 通常是 .dll文件,Linux 下是 .so文件,OS/X中为 .dylib的文件。

当客户端库已经正确安装,你便可以使用 TSQLConnection 组件连接到数据库服务器。各种 TSQLConnection 组件可连接到不同的数据库服务器。(查看 SQLdb 包):

MySQL留意 - 在某种程度上客户端版本之间的差异使得客户端和连接不能互换。如 MySQL 客户端版本为4.1,你必须使用 TMySQL41Connection 连接。它与 MySQL 服务器端无关;也许你可以使用 4.1 的客户端,连接到 MySQL 5.0 的服务器(请参见 MySQL文档 关于支持哪些组合)


虽然各数据库的细节不同,不过,一般只需要设置四个属性就可以连接到数据库服务器:

  • 服务器名或 IP 地址
  • 数据库名称
  • 用户名
  • 密码

设置好这些属性,使用 'open' 方法打开连接。如果连接失败,你可以使用 EDatabaseError 抛出异常。使用 'connected' 属性来确定是否建立与数据库服务器的连接。使用 'close' 方法来关闭与服务器的连接。

Program ConnectDB
 
var AConnection : TIBConnection;
 
Procedure CreateConnection;
begin
  AConnection := TIBConnection.Create(nil);
  AConnection.Hostname := 'localhost';
  AConnection.DatabaseName := '/opt/firebird/examples/employee.fdb';
  AConnection.UserName := 'sysdba';
  AConnection.Password := 'masterkey';
end;
 
begin
  CreateConnection;
  AConnection.Open;
  if Aconnection.Connected then
    writeln('Successful connect!')
  else
    writeln('This is not possible, because if the connection failed, ' +
            'an exception should be raised, so this code would not ' +
            'be executed');
  AConnection.Close;
  AConnection.Free;
end.

如果抛出异常,仔细阅读错误消息。可能是数据库服务器没有运行,用户名、密码不正确,也可能是数据库名称或IP地址输入错误。如果消息提示客户端库无法找到,你需要检查客户端库是否安装正确。Often the error message states literally the name of the file looked for. (通常按错误消息上的名称查找。

如何执行查询/创建表

SqlDB - 见名知意 - 适用于使用 SQL 的数据库服务器。SQL代表 '结构化查询语言',它工作在关系型数据库上。事实上,每个数据库系统都有自己的方言,不过,大多 SQL 语句通用于所有数据库系统。

在 FPC 中,期间有些区别:

  • SQL 语句返回的信息(数据集)。对于这一点,你需要使用 TSQLQuery 组件; 查看#如何读取表中数据
  • 语句不返回信息,但在做其他事,例如更新数据,为此,你可以使用 TSQLConnection 的 'ExecuteDirect' 方法。You can also use this if you get a dataset back but are not interested in the results, e.g. in a selectable stored procedure.


Most database system execute SQL statements within a transaction. If you want changes made within a transaction available in other transactions, or have those changes available even after closing the transaction(!), then you have to 'commit' the transaction.


支持事务的 Sqldb 包含 TSQLTransaction 组件。由 Sqldb 执行的 SQL 语句必须在事务内执行,即使数据库系统不支持事务。此外,there are database systems that do support transaction for which TSQLConnection does not (yet) support transaction(使用 TSQLConnection 操作支持事务的数据库系统),即使这样,你也必须使用 TSQLTransaction 组件。

使用 TSQLConnection.ExecuteDirect 执行SQL语句你必须指定 'Transaction';反过来,使用 TSQLTransaction 你也必须指定使用哪个 TSQLConnection 组件。

下面的示例将创建 'TBLNAMES' 表,包含字段有 'NAME' 和 'ID',并插入2条记录。不解释所使用的 SQL 语句。 SQL 语句相关用途和语法,请参阅数据库系统文档。程序中定义的 'CreateConnection',代码示例在#如何连接到数据库服务器上。

program CreateTable;
 
var 
  AConnection : TSQLConnection;
  ATransaction : TSQLTransaction;
 
procedure CreateTransaction;
begin
  ATransaction := TSQLTransaction.Create;
  ATransaction.Database := AConnection;
end;
 
begin
  CreateConnection;
  CreateTransaction;
  AConnection.Transaction := ATransaction;
  AConnection.Open;
  ATransaction.StartTransaction;
  AConnection.ExecuteDirect('create table TBLNAMES (ID integer, NAME varchar(40));'); 
   
  // Some database-server types need a commit before you can use a newly created table. (Firebird)
  // With .Commit you also close the transaction
  ATransaction.Commit; 
 
  ATransaction.StartTransaction;
  AConnection.ExecuteDirect('insert into TBLNAMES (ID,NAME) values (1,'Name1');'); 
  AConnection.ExecuteDirect('insert into TBLNAMES (ID,NAME) values (2,'Name2');'); 
  ATransaction.Commit; 
  AConnection.Close;
  AConnection.Free;
  ATransaction.Free;
end.

如何读取表中数据

使用 TSQLQuery 组件从表中读取数据。它必须连接到 TSQLConnection 和 TSQLTransaction 组件才能正常工作。设置 TSQLConnection 和 TSQLTransaction 讨论在 #如何连接到数据库服务器#如何执行查询/创建表

当使用 TSQLConnection、 TSQLTransaction 和 TSQLQuery 连接时,TSQLQuery 需要进行些配置,'SQL' 属性包含要执行的 SQL 语句。如只读取表,那么将其属性设置为:

'SELECT * FROM tablename;'

使用 'open' 从服务器中读取表并将数据放在 TSQLQuery 数据集中。可以通过 TSQLQuery 访问数据,直到使用 'close' 关闭查询。

TSQLQuery 是 TDataSet 的一个子类。TDataset 是 'Fields' 集合,包含表中的所有列。TDataset 可以定位当前记录,使用 'First'、 'Next'、 'Prior' 和 'Last' 分别改变到 '第一条'、'下一条'、'上一条'和'最后一条'记录。当在第一条记录时,Bof 为真;为最后一条记录时 Eof 为真。读取当前记录某字段的值,先找到合适的 'TField' 对象,之后使用 'AsString'、 'AsInteger' 等等。

示例:从表中读取数据

下面的示例将显示表中的所有数据,表来自 #如何执行查询/创建表

Program ShowData;
 
var 
  AConnection : TSQLConnection;
  ATransaction : TSQLTransaction;
 
function GetQuery : TSQLQuery;
  var AQuery : TSQLQuery;
begin
  AQuery := TSQLQuery.Create;
  AQuery.Database := FConnection;
  AQuery.Transaction := FTransaction;
  Result := AQuery;
end;
 
var 
  Query : TSQLQuery;
 
begin
  CreateConnection;
  CreateTransaction;
  Query := GetQuery;
  Query.SQL.Text := 'select * from tblNames';
  AConnection.Open;
  Query.Open;
  while not Query.Eof do
  begin
    Writeln('ID: ', Query.FieldByName('Name').AsInteger, 'Name: ' +
                                  Query.FieldByName('Name').AsString);
    Query.Next;
  end;
  Query.Close;
  AConnection.Close;
  Query.Free;
  ATransaction.Free;
  AConnection.Free;
end.

(上面的代码不是很完善,因为忽略了 'try...finally' 块;旨在演示显示数据,因此'美化'工作被忽略。) Please note that 'TSQLTransaction.StartTransaction' is not used. This is not necessary. When TSQLQuery is opened, the SQL statement is executed and if no transaction is available then a transaction is automatically started. The programmer does not need to start the transaction explicitly.(请注意,未使用 'TSQLTransaction.StartTransaction' 。似乎没有这个必要。当 TSQLQuery 被打开时,SQL语句被执行,如果没有事务可用,那么事务将自动启动。程序员并不需要明确的开始事务。)


The same applies for the connection maintained by TSQLConnection. The connection is opened as needed, the line 'Aconnection.Open' is not really required. If a TSQLTransaction is destroyed, an automatic 'rollback' will be executed. Possible changes to data contained in the transaction will be lost. (这同样适用 TSQLConnection 连接。根据需要打开连接,Aconnection.Open 是否真的需要。如果 TSQLTransaction 被销毁,将会 'rollback'(回退)刚才执行的。 包含在事务中的数据,可能会丢失。)

为什么 TSQLQuery.RecordCount 总返回 10

使用 '.RecordCount' 统计数据集记录数。需要注意的是,'.RecordCount' 表示的是已经从服务器加载的记录数。出于性能考虑,SqlDB 默认情况下只读取 TSQLQuery 的前 10 条记录。只有当访问第 11 条记录时,下一组的 10 条记录才被加载。使用 '.Last',将载入所有记录。

如果你想知道服务器真正的记录数,先调用 '.Last' 再调用 '.RecordCount'。

另一种方法更实用,服务器返回记录数是由 '.PacketRecords' 控制,默认值时 10,你可以设置为 -1,那么所有记录都将被加载。

In current stable FPC, '.RecordCount' does not take filters into account, i.e. it shows the unfiltered total. (当前稳定的 FPC,'.RecordCount' 不会考虑筛选器,既便它显示了过滤。)

If you need the exact number of records, it often is a better idea to directly query the number of records in a query using another SQL query, but you would have to do that in the same transaction, as other transactions may have changed the number of records in the meanwhile.(如果你需要确切记录数量,在同一个事务中使用 SQL 查询记录数。否则,其他事务或许会改变记录数。

Lazarus

Lazarus 有各种组件在窗体上显示 TDataset 数据。而不是使用 While-loop 或 Writeln 语句在上面显示,你可以使用组件显示表中的数据。

请正确在窗体上放置 TSQLConnection、TSQLTransaction 和 TSQLQuery 组件,此外还需要一个 TDatasource 组件,设置 'TDatasource.Dataset' 使用 TSQLQuery 组件。(注意,不要设置 'TSQLQuery.Datasource' 的属性为 TDatasource 组件。'TSQLQuery.Datasource' 使用主从表)之后,你可以把 TDBGrid 的属性 'Datasource' 设置为 TDatasource 。看下能否工作,设置 TSQLConnection 的 'Connected' 属性为真,IDE 将尝试立刻连接到数据库服务器。如果正常,设置 'TSQLQuery.Active'属性为真。如果一切顺利,你将在屏幕上看到所有表数据。


译者注:

在测试使用时,设置 'TSQLQuery.Active'属性 或 TSQLConnection 的 'Connected' 为真,(因为我使用的是 MySQL) 因此提示:

Can not load default MySQL library libmysql.dll ......

完全可以不用理会,你在程序中手动连接数据库服务器就行了。

如何修改表中数据

要更改记录中的数据,TDataset (由 TSQLQuery 派生)必须设置为编辑模式。进入编辑模式可以调用 '.Edit'、 '.Insert' 或 '.Append' 方法。使用 '.Edit' 方法用来修改当前记录。'.Insert' 方法,在当前记录前插入新记录。'.Append' 方法,在表尾插入新记录。在编辑模式中,你可以通过 'Fields' 属性更改字段值。使用 'Post' 以验证新的数据,如果数据有效将离开编辑模式。If you move to another record - for example by using '.Next' - and the dataset is in edit mode, then first '.Post' is called. (如果你移动到另一条记录 - 像通过使用 '.Next' - 而数据集处于编辑模式,那么 '.Post' 将被调用。)使用 '.Cancel' 放弃自上次 '.Post' 的所有更改并退出编辑模式。

Query.Edit;
Query.FieldByName('NAME').AsString := 'Edited name';
Query.Post;

上述还不完整。TSQLQuery is derived from TBufDataset which makes use of buffered updates. Buffered update means that after you called 'Post' the changes in the dataset are visible immediately,(TSQLQuery 派生自 TBufDataset 利用缓冲更新。缓冲更新意味着,调用 'Post' 更新数据集是即刻生效。)但它们还没被发送到数据库服务器。 What does happen is that the changes are maintained in a change log. (所发生的是,改变在更新日志中。) 当调用 '.ApplyUpdates' 方法时,所做的更改都将发送到数据库。只有这样,数据库服务器才知道所做的更改。所做的更改发送到 TSQLTransaction 事务内部服务器。 Make sure to properly set the transaction before 'ApplyUpdates'. After applying the updates, a commit must be executed to save the changes on the database server. (在事务开始之前正确设置 'ApplyUpdates'。应用更新后,必须执行提交,将更改保存在数据库服务器上。

下面是更改表中数据的示例,sending the changes to the server and comitting the transaction.(发送变更到服务器。

Program EditData;
 
var 
  AConnection : TSQLConnection;
  ATransaction : TSQLTransaction;
  Query : TSQLQuery;
 
begin
  CreateConnection;
  CreateTransaction;
  AConnection.Transaction := ATransaction;
  Query := GetQuery;
  Query.SQL.Text := 'select * from tblNames';
  Query.Open;
  Query.Edit;
  Query.FieldByName('NAME').AsString := 'Edited name';
  Query.Post;
  Query.UpdateMode := upWhereAll;
  Query.ApplyUpdates;
  AConnection.Transaction.Commit;
  Query.Free;
  ATransaction.Free;
  AConnection.Free;
end.

探讨 'UpdateMode' 请继续阅读。

如何将SqlDB更改发送到服务器

In the code example in #How to change data in a table?, you will find the line

Query.UpdateMode := upWhereAll;

without explanation of what it does. The best way to find out what that line does is to leave it out. If you leave out the statement and the followed this howto precisely, then you will receive the following error message:

No update query specified and failed to generate one. (No fields for inclusion in where statement found)

To understand what went wrong, you must understand how changes are sent to the database server. The only way to get data in a SQL server is by executing SQL queries. SQL has three types of queries for three different ways of manupulating a record. To create a new record, change or delete a record insert, update and delete statements are executed respectively. An update statement may be as follows:

update TBLNAMES set NAME='Edited name' where ID=1;

To send a change to the database server, Sqldb must assemble an update query. To assemble the query, three things are needed:

The name of the table
The table name is retrieved from parsing the select query, although this doesn't always work.
UPDATE or INSERT clause
These contain the fields that must be changed.
WHERE clause
This contains the fields that determine which records should be changed.

Every field (each TField in Fields) has a ProviderFlags property. Only fields with pfInUpdate in ProviderFlags will be used in the update or insert cluase of a query. By default all fields have pfInUpdate set in their ProviderFlags property.

Which fields are used in the WHERE clause depends on the UpdateMode property of the query and the ProviderFlags property of the fields. Fields with pfInkey in their ProviderFlags are always used in the WHERE clause. A field will have the pfInKey flag set automatically if the field is part of the primary key of the table and 'TSQLQuery.UsePrimaryKeyAsKey' returns 'True'.

The default value for UpdateMode of the query is upWhereKeyOnly. In this update mode only fields with pfInkey in their ProviderFlags property are used in the WHERE clause. If none of the fields have their pfInKey flag set, then no fields are available for the WHERE clause and the error message from the beginning of this section will be returned. You can solve the issue by:

  • Adding a primary key to the table and set TSQLQuery.UsePrimaryKeyAsKey to 'True', or
  • Setting the pfInkey flag for one or more fields in code.

The UpdateMode property knows two more possible values. 'upWhereAll' can be used to add all fields with the 'pfInWhere' flag set to the WHERE clause. By default all fields have this flag set. 'upWhereChanged' can be used to add only those fields that have the 'pfInWhere' flag set and that are changed in the current record.

如何使用 TSQLQuery 执行查询

Next to statements that return a dataset (see #How to read data from a table?) SQL has statements that do not return data. For example INSERT, UPDATE and DELETE statements do not return data. These statements can be executed using TSQLConnection.ExecuteDirect, but TSQLQuery can also be used. If you do not expect return data use TSQLQuery.ExecSQL instead of TSQLQuery.Open. As mentioned earlier, use TSQLQuery.Open to open the dataset returned by the SQL statement.

The following procedure creates a table and inserts two records using TSQLQuery.

procedure CreateTable;
  
var 
  Query : TSQLQuery;
  
begin
  Query := GetQuery;
  Query.SQL.Text := 'create table TBLNAMES (ID integer, NAME varchar(40));';
  Query.ExecSQL;
 
  Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (1,''Name1'');';
  Query.ExecSQL;
  
  Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (2,''Name2'');';
  Query.ExecSQL;
  
  Query.Close;
  Query.Free;
end;

如何在查询中使用参数

In the code example of #How to execute a query using TSQLQuery? the same query is used twice, only the values to be inserted differ. A better way to do this is by using parameters in the query.

The syntax of parameters in queries is different per database system, but the differences are handled by TSQLQuery. Replace the values in the query with a colon followed by the name of the parameter you want to use. For example:

Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (:ID,:NAME);';

This query will create two parameters: 'ID' and 'NAME'. To determine the parameters, the query is parsed at the moment the text of TSQLQuery.SQL is assigned or changed. All existing parameters will be removed and the new parameters will be added to the 'TSQLQuery.Params' property. Assigning a value to a parameter is similar to assigning a value to a field in the dataset:

Query.Params.ParamByName('Name').AsString := 'Name1'

;

You can't tell from the query what kind of data must be stored in the parameter. The data type of the parameter is determined at the moment a value is first assigned to the parameter. By assigning a value using '.AsString', the parameter is assigned the data type 'ftString'. You can determine the data type directly by setting the 'DataType' property. If an incorrect datatype is assigned to the parameter, then problems will occur during opening or executing the query. See Database field type for more information on data types.

Select 查询

An example of a select query with parameters would be to change something like this:

  Query.SQL.Text := 'select ID,NAME from TBLNAMES where NAME = '''+Edit1.Text+''' ORDER BY NAME ';

to something like this:

  Query.SQL.Text := 'select ID,NAME from TBLNAMES where NAME = :NAMEPARAM ORDER BY NAME ';
  Query.Params.ParamByName('NAMEPARAM').AsString := Edit1.Text;

示例

The following example creates the same table as the previous example, but now parameters are used:

procedure CreateTableUsingParameters;
  
var 
  Query : TSQLQuery;
  
begin
  Query := GetQuery;
  Query.SQL.Text := 'create table TBLNAMES (ID integer, NAME varchar(40));';
  Query.ExecSQL;

  Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (:ID,:NAME);';
  
  Query.Params.ParamByName('ID').AsInteger := 1;
  Query.Params.ParamByName('NAME').AsString := 'Name1';
  Query.ExecSQL;
  
  Query.Params.ParamByName('ID').AsInteger := 2;
  Query.Params.ParamByName('NAME').AsString := 'Name2';
  Query.ExecSQL;
  
  Query.Close;
  Query.Free;
end;

Notice that this example requires more code than the example without the parameters. Then what is the use of using parameters? Speed is one of the reasons. The example with parameters is faster because the query is parsed only once. TSQLQuery only parses the query once, but also the database server parses the query only once. Most database systems support parameters. Whenever a query is used more than once with different values for the parameter each time, then the database server only parses the query and plans the query only once making execution considerably faster. Use 'TSQLQuery.Prepare' to determine the moment the query is parsed and planned by the database server. Use 'TSQLQuery.UnPrepare' to make sure the query is parsed and planned every time by the data server.

Another reason to use prepared statements is prevention of SQL注入 (see also Secure programming.

Finally, in some cases it just simplifies coding.

Troubleshooting: TSQLConnection logging

You can let a TSQLConnection log what it is doing. This can be handy to see what your Lazarus program sends to the database exactly, to debug the database components themselves and perhaps to optimize your queries. NB: if you use prepared statements/parametrized queries (see section above), the parameters are often sent in binary by the TSQLConnection descendent (e.g. TIBConnection), so you can't just copy/paste the logged SQL into a database query tool. Regardless, connection logging can give a lot of insight in what your program is doing.

Alternatives are:

  1. you can use the debugger to step through the database code if you have built FPC (and Lazarus) with debugging enabled.
  2. if you use ODBC drivers (at least on Windows) you could enable tracelog output in the ODBC control panel.
  3. many databases allow you to monitor all statements sent to it from a certain IP address/connection.


If you use TSQLConnection logging, two things are required:

  1. indicate which event types your TSQLConnection should log
  2. point TSQLConnection at a function that receives the events and processes them (logs them to file, prints them to screen, etc.).

That function must be of type TDBLogNotifyEvent (see sqldb.pp), so it needs this signature:

TDBLogNotifyEvent = Procedure (Sender : TSQLConnection; EventType : TDBEventType; Const Msg : String) of object;

FPC (或:手动方式)

A code snippet can illustrate this:

uses
...
TSQLConnection, //or a child object like TIBConnection, TMSSQLConnection
...
var
type 
  TMyApplication = class(TCustomApplication); //this is our application that uses the connection
...
  private
    // This example stores the logged events in this stringlist:
    FConnectionLog: TStringList;
...
  protected
    // This procedure will receive the events that are logged by the connection:
    procedure GetLogEvent(Sender: TSQLConnection; EventType: TDBEventType; Const Msg : String);
...
  procedure TMyApplication.GetLogEvent(Sender: TSQLConnection;
    EventType: TDBEventType; const Msg: String);
  // The procedure is called by TSQLConnection and saves the received log messages
  // in the FConnectionLog stringlist
  var
    Source: string;
  begin
    // Nicely right aligned...
    case EventType of
      detCustom:   Source:='Custom:  ';
      detPrepare:  Source:='Prepare: ';
      detExecute:  Source:='Execute: ';
      detFetch:    Source:='Fetch:   ';
      detCommit:   Source:='Commit:  ';
      detRollBack: Source:='Rollback:';
      else Source:='Unknown event. Please fix program code.';
    end;
    FConnectionLog.Add(Source + ' ' + Msg);
  end;

...
  // We do need to tell our TSQLConnection what to log:
    FConnection.LogEvents:=LogAllEvents; //= [detCustom, detPrepare, detExecute, detFetch, detCommit, detRollBack]
    // ... and to which procedure the connection should send the events:
    FConnection.OnLog:=@Self.GetLogEvent;
...
  // now we can use the connection and the FConnectionLog stringlist will fill with log messages.

You can also use TSQLConnection's GlobalDBLogHook instead to log everything from multiple connections.

Lazarus (或: 快捷方式)

Finally, the description above is the FPC way of doing things as indicated in the introduction; if using Lazarus, a quicker way is to assign an event handler to the TSQLConnection's OnLog event.

参见