forked from gleu/pgdocs_fr
-
Notifications
You must be signed in to change notification settings - Fork 0
/
contrib-spi.xml
248 lines (211 loc) · 9.86 KB
/
contrib-spi.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
<?xml version="1.0" encoding="UTF-8"?>
<!-- Dernière modification
le $Date$
par $Author$
révision $Revision$ -->
<sect1 id="contrib-spi">
<title>spi</title>
<indexterm zone="contrib-spi">
<primary>SPI</primary>
<secondary>examples</secondary>
</indexterm>
<para>
Le module <filename>contrib/spi</filename> fournit plusieurs exemples
fonctionnels d'utilisation de SPI et des déclencheurs. Bien que ces fonctions aient un
intérêt certain, elles sont encore plus utiles en tant qu'exemples
à modifier pour atteindre ses propres buts. Les fonctions sont suffisamment
généralistes pour être utilisées avec une table quelconque, mais la création d'un
déclencheur impose que les noms des tables et des champs soient précisés
(comme cela est décrit ci-dessous).
</para>
<sect2>
<title>refint.c — fonctions de codage de l'intégrité
référentielle</title>
<para>
<function>check_primary_key()</function> et
<function>check_foreign_key()</function> sont utilisées pour vérifier les
contraintes de clé étrangère. (Cette fonctionnalité est dépassée depuis
longtemps par le mécanisme interne, mais le module conserve un rôle
d'exemple.)
</para>
<para>
<function>check_primary_key()</function> vérifie la table de référence.
Pour l'utiliser, on crée un déclencheur <literal>BEFORE INSERT OR UPDATE</literal>
qui utilise cette fonction sur une table référençant une autre table.
En arguments du déclencheur, on trouve : le nom de la colonne
de la table référençant qui forme la clé étrangère, le nom de la table
référencée et le nom de la colonne de la table référencée qui forme la
clé primaire/unique. Il peut y avoir plusieurs colonnes. Pour gérer
plusieurs clés étrangères, on crée un déclencheur pour chaque référence.
</para>
<para>
<function>check_foreign_key()</function> vérifie la table référencée.
Pour l'utiliser, on crée un déclencheur <literal>BEFORE DELETE OR UPDATE</literal>
qui utilise cette fonction sur une table référencée par d'autres tables.
En arguments du déclencheur, on trouve : le nombre de tables référençant pour
lesquelles la fonction réalise la vérification, l'action à exécuter si une clé
de référence est trouvée (<literal>cascade</literal> — pour supprimer
une ligne qui référence, <literal>restrict</literal> — pour annuler la
transaction si des clés de référence existent, <literal>setnull</literal>
— pour initialiser les champs des clés référençant à NULL), les noms
des colonnes de la table surveillées par le déclencheur, colonnes qui
forment la clé primaire/unique, puis le nom de la table référençant et les noms des
colonnes (répétés pour autant de tables référençant que cela est précisé par
le premier argument). Les colonnes de clé
primaire/unique doivent être marquées NOT NULL et posséder un index
d'unicité.
</para>
<para>
Il y a des exemples dans <filename>refint.example</filename>.
</para>
</sect2>
<sect2>
<title>timetravel.c — fonctions de codage du voyage dans le
temps</title>
<para>
Dans le passé, <productname>PostgreSQL</productname> disposait d'une fonctionnalité
de voyage dans le temps, permettant de conserver l'heure d'insertion et
de suppression de chaque ligne. Ce comportement peut être émulé en
utilisant ces fonctions. Pour les utiliser, il faut ajouter deux champs
de type <type>abstime</type> à la table pour stocker le moment où une
ligne a été insérée (start_date) et le moment où elle a été
modifiée/supprimée (stop_date) :
<programlisting>
CREATE TABLE mytab (
... ...
start_date abstime,
stop_date abstime
... ...
);
</programlisting>
Le nom des colonnes n'a aucune importance, mais dans ce
chapitre, elles sont nommées start_date et stop_date.
</para>
<para>
À l'insertion d'une nouvelle ligne, start_date doit normalement
être initialisée à l'heure courante et stop_date à
<literal>infinity</literal>. Le déclencheur substitue automatiquement ces
valeurs si les données insérées sont NULL pour ces colonnes.
L'insertion de données explicitement non-NULL dans ces colonnes n'intervient
qu'au rechargement de données sauvegardées.
</para>
<para>
Les lignes pour lesquelles stop_date vaut <literal>infinity</literal> sont des
lignes <quote>actuellement valides</quote>, et peuvent être modifiées.
Les lignes dont stop_date est fini ne peuvent plus être modifiées —
le déclencheur les protège. (Pour les modifier, il est nécessaire de
désactiver le voyage dans le temps comme indiqué ci-dessous.)
</para>
<para>
Pour une ligne modifiable en mise à jour, seul stop_date est
modifié (positionné à l'heure courante) et une nouvelle ligne avec la donnée modifiée
est insérée. Pour cette nouvelle ligne, start_date est positionné à
l'heure courante et stop_date à <literal>infinity</literal>.
</para>
<para>
Une suppression ne supprime pas réellement la ligne mais positionne
stop_date à l'heure courante.
</para>
<para>
Pour trouver les lignes <quote>actuellement valides</quote>, on ajoute la
clause <literal>stop_date = 'infinity'</literal> dans la condition
WHERE de la requête. (Cela peut se faire au travers d'une vue.) De façon
similaire, une requête peut être exécutée sur les lignes valides à
un moment du passé si des conditions adéquates sont posées sur
start_date et stop_date.
</para>
<para>
<function>timetravel()</function> est la fonction déclencheur générique
associée à ce fonctionnement.
On crée un déclencheur <literal>BEFORE INSERT OR UPDATE
OR DELETE</literal> qui utilise cette fonction pour chaque table sur laquelle
la fonctionnalité de voyage dans le temps est activée. Le déclencheur
accepte deux arguments : les noms réels des colonnes start_date et
stop_date. La fonction accepte jusqu'à trois arguments optionnels
qui doivent faire référence à des colonnes de type
<type>text</type>. Le déclencheur stocke le nom de l'utilisateur courant
dans la première de ces colonnes lors d'un INSERT, dans la seconde lors
d'un UPDATE et dans la troisième lors un DELETE.
</para>
<para>
<function>set_timetravel()</function> permet d'activer et de
désactiver la fonctionnalité de voyage dans le temps pour une table.
<literal>set_timetravel('ma_table', 1)</literal> l'active pour la table
ma_table.
<literal>set_timetravel('ma_table', 0)</literal> la désactive pour la table
ma_table.
Dans les deux cas, l'ancien statut est rapporté. Quand elle est
désactivée, les colonnes start_date et stop_date peuvent être librement
modifiées. Le statut actif/inactif est local à la session
courante — toute session commence avec cette
fonctionnalité activée sur toutes les tables.
</para>
<para>
<function>get_timetravel()</function> renvoie l'état de la fonctionnalité
du voyage dans le temps pour une table sans le modifier.
</para>
<para>
Il y a un exemple dans <filename>timetravel.example</filename>.
</para>
</sect2>
<sect2>
<title>autoinc.c — fonctions pour l'incrémentation automatique
d'un champ</title>
<para>
<function>autoinc()</function> est un déclencheur qui stocke la prochaine valeur
d'une séquence dans un champ de type integer. Cela recouvre quelque peu
la fonctionnalité interne de la colonne <quote>serial</quote>, mais
ce n'est pas strictement identique : <function>autoinc()</function>
surcharge les tentatives de substitution d'une valeur différente pour ce
champ lors des insertions et, optionnellement, peut aussi être utilisé pour
incrémenter le champ lors des mises à jour.
</para>
<para>
Pour l'utiliser, on crée un déclencheur <literal>BEFORE INSERT</literal> (ou
en option <literal>BEFORE INSERT OR UPDATE</literal>) qui utilise cette
fonction. Le déclencheur accepte deux arguments : le nom de la
colonne de type integer à modifier et le nom de la séquence qui fournit
les valeurs. (En fait, plusieurs paires de noms peuvent être indiquées pour
actualiser plusieurs colonnes.)
</para>
<para>
Un exemple est fourni dans <filename>autoinc.example</filename>.
</para>
</sect2>
<sect2>
<title>insert_username.c — fonctions pour tracer les utilisateurs qui
ont modifié une table</title>
<para>
<function>insert_username()</function> est un déclencheur qui stocke le
nom de l'utilisateur courant dans un champ texte. C'est utile pour
savoir quel est le dernier utilisateur à avoir modifié une ligne particulière d'une
table.
</para>
<para>
Pour l'utiliser, on crée un déclencheur <literal>BEFORE INSERT</literal> et/ou
<literal>UPDATE</literal> qui utilise cette fonction. Le déclencheur prend
pour seul argument le nom de la colonne texte à modifier.
</para>
<para>
Un exemple est fourni dans <filename>insert_username.example</filename>.
</para>
</sect2>
<sect2>
<title>moddatetime.c — fonctions pour tracer la date et l'heure
de la dernière modification</title>
<para>
<function>moddatetime()</function> est un déclencheur qui stocke la date et
l'heure de la dernière modification dans un champ de type
<type>timestamp</type>. C'est utile pour savoir quand a eu lieu la
dernière modification sur une ligne particulière d'une table.
</para>
<para>
Pour l'utiliser, on crée un déclencheur <literal>BEFORE UPDATE</literal> qui
utilise cette fonction. Le déclencheur prend pour seul argument le
nom de la colonne de type <type>timestamp</type> à modifier.
</para>
<para>
Un exemple est fourni dans <filename>moddatetime.example</filename>.
</para>
</sect2>
</sect1>