SqlDBHowto/fr: what changed

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

Old	New		Line
1	1		Ce texte est conçu comme un 'comment-faire'. Je veux répondre à un nombre de question une par une, et expliquer comment vous pouvez utiliser les diverses classes. Toutes ces questions sont posées l'une après l'autre et forme une sorte de tutoriel.
2	2
3	3		Je vais essayer de le dire de telle façon que le texte peut être utilisé pour Lazarus ainsi que FreePascal. Cependant, les exemples sont écrits pour FreePascal (c'est-à-dire qu'ils sont des applications de type console).
4	4
5	5		## Où puis-je trouver la documentation officielle ?
6	6
7	7		Veuillez voir la documentation officielle à la page [SQLDB documentation](http://www.freepascal.org/docs-html/fcl/sqldb/index.html).
8	8
9	9		## Comment se connecter à un serveur de base de données ?
10	10
11	11		SqlDB ne se connecte pas directement à un serveur de base de données mais utilise un client qui correspond au serveur de base de données employé. SqlDB envoie les commandes à la bibliothèque cliente ; la bibliothèque cliente se connecte au serveur de base de données et transfert les commandes. Ce qui veut dire que la bibliothèque cliente doit être installée pour faire la connection à la base de données. Sous Windows le client est souvent une .dll, sous Linux un .so et sous OS/X une .dylib.
12	12
13	13		Quand la bibliothèque cliente est installée convenablement, vous pouvez vous connecter à la base de données en utilisant un composant TSQLConnection. Divers composants TSQLConnection sont disponibles pour les différents serveurs de bases de données (voir [[SQLdb Package/fr\|SQLdb_Package]]) :
14	14
15	15		- Firebird/Interbase: [[TIBConnection/fr\|TIBConnection]]
16	16		- MS SQL Server: [[TMSSQLConnection/fr\|TMSSQLConnection]] (disponible depuis FPC 2.6.1)
17	17		- MySQL v4.0: [[TMySQL40Connection/fr\|TMySQL40Connection]]
18	18		- MySQL v4.1: [[TMySQL41Connection/fr\|TMySQL41Connection]]
19	19		- MySQL v5.0: [[TMySQL50Connection/fr\|TMySQL50Connection]]
20	20		- MySQL v5.1: [[TMySQL51Connection/fr\|TMySQL51Connection]] (disponible depuis FPC version 2.5.1
21	21		- MySQL v5.5: [[TMySQL55Connection/fr\|TMySQL55Connection]] (disponible depuis Lazarus 1.0.8/FPC version 2.6.2
22	22		- MySQL v5.6: [[TMySQL56Connection/fr\|TMySQL56Connection]] (disponible dans Lazarus 1.2.4/FPC version 2.6.4
23	23		- ODBC: [[TODBCConnection/fr\|TODBCConnection]] (voir [[ODBCConn/fr\|ODBCConn/fr#TODBCConnection]])
24	24		- Oracle: [[TOracleConnection/fr\|TOracleConnection]] (voir [[Oracle/fr\|Oracle]])
25	25		- PostgreSQL: [[TPQConnection/fr\|TPQConnection]] (voir [[postgres/fr\|postgres/fr#SQLDB]])
26	26		- Sqlite3: [[TSQLite3Connection/fr\|TSQLite3Connection]] (disponible depuis FPC version 2.2.2, voir [[SQLite/fr\|SQLite/fr#Built-in_SQLDB]])
27	27		- Sybase ASE: [[TSybaseConnection/fr\|TSybaseConnection]] (disponible depuis FPC 2.6.1, voir [[Lazarus Database Overview/fr\|Lazarus et MSSQL/Sybase]])
28	28
29	29		Note pour MySQL - Il y a plusieurs différences entre les versions de clients qui font que les connections ne peuvent être interchangées. Si une bibliothèque cliente version 4.1 est installée, vous devez utiliser un TMySQL41Connection. Ce n'est pas lié au serveur MySQL ; en utilisant une bibliothèque cliente MySQL 4.1, vous pouvez probablement vous connecter à un serveur MySQL 5.0 (voir la documentation MySQL concernant les combinaisons supportées).
30	30
31	31		Bien que les détails diffèrent entre les les diverses bases de données, en général, vous aurez besoin de définir quatre propriétés pour vous connecter au serveur de base de données :
32	32
33	33		- Le nom du serveur ou l'adresse IP
34	34		- Le nom de la base de données
35	35		- Le nom de connection
36	36		- Le mot de passe
37	37
38	38		Quand ces propriétés sont définies, vous pouvez créer une connection avec la méthode 'open'. Si la connection échoue, une exception EDatabaseError est levée. Utilisez la propriété 'connected' pour savoir si la connection a été établie avec le serveur de base données. Utilisez la méthode 'close' pour mettre fin à la connection avec le serveur.
39	39
40	40		``` pascal
41	41		Program ConnectDB;
42	42
43	43		{$mode objfpc}{$H+}
44	44
45	45		uses
46	46		IBConnection;
47	47
48	48		function CreateConnection: TIBConnection;
49	49		begin
50	50		result := TIBConnection.Create(nil);
51	51		result.Hostname := 'localhost';
52	52		result.DatabaseName := '/opt/firebird/examples/employee.fdb';
53	53		result.UserName := 'sysdba';
54	54		result.Password := 'masterkey';
55	55		end;
56	56
57	57		var
58	58		AConnection : TIBConnection;
59	59
60	60		begin
61	61		AConnection := CreateConnection;
62	62		AConnection.Open;
63	63		if Aconnection.Connected then
64	64		writeln('Successful connect!')
65	65		else
66	66		writeln('This is not possible, because if the connection failed, ' +
67	67		'an exception should be raised, so this code would not ' +
68	68		'be executed');
69	69		AConnection.Close;
70	70		AConnection.Free;
71	71		end.
72	72		```
73	73
74	74		Si une exception est levée, lisez le message attentivement. Il se peut que le serveur ne soit pas en cours d'exécution, le nom de connection et/ou le mot de passe est incorrect ou le nom de base de données ou l'adresse IP sont mal orthographiés. Si le message d'erreur indique que la bibliothèque cliente n'est pas trouvée, alors il faut contrôler que le client est correctement installé. Souvent, le message d'erreur donne le nom du fichier recherché.
75	75
76	76		## Comment exécuter des requêtes directes/créer une base de données ?
77	77
78	78		SQlDB - le nom dit tout - fonctionne uniquement avec des serveurs de bases de données qui font usage de SQL. SQL signifie Langage Structuré de Requête (Structured Query Language), il est un langage développé pour permettre de travailler avec des bases de données relationnelles. Virtuellement chaque SGDBR (Système de Gestion de Bases de Données Relationnelles) a son propre dialecte, mais une grande partie des ordres SQL est la même pour tous les SGBDR.
79	79
80	80		Dans FPC, il y a une différence entre :
81	81
82	82		- des instructions qui retournent de l'information (un DataSet). Pour ceci, vous utiliserez un composant TSQLQuery ; voir #Comment lire de la donnée depuis une table ?.
83	83		- des instructions qui ne retournent pas d'information mais font quelque chose d'autre p.ex. mettre à jour des données. Pour ceci, vous pouvez aussi utiliser la méthode 'ExecuteDirect' de TSQLConnection (Vous pouvez également utiliser cette option si vous récupérez un jeu de données, mais que vous n'êtes pas intéressé par les résultats, par exemple dans une procédure stockée pouvant être sélectionnée).
84	84
85	85		La plupart des SGBDR exécute des ordres SQL dans une transaction. Si vous voulez rendre les changements dans une transaction disponibles dans d'autres transactions, ou avoir ces changements disponibles après la fermeture de la transaction, alors vous devez faire un 'commit' de la transaction.
86	86
87	87		Pour supporter les transactions, SqlDB contient un composant TSQLTransaction. Un ordre SQL qui est exécuté par SqlDB doit toujours être exécuté au sein d'une transaction, même si le SGBDR ne supporte pas les transactions. Aussi, il y a des SGBD qui supporte la transaction et pour lequel TSQLConnection ne supporte pas (encore) la transaction. Même là, vous devez employer le composant TSQLTransaction.
88	88
89	89		Pour utiliser `TSQLConnection.ExecuteDirect` pour exécuter un ordre SQL, vous devez spécifier quelle 'transaction' doit être utilisée. A son tour, pour utiliser TSQLTransaction, vous devez spécifier quel composant TSQLConnection doit être utilisé.
90	90
91	91		L'exemple suivant crée une table 'TBLNAMES' avec des champs 'NAME' et 'ID' et insère deux enregistrements. Cette fois en utilisant SQLite. Les ordres SQL employés ne sont pas expliqués. Pour plus d'information sur les ordres SQL, leur emploi et syntaxe, veuillez vous référer à la documentation du SGBDR. Remarquez que cet exemple ne tente pas d'intercepter les exceptions, ce qui est une mauvaise chose ! Regardez dans [Exceptions](https://www.freepascal.org/docs-html/current/ref/refch17.html#x226-24800017).
92	92
93	93		``` pascal
94	94		program CreateTable;
95	95		{$mode objfpc} {$ifdef mswindows}{$apptype console}{$endif}
96	96		uses
97	97		sqldb, sqlite3conn;
98	98
99	99		var
100	100		AConnection : TSQLite3Connection;
101	101		ATransaction : TSQLTransaction;
102	102
103	103		begin
104	104		AConnection := TSQLite3Connection.Create(nil);
105	105		AConnection.DatabaseName := 'test_dbase';
106	106
107	107		ATransaction := TSQLTransaction.Create(AConnection);
108	108		AConnection.Transaction := ATransaction;
109	109		AConnection.Open;
110	110		ATransaction.StartTransaction;
111	111		AConnection.ExecuteDirect('create table TBLNAMES (ID integer, NAME varchar(40));');
112	112
113	113		ATransaction.Commit;
114	114
115	115		ATransaction.StartTransaction;
116	116		AConnection.ExecuteDirect('insert into TBLNAMES (ID,NAME) values (1,''Name1'');');
117	117		AConnection.ExecuteDirect('insert into TBLNAMES (ID,NAME) values (2,''Name2'');');
118	118		ATransaction.Commit;
119	119		AConnection.Close;
120	120		ATransaction.Free;
121	121		AConnection.Free;
122	122		end
123	123		```
124	124
125	125		## Comment lire de la donnée depuis une table ?
126	126
127	127		Utilisez le composant TSQLQuery pour lire la donnée depuis une table. Un composant TSQLQuery doit être connecté à un composant TSQLConnection et à un composant TSQLTransaction pour réaliser sa tâche. La configuration de TSQLConnection et TSQLTransaction est discutée dans #Comment se connecter à un serveur de base de données ? et #Comment exécuter des requêtes directes/créer une base de données ?.
128	128
129	129		Quand les TSQLConnection, TSQLTransaction et TSQLQuery sont connectés, alors TSQLQuery demande davantage de configuration pour fonctionner. TSQLQuery possède une propriété 'SQL' contenant un objet TStrings. La propriété TStrings contient un ordre SQL qui doit être exécuté. Si toutes les données de la table `tablename` doivent être lues, alors la propriété SQL doit contenir :
130	130
131	131		``` sql
132	132		'SELECT * FROM tablename;'
133	133		```
134	134
135	135		.
136	136
137	137		Utilisez 'Open' pour lire la table du serveur et mettre les données dans le DataSet TSQLQuery. La donnée peut être accédée à travers TSQLQuery jusqu'à ce que la requête soit fermée en utilisant 'Close'.
138	138
139	139		TSQLQuery est une sous-classe de TDataset. TDataset possède une collection de 'Fields' (champs) qui contiennent toutes les colonnes de la table. Le DataSet garde aussi la trace de l'enregistrement courant. Utilisez 'First', 'Next', 'Prior' et 'Last' pour changer l'enregistrement courant. 'Bof' retourne 'True' si le premier enregistrement est atteint et 'Eof' retourne 'True' si le dernier enregistrement est atteint. Pour lire la valeur d'un champ dans l'enregistrement courant, trouvez d'abord le bon objet 'TField' et alors utilisez 'AsString', AsInteger', etc.
140	140
141	141		### Exemple : Lecture de donnée depuis une table
142	142
143	143		Ci-dessous se trouve un exemple qui affiche toutes les valeurs de la table tel que cela est fait au dessus #Comment exécuter des requêtes directes/créer une base de données ?.
144	144
145	145		``` pascal
146	146		Program ShowData;
147	147
148	148		function CreateQuery(pConnection: TIBConnection; pTransaction: TSQLTransaction): TSQLQuery;
149	149		begin
150	150		result := TSQLQuery.Create(nil);
151	151		result.Database := pConnection;
152	152		result.Transaction := pTransaction
153	153		end;
154	154
155	155		var
156	156		AConnection : TSQLConnection;
157	157		ATransaction : TSQLTransaction;
158	158		Query : TSQLQuery;
159	159
160	160		begin
161	161		AConnection := CreateConnection;
162	162		ATransaction := CreateTransaction(AConnection);
163	163		Query := CreateQuery(AConnection, ATransaction);
164	164		Query.SQL.Text := 'select * from tblNames';
165	165		AConnection.Open;
166	166		Query.Open;
167	167		while not Query.Eof do
168	168		begin
169	169		Writeln('ID: ', Query.FieldByName('ID').AsInteger, 'Name: ' +
170	170		Query.FieldByName('Name').AsString);
171	171		Query.Next;
172	172		end;
173	173		Query.Close;
174	174		AConnection.Close;
175	175		Query.Free;
176	176		ATransaction.Free;
177	177		AConnection.Free;
178	178		end.
179	179		```
180	180
181	181		(le code du dessus n'est bien sûr pas tout à fait terminé. Il manque des blocs 'try...finally'. Il s'agit de montrer le code d'accès à la base de données, la finition est mise de côté.) Veuillez remarquer que 'TSQLTransaction.StartTransaction' n'est pas utilisé. Ce n'est pas nécessaire. Quand TSQLQuery est ouverte, l'ordre SQL est exécuté et si aucune transaction n'est disponible alors une transaction est automatiquement démarrée. Le développeur n'a pas besoin de démarrer une transaction explicitement. La même chose s'applique à la connection maintenue par TSQLConnection. La connection est ouverte au besoin, La ligne 'Aconnection.Open' n'est pas vraiment requise. Si un TSQLTransaction est détruit, un 'RollBack' automatique sera exécuté. Des modifications de données contenues dans la transaction pourront être perdues.
182	182
183	183		### Pourquoi TSQLQuery.RecordCount retourne toujours 10 ?
184	184
185	185		Pour compter les enregistrements dans un DataSet, utilisez la propriété '.RecordCount'. Pourtant, remarquez que '.RecordCount' montre le nombre d'enregistrements qui sont déjà chargés depuis le serveur. Pour des raisons de performance, SqlDB ne lit pas tous les enregistrements à l'ouverture du TSQLQuery par défaut, seulement les 10 premiers. Ce n'est que lorsque le onzième enregistrement est accédé que le prochain ensemble de 10 enregistrements sera chargé, etc. En utilisant '.Last', tous les enregistrements seront chargés.
186	186
187	187		Quand vous voulez savoir le nombre effectif d'enregistrements sur le serveur, vous pouvez appeler '.Last' puis appeler '.RecordCount'.
188	188
189	189		Une alternative est disponible. Le nombre d'enregistrements retourné par le serveur est définie par la propriété '.PacketRecords'. La valeur par défaut est 10, si vous la mettez à -1 alors tous les enregistrements seront chargés en une seule fois.
190	190
191	191		Dans la version stable actuelle de FPC, '.RecordCount' ne prend pas en considération les filtres, i.e. montre le total non filtré.
192	192
193	193		Si vous avez besoin du nombre exact d'enregistrement, il est mieux de demander directement le nombre d'enregistrements dans une autre requête SQL, mais vous devez faire cela dans la même transaction, car d'autres transaction ont pu modifier ce nombre dans l'entre-temps.
194	194
195	195		### Lazarus
196	196
197	197		Lazarus possède divers composants pour montrer les données d'un DataSet sur une fiche. A la place d'une boucle while et d'appels WriteLn comme ci-dessus, vous pouvez utiliser des composants pour montrer les données dans une table. Placez les bons composant TSQLConnection, TSQLTransaction et TSQLQuery sur une fiche, connectez-les et configurez-les convenablement. En plus, vous aurez besoin d'un TDataSource ; mettez dans la propriété 'TDatasource.Dataset' le composant TSQLQuery que vous utilisez.
198	198
199	199		(Remarque ne définissez pas la propriété 'TSQLQuery.Datasource' par le composant TDatasource que vous utilisez. Cette propriété est réservée à la mise en place de realtion maître/détail entre tables - voir [[MasterDetail/fr\|MasterDetail]]). Par la suite, vous pouvez poser un TDBGrid sur la fiche et définir la propriété 'DataSource' de la grille avec le composant TDataSource que vous avez ajouté auparavant.
200	200
201	201		Pour voir si tout marche, mettez à 'True' la propriété 'Connected' du TSQLConnection dans l'EDI de Lazarus. L'EDI tentera de se connecter au serveur de base de données immédiatement. Si cela marche, mettez à 'True' la proriété 'TSQLQuery.Active'. Si tout est bon, vous verrez - dans l'EDI - toutes les données de la table immédiatement à l'écran.
202	202
203	203		## Comment modifier de la donnée dans une table ?
204	204
205	205		Pour modifier les données dans un enregistrement, les [[TDataSet/fr\|TDataSet]] (duquel est dérivé TSQLQuery) doit être mis en mode édition. Pour ce faire, appelez l'une des méthodes '.Edit', '.Insert' ou '.Append'. Utilisez '.Edit' pour modifier les valeurs de l'enregistrement courant. Utilisez '.Insert' pour insérer un nouvel enregistrement avant l'enregistrement courant. Utilisez '.Append' pour ajouter un nouvel enregistrement en fin de la table. En mode Edit, vous pouvez changer les valeurs des champs grâce à la propriété 'Fields'. Utilisez la méthode '.Post' pour valider les nouvelles données, si les données sont valides, le mode Edit est abandonné. Si vous vous déplacez vers un autre enregistrement - par exemple en appelant '.Next' - et que le DataSet est en mode Edit, alors '.Post' est d'abord appelé. Utilisez '.Cancel' pour annuler tous les changements apportés depuis le dernier appel à '.Post' et quitter le mode Edit.
206	206
207	207		``` pascal
208	208		Query.Edit;
209	209		Query.FieldByName('NAME').AsString := 'Edited name';
210	210		Query.Post;
211	211		```
212	212
213	213		Ce qu'il y a au dessus n'est pas encore complet. TSQLQuery est dérivé de TBufDataset qui fait des mises à jour tamponnées (buffered updates). Les mises à jour tamponnées veulent dire qu'après l'appel à '.Post', les modifications sont visibles immédiatement dans l'ensemble de données mais pas envoyées au serveur de base de données. Il se passe que les modifications sont maintenues dans un journal des modifications. Quand la méthode '.ApplyUpdates' est appelée, tous les changements sont envoyés à la base de données. C'est à ce moment seulement que la base de données connaîtra les modifications. Les changements sont envoyés au serveur dans une transaction de TSQLTransaction. Assurez-vous de définir correctement la transaction avant d'appeler '.ApplyUpdates'. Après avoir appliquer les mises à jour, un commit doit être exécuté pour enregistrer les modifications sur le serveur de base de données.
214	214
215	215		Ci-dessous est un exemple de modification de données dans une table, d'envoi les modifications et de commit de la transaction.
216	216
217	217		``` pascal
218	218		Program EditData;
219	219
220	220		var
221	221		AConnection : TSQLConnection;
222	222		ATransaction : TSQLTransaction;
223	223		Query : TSQLQuery;
224	224
225	225		begin
226	226		AConnection := CreateConnection;
227	227		ATransaction := CreateTransaction(AConnection);
228	228		AConnection.Transaction := ATransaction;
229	229		Query := CreateQuery(AConnection, ATransaction);
230	230		Query.SQL.Text := 'select * from tblNames';
231	231		Query.Open;
232	232		Query.Edit;
233	233		Query.FieldByName('NAME').AsString := 'Edited name';
234	234		Query.Post;
235	235		Query.UpdateMode := upWhereAll;
236	236		Query.ApplyUpdates;
237	237		ATransaction.Commit;
238	238		Query.Free;
239	239		ATransaction.Free;
240	240		AConnection.Free;
241	241		end.
242	242		```
243	243
244	244		Pour une discussion sur 'UpdateMode', continuer la lecture.
245	245
246	246		## Comment SqlDB envoie les modifications aux serveur de base de données ?
247	247
248	248		Dans l'exemple de code dans #Comment modifier de la donnée dans une table ?, vous trouverez la ligne :
249	249
250	250		``` pascal
251	251		Query.UpdateMode := upWhereAll;
252	252		```
253	253
254	254		Sans explication de ce que cela fait. La meilleure façon de savoir ce que cette ligne fait est de la laisser de côté. Si vous laissez de côté l'instruction et suivez ce Comment-faire précisément, alors vous recevrez ce message d'erreur :
255	255
256		-	~~`No update query specified and failed to generate one. (No fields for inclusion in where statement found)`~~
	256	+	```text
	257	+	No update query specified and failed to generate one. (No fields for inclusion in where statement found)
	258	+	```
257	259
258	260		Pour comprendre ce qui n'a pas marché, vous devez comprendre comment les modifications sont envoyées au serveur. La seule façon d'obtenir des données dans un serveur SQL est d'exécuter des requêtes. SQL a trois types de requêtes pour trois différentes façons de manipuler un enregistrement. Pour créer un nouvel enregistrement, modifier ou supprimer un enregistrement, les ordres insert, update et delete sont exécutés respectivement. Un ordre de mise à jour peut être comme ce qui suit :
259	261
260	262		``` sql
261	263		update TBLNAMES set NAME='Edited name' where ID=1;
262	264		```
263	265
264	266		Pour envoyer le changement au serveur de base de données, SqlDB doit assembler une requête update. Pour ce faire, trois choses sont nécessaires :
265	267
266	268		Le nom de la table
267	269		La nom de la table est récupéré par l'analyse de la requête de sélection, même si cela ne marche pas toujours.
268	270
269	271		Clause `UPDATE` ou `INSERT`
270	272		Celle-ci contient les champs qui doivent être changés.
271	273
272	274		Clause `WHERE`
273	275		Celle-ci contient les champs qui détermine quels enregistrements devraient être changés.
274	276
275	277		Chaque champ (chaque TField dans Fields) possède une propriété ProviderFlags. Seuls les champs avec pfInUpdate dans ProviderFlags seront utilisés dans la clause update ou insert d'une requête. Par défaut, pfInUpdate est mis pour tous les champs dans leur proriété ProviderFlags.
276	278
277	279		Le choix des champs utilisés dans la clause `WHERE` dépend de la propriété UpdateMode de la requête et de la propriété ProviderFlags des champs. Les champs avec pfInkey dans leur ProviderFlags sont toujours utilisés dans la clause `WHERE`. Un champ aura le drapeau pfInKey défini automatiquement si le champ fait partie de la clé primaire de la table et 'TSQLQuery.UsePrimaryKeyAsKey' retourne 'True'.
278	280
279	281		La valeur par défaut de UpdateMode de la requête est upWhereKeyOnly. Dans le mode update, seuls les champs avec pfInkey dans leur propriété ProviderFlags sont utilisés dans la clause `WHERE`. Si aucun des champs n'a de drapeau pfInKey mis, alors aucun champ n'est disponible pour la clause `WHERE` et le message d'erreur du début de la section sera retourné. Vous pouvez résoudre ce problème en :
280	282
281	283		- En ajoutant une clé primaire à la table et mettre TSQLQuery.UsePrimaryKeyAsKey à 'True', ou
282	284		- en définissant le drapeau pfInkey pour un ou plusieurs champs dans le code.
283	285
284	286		La propriété UpdateMode connaît deux autres valeurs. 'upWhereAll' peut être utilisée pour ajouter tous les champs avec le drapeau 'pfInWhere' mis à la clause `WHERE`. Par défaut, tous les champs ont ce drapeau mis. 'upWhereChanged' peut être utilisé pour ceux des champs qui ont le drapeau 'pfInWhere' mis et dont la valeur a été changée dans l'enregistrement courant.
285	287
286	288		## Comment exécuter une requête en utilisant TSQLQuery ?
287	289
288	290		À côté des instructions qui renvoient un DataSet (voir #Comment lire de la donnée depuis une table ?, SQL a des ordres qui ne retournent pas de donnée. P.ex., les ordres `INSERT`, `UPDATE` et `DELETE`. Ces ordres peuvent être exécutés en utilisant TSQLConnection.ExecuteDirect, mais TSQLQuery peut être aussi utilisé. Si vous n'attendez pas de donnée en retour, utilisez TSQLQuery.ExecSQL au lieu de TSQLQuery.Open. Comme indiqué précédemment, utilisez TSQLQuery.Open pour ouvrir le DataSet retourné par l'ordre SQL.
289	291
290	292		La procédure suivante crée une table et insère deux enregistrements en utilisant TSQLQuery.
291	293
292	294		``` pascal
293	295		procedure CreateTable;
294	296
295	297		var
296	298		Query : TSQLQuery;
297	299
298	300		begin
299	301		Query := CreateQuery(AConnection, ATransaction);
300	302		Query.SQL.Text := 'create table TBLNAMES (ID integer, NAME varchar(40));';
301	303		Query.ExecSQL;
302	304
303	305		Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (1,''Name1'');';
304	306		Query.ExecSQL;
305	307
306	308		Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (2,''Name2'');';
307	309		Query.ExecSQL;
308	310
309	311		Query.Close;
310	312		Query.Free;
311	313		end;
312	314		```
313	315
314	316		## Comment utiliser des paramètres dans une requête ?
315	317
316	318		Dans l'exemple de code de #Comment exécuter une requête en utilisant TSQLQuery ?, la même requête est utilisée deux fois, seules les valeurs à insérer diffèrent. Une meilleure façon pour faire cela consiste à utiliser des paramètres dans la requête.
317	319
318	320		La syntaxe des paramètres dans les requêtes est différente selon le SGBDR, mais les différences sont traitées par TSQLQuery. Remplacez les valeurs dans la requête avec un caractère deux-points suivi du nom du paramètre que vous voulez utiliser. Par exemples :
319	321
320	322		``` pascal
321	323		Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (:ID,:NAME);';
322	324		```
323	325
324	326		Cette requête créera deux paramètres : 'ID' et 'NAME'. Pour déterminer les paramètres, la requête est analysée au moment où le texte de TSQLQuery.SQL est affecté ou modifié. Tous les paramètres existants seront supprimés et les nouveaux paramètres seront ajoutés à la propriété 'TSQLQuery.Params'. L'affectation d'une valeur à un paramètre est similaire à l'affectation d'un champ dans un DataSet :
325	327
326	328		``` pascal
327	329		Query.Params.ParamByName('Name').AsString := 'Name1';
328	330		```
329	331
330	332		Vous ne pouvez pas savoir depuis la requête quel type de donnée doit être stocké dans le paramètre. Le type de donnée est déterminé au moment où une valeur est en premier affectée à un paramètre. En affectant une valeur en utilisant '.AsString', le paramètre est affecté du type 'ftString'. Vous pouvez déterminer le type de donnée directement en définissant la propriété 'DataType'. Si un type de donnée incorrect est affecté au paramètre alors des problèmes surviendront lors de l'ouverture ou de l'exécution de la requête. Voir [[Database field type/fr\|Type de champ de base de données]] pour plus d'information sur les types de donnée.
331	333
332	334		### Requête de sélection
333	335
334	336		Un exemple de requête de sélection avec des paramètres changera quelque chose comme ceci :
335	337
336	338		``` pascal
337	339		Query.SQL.Text := 'select ID,NAME from TBLNAMES where NAME = '''+Edit1.Text+''' ORDER BY NAME ';
338	340		```
339	341
340	342		en quelque chose comme cela :
341	343
342	344		``` pascal
343	345		Query.SQL.Text := 'select ID,NAME from TBLNAMES where NAME = :NAMEPARAM ORDER BY NAME ';
344	346		Query.Params.ParamByName('NAMEPARAM').AsString := Edit1.Text;
345	347		```
346	348
347	349		### Exemple
348	350
349	351		L'exemple suivant crée la même table que l'exemple précédent, mais maintenant des paramètres sont utilisés :
350	352
351	353		``` pascal
352	354		procedure CreateTableUsingParameters;
353	355
354	356		var
355	357		Query : TSQLQuery;
356	358
357	359		begin
358	360		Query := CreateQuery(AConnection, ATransaction);
359	361		Query.SQL.Text := 'create table TBLNAMES (ID integer, NAME varchar(40));';
360	362		Query.ExecSQL;
361	363
362	364		Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (:ID,:NAME);';
363	365		Query.Prepare;
364	366
365	367		Query.Params.ParamByName('ID').AsInteger := 1;
366	368		Query.Params.ParamByName('NAME').AsString := 'Name1';
367	369		Query.ExecSQL;
368	370
369	371		Query.Params.ParamByName('ID').AsInteger := 2;
370	372		Query.Params.ParamByName('NAME').AsString := 'Name2';
371	373		Query.ExecSQL;
372	374
373	375		//Query.UnPrepare; // no need to call this; should be called by Query.Close
374	376		Query.Close;
375	377		Query.Free;
376	378		end;
377	379		```
378	380
379	381		Remarquez que cet exemple demande plus de code que l'exemple sans paramètre. Alors, à quoi sert l'utilisation de paramètres?
380	382
381	383		La vitesse est une des raisons. L'exemple avec des paramètres est plus rapide, parce que le serveur de base de donnée analyse la requête une seule fois (dans l'instruction '.Prepare' ou à la première exécution). Une autre raison pour employer les instructions préparées est la prévention des [injections SQL](https://fr.wikipedia.org/wiki/Injection_SQL) (voir aussi [[Secure programming/fr\|Programmation sécurisée]]).
382	384
383	385		Finalement, dans certains cas, ils simplifient le codage.
384	386
385	387		## Dépannage : Journalisation par TSQLConnection
386	388
387	389		Vous pouvez laisser un journal TSQLConnection à ce qu'il fait. Cela peut être pratique pour voir ce que votre programme Lazarus envoie à la base de données exactement, pour déboguer les composants de base de données eux-mêmes et peut-être pour optimiser vos requêtes.\
388	390		NB : Si vous utilisez des ordres préparés/requêtes paramétrées (vois la section du dessus), les paramètres sont souvent envoyées en binaire par le descendant de TSQLConnection (p.ex. TIBConnection), donc vous ne pouvez juste copier/coller le SQL journalisé dans un outil d'interrogation de la base de données. Indépendamment, la journalisation de la connection peut donner beaucoup d'indication sur ce que le programme fait.
389	391
390	392		Les alternatives sont :
391	393
392	394		1. vous pouvez utiliser le débogueur pour passer le code de base données si vous avez construit FPC (et Lazarus) avec le débogage activé.
393	395		2. si vous utilisez les pilotes ODBC (au moins sous Windows), vous pourrez activer la sortie tracelog depuis le panneau de contrôle ODBC.
394	396		3. plusieurs SGBD vous permettent de contrôler tous les ordres envoyés vers lui depuis une adresse IP/une connection.
395	397
396	398		Si vous utilisez la jouranlisation TSQLConnection, deux choses sont requises :
397	399
398	400		1. indiquer quels sont les types d'événement que TSQLConnection doit journaliser.
399	401		2. associer TSQLConnection à une fonction qui reçoit les événements et les traite (les enregistre dans un fichier, les affiche à l'écran, etc.).
400	402
401	403		Cette fonction doit être du type TDBLogNotifyEvent (voir sqldb.pp), donc elle doit avoir la signature :
402	404
403	405		``` pascal
404	406		TDBLogNotifyEvent = Procedure (Sender : TSQLConnection; EventType : TDBEventType; Const Msg : String) of object;
405	407		```
406	408
407	409		### FPC (ou : la façon manuelle)
408	410
409	411		Un extrait de code illustre ceci :
410	412
411	413		``` pascal
412	414		uses
413	415		...
414	416		TSQLConnection, //or a child object like TIBConnection, TMSSQLConnection
415	417		...
416	418		var
417	419		type
418	420		TMyApplication = class(TCustomApplication); //this is our application that uses the connection
419	421		...
420	422		private
421	423		// This example stores the logged events in this stringlist:
422	424		FConnectionLog: TStringList;
423	425		...
424	426		protected
425	427		// This procedure will receive the events that are logged by the connection:
426	428		procedure GetLogEvent(Sender: TSQLConnection; EventType: TDBEventType; Const Msg : String);
427	429		...
428	430		procedure TMyApplication.GetLogEvent(Sender: TSQLConnection;
429	431		EventType: TDBEventType; const Msg: String);
430	432		// The procedure is called by TSQLConnection and saves the received log messages
431	433		// in the FConnectionLog stringlist
432	434		var
433	435		Source: string;
434	436		begin
435	437		// Nicely right aligned...
436	438		case EventType of
437	439		detCustom: Source:='Custom: ';
438	440		detPrepare: Source:='Prepare: ';
439	441		detExecute: Source:='Execute: ';
440	442		detFetch: Source:='Fetch: ';
441	443		detCommit: Source:='Commit: ';
442	444		detRollBack: Source:='Rollback:';
443	445		else Source:='Unknown event. Please fix program code.';
444	446		end;
445	447		FConnectionLog.Add(Source + ' ' + Msg);
446	448		end;
447	449
448	450		...
449	451		// We do need to tell our TSQLConnection what to log:
450	452		FConnection.LogEvents:=LogAllEvents; //= [detCustom, detPrepare, detExecute, detFetch, detCommit, detRollBack]
451	453		// ... and to which procedure the connection should send the events:
452	454		FConnection.OnLog:=@Self.GetLogEvent;
453	455		...
454	456		// now we can use the connection and the FConnectionLog stringlist will fill with log messages.
455	457		```
456	458
457	459		Vous pouvez aussi utiliser GlobalDBLogHook de TSQLConnection au lieu de journaliser depuis de multiples connections.
458	460
459	461		### Lazarus (ou : la manière rapide)
460	462
461	463		Au final, la description du dessus est la manière FPC de procéder comme annoncé dans l'introduction ; si vous utilisez Lazarus, une façon plus rapide est d'affecter le gestionnaire d'événement dans l'événement OnLog de TSQLConnection.
462	464
463	465		## Voir aussi
464	466
465	467		- [[SQLdb Tutorial0/fr\|SQLdb Tutorial0]] : Instructions pour configurer les tables et les données d'exemple pour la série de tutoriels.
466	468		- [[SQLdb Tutorial1/fr\|SQLdb Tutorial1]] : 1re partie de la série de tutoriels sur les bases de données, montrant comment configurer un grid pour afficher les données.
467	469		- [[SQLdb Tutorial2/fr\|SQLdb Tutorial2]] : 2e partie de la série de tutoriels, montrant l'édition, l'insertion, etc.
468	470		- [[SQLdb Tutorial3/fr\|SQLdb Tutorial3]] : 3e partie de la série de tutoriels, montrant comment développer pour des bases de données multiples et utiliser une form de login.
469	471		- [[SQLdb Tutorial4/fr\|SQLdb Tutorial4]] : 4e partie de la série de tutoriels, montrant comment utiliser les data modules.
470	472		- [[Lazarus Database Overview/fr\|Vue d'ensemble des bases de données pour Lazarus]] : Information sur les bases de données supportées par Lazarus. Redirige vers des notes spécifiques à certaines bases de données.
471	473		- [[SQLdb Package/fr\|Paquet SQLdb]] : Information sur le paquetage SQLdb.
472	474		- [[SQLdb Programming Reference/fr\|Référence de programmation SQLdb]] : Une vue d'ensemble de l'interaction entre les composants de bases de données SQLdb.
473	475		- [[SqlDBHowto/fr\|SqlDBHowto]] : Information sur l'utilisation du paquet SQLdb.
474	476		- [[Working With TSQLQuery/fr\|Travailler avec TSQLQuery]] : Informations sur TSQLQuery.
475	477
476	478		---
477	479		From the Free Pascal wiki, page "SqlDBHowto/fr", as it stood on 2020-02-27 after a change by Trev, 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