SqlDBHowto/nl: what changed

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

Old	New		Line
1	1		## Introductie
2	2
3	3		Omdat er heel veel vragen over SqlDb zijn, en zo weinig documentatie beschikbaar is, heb ik besloten toch het een en ander op te gaan schrijven. Ik doe het in het Nederlands, omdat dat me nu eenmaal veel beter afgaat. Later kunnen anderen het altijd nog naar het Engels vertalen.
4	4
5	5		Ik heb gekozen voor een soort 'howto'-opzet. Ik wil één voor één vragen beantwoorden, uitleggen hoe je iets doet. Al die vragen achter elkaar moeten wel ook een verhaal vormen, die als een soort tutorial doorlopen kan worden.
6	6
7	7		Ik zal proberen het zo te verwoorden dat het duidelijk is voor zowel Lazarus als Freepascal, maar de voorbeelden zijn voor Freepascal. (Daarmee bedoel ik dus dat het console-applicaties zijn.)
8	8
9	9		## Hoe maak ik een verbinding met een database-server?
10	10
11	11		SqlDB maakt niet direct verbinding met de database server, maar maakt gebruik van de client die bij de besbetreffende database-server hoort. SqlDB stuurt de commando's naar de client-library, die vervolgens de daadwerkelijke verbinding maakt. Dat betekent dus dat deze library altijd op de computer geinstalleerd moet zijn, wil je een verbinding kunnen maken. In Windows is dat meestal een dll, in Linux een .so en voor OS/X een .dylib-bestand.
12	12
13	13		Als de client-library goed geinstalleerd is, kan je een verbinding maken met een database-server met een TSQLConnection-component. Er zijn verschillende TSQLConnection componenten voor de verschillende database-servers. Voorbeelden zijn TIBConnection om met een Firebird/Interbase client-library te verbinden. TPQConnection voor PostgreSQL en TMySQL40Connection, TMySQL41Connection en TMySQL50connection voor MySQL-clients met versienummer 4.0, 4.1 of 5.0. De verschillen tussen deze MySQL versies zijn zo groot, dat ze niet door elkaar te gebruiken zijn. Als de MySQL-client library versie 4.1 is geinstalleerd, moet een TMySQL41Connection gebruikt worden, onafhankelijk van de versie van de MySQL-server.
14	14
15	15		Het kan per database verschillen, maar over het algemeen moeten er vier properties ingesteld worden om met een database-server te kunnen verbinden:
16	16
17	17		- de server-naam of ip-adres
18	18		- de naam van de database
19	19		- een gebruikersnaam
20	20		- een wachtwoord.
21	21
22	22		Als deze zijn ingesteld kan er een verbinding gemaakt worden met de 'open' methode. Als de verbinding mislukt, komt er een EDatabaseError. Met de property 'connected' kan gekeken worden of er al een verbinding met de database-server is. Met 'close' kan de verbinding weer afgesloten worden.
23	23
24	24		``` pascal
25	25		Program ConnectDB
26	26
27	27		var AConnection : TSQLConnection;
28	28
29	29		Procedure CreateConnection;
30	30		begin
31	31		AConnection := TIBConnection.Create(nil);
32	32		AConnection.Hostname := 'localhost';
33	33		AConnection.DatabaseName := '/opt/firebird/examples/employee.fdb';
34	34		AConnection.UserName := 'sysdba';
35	35		AConnection.Password := 'masterkey';
36	36		end;
37	37
38	38		begin
39	39		CreateConnection;
40	40		AConnection.Open;
41	41		if Aconnection.Connected then
42	42		writeln('Succesful connect!')
43	43		else
44	44		writeln('This is not possible, because if the connection failed, an exception should be raised, so this code would not be executed');
45	45		AConnection.Close;
46	46		AConnection.Free;
47	47		end.
48	48		```
49	49
50	50		Als er een exceptie optreedt, lees de foutmelding dan zorgvuldig. Het kan zijn dat de databaseserver niet draait, dat de gebruikersnaam of wachtwoord niet goed zijn, of bijvoorbeeld het ip-adres. Als in de foutmelding staat dat de client-library niet gevonden kan worden, controleer dan of die client juist geinstalleerd is. Vaak staat in de foutmelding de letterlijke naam van het bestand waarnaar gezocht wordt.
51	51
52	52		## Hoe voer ik direct queries uit/maak ik een tabel?
53	53
54	54		SqlDB- de naam zegt het al, werkt alleen met database-servers die van SQL gebruik maken. SQL staat voor 'Structured Query Language' en is een taal speciaal ontwikkeld om met relationele databases te werken. Vrijwel iedere database-server heeft zijn eigen dialect, maar een aantal SQL-commando's zijn voor alle database types hetzelfde.
55	55
56	56		FPC maakt een verschil tussen:
57	57
58	58		- SQL-commando's die gegevens (een dataset) terug geven. Hierbij moet je altijd een TSQLQuery-component gebruiken (zie hier)
59	59		- commando's die geen gegevens terugsturen maar bijvoorbeeld gegevens bijwerken. Hiervoor mag je ook de 'ExecuteDirect' methode van een TSQLConnection gebruiken. (Je kan dit ook doen als je een dataset terugkrijgt maar niet geinteresseerd bent in de gegevens, bijv. bij het aanroepen van een selectable stored procedure).
60	60
61	61		De meeste typen database-servers kunnen SQL-commando's uitvoeren binnen een transactie. Wil je dat de wijzigingen die je binnen een transactie gemaakt hebt ook beschikbaar komen in de andere transacties, of nog steeds beschikbaar zijn nadat je de transactie hebt afgesloten(!), dan moet de de transactie 'committen'.
62	62
63	63		Om daar ondersteuning voor te bieden, heeft SqlDB het TSQLTransaction-component. Een SQL-commando dat door SqlDB wordt uitgevoerd, moet altijd binnen een transactie uitgevoerd worden, zelfs als de database-server geen transacties ondersteunt. Er zijn ook typen database-servers die wel transacties ondersteunen, maar waarvan de TSQLConnection (nog) geen transacties ondersteunt. Maar ook dan moet dus een TSQLTransaction-component gebruikt worden.
64	64
65	65		Wil je dus met `TSQLConnection.ExecuteDirect` een SQL-commando kunnen uitvoeren, moet je voor de TSQLConnection eerst opgeven welke 'Transaction' hij moet gebruiken. Voor de TSQLTransaction op zijn beurt, moet je opgeven welke TSQLConnection component gebruikt moet worden.
66	66
67	67		Het volgende voorbeeld maakt een tabel 'TBLNAMES' met de velden 'NAME' en 'ID' aan, en voegt twee records toe. Er worden twee SQL-commando's gebruikt die ik hier verder niet uitleg. Voor meer informatie over SQL-queries kan je de documentatie van de database-server raadplegen. De procedure 'CreateConnection' staat hierboven gedefinieerd.
68	68
69		-	~~`program CreateTable;`\~~
	69	+	``` pascal
	70	+	program CreateTable;
70	71
71		-	~~`var AConnection : TSQLConnection;`\~~
72		-	~~` ATransaction : TSQLTransaction;`\~~
	72	+	var AConnection : TSQLConnection;
	73	+	ATransaction : TSQLTransaction;
73	74
74		-	~~`procedure CreateTransaction;`\~~
75		-	~~`begin`\~~
76		-	~~` ATransaction := TSQLTransaction.Create;`\~~
77		-	~~` ATransaction.Database := AConnection;`\~~
78		-	~~`end;`\~~
	75	+	procedure CreateTransaction;
	76	+	begin
	77	+	ATransaction := TSQLTransaction.Create;
	78	+	ATransaction.Database := AConnection;
	79	+	end;
79	80
80		-	~~`begin`\~~
81		-	~~` CreateConnection;`\~~
82		-	~~` CreateTransaction;`\~~
83		-	~~` AConnection.Transaction := ATransaction;`\~~
84		-	~~` AConnection.Open;`\~~
85		-	~~` ATransaction.StartTransaction;`\~~
86		-	~~` AConnection.ExecuteDirect('create table TBLNAMES (ID integer, NAME varchar(40));'); `\~~
87		-	~~` `\~~
88		-	~~` // Some database-server types need a commit before you can use a newly created table. (Firebird)`\~~
89		-	~~` // With .Commit you also close the transaction`\~~
90		-	~~` ATransaction.Commit; `\~~
	81	+	begin
	82	+	CreateConnection;
	83	+	CreateTransaction;
	84	+	AConnection.Transaction := ATransaction;
	85	+	AConnection.Open;
	86	+	ATransaction.StartTransaction;
	87	+	AConnection.ExecuteDirect('create table TBLNAMES (ID integer, NAME varchar(40));');
	88	+
	89	+	// Some database-server types need a commit before you can use a newly created table. (Firebird)
	90	+	// With .Commit you also close the transaction
	91	+	ATransaction.Commit;
91	92
92		-	~~` ATransaction.StartTransaction;`\~~
93		-	~~` AConnection.ExecuteDirect('insert into TBLNAMES (ID,NAME) values (1,'Name1');'); `\~~
94		-	~~` AConnection.ExecuteDirect('insert into TBLNAMES (ID,NAME) values (2,'Name2');'); `\~~
95		-	~~` ATransaction.Commit; `\~~
96		-	~~` AConnection.Close;`\~~
97		-	~~` AConnection.Free;`\~~
98		-	~~` ATransaction.Free;`\~~
99		-	~~`end.`~~
	93	+	ATransaction.StartTransaction;
	94	+	AConnection.ExecuteDirect('insert into TBLNAMES (ID,NAME) values (1,'Name1');');
	95	+	AConnection.ExecuteDirect('insert into TBLNAMES (ID,NAME) values (2,'Name2');');
	96	+	ATransaction.Commit;
	97	+	AConnection.Close;
	98	+	AConnection.Free;
	99	+	ATransaction.Free;
	100	+	end.
	101	+	```
100	102
101	103		## Hoe lees ik data in uit een tabel?
102	104
103	105		Om data uit een tabel in te lezen maak je gebruik van een TSQLQuery component. Een TSQLQuery moet verbonden worden met een TSQLConnection en een TSQLTransaction om te kunnen werken. Het instellen van de TSQLConnection en TSQLTransaction worden hier en hier besproken.
104	106
105	107		Als de TSQLConnection, TSQLQuery en TSQLTransaction met elkaar zijn verbonden, moet TSQLQuery nog worden ingesteld. TSQLQuery heeft een 'SQL'-property die een TStrings-object bevat met daarin een SQL-statement dat uitgevoerd moet worden. Als alle gegevens uit een tabel `tablename` ingelezen moeten worden, stel de query dan in op
106	108
107	109		``` sql
108	110		'select * from tablename;'
109	111		```
110	112
111	113		. Met 'open' worden de gegevens in de tabel uitgelezen van de server en in de TSQLQuery opgeslagen. De gegevens zijn nu via TSQLQuery te benaderen totdat de query met 'close' weer wordt afgesloten.
112	114
113	115		TSQLQuery is een afgeleide van TDataset en een TDataset heeft een 'Fields' collectie, waarin alle kolommen van de tabel staan. En een TDataset houdt het huidige record bij. Met 'First', 'Next', 'Prior' en 'Last' kan het huidige record gewijzigd worden. 'Eof' en 'Bof' geven aan of het eerste of laatste record bereikt zijn. Om de waarde van een veld in het huidige record op te vragen, moet je eerst het juiste 'TField'-object zoeken en dan de 'AsString', 'AsInteger',... property uitlezen.
114	116
115	117		Hieronder staat een voorbeeld dat van een tabel zoals die hierboven gemaakt is alle waarden weergeeft.
116	118
117	119		``` pascal
118	120		Program ShowData;
119	121
120	122		var AConnection : TSQLConnection;
121	123		ATransaction : TSQLTransaction;
122	124
123	125		procedure GetQuery : TSQLQuery;
124	126		var AQuery : TSQLQuery;
125	127		begin
126	128		AQuery := TSQLQuery.Create;
127	129		AQuery.Database := FConnection;
128	130		AQuery.Transaction := FTransaction;
129	131		Result := AQuery;
130	132		end;
131	133
132	134		var Query : TSQLQuery;
133	135
134	136		begin
135	137		CreateConnection;
136	138		CreateTransaction;
137	139		Query := GetQuery;
138	140		Query.SQL.Text := 'select * from tblNames';
139	141		AConnection.Open;
140	142		Query.Open;
141	143		while not Query.Eof do
142	144		begin
143	145		Writeln('ID: ', Query.FieldByName('Name').AsInteger, 'Name: '+Query.FieldByName('Name').AsString);
144	146		Query.Next;
145	147		end;
146	148		Query.Close;
147	149		AConnection.Close;
148	150		Query.Free;
149	151		ATransaction.Free;
150	152		AConnection.Free;
151	153		end.
152	154		```
153	155
154	156		(De code hierboven is natuurlijk niet helemaal netjes, zo missen er 'try..finally' blokken, maar daar gaat het hier niet om, dus heb ik ze weggelaten.) Als je goed oplet zie je dat ik hier geen gebruik maak van 'TSQLTransaction.StartTransaction'. Dat is ook niet nodig. Als een TSQLQuery uitgevoerd wordt terwijl er geen transactie gestart is, dan wordt er automatisch een transactie gestart, dat hoeft de programmeur niet expliciet te doen. Hetzelfde geldt trouwens voor de verbinding van een TSQLConnection. Die wordt ook automatisch geopend als dat nodig is. De regel 'AConnection.Open;' zoals die hierboven staat is dus niet nodig. Als een TSQLTransaction wordt vernietigd, wordt eerst automatisch een 'rollback' uitgevoerd. Eventuele wijzigingen aan de data in die transactie worden dan dus teniet gedaan!
155	157
156	158		### Waarom geeft TSQLQuery.RecordCount altijd 10 terug?
157	159
158	160		Als je wilt weten hoeveel records er in een dataset zijn, kan je .RecordCount gebruiken. Maar houd er rekening mee dat .RecordCount het aantal records laat zien dat al geladen is van de server. SqlDB leest bij het openen van een TSQLQuery standaard niet alle records in, maar alleen de eerste 10. Pas als er geprobeerd word om naar het 11e record te gaan worden de volgende 10 records geladen, enzovoorts. Als .Last wordt aangeroepen, worden alle records ingelezen.
159	161
160	162		Wil je dus weten hoeveel records er echt op de server staan, kan je eerst .last aanroepen en daarna .recordcount uitlezen. Er is echter ook een andere mogelijkheid. Het aantal records dat per keer wordt opgehaald van de server is in te stellen met .Packetrecords (standaard dus 10). Als hier -1 wordt ingevuld wordt de dataset altijd in een keer ingelezen.
161	163
162	164		Je kan natuurlijk ook middels een expliciete SQL query het aantal records opvragen van de database. Dat moet dan wel in dezelfde transactie gebruiken, want andere transacties kunnen inmiddels het aantal records beïnvloed hebben.
163	165
164	166		### Lazarus
165	167
166	168		Lazarus heeft verschillende componenten om gegevens uit een [[TDataSet]] op een formulier te tonen. In plaats van de while-loop en WriteLn zoals in het voorbeeld hierboven, kan je van deze componenten gebruik maken om de data in de tabel te laten zien. Plaats daarvoor de juiste TSQLConnection, TSQLTransaction en TSQLQuery op een formulier, stel ze goed in en verbind ze met elkaar zoals eerder besproken. Verder heb je een [[TDatasource]] nodig; geef als TDatasource.Dataset de TSQLQuery op. (Doe dit niet andersom, TSQLQuery heeft een 'Datasource' property, maar gebruik die alleen als je met master-detail tabellen werkt) Vervolgens kan je bijvoorbeeld een TDBGrid op het formulier zetten en de datasource daarvan instellen op de TDatasource die je net gemaakt hebt.
167	169
168	170		Om te kijken of het werkt, kan je in de Lazarus-IDE de property 'Connected' van de TSQLConnection op 'True' zetten. Dan wordt er meteen geprobeerd om een verbinding met de database-server te maken. Als dat gelukt is kan je TSQLQuery.Active op 'True' zetten. Als alles goed is gedaan, zie je - in de IDE - meteen alle gegevens in de tabel op je scherm verschijnen.
169	171
170	172		## Hoe wijzig ik gegevens in een tabel?
171	173
172	174		Om de gegevens in een record te wijzigen, moet de TDataset (waarvan TSQLQuery een afgeleide is) in edit-modus gezet worden. Dat gebeurt met de 'Edit', 'Insert' of 'Append' methodes. Met 'Edit' is het huidige record te wijzigen, 'Insert' en 'Append' maken een nieuw record aan voor het huidige record of helemaal aan het eind van de dataset. Daarna zijn de gegevens via de 'Fields' property te wijzigen. Met 'Post' wordt er eerst gecontroleerd of de nieuwe gegevens wel geldig zijn en als dat zo is dan verlaat de dataset de edit-modus. Als je naar een ander record gaat (bijvoorbeeld met 'Next') en de dataset is in de edit-modus, dan wordt altijd eerst 'Post' aangeroepen. Met de methode 'Cancel' kan je de wijzigingen die je sinds de aanroep van 'Post' in de dataset hebt gemaakt weer ongedaan maken en wordt de edit-modus ook weer verlaten.
173	175
174		-	~~`Query.Edit;`\~~
175		-	~~`Query.FieldByName('NAME').AsString := 'Edited name';`\~~
176		-	~~`Query.Post;`~~
	176	+	``` pascal
	177	+	Query.Edit;
	178	+	Query.FieldByName('NAME').AsString := 'Edited name';
	179	+	Query.Post;
	180	+	```
177	181
178	182		Dit is echter nog niet het hele verhaal. TSQLQuery is afgeleid van TBufDataset, dat gebruik maakt van gebufferde updates. Dat houdt in dat nadat 'Post' is aangeroepen, de wijzigingen in de dataset in het geheugen direct zichtbaar zijn, maar dat ze nog niet naar de database-server worden gestuurd. Wat er wel gebeurt is dat er een changelog wordt bijgehouden met alle wijzigingen. Als de methode 'ApplyUpdates' wordt aangeroepen, worden alle wijzigingen in het changelog één voor één naar de database gestuurd. Pas daarna weet de database-server van de wijzigingen. De wijzigingen worden naar de database verstuurd binnen de transactie van de TSQLConnection. Vergeet dus niet om die in te stellen voordat 'ApplyUpdates' aangeroepen wordt. Daarna moet er natuurlijk ook nog een commit uitgevoerd worden om de wijzigingen op te slaan.
179	183
180	184		Hieronder een voorbeeld van het wijzigen van gegevens in de database, het versturen van de wijzigingen naar de server en het committen van de transactie.
181	185
182	186		``` pascal
183	187		Program EditData;
184	188
185	189		var AConnection : TSQLConnection;
186	190		ATransaction : TSQLTransaction;
187	191		Query : TSQLQuery;
188	192
189	193		begin
190	194		CreateConnection;
191	195		CreateTransaction;
192	196		AConnection.Transaction := ATransaction;
193	197		Query := GetQuery;
194	198		Query.SQL.Text := 'select * from tblNames';
195	199		Query.Open;
196	200		Query.Edit;
197	201		Query.FieldByName('NAME').AsString := 'Edited name';
198	202		Query.Post;
199	203		Query.UpdateMode := upWhereAll;
200	204		Query.ApplyUpdates;
201	205		AConnection.Transaction.Commit;
202	206		Query.Free;
203	207		ATransaction.Free;
204	208		AConnection.Free;
205	209		end.
206	210		```
207	211
208	212		Voor een uitleg van UpdateMode, lees hieronder verder.
209	213
210	214		## Hoe stuurt SqlDB de wijzigingen naar de Database-server?
211	215
212	216		In het voorbeeld voor het wijzigen van gegevens in een tabel, staat de regel
213	217
214		-	~~` Query.UpdateMode := upWhereAll;`~~
	218	+	``` pascal
	219	+	Query.UpdateMode := upWhereAll;
	220	+	```
215	221
216	222		waarvan niet uitgelegd is wat de regel doet. De beste manier om daar achter te komen is door de regel weg te laten. Als je dat doet en je hebt deze howto precies hebt gevolgd, dan krijg je de volgende foutmelding:
217	223
218		-	~~`No update query specified and failed to generate one. (No fields for inclusion in where statement found)`~~
	224	+	```text
	225	+	No update query specified and failed to generate one. (No fields for inclusion in where statement found)
	226	+	```
219	227
220	228		Om te begrijpen wat er hier fout gaat is het nodig om precies te begrijpen hoe wijzigingen naar de database-server gestuurd worden. De enige manier om een gegevens op een SQL-server te wijzigen is door een SQL-query uit te voeren. Er zijn drie type queries voor de drie verschillende manieren waarop een record gewijzigd kan worden: Een record kan nieuw zijn, verwijderd of gewijzigd waarvoor respectievelijk een insert-, delete- of update-query voor uitgevoerd moet worden. Een update-query kan er als volg uitzien:
221	229
222		-	~~`update TBLNAMES set NAME='Edited name' where ID=1;`~~
	230	+	```text
	231	+	update TBLNAMES set NAME='Edited name' where ID=1;
	232	+	```
223	233
224	234		Om een wijziging naar de database-server te sturen, moet SqlDB dus zo'n update-query samenstellen. Daarvoor zijn drie dingen nodig:
225	235
226	236		De tabelnaam
227	237		Deze wordt achterhaald door de opgegeven select-query te parsen (dit lukt niet altijd.)
228	238
229	239		Update- of insert-deel
230	240		Dit zijn de velden die gewijzigd worden.
231	241
232	242		Where-deel
233	243		Dit zijn de velden die aangeven welk record er nou eigenlijk gewijzigd moet worden.
234	244
235	245		Ieder veld (TField) heeft een property ProviderFlags. Alleen de velden met pfInUpdate in de ProviderFlags worden in het update- of insert-deel van de query opgenomen. Standaard hebben alle velden dat.
236	246
237	247		Welke velden in het where-gedeelte worden opgenomen hangt af van de UpdateMode van de query en de ProviderFlags van de betreffende velden. De velden met pfInKey in hun ProviderFlags komen altijd in het where-gedeelte terecht. Een veld krijgt de pfInKey vlag automatisch als het veld deel uitmaakt van de primary key van de tabel en TSQLQuery.UsePrimaryKeyAsKey waar is.
238	248
239	249		De standaard waarde voor de UpdateMode van de query is upWhereKeyOnly. In deze UpdateMode zijn de velden met pfInKey in de ProviderFlags de enige velden die gebruikt worden in het where-gedeelte. Als er geen enkel veld de pfInKey vlag heeft en de UpdateMode is upWhereKeyOnly dan zijn er geen velden beschikbaar zijn voor het where-deel van de query en treedt de foutmelding op van het begin van deze sectie. Dit kan dan opgelost worden door een primary key aan de tabel toe te voegen en TSQLQuery.UsePrimaryKeyAsKey op 'true' in te stellen of door handmatig de pfInKey vlag in te stellen op voor of meer van de velden van de tabel.
240	250
241	251		Er zijn nog twee andere UpdateMode's. Met UpWhereAll worden naast de velden met pfInKey alle velden met de pfInWhere flag opgenomen in het where-deel van de query. Standaard heeft ieder veld deze vlag ingesteld staan. Als de UpdateMode UpWhereChanged is dan worden alleen die velden met pfInWhere opgenomen die in het huidige record gewijzigd zijn.
242	252
243	253		## Hoe voer je een query uit met een TSQLQuery?
244	254
245	255		Naast queries die een dataset teruggeven zijn er ook queries die dat niet doen. Bijvoorbeeld de 'update', 'insert' en 'delete' queries. Deze queries kunnen niet alleen uitegvoerd worden met TSQLConnection.ExecuteDirect maar ook door een TSQLQuery te gebruiken. Dit doe je door TSQLQuery.ExecSQL aan te roepen in plaats van TSQLQuery.Open (wat je gebruikt om een tabel die je met een query opvraagt te openen).
246	256
247	257		De volgende procedure maakt een tabel en voegt twee records toe door gebruik te maken van TSQLQuery.
248	258
249	259		``` pascal
250	260		procedure CreateTable;
251	261
252	262		var Query : TSQLQuery;
253	263
254	264		begin
255	265		Query := GetQuery;
256	266		Query.SQL.Text := 'create table TBLNAMES (ID integer, NAME varchar(40));';
257	267		Query.ExecSQL;
258	268
259	269		Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (1,'Name1');';
260	270		Query.ExecSQL;
261	271
262	272		Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (2,'Name2');';
263	273		Query.ExecSQL;
264	274
265	275		Query.Close;
266	276		Query.Free;
267	277		end;
268	278		```
269	279
270	280		## Hoe maak je gebruik van parameters in een query?
271	281
272	282		In dit voorbeeld wordt twee keer dezelfde query uitgevoerd met alleen verschillende parameters. Een betere manier om dit te doen is door een query met parameters te gebruiken.
273	283
274	284		De syntax van parameters in queries is per database server verschillend maar dat wordt door TSQLQuery afgehandeld. Vervang de parameter in de query met een dubbele punt, gevolgd door de naam die je de parameter wilt geven. Bijvoorbeeld
275	285
276	286		``` pascal
277	287		Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (:ID,:NAME);';
278	288		```
279	289
280	290		maakt twee parameters aan, 'ID' en 'NAME'. Om te bepalen wat de parameters zijn wordt de query geparsed als hij aan TSQLQuery.SQL wordt toegewezen of gewijzigd. Alle bestaande parameters worden dan verwijderd en de nieuwe worden toegevoegd aan de TSQLQuery.Params property. Om een waarde aan een parameter toe te wijzen lijkt op de manier waarop de waarde van een veld wordt gewijzigd:
281	291
282	292		``` pascal
283	293		Query.Params.ParamByName('Name').AsString := 'Name1';
284	294		```
285	295
286	296		Het is aan de query zelf niet te zien wat voor soort data de parameter moet opslaan. Daarom wordt het datatype pas bepaald op het moment dat er voor het eerst een waarde aan de parameter wordt toegewezen. Door .AsString te gebruiken bijvoorbeeld, krijgt de parameter het datatype 'ftString'. Het datatype is ook direct in te stellen door de 'DataType' property te gebruiken. Als het verkeerde datatype aan een parameter toegewezen wordt, kan dat tot problemen leiden tijdens het openen of uitvoeren van de query.
287	297
288	298		Het volgende voorbeeld maakt dezelfde tabel aan als in het vorige voorbeeld maar dan door gebruik te maken van parameters:
289	299
290	300		``` pascal
291	301		procedure CreateTableUsingParameters;
292	302
293	303		var Query : TSQLQuery;
294	304
295	305		begin
296	306		Query := GetQuery;
297	307		Query.SQL.Text := 'create table TBLNAMES (ID integer, NAME varchar(40));';
298	308		Query.ExecSQL;
299	309
300	310		Query.SQL.Text := 'insert into TBLNAMES (ID,NAME) values (:ID,:NAME);';
301	311
302	312		Query.Params.ParamByName('ID').AsInteger := 1;
303	313		Query.Params.ParamByName('NAME').AsString := 'Name1';
304	314		Query.ExecSQL;
305	315
306	316		Query.Params.ParamByName('ID').AsInteger := 2;
307	317		Query.Params.ParamByName('NAME').AsString := 'Name2;
308	318		Query.ExecSQL;
309	319
310	320		Query.Close;
311	321		Query.Free;
312	322		end;
313	323		```
314	324
315	325		Wat meteen opvalt is dat dit voorbeeld meer code heeft dan het voorbeeld dat geen gebruik maakt van parameters. Waarom zou je dan parameters gebruiken? Eén van de redenen is dat het voorbeeld met parameters sneller is. Dat komt omdat de query niet twee keer geparsed hoeft te worden. Niet alleen door TSQLQuery, maar ook door de database server. De meeste database servers ondersteunen parameters. Als eenzelfde query meerdere keren wordt aangeroepen met steeds verschillende waarden als parameter, dan hoeft de database server maar één keer een plan te maken voor het uitvoeren van de query. Dat maakt het sneller. (Met TSQLQuery.Prepare kan je zelf bepalen wanneer de query door de database server geparsed en gepland moet worden. Met .UnPrepare zorg je ervoor dat de query de volgende keer dat hij uitgevoerd wordt, altijd eerst opnieuw wordt voorbereid door de database-server)
316	326
317	327		Een andere reden kan het voorkomen van SQL-injectie [1](http://en.wikipedia.org/wiki/SQL_injection) zijn (zie ook [[Secure programming]]).
318	328
319	329		Tenslotte: in sommige gevallen kan het de code ook een stuk vergemakkelijken.
320	330
321	331		## Troubleshooting: TSQLConnection logging
322	332
323	333		Je kan een TSQLConnection laten loggen wat hij allemaal uitvoert. Dit kan handit zijn om te kijken wat je Lazarus-programma precies verstuurt naar de database, om de database-componenten zelf te debuggen en wellicht je queries te optimaliseren. Let wel: als je parameters in queries gebruikt, worden die vaak door de database TSQLConnection afstammeling (zoals TIBConnection) binair verstuurd; je kan dus niet zomaar altijd de gelogde SQL knippen en plakken in een databasequerytool. Hoe het ook zij, loggen van de connectie kan veel inzicht geven in wat je programma doet.
324	334
325	335		Hiervoor moet je twee dingen doen:
326	336
327	337		1. bij de TSQLConnection instellen welke event types/soorten gebeurtenissen hij moet loggen
328	338		2. een functie aanwijzen die de loggegevens ontvangt van de TSQLConnection en op de een of andere manier verwerkt.
329	339
330	340		De functie moet er een zijn van het type TDBLogNotifyEvent (zie sqldb.pp), dus met deze signatuur:
331	341
332	342		``` pascal
333	343		TDBLogNotifyEvent = Procedure (Sender : TSQLConnection; EventType : TDBEventType; Const Msg : String) of object;
334	344		```
335	345
336	346		Een stukje voorbeeldcode kan dit verduidelijken:
337	347
338	348		``` pascal
339	349		uses
340	350		...
341	351		TSQLConnection, //of een kindobject zoals TIBConnection, TMSSQLConnection
342	352		...
343	353		var
344	354		type
345	355		TMyApplication = class(TCustomApplication); //dit is onze applicatie die de connectie gebruikt
346	356		...
347	357		private
348	358		// We laten bijvoorbeeld het log wegschrijven naar deze variabelen in onze class:
349	359		FConnectionLog: TStringList;
350	360		...
351	361		protected
352	362		// Deze procedure gaat de te loggen events opvangen:
353	363		procedure GetLogEvent(Sender: TSQLConnection; EventType: TDBEventType; Const Msg : String);
354	364		...
355	365		procedure TMyApplication.GetLogEvent(Sender: TSQLConnection;
356	366		EventType: TDBEventType; const Msg: String);
357	367		// De procedure wordt aangeroepen door TSQLConnection en slaat de ontvangen logberichten
358	368		// op in de FConnectionLog stringlist
359	369		var
360	370		Source: string;
361	371		begin
362	372		// Nicely right aligned...
363	373		case EventType of
364	374		detCustom: Source:='Custom: ';
365	375		detPrepare: Source:='Prepare: ';
366	376		detExecute: Source:='Execute: ';
367	377		detFetch: Source:='Fetch: ';
368	378		detCommit: Source:='Commit: ';
369	379		detRollBack: Source:='Rollback:';
370	380		else Source:='Unknown event. Please fix program code.';
371	381		end;
372	382		FConnectionLog.Add(Source + ' ' + Msg);
373	383		end;
374	384
375	385		...
376	386		// We moeten de TSQLConnection wel vertellen wat te loggen...
377	387		FConnection.LogEvents:=LogAllEvents; //= [detCustom, detPrepare, detExecute, detFetch, detCommit, detRollBack]
378	388		// ... en waar de info heen moet:
379	389		FConnection.OnLog:=@Self.GetLogEvent;
380	390		...
381	391		// nu kunnen we de connectie gebruiken en zal de FConnectionLog stringlist zich vullen met logberichten.
382	392		```
383	393
384	394		Je kan ook de GlobalDBLogHook functie in TSQLConnection gebruiken wanneer je voor meerdere connecties tegelijk wil loggen. Tenslotte: zoals in de introductie vermeld beschrijft dit stuk de FPC manier van doen; als je met Lazarus werkt kan je sneller werken door aan de TSQLConnection OnLog gebeurtenis je gebeurtenisprocedure/event handler te koppelen.
385	395
386	396		---
387	397		From the Free Pascal wiki, page "SqlDBHowto/nl", as it stood on 2021-11-16 after a change by Slawek, 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