SqlDBHowto/ja: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		このテキストは「how-to」として作られている。数多くの質問に1つ、1つ答え、どのように様々なクラスを用いるのか説明したい。これらすべての質問は次から次へと沸き起こり、ある種のチュートリアルとなった。
2	2
3	3		このテキストがFree Pascal同様にLazarusでも用いられるように書くつもりだが、例はFree Pascal(即ち、コンソールアプリケーション)に向けてある。
4	4
5	5		## どこで公式のドキュメンテーションが見つかるか
6	6
7	7		公式ドキュメンテーションはここを参照されたい[SQLDBドキュメンテーション](http://www.freepascal.org/docs-html/fcl/sqldb/index.html)。
8	8
9	9		## どのようにしてデータベースサーバに接続するか
10	10
11	11		SqlDBは直接データベースサーバには接続せず、用いられているデータベースサーバに対応するクライアントを用いる。SqlDBはクライアントライブラリにコマンドを送り、クライアントライブラリがデータベースサーバに接続しコマンドを送る。これはデータベースと接続を持つためにクライアントライブラリがインストールされていなければならないことを意味する。Windowsではクライアントライブラリは通常、.dll、Linux では.so、OS/Xでは.dylibである。
12	12
13	13		クライアントライブラリが適切にインストールされているときには、TSQLConnectionコンポーネントを用いてデータベースサーバに接続できる。様々なTSQLConnectionコンポーネントが異なるデータベースサーバに対して利用可能である([[SQLdb Package\|SQLdb_Packageを]]参照):
14	14
15	15		- Firebird/Interbase: [[TIBConnection]]
16	16		- MS SQL Server: [[TMSSQLConnection]] (FPC 2.6.1から利用可能)
17	17		- MySQL v4.0: [[TMySQL40Connection]]
18	18		- MySQL v4.1: [[TMySQL41Connection]]
19	19		- MySQL v5.0: [[TMySQL50Connection]]
20	20		- MySQL v5.1: [[TMySQL51Connection]] (FPC version 2.5.1から利用可能)
21	21		- MySQL v5.5: [[TMySQL55Connection]] (Lazarus 1.0.8/FPC version 2.6.2から利用可能)
22	22		- MySQL v5.6: [[TMySQL56Connection]] (Lazarus 1.2.4/FPC version 2.6.4から利用可能)
23	23		- MySQL v5.7: [[TMySQL57Connection]] (訳注:いつから?)
24	24		- ODBC: [[TODBCConnection]] ([[ODBCConn\|ODBCConn#TODBCConnectionを]]参照)
25	25		- Oracle: [[TOracleConnection]] ([[Oracle\|Oracleを]]参照)
26	26		- PostgreSQL: [[TPQConnection]] ([[postgresql\|postgresql#SQLDBを]]参照)
27	27		- Sqlite3: [[TSQLite3Connection/ja]] (FPC version 2.2.2から利用可能、[[SQLite\|SQLite#Built-in_SQLDBを]]参照)
28	28		- Sybase ASE: [[TSybaseConnection]] (FPC 2.6.1から利用可能、[[Lazarus Database Overview\|LazarusとMSSQL/Sybase]])
29	29
30	30		MySQLに対する注意 - クライアントとコネクションが相互交換できないほどクライアントバージョン間に多くの相違がある。もしクライアントライブラリバージョン 4.1がインストールされているとすると、TMySQL41Connectionを用いなければならない。これはMySQLサーバには関連しておらずMySQL 4.1クライアントライブラリを用いて、おそらくMySQL 5.0サーバに接続できる(どの組み合わせがサポートされているかはMySQLドキュメンテーションを参照されたい)。
31	31
32	32		さまざまなデータベースで細部は異なるが、一般的にデータベースサーバに接続するために4つのプロパティを設定しなければならない:
33	33
34	34		- サーバの名前とIPアドレス
35	35		- データベースの名前
36	36		- ユーザー名
37	37		- パスワード
38	38
39	39		これらのプロパティが設定されると、サーバに「open」メソッドを作ることができる。もし接続に失敗するとEDatabaseError例外が生じる。データベースサーバに接続が確立しているかどうか確かめるために、「connected」プロパティを用いること。
40	40
41	41		``` pascal
42	42		Program ConnectDB;
43	43
44	44		{$mode objfpc}{$H+}
45	45
46	46		uses
47	47		IBConnection;
48	48
49	49		function CreateConnection: TIBConnection;
50	50		begin
51	51		result := TIBConnection.Create(nil);
52	52		result.Hostname := 'localhost';
53	53		result.DatabaseName := '/opt/firebird/examples/employee.fdb';
54	54		result.UserName := 'sysdba';
55	55		result.Password := 'masterkey';
56	56		end;
57	57
58	58		var
59	59		AConnection : TIBConnection;
60	60
61	61		begin
62	62		AConnection := CreateConnection;
63	63		AConnection.Open;
64	64		if Aconnection.Connected then
65	65		writeln('Successful connect!')
66	66		else
67	67		writeln('This is not possible, because if the connection failed, ' +
68	68		'an exception should be raised, so this code would not ' +
69	69		'be executed');
70	70		AConnection.Close;
71	71		AConnection.Free;
72	72		end.
73	73		```
74	74
75	75		もし、エラーが発生したら、注意してエラーメッセージを読むこと。データベースサーバが稼働していない、ユーザー名もしくはパスワードが誤っている、データベース名またはIPアドレスが誤って入力されたかもしれない。もしエラーメッセージがクライアントライブラリが見つからないと言っているなら、クライアントライブラリが正しくインストールされているか確かめること。しばしばエラーメッセージは探しているファイル名を文字通り言う。
76	76
77	77		## どのようにして直接クエリを実行/テーブルを作るのか
78	78
79	79		SqlDB - 文字通り名前がすべてを体現している - はSQLを用いて唯一、データベースサーバとやり取りをする。SQL は「Structured Query Language」を意味する。 SQLはリレーショナルデータベースとやり取りすることを可能にするために開発された言語である。実際にはすべてのデータベースシステムはそれぞれ方言を持っているが、SQLステートメントの多くはすべてのデータベースシステムで共通している。
80	80
81	81		FPCでは、以下の違いがある:
82	82
83	83		- 情報(データセット)を返すSQLステートメント。このため、TSQLQueryコンポーネントを用いなければならない; #How to read data from a table?を参照のこと。
84	84		- 情報を返さずに、変わって何かを行うステートメント、例えば、データを更新する。このため、またTSQLConnectionの「ExecuteDirect」メソッドを使うかもしれない(データセットを引き戻すためにこれを使うこともできるが、結果に興味はない、例えばセレクタブルストアドプロシージャ)。
85	85
86	86		大半のデータベースシステムはトランザクションでSQLステートメントを実行する。もし、他のトランザクションの中で利用できるトランザクションの中で行われる変更を望む、もしくはトランザクションが閉じた後でそれらの変更する(!)ならば、トランザクションを「commit」しなければならない。
87	87
88	88		トランザクションをサポートするために、SqlDBはTSQLTransactionコンポーネントを含んでいる。SqlDBによって実行されるSQLステートメントはデータベースシステムが、トランザクションをサポートしていなくとも、常にトランザクションの最中に行われる必要がある。同様に、TSQLTransactionがいまだにサポートしていないトランザクションをサポートしているデータベースシステムも存在する。その時ですらTSQLTransactionコンポーネントを使わなければならない。
89	89
90	90		SQLステートメントを実行するために`TSQLConnection.ExecuteDirect`を使うには、どの「Transaction」が使われなければならないかを明示しなければならない。逆に、TSQLTransactionを使うためには、どのTSQLTransactionコンポーネントが使われるかを明示しなければならない。
91	91
92	92		以下の例は「NAME」と「ID」フィールドを持つ「TBLNAMES」を生成し2つのレコードを挿入する。今回はSQLiteを用いる。使われるSQLステートメントは説明されない。SQLステートメント、その使用と文法に関しては、データベースシステムのドキュメンテーションを参照されたい。この例ではいかなるエラーの捕捉も試みないことに注意すること、それは悪いことである! [例外](https://www.freepascal.org/docs-html/current/ref/refch17.html#x226-24800017)を調べていただきたい。
93	93
94	94		``` pascal
95	95		program CreateTable;
96	96		{$mode objfpc} {$ifdef mswindows}{$apptype console}{$endif}
97	97		uses
98	98		sqldb, sqlite3conn;
99	99
100	100		var
101	101		AConnection : TSQLite3Connection;
102	102		ATransaction : TSQLTransaction;
103	103
104	104		begin
105	105		AConnection := TSQLite3Connection.Create(nil);
106	106		AConnection.DatabaseName := 'test_dbase';
107	107
108	108		ATransaction := TSQLTransaction.Create(AConnection);
109	109		AConnection.Transaction := ATransaction;
110	110		AConnection.Open;
111	111		ATransaction.StartTransaction;
112	112		AConnection.ExecuteDirect('create table TBLNAMES (ID integer, NAME varchar(40));');
113	113
114	114		ATransaction.Commit;
115	115
116	116		ATransaction.StartTransaction;
117	117		AConnection.ExecuteDirect('insert into TBLNAMES (ID,NAME) values (1,''Name1'');');
118	118		AConnection.ExecuteDirect('insert into TBLNAMES (ID,NAME) values (2,''Name2'');');
119	119		ATransaction.Commit;
120	120		AConnection.Close;
121	121		ATransaction.Free;
122	122		AConnection.Free;
123	123		end.
124	124		```
125	125
126	126		## どのようにしてテーブルからデータを取得するのか
127	127
128	128		テーブルからデータを読み込むときにはTSQLQueryを用いること。TSQLQueryコンポーネントはその仕事をするために、TSQLConnectionコンポーネントとTSQLTransactionコンポーネントに接続されなければない。TSQLConnectionとTSQLTransactionの設定は#How to connect to a database server?と#How to execute direct queries/make a table?で議論する。
129	129
130	130		TSQLConnectionの時、TSQLTransactionとTSQLQueryが接続される、そしてTSQLQueryは動作するためにさらに設定される。TSQLQueryはTStringsオブジェクトを含む「SQL」プロパティを持つ。「SQL」プロパティは実行されるべきSQLステートメントを含んでいる。もしテーブル`tablename`のすべてのデータを読まなければならないときには、「SQL」プロパティを以下のように設定する:
131	131
132	132		``` sql
133	133		'SELECT * FROM tablename;'
134	134		```
135	135
136	136		サーバからテーブルを読み込み、TSQLQueryデータセットにデータを読み込むには「open」を使うこと。データは「close」を用いてクエリが閉じられるまでTSQLQueryを通してアクセスできる。
137	137
138	138		TSQLQueryはTDatasetのサブクラスである。TDatasetはテーブルのすべてのカラムを含む「Field」コレクションを持っている。TDatasetはまた、現在のレコードを追跡する。現在のレコードを変更するために「First」、「Next」、「Prior」、「Last」を用いること。もし最初のレコードが届いたら「Bof」が「True」となり、もし最後のレコードに達したら、「Eof」が「True」になる。現在のレコードの値を読むためには初めに正しい「TField」オブジェクトを見つけ、そして「AsString」、「AsInteger」を用いること。
139	139
140	140		### 例: テーブルからデータを取得する
141	141
142	142		以下は上のCreateTable例で作られたテーブルのすべての値を表示する例である。test_databaseファイルをShowDataワーキングディレクトリにコピーすること。エラーチェックを行っていないことに再び注意すること!
143	143
144	144		``` pascal
145	145		Program ShowData;
146	146		{$mode objfpc} {$ifdef mswindows}{$apptype console}{$endif}
147	147		uses
148	148		DB, Sysutils, sqldb, sqlite3conn;
149	149
150	150		var
151	151		AConnection : TSQLConnection;
152	152		ATransaction : TSQLTransaction;
153	153		Query : TSQLQuery;
154	154
155	155		begin
156	156		AConnection := TSQLite3Connection.Create(nil);
157	157		ATransaction := TSQLTransaction.Create(AConnection);
158	158		AConnection.Transaction := ATransaction;
159	159		AConnection.DatabaseName := 'test_dbase';
160	160		Query := TSQLQuery.Create(nil);
161	161		Query.SQL.Text := 'select * from tblNames';
162	162		Query.Database := AConnection;
163	163		Query.Open;
164	164		while not Query.Eof do
165	165		begin
166	166		Writeln('ID: ', Query.FieldByName('ID').AsInteger, 'Name: ' +
167	167		Query.FieldByName('Name').AsString);
168	168		Query.Next;
169	169		end;
170	170		Query.Close;
171	171		AConnection.Close;
172	172		Query.Free;
173	173		ATransaction.Free;
174	174		AConnection.Free;
175	175		end.
176	176		```
177	177
178	178		もちろん、上記のコードは未完成で、「try...finally」ブロックを欠く。しかし、上のコードはデータベースコードを示す意図のもので、そのため仕上げの一筆は省いてある。「TSQLTransaction.StartTransaction」が使われてないことに注意してほしい。これは不要である。TSQLQueryが開かれるとき、SQLステートメントが実行され、もしトランザクションが利用できないときにはトランザクションが自動的に始まる。プログラマは明示的にトランザクションを開始させる必要はない。同様のことがTSQLConnectionによって維持されている接続にも適用される。接続は必要に応じて開かれ、「Aconnection.Open」は全く必要ない。もし、TSQLTransactionが破棄されると、自動的「rollback」が実行される。トランザクションに含まれるデータに対する、ありえる変更は失われるだろう。
179	179
180	180		### なぜ TSQLQuery.RecordCount はいつも10を返すのか
181	181
182	182		データセットのレコードを数えるためには、「.RecordCount」を用いること。しかし、「.RecordCount」はサーバからすでに送り出されたレコードの数を示している。性能上の理由により、SqlDBはデフォルトではTSQLQueryを開いたときすべてのレコードを読まず、最初の10を読む。11番目のレコードを読むときのみに次の10レコードがアクセスされる、など。「.Last」を用いると、すべてのレコードが読み込まれる。サーバにあるレコードの真の数を知りたいときは、初めに「.Last」、そして「.RecordCount」を呼ぶことができる。また別のやり方もある。サーバによって返されるレコードの数は「.PacketRecords」プロパティにセットされる。そのデフォルト値は10、これを-1に設定すると、一度にすべてのレコードが読み込まれる。
183	183
184	184		現在の安定版のFPCでは、.RecordCountはフィルタを考慮に入れていない。即ち、それはフィルタをかけられない総和となる。
185	185
186	186		もしレコードの正確な数を必要としているのであれば、ほかのSQLクエリをクエリの中で用いてレコードの数を直接問い合わせるのがしばしばより良い考えであるが、その間に他のトランザクションがレコードの数を変えたかもしれないので、同じトランザクションの中でそれをしなければならないだろう。
187	187
188	188		### Lazarus
189	189
190	190		Lazarusはフォーム上にTDatasetからのデータを示すために様々なコンポーネントを持っている。正しいTSQLConnection、TSQLTransaction、TSQLQueryコンポーネントをフォームに置き、そしてそれらを適切に接続、設定すること。加えて、TDatasourceが必要となり、「TDatasource.Dataset」プロパティを、用いるTSQLQueryコンポーネントに設定すること。 (注意「TSQLQuery.Datasource」プロパティを、用いるTDatasourceコンポーネントに設定しないこと。「TSQLQuery.Datasource」プロパティはmaster-detailテーブルのみに使われる - [[MasterDetail]]参照)。結果としてTDGridをフォームに配置して、前に加えたTDatasourceをグリッドのプロパティに設定するることになる。
191	191
192	192		これらすべてが機能していることを見るために、TSQLConnectionの「Connected」プロパティをLazarus IDEで「True」に設定すること。IDEはデータベースサーバへ直ちに接続を試みるだろう。もし、これが動いたら、「TSQLQuery.Active」プロパティを「True」に設定できる。もしすべてが正しいなら、IDEの中に、直ちにテーブルからのすべてのデータがみられるだろう。
193	193
194	194		## どのようにしてテーブルのデータを変更するのか
195	195
196	196		レコード内のデータを変更するための一般的なプロセスは、TSQLQuery を取得して変更するレコードを検索し、そこで変更を加えてデータベースにプッシュし直すことである。[[TDataSet]] (TSQLQuery の派生元) は編集モードに設定する必要がある。編集モードに入るには、「.Edit」、「.Insert」、または「.Append」メソッドを呼び出す。現在のレコードを変更するには、「.Edit」メソッドを使用する。現在のレコードを変更するには、「.Edit」メソッドを使用する。現在のレコードの前に新しいレコードを挿入するには、「.Insert」を使用する。テーブルの最後に新しいレコードを挿入するには、「.Append」を使用する。編集モードでは、「フィールド」プロパティを通じてフィールド値を変更できる。「Post」を使用して新しいデータを検証する。データが有効な場合は、編集モードが終了する。たとえば「.Next」を使用して別のレコードに移動し、データセットが編集モードの場合、最初に「.Post」が呼び出される。「.Cancel」を使用すると、最後の「.Post」呼び出し以降に加えたすべての変更が破棄され、編集モードが終了します。
197	197
198	198		``` pascal
199	199		Query.Edit;
200	200		Query.FieldByName('NAME').AsString := 'Edited name';
201	201		Query.Post;
202	202		```
203	203
204	204		上記はまだ完全な話ではない。 TSQLQuery は、バッファされた更新を利用する TBufDataset から派生している。バッファ更新とは、「Post」を呼び出した後、データセット内の変更がすぐに表示されるが、データベースサーバーには送信されないことを意味する。実際に起こるのは、変更が変更ログに保持されることである。「.ApplyUpdates」メソッドが呼び出されると、変更ログ内のすべての変更がデータベースに送信される。そうして初めて、データベースサーバーは変更を認識する。変更は、TSQLTransaction のトランザクション内でサーバーに送信される。「ApplyUpdates」の前にトランザクションを正しく設定すること。更新を適用した後、コミットを実行して変更をデータベースサーバーに保存する必要がある。
205	205
206	206		以下は、テーブル内のデータを変更し、変更をサーバーに送信し、トランザクションをコミットする例である。繰り返すが、エラーチェックがない。これは非常に芳しくない!
207	207
208	208		``` pascal
209	209		Program EditData;
210	210		{$mode objfpc} {$ifdef mswindows}{$apptype console}{$endif}
211	211		uses
212	212		db, sqldb, sqlite3conn;
213	213		var
214	214		AConnection : TSQLConnection;
215	215		ATransaction : TSQLTransaction;
216	216		Query : TSQLQuery;
217	217
218	218		begin
219	219		AConnection := TSQLite3Connection.Create(nil);
220	220		ATransaction := TSQLTransaction.Create(AConnection);
221	221		AConnection.Transaction := ATransaction;
222	222		AConnection.DatabaseName := 'test_dbase';
223	223		Query := TSQLQuery.Create(nil);
224	224		Query.DataBase := AConnection;
225	225		Query.SQL.Text := 'select * from tblNames where ID = 2';
226	226		Query.Open;
227	227		Query.Edit;
228	228		Query.FieldByName('NAME').AsString := 'Name Number 2';
229	229		Query.Post;
230	230		Query.UpdateMode := upWhereAll; // dbで定義されている
231	231		Query.ApplyUpdates;
232	232		ATransaction.Commit;
233	233		Query.Free;
234	234		ATransaction.Free;
235	235		AConnection.Free;
236	236		end.
237	237		```
238	238
239	239		実際の作業は、変更するレコードを識別する SQL ステートメント「select * from tblNames where ID = 2」から始まる。「where ID = 2」ビットを省略すると、TSQLQuery は明らかに ID (および他の整数フィールド?) を 1 に設定する。そのため、ID=1 の行のみで動作する。「UpdateMode」については、引き続き読み進められたい。
240	240
241	241		## どのようにして SqlDB はデータベースサーバに変更を送るのか
242	242
243	243		#どのようにしてテーブルのデータを変更するのかのコード例で以下が、何をしているのか説明なしに記載されている。
244	244
245	245		``` pascal
246	246		Query.UpdateMode := upWhereAll;
247	247		```
248	248
249	249		その行が何をしているのかを知る最良の方法は、その行を省略することだ。このステートメントを省略し、この Howto に正確に従った場合、次のエラーメッセージが表示される:
250	250
251		-	~~`No update query specified and failed to generate one. (No fields for inclusion in where statement found)`~~
	251	+	```text
	252	+	No update query specified and failed to generate one. (No fields for inclusion in where statement found)
	253	+	```
252	254
253	255		何が問題なのかを理解するには、変更がどのようにデータベースサーバーに送信されるかを理解する必要がある。SQL サーバー内のデータを取得する唯一の方法は、SQL クエリを実行することだ。SQL には、レコードを操作する 3 つの異なる方法に対応する 3 種類のクエリがある。新しいレコードの作成、レコードの変更または削除には、それぞれ、insert、update、delete ステートメントが実行される。アップデートステートメントは以下のようなものだろう:
254	256
255	257		``` sql
256	258		update TBLNAMES set NAME='Edited name' where ID=1;
257	259		```
258	260
259	261		変更をデータベースサーバーに送信するには、Sqldb は更新クエリを組み立てる必要がある。クエリを組み立てるには、以下の3つが必要である:
260	262
261	263		テーブルの名前
262	264		テーブル名は選択クエリの解析から取得されるが、これは常に機能するとは限らない。
263	265
264	266		`UPDATE` もしくは `INSERT` 句
265	267		これらには、変更する必要があるフィールドが含まれている。
266	268
267	269		`WHERE` 句
268	270		これには、どのレコードを変更する必要があるかを決定するフィールドが含まれる。
269	271
270	272		すべてのフィールド(Fieldの各TField) には ProviderFlags プロパティがある。ProviderFlags に pfInUpdate があるフィールドのみが、クエリの更新または挿入条件で使用される。デフォルトではすべてのフィールドの ProviderFlags プロパティに pfInUpdate が設定されている。`WHERE` 句でどのフィールドが使用されるかは、クエリの UpdateMode プロパティとフィールドの ProviderFlags プロパティによって異なる。「ProviderFlags」に「pfInkey」が含まれるフィールドは、常に `WHERE` 句で使用されます。フィールドがテーブルの主キーの一部であり、「TSQLQuery.UsePrimaryKeyAsKey」が「True」を返す場合、フィールドには自動的に「pfInKey」フラグが設定されます。クエリの UpdateMode のデフォルト値は upWhereKeyOnly である。この更新モードでは、ProviderFlags プロパティに pfInkey を持つフィールドのみが `WHERE` 句で使用される。どのフィールドにも pfInKey フラグが設定されていない場合、`WHERE` 句に使用できるフィールドはなく、このセクションの冒頭のエラーメッセージが返される。
271	273
272	274		この問題は以下で解決される:
273	275
274	276		- テーブルにプライマリキーを加え、TSQLQuery.UsePrimaryKeyAsKey を「True」に設定するか、
275	277		- コードの中でpfInkeyフラグを1つ、またはそれ以上のフィールドに設定する。
276	278
277	279		UpdateMode プロパティは、さらに 2 つの可能な値を認識します。「upWhereAll」を使用すると、「pfInWhere」フラグが `WHERE` 句に設定されているすべてのフィールドを追加できる。UpdateModeプロパティは2つの可能な値を知っている。デフォルトでは、すべてのフィールドにこのフラグが設定されている。「upWhereChanged」は「pfInWhere」フラグセットを持つフィールドおよび現在のレコードで、変更されたフィールドに用いることができる。
278	280
279	281		## エラーの取り扱い方
280	282
281	283		実行時エラーは避けられず、ディスクがいっぱいになる、必要なライブラリやヘルパーアプリケーションが利用できない、等の問題が発生する可能性があるため、それを許容する必要がある。 FPC は実行時エラーを非常に適切に検出して処理する。通常、何が問題だったのかについて簡潔かつ合理的な説明が得られるが、多くの理由でエラーを監視し、取り扱うことを望むだろう -
282	284
283	285		- おそらく、問題の最初の兆候が現れた時点でプログラムが終了することは望ましくないだろう。
284	286		- 続行する場合は、問題領域に割り当てられたメモリが回復されることを確認すること。メモリリークは発生しないようにする。
285	287		- ただし、さらに詳しく説明する場合は、状況に応じた説明をユーザーに提供しよう。
286	288
287	289		次のコードは上記の例に基づいているが、今回は重要な場所でのエラーをチェックをする。鍵はtry...finally...end と try...except...end ブロックである。SQLite3をアンインストールして、test_dbaseのあったところにダミーファイルを置くなどして、これをテストすることができる。
288	290
289	291		``` pascal
290	292		program DemoDBaseWithErrors;
291	293		{$mode objfpc} {$ifdef mswindows}{$apptype console}{$endif}
292	294		uses
293	295		DB, Sysutils, sqldb, sqlite3conn;
294	296		var
295	297		Connect : TSQLite3Connection;
296	298		Trans : TSQLTransaction;
297	299
298	300		procedure WriteTable (Command : string);
299	301		begin
300	302		Connect.ExecuteDirect(Command);
301	303		Trans.Commit;
302	304		end;
303	305
304	306		procedure ReadTable ();
305	307		var
306	308		Query : TSQLQuery;
307	309		Count : smallint;
308	310		begin
309	311		Count := 0;
310	312		try
311	313		Query := TSQLQuery.Create(nil);
312	314		Query.DataBase := Connect;
313	315		Query.SQL.Text:= 'select * from tblNames';
314	316		Query.Open; // これは接続を開始する
315	317		while not Query.EOF do begin
316	318		writeln('ID: ', Query.FieldByName('ID').AsInteger, ' Name: ' +
317	319		Query.FieldByName('Name').AsString);
318	320		Query.Next;
319	321		Count := Count + 1;
320	322		end;
321	323		finally
322	324		Query.Close;
323	325		Query.Free;
324	326		end;
325	327		writeln('Found a total of ' + InttoStr(Count) + ' lines.');
326	328		end;
327	329
328	330		procedure FatalError(ClassName, Message, Suggestion : string);
329	331		begin
330	332		writeln(ClassName);
331	333		writeln(Message);
332	334		writeln(Suggestion);
333	335		Connect.Close; // 解放することを心配するのはばかげているかもしれない。
334	336		Trans.free; // halt()を呼ぶつもりだが
335	337		Connect.Free; // これはデモだから、いいか ?
336	338		halt();
337	339		end;
338	340
339	341		begin
340	342		Connect := TSQLite3Connection.Create(nil);
341	343		Trans := TSQLTransaction.Create(Connect);
342	344		Connect.Transaction := Trans;
343	345		Connect.DatabaseName := 'test_dbase';
344	346		try
345	347		if not fileexists(Connect.DatabaseName) then begin
346	348		Connect.Open; // もし例えばSQLiteがインストールされていないときにEInOutErrorをあげる
347	349		Trans.StartTransaction;
348	350		WriteTable('create table TBLNAMES (ID integer Primary Key, NAME varchar(40));');
349	351		Trans.Commit;
350	352		end;
351	353		Connect.open;
352	354		Trans.StartTransaction;
353	355		WriteTable('insert into TBLNAMES (NAME) values (''AName1'');');
354	356		WriteTable('insert into TBLNAMES (NAME) values (''AName2'');');
355	357		except
356	358		on E : EDatabaseError do
357	359		FatalError(E.ClassName, E.Message, 'Does the file contain the correct database ?');
358	360		on E : EInOutError do
359	361		FatalError(E.ClassName, E.Message, 'Have you installed SQLite (and dev package)?');
360	362		on E : Exception do
361	363		FatalError(E.ClassName, E.Message, 'Something really really bad happened.');
362	364		end;
363	365		ReadTable();
364	366		Connect.Close;
365	367		Trans.Free;
366	368		Connect.Free;
367	369		end.
368	370		```
369	371
370	372		## どのようにしてTSQLQuery を用いてクエリを実行するのか
371	373
372	374		次にデータセット(#どのようにしてテーブルからデータを取得するのか参照)を返すステートメントである。SQLはデータを返さないステートメントを持っている。例えば、`INSERT`、`UPDATE`、`DELETE`ステートメントはデータを返さない。これらはTSQLConnection.ExecuteDirectを用いることで実行できるが、TSQLQueryもまた用いることができる。もし、TSQLQuery.Open の代わりに TSQLQuery.ExecSQL を使って、データが変えることを期待しないなら、先に述べたように、SQLステートメントによりデータセットを開くために、TSQLQuery.Open を用いること。
373	375
374	376		以下は TSQLQuery を用いてテーブルを作り、2つのレコードを作るプロシージャである。
375	377
376	378		``` pascal
377	379		procedure CreateTable;
378	380
379	381		var
380	382		Query : TSQLQuery;
381	383
382	384		begin
383	385		Query := TSQLQuery.Create(nil);
384	386		try
385	387		Query.Database := AConnection;
386	388
387	389		Query.SQL.Text := 'create table TBLNAMES (ID integer, NAME varchar(40));';
388	390		Query.ExecSQL;
389	391
390	392		Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (1,''Name1'');';
391	393		Query.ExecSQL;
392	394
393	395		Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (2,''Name2'');';
394	396		Query.ExecSQL;
395	397		finally
396	398		Query.Free;
397	399		end;
398	400		end;
399	401		```
400	402
401	403		## どのようにしてクエリの中でパラメータを用いるのか
402	404
403	405		In the code example of #どのようにしてTSQLQuery を用いてクエリを実行するのかのコード例の中で同じクエリが2回使われており、挿入される値が異なるだけである。これを行うより良い方法は、クエリの中でパラメータを用いることである。
404	406
405	407		クエリ内のパラメータの構文はデータベースシステムごとに異なるが、その違いは TSQLQuery によって処理される。
406	408
407	409		クエリ内の値をコロンに置き換え、その後に使用するパラメータの名前を続ける。例えば:
408	410
409	411		``` pascal
410	412		Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (:ID,:NAME);';
411	413		```
412	414
413	415		このクエリは2つのパラメータ: 「ID」と「NAME」を作る。
414	416
415	417		パラメーターを決定するために、TSQLQuery.SQL のテキストが割り当てられるか変更される時点でクエリが解析される。既存のパラメータはすべて削除され、新しいパラメータが「TSQLQuery.Params」プロパティに追加される。パラメーターに値を割り当てることは、データセット内のフィールドに値を割り当てることと似ている:
416	418
417	419		``` pascal
418	420		Query.Params.ParamByName('Name').AsString := 'Name1';
419	421		```
420	422
421	423		クエリからは、どのような種類のデータをパラメータに保存する必要があるかを知ることはできない。パラメータのデータ型は、パラメータに値が最初に割り当てられた時点で決定される。「.AsString」を使用して値を割り当てると、パラメータにはデータ型「ftString」が割り当てられる。'DataType' プロパティを設定することで、データ型を直接決定できる。不正なデータ型がパラメータに割り当てられている場合、クエリを開いたり実行したりするときに問題が発生する。データ型についてのさらなる情報は [[Database field type]] を参照されたい。
422	424
423	425		### Select クエリ
424	426
425	427		パラメーターを使用した選択クエリの例は、次のように変更することになる:
426	428
427	429		``` pascal
428	430		Query.SQL.Text := 'select ID,NAME from TBLNAMES where NAME = '''+Edit1.Text+''' ORDER BY NAME ';
429	431		```
430	432
431	433		をこのように:
432	434
433	435		``` pascal
434	436		Query.SQL.Text := 'select ID,NAME from TBLNAMES where NAME = :NAMEPARAM ORDER BY NAME ';
435	437		Query.Params.ParamByName('NAMEPARAM').AsString := Edit1.Text;
436	438		```
437	439
438	440		### 実装例
439	441
440	442		以下の例は1つ前の例と同じテーブルを生成するが、パラメータが用いられている:
441	443
442	444		``` pascal
443	445		procedure CreateTableUsingParameters;
444	446
445	447		var
446	448		Query : TSQLQuery;
447	449
448	450		begin
449	451		Query := TSQLQuery.Create(nil);
450	452		try
451	453		Query.Database := AConnection;
452	454
453	455		Query.SQL.Text := 'create table TBLNAMES (ID integer, NAME varchar(40));';
454	456		Query.ExecSQL;
455	457
456	458		Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (:ID,:NAME);';
457	459		Query.Prepare;
458	460
459	461		Query.Params.ParamByName('ID').AsInteger := 1;
460	462		Query.Params.ParamByName('NAME').AsString := 'Name1';
461	463		Query.ExecSQL;
462	464
463	465		Query.Params.ParamByName('ID').AsInteger := 2;
464	466		Query.Params.ParamByName('NAME').AsString := 'Name2';
465	467		Query.ExecSQL;
466	468
467	469		//Query.UnPrepare; // これを呼ぶ必要はない; Query.Closeによって呼ばれるはずである
468	470		Query.Close;
469	471		finally
470	472		Query.Free;
471	473		end;
472	474		end;
473	475		```
474	476
475	477		この例はパラメータを用いないコードよりもコード量が多くなることに気を付けること。ではパラメータの用途は何であろうか?
476	478
477	479		速度が1つの理由である。このパラメータを用いた例はより実行が速い、何故なら(.Prepareステートメントもしくは最初の実行で)データベースサーバはクエリを1回のみパースするからである。
478	480
479	481		またプリペアードステートメントを用いる別の理由は、[SQL-インジェクション](http://en.wikipedia.org/wiki/SQL_injection)を防ぐことになる ([[Secure programming\|Secure programmingも]]参照のこと)。
480	482
481	483		最後に、ある例ではコーディングを簡素化するためである。
482	484
483	485		## 問題解決法: TSQLConnection ログ
484	486
485	487		TSQLConnection の動作をログに記録させることができる。これは、Lazarus プログラムがデータベースに送信する内容を正確に確認したり、データベースコンポーネント自体をデバッグしたり、クエリを最適化したりする場合に便利である。注意: 準備されたステートメント/パラメータ化されたクエリ (上記のセクションを参照) を使用する場合、パラメータは多くの場合、TSQLConnection の派生 (TIBConnection など) によってバイナリで送信されるため、ログに記録された SQL をコピーしてデータベースクエリツールに貼り付けるだけではすまない。いずれにせよ、接続ログにより、プログラムの動作について多くの洞察が得られる。
486	488
487	489		これに代わるものとして:
488	490
489	491		1. デバッグを有効にして FPC (および Lazarus) をビルドした場合は、デバッガーを使用してデータベースコードをステップ実行できます。
490	492		2. ODBC ドライバーを使用している場合 (少なくとも Windows では)、ODBC コントロールパネルでトレースログ出力を有効にすることができる。
491	493		3. 多くのデータベースでは、特定の IP アドレス/接続から送信されるすべてのステートメントを監視できる。
492	494
493	495		TSQLConnection ログを使用する場合は、2 つのことが必要である:
494	496
495	497		1. TSQLConnection がログに記録する必要があるイベントタイプを指定する。
496	498		2. イベントを受信して処理する関数に TSQLConnection を指定する (イベントをファイルに記録したり、画面に出力したりするなど)。
497	499
498	500		この関数は TDBLogNotifyEvent 型である必要があるため (sqldb.pp を参照)、次の署名が必要である:
499	501
500	502		``` pascal
501	503		TDBLogNotifyEvent = Procedure (Sender : TSQLConnection; EventType : TDBEventType; Const Msg : String) of object;
502	504		```
503	505
504	506		### FPC (もしくは: 手動的方法)
505	507
506	508		コードスニペットでこれを説明できる:
507	509
508	510		``` pascal
509	511		uses
510	512		...
511	513		TSQLConnection, //もしくはTIBConnection、TMSSQLConnection といった派生オブジェクト
512	514		...
513	515		var
514	516		type
515	517		TMyApplication = class(TCustomApplication); //これが接続を用いるアプリケーション
516	518		...
517	519		private
518	520		// この例はこの文字列リストにログを格納する:
519	521		FConnectionLog: TStringList;
520	522		...
521	523		protected
522	524		// このプロシージャは接続によるログのイベントを受け取るだろう:
523	525		procedure GetLogEvent(Sender: TSQLConnection; EventType: TDBEventType; Const Msg : String);
524	526		...
525	527		procedure TMyApplication.GetLogEvent(Sender: TSQLConnection;
526	528		EventType: TDBEventType; const Msg: String);
527	529		// TSQLConnectionによってプロシージャが呼ばれ、FConnectionLogに
528	530		// 受け取ったメッセージログが保存される
529	531		var
530	532		Source: string;
531	533		begin
532	534		// 見た目よく右揃え
533	535		case EventType of
534	536		detCustom: Source:='Custom: ';
535	537		detPrepare: Source:='Prepare: ';
536	538		detExecute: Source:='Execute: ';
537	539		detFetch: Source:='Fetch: ';
538	540		detCommit: Source:='Commit: ';
539	541		detRollBack: Source:='Rollback:';
540	542		else Source:='Unknown event. Please fix program code.';
541	543		end;
542	544		FConnectionLog.Add(Source + ' ' + Msg);
543	545		end;
544	546
545	547		...
546	548		// 何をログに残したいか TSQLConnection に知らせる必要がある:
547	549		FConnection.LogEvents:=LogAllEvents; //= [detCustom, detPrepare, detExecute, detFetch, detCommit, detRollBack]
548	550		// ... そして、どのプロシージャに向けて、接続がイベントを送るべきか:
549	551		FConnection.OnLog:=@Self.GetLogEvent;
550	552		...
551	553		// これで接続を使用できるようになり、FConnectionLog 文字列リストにログメッセージが表示される
552	554		```
553	555
554	556		代わりに TSQLConnection の GlobalDBLogHook を使用して、複数の接続からすべてをログに記録することもできる。
555	557
556	558		### Lazarus (もしくは: 速い方法)
557	559
558	560		最後に、上記の説明は、冒頭で示した FPC の方法である。 Lazarus を使用している場合、より簡単な方法は、TSQLConnection の OnLog イベントにイベントハンドラーを割り当てることである。
559	561
560	562		## 以下も参照のこと
561	563
562	564		- [[Working With TSQLQuery]]
563	565
564	566		---
565	567		From the Free Pascal wiki, page "SqlDBHowto/ja", as it stood on 2024-04-01 after a change by Ariben, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history