diff --git a/postgresql/extend.xml b/postgresql/extend.xml
index 64d8eb737..6854977b0 100644
--- a/postgresql/extend.xml
+++ b/postgresql/extend.xml
@@ -42,7 +42,7 @@
- packages of related objects (starting in )
+ d'extensions permettant de créer un paquetage d'objets qui disposent d'un point commun (voir )
@@ -289,112 +289,110 @@
&xindex;
- Packaging Related Objects into an Extension
+ Empaqueter des objets en une extension
extension
- A useful extension to PostgreSQL typically includes
- multiple SQL objects; for example, a new datatype will require new
- functions, new operators, and probably new index operator classes.
- It is helpful to collect all these objects into a single package
- to simplify database management. PostgreSQL calls
- such a package an extension. To define an extension,
- you need at least a script file that contains the
- SQL commands to create the extension's objects, and a
- control file that specifies a few basic properties
- of the extension itself. If the extension includes C code, there
- will typically also be a shared library file into which the C code
- has been built. Once you have these files, a simple
- command loads the objects into
- your database.
+ Les extensions utiles à PostgreSQL contiennent généralement
+ plusieurs objets SQL. Par exemple, un nouveau type de données va nécessiter de
+ nouvelles fonctions, de nouveaux opérateurs, et probablement de nouvelles méthodes
+ d'indexation.
+ Il peut être utile de les grouper en un unique paquetage pour simplifier la gestion
+ de base de données. Avec PostgreSQL, ces paquetages sont
+ appelés extension. Pour créer une extension, vous avez besoin
+ au minimum d'un fichier de script qui contient les commandes
+ SQL permettant de créer ses objets, et un
+ fichier de contrôle qui rapporte quelques propriétés de base
+ de cette extension. Si cette extension inclus du code C, elle sera aussi généralement
+ accompagnée d'une librairie dans lequel le code C aura été compilé.
+ Une fois ces fichiers en votre possession, un simple appel à la commande
+ vous permettra de charger ses objets dans la base
+ de données.
- The main advantage of using an extension, rather than just running the
- SQL script to load a bunch of loose
objects
- into your database, is that PostgreSQL will then
- understand that the objects of the extension go together. You can
- drop all the objects with a single
- command (no need to maintain a separate uninstall
script).
- Even more useful, pg_dump knows that it should not
- dump the individual member objects of the extension — it will
- just include a CREATE EXTENSION command in dumps, instead.
- This vastly simplifies migration to a new version of the extension
- that might contain more or different objects than the old version.
- Note however that you must have the extension's control, script, and
- other files available when loading such a dump into a new database.
+ Le principal avantage des extensions n'est toutefois pas de pouvoir de charger une
+ grande quantité d'objets dans votre base de donnée. Les extensions permettent en effet
+ surtout à PostgreSQL de comprendre que ces objets sont liés par cette
+ extension. Vous pouvez par exemple supprimer tous ces objets avec une simple commande
+ . Il n'est ainsi pas nécessaire de maintenir un script de
+ désintallation
.
+ Plus utile encore, l'outil pg_dump saura reconnaître les objets
+ appartenant à une extension, et plutôt que de les extraire individuellement, ajoutera simplement
+ une commande CREATE EXTENSION à la sauvegarde.
+ Ce mécanisme simplifie aussi la migration à une nouvelle version de l'extension
+ qui peut contenir de nouveaux objets ou des objets différents de la version d'origine.
+ Notez bien toutefois qu'il est nécessaire de disposer des fichiers de contrôles, de script,
+ et autres pour permettre la restauration d'une telle sauvegarde dans une nouvelle base
+ de donnée.
- PostgreSQL will not let you drop an individual object
- contained in an extension, except by dropping the whole extension.
- Also, while you can change the definition of an extension member object
- (for example, via CREATE OR REPLACE FUNCTION for a
- function), bear in mind that the modified definition will not be dumped
- by pg_dump. Such a change is usually only sensible if
- you concurrently make the same change in the extension's script file.
- (But there are special provisions for tables containing configuration
- data; see below.)
+ PostgreSQL ne permet pas de supprimer de manière individuelle
+ les objets d'une extension sans supprimer l'extension tout entière.
+ Aussi, bien que vous ayez la possibilité de modifier la définition d'un objet inclus dans
+ une extension (par exemple via la commande CREATE OR REPLACE FUNCTION dans
+ le cas d'une fonction), il faut garder en tête que cette modification ne sera pas sauvegardée
+ par l'outil pg_dump. Une telle modification n'est en pratique raisonnable
+ que si vous modifiez parallèlement le fichier de script de l'extension. Il existe toutefois des
+ cas particuliers comme celui des tables qui contiennent des données de configuration (voir ci-après).
- The extension mechanism also has provisions for packaging modification
- scripts that adjust the definitions of the SQL objects contained in an
- extension. For example, if version 1.1 of an extension adds one function
- and changes the body of another function compared to 1.0, the extension
- author can provide an update script that makes just those
- two changes. The ALTER EXTENSION UPDATE command can then
- be used to apply these changes and track which version of the extension
- is actually installed in a given database.
+ Il existe aussi un mécanisme permettant de créer des scripts de mise à jour de la définition des objets
+ SQL contenus dans une extension.
+ Par exemple, si la version 1.1 d'une extension ajoute une fonction et change le corps d'une autre
+ vis à vis de la version 1.0 d'origine, l'auteur de l'extension peut fournir un script
+ de mise à jour qui effectue uniquement ces deux modifications. La commande
+ ALTER EXTENSION UPDATE peut alors être utilisée pour appliquer ces changements et vérifier
+ quelle version de l'extension est actuellement installée sur une base de donnée spécifiée.
- The kinds of SQL objects that can be members of an extension are shown in
- the description of . Notably, objects
- that are database-cluster-wide, such as databases, roles, and tablespaces,
- cannot be extension members since an extension is only known within one
- database. (Although an extension script is not prohibited from creating
- such objects, if it does so they will not be tracked as part of the
- extension.) Also notice that while a table can be a member of an
- extension, its subsidiary objects such as indexes are not directly
- considered members of the extension.
+ Les catégories d'objets SQL qui peuvent être inclus dans une extension
+ sont spécifiées dans la description de la commande .
+ D'une manière générale, les objets qui sont communs à l'ensemble de la base ou du cluster,
+ comme les bases de données, les rôles, les tablespaces ne peuvent être inclus dans une
+ extension car une extension n'est référencée qu'à l'intérieur d'une base de donnée.
+ A noter que rien n'empêche la création de fichier de script qui créée de tels objets, mais
+ qu'ils ne seront alors pas considérés après leur création comme faisant partie de l'extension.
+ A savoir en outre que bien que les tables puissent être incluses dans une extension, les objets
+ annexes tels que les index ne sont pas automatiquement inclus dans l'extension et devront être
+ explicitement mentionnés dans les fichiers de script.
- Extension Files
+ Fichiers des extensions
- control file
+ Fichier de contrôle
- The command relies on a control
- file for each extension, which must be named the same as the extension
- with a suffix of .control, and must be placed in the
- installation's SHAREDIR/extension directory. There
- must also be at least one SQL script file, which follows the
- naming pattern
- extension--version.sql
- (for example, foo--1.0.sql for version 1.0 of
- extension foo). By default, the script file(s) are also
- placed in the SHAREDIR/extension directory; but the
- control file can specify a different directory for the script file(s).
+ La commande repose sur un fichier de contrôle
+ associé à chaque extension. Ce fichier doit avoir le même nom que l'extension suivi du suffixe
+ .control, et doit être placé dans le sous-répertoire SHAREDIR/extension
+ du répertoire d'installation. Il doit être accompagné d'au moins un fichier de script SQL
+ dont le nom doit répondre à la syntaxe extension--version.sql
+ (par exemple, foo--1.0.sql pour la version 1.0 de l'extension foo).
+ Par défaut, les fichiers de script sont eux-aussi situés dans le répertoire SHAREDIR/extension. Le fichier
+ de contrôle peut toutefois spécifier un répertoire différent pour chaque fichier de script.
- The file format for an extension control file is the same as for the
- postgresql.conf file, namely a list of
- parameter_name = value
- assignments, one per line. Blank lines and comments introduced by
- # are allowed. Be sure to quote any value that is not
- a single word or number.
+ Le format de fichier du fichier de contrôle d'une extension est le même que pour le
+ fichier postgresql.conf, à savoir une liste d'affectation
+ parameter_name = value
+ avec un maximum d'une affectation par ligne.
+ Les lignes vides et les commentaires introduits par # sont eux-aussi autorisés.
+ Prenez garde à placer entre guillemets les valeurs qui ne sont ni des nombres ni des mots isolés.
- A control file can set the following parameters:
+ Un fichier de contrôle peut définir les paramètres suivants:
@@ -402,11 +400,11 @@
directory (string)
- The directory containing the extension's SQL script
- file(s). Unless an absolute path is given, the name is relative to
- the installation's SHAREDIR directory. The
- default behavior is equivalent to specifying
- directory = 'extension'.
+ Le répertoire qui inclus les scripts SQL de l'extension.
+ Si un chemin relatif est spécifié, le sous-répertoire SHAREDIR
+ du répertoire d'installation sera choisi comme base.
+ Le comportement par défaut de ce paramètre revient à le définir tel que
+ directory = 'extension'.
@@ -415,11 +413,12 @@
default_version (string)
- The default version of the extension (the one that will be installed
- if no version is specified in CREATE EXTENSION). Although
- this can be omitted, that will result in CREATE EXTENSION
- failing if no VERSION option appears, so you generally
- don't want to do that.
+ La version par défaut de l'extension, qui sera installée si aucune
+ version n'est spécifiée avec la commande CREATE EXTENSION.
+ Ainsi, bien que ce paramètre puisse ne pas être spécifié, il reste
+ recommandé de le définir pour éviter que la commande
+ CREATE EXTENSION ne provoque une erreur
+ en l'absence de l'option VERSION.
@@ -428,9 +427,9 @@
comment (string)
- A comment (any string) about the extension. Alternatively,
- the comment can be set by means of the
- command in the script file.
+ Un commentaire de type chaîne de caractère au sujet de l'extension. Une alternative
+ consiste à utiliser la commande dans
+ le script de l'extension.
@@ -439,9 +438,10 @@
encoding (string)
- The character set encoding used by the script file(s). This should
- be specified if the script files contain any non-ASCII characters.
- Otherwise the files will be assumed to be in the database encoding.
+ L'encodage de caractère utilisé par les fichiers de script. Ce paramètre
+ doit être spécifié si les fichiers de script contiennent des caractères
+ non ASCII. Le comportement par défaut en l'absence de ce paramètre consiste à utiliser
+ l'encodage de la base de donnée.
@@ -450,13 +450,12 @@
module_pathname (string)
- The value of this parameter will be substituted for each occurrence
- of MODULE_PATHNAME in the script file(s). If it is not
- set, no substitution is made. Typically, this is set to
- $libdir/shared_library_name and
- then MODULE_PATHNAME is used in CREATE
- FUNCTION commands for C-language functions, so that the script
- files do not need to hard-wire the name of the shared library.
+ La valeur de ce paramètre sera utilisée pour toute référence à MODULE_PATHNAME
+ dans les fichiers de script. Si ce paramètre n'est pas défini, la substitution ne sera pas effectuée.
+ La valeur $libdir/nom_de_librairie lui est usuellement attribuée
+ et dans ce cas, MODULE_PATHNAME est utilisé dans la commande CREATE
+ FUNCTION concernant les fonctions en langage C, de manière à ne pas mentionner en dur
+ le nom de la librairie partagée.
@@ -465,9 +464,9 @@
requires (string)
- A list of names of extensions that this extension depends on,
- for example requires = 'foo, bar'. Those
- extensions must be installed before this one can be installed.
+ Une liste de noms d'extension dont dépend cette extension, comme
+ par exemple requires = 'foo, bar'. Ces extensions
+ doivent être installées avant que l'extension puisse être installée.
@@ -476,11 +475,10 @@
superuser (boolean)
- If this parameter is true (which is the default),
- only superusers can create the extension or update it to a new
- version. If it is set to false, just the privileges
- required to execute the commands in the installation or update script
- are required.
+ Si ce paramètre est à true (il s'agit de la valeur par défaut),
+ seuls les superutilisateurs pourront créer cet extension ou la mettre à jour.
+ Si ce paramètre est à false, seuls les privilèges nécessaires
+ seront requis pour installer ou mettre à jour l'extension.
@@ -489,11 +487,11 @@
relocatable (boolean)
- An extension is relocatable if it is possible to move
- its contained objects into a different schema after initial creation
- of the extension. The default is false, i.e. the
- extension is not relocatable.
- See below for more information.
+ Une extension est dite déplaçable
(relocatable)
+ s'il est possible de déplacer les objets qu'elle contient dans un schéma différent
+ de celui attribué initialement par l'extension. La valeur par défaut est à
+ false, ce qui signifie que l'extension n'est pas déplaçable.
+ Voir ci-dessous pour des informations complémentaires.
@@ -502,319 +500,307 @@
schema (string)
- This parameter can only be set for non-relocatable extensions.
- It forces the extension to be loaded into exactly the named schema
- and not any other. See below for more information.
+ Ce paramètre ne peut être spécifié que pour les extensions non déplaçables.
+ Il permet de forcer l'extension à charger ses objets dans le schéma spécifié
+ et aucun autre. Voir ci-dessous pour des informations complémentaires.
- In addition to the primary control file
- extension.control,
- an extension can have secondary control files named in the style
- extension--version.control.
- If supplied, these must be located in the script file directory.
- Secondary control files follow the same format as the primary control
- file. Any parameters set in a secondary control file override the
- primary control file when installing or updating to that version of
- the extension. However, the parameters directory and
- default_version cannot be set in a secondary control file.
+ En complément au fichier de contrôle extension.control,
+ une extension peut disposer de fichiers de contrôle secondaires pour chaque version dont le nommage correspond à
+ extension--version.control.
+ Ces fichiers doivent se trouver dans le répertoire des fichiers de script de l'extension.
+ Les fichiers de contrôle secondaires suivent le même format que le fichier de contrôle principal.
+ Tout paramètre spécifié dans un fichier de contrôle secondaire surcharge la valeur spécifiée dans le
+ fichier de contrôle principal concernant les installations ou mises à jour à la version considérée.
+ Cependant, il n'est pas possible de spécifier les paramètres directory et
+ default_version dans un fichier de contrôle secondaire.
- An extension's SQL script files can contain any SQL commands,
- except for transaction control commands (BEGIN,
- COMMIT, etc) and commands that cannot be executed inside a
- transaction block (such as VACUUM). This is because the
- script files are implicitly executed within a transaction block.
+ Un fichier de script SQL d'une extension peut contenir toute commande
+ SQL, à l'exception des commandes de contrôle de transaction (BEGIN,
+ COMMIT, etc), et des commandes qui ne peuvent être exécutées au sein
+ d'un bloc transactionnel (comme la commande VACUUM). Cette contrainte
+ est liée au fait que les fichiers de script sont implicitement exécutés dans une transaction.
- While the script files can contain any characters allowed by the specified
- encoding, control files should contain only plain ASCII, because there
- is no way for PostgreSQL to know what encoding a
- control file is in. In practice this is only an issue if you want to
- use non-ASCII characters in the extension's comment. Recommended
- practice in that case is to not use the control file comment
- parameter, but instead use COMMENT ON EXTENSION
- within a script file to set the comment.
+ Bien que les fichiers de script puisse contenir n'importe quel caractère autorisé
+ par l'encodage spécifié, les fichiers de contrôle ne peuvent contenir que des caractères
+ ASCII non formatés. PostgreSQL ne peut en effet pas déterminer
+ l'encodage utilisé par les fichiers de contrôle. Dans la pratique, cela ne pose problème
+ que dans le cas où vous voudriez utiliser des caractères non ASCII dans le commentaire
+ de l'extension. Dans ce cas de figure, il est recommandé de ne pas utiliser le paramètre
+ comment du fichier de contrôle pour définir ce commentaire, mais plutôt
+ la commande COMMENT ON EXTENSION dans un fichier de script.
- Extension Relocatability
+ Possibilités concernant le déplacement des extensions
- Users often wish to load the objects contained in an extension into a
- different schema than the extension's author had in mind. There are
- three supported levels of relocatability:
+ Les utilisateurs souhaitent souvent charger les objets d'une extension
+ dans un schéma différent de celui imposé par l'auteur. Trois niveaux
+ de déplacement sont supportés :
- A fully relocatable extension can be moved into another schema
- at any time, even after it's been loaded into a database.
- This is done with the ALTER EXTENSION SET SCHEMA
- command, which automatically renames all the member objects into
- the new schema. Normally, this is only possible if the extension
- contains no internal assumptions about what schema any of its
- objects are in. Also, the extension's objects must all be in one
- schema to begin with (ignoring objects that do not belong to any
- schema, such as procedural languages). Mark a fully relocatable
- extension by setting relocatable = true in its control
- file.
+ Une extension supportant complétement le déplacement peut être déplacé
+ dans un autre schéma à tout moment, y compris après son chargement
+ dans une base de donnée.
+ Initialement, tous les objets de l'extension installée appartiennent à un
+ premier schéma (excepté les objets qui n'appartiennent à aucun schéma comme les
+ langages procéduraux).
+ L'opération de déplacement peut alors être réalisée avec la commande ALTER EXTENSION SET SCHEMA,
+ qui renomme automatiquement tous les objets de l'extension pour être intégrés dans le nouveau
+ schéma. Le déplacement ne sera toutefois fonctionnel
+ que si l'extension ne contient aucune référence de l'appartenance d'un de ses objets à un schéma.
+ Dans ce cadre, il est alors possible de spécifier qu'une extension supporte complétement le déplacement en initialisant
+ relocatable = true dans son fichier de contrôle.
- An extension might be relocatable during installation but not
- afterwards. This is typically the case if the extension's script
- file needs to reference the target schema explicitly, for example
- in setting search_path properties for SQL functions.
- For such an extension, set relocatable = false in its
- control file, and use @extschema@ to refer to the target
- schema in the script file. All occurrences of this string will be
- replaced by the actual target schema's name before the script is
- executed. The user can set the target schema using the
- SCHEMA option of CREATE EXTENSION.
+ Une extension peut être déplaçable durant l'installation et ne plus l'être
+ par la suite. Un exemple courant est celui du fichier de script de l'extension
+ qui doit référencer un schéma cible de manière explicite pour des fonctions SQL, par exemple en définissant
+ la propriété search_path.
+ Pour de telles extensions, il faut définir relocatable = false dans
+ son fichier de contrôle, et utiliser @extschema@ pour référencer
+ le schéma cible dans le fichier de script. Toutes les occurences de cette chaîne dans le
+ fichier de script seront remplacées par le nom du schéma choisi avant son exécution.
+ Le nom du schéma choisi peut être fixé par l'option SCHEMA de la
+ commande CREATE EXTENSION>.
- If the extension does not support relocation at all, set
- relocatable = false in its control file, and also set
- schema to the name of the intended target schema. This
- will prevent use of the SCHEMA option of CREATE
- EXTENSION, unless it specifies the same schema named in the control
- file. This choice is typically necessary if the extension contains
- internal assumptions about schema names that can't be replaced by
- uses of @extschema@. The @extschema@
- substitution mechanism is available in this case too, although it is
- of limited use since the schema name is determined by the control file.
+ Si l'extension ne permet pas du tout le déplacement, il faut définir relocatable = false
+ dans le fichier de contrôle, mais aussi définir schema comme étant le nom du schéma cible.
+ Cette précaution permettra d'empêcher l'usage de l'option SCHEMA de la commande CREATE
+ EXTENSION, à moins que cette option ne référence la même valeur que celle spécifiée dans le fichier de
+ contrôle. Ce choix est à priori nécessaire si l'extension contient des références à des noms
+ de schéma qui ne peuvent être remplacés par @extschema@. A noter que même si son usage reste
+ relativement limité dans ce cas de figure puisque le nom du schéma est alors fixé dans le fichier de contrôle,
+ le mécanisme de substitution de @extschema@ reste toujours opérationnel.
- In all cases, the script file will be executed with
- initially set to point to the target
- schema; that is, CREATE EXTENSION does the equivalent of
- this:
+ Dans tous les cas, le fichier de script sera exécuté avec comme valeur de
+ le schéma cible. Cela signifie que la commande CREATE EXTENSION réalisera l'équivalent
+ de la commande suivante :
SET LOCAL search_path TO @extschema@;
- This allows the objects created by the script file to go into the target
- schema. The script file can change search_path if it wishes,
- but that is generally undesirable. search_path is restored
- to its previous setting upon completion of CREATE EXTENSION.
+ Cela permettra aux objets du fichier de script d'être créés dans le schéma cible. Le fichier de script
+ peut toutefois modifier la valeur de search_path si nécessaire, mais cela n'est
+ généralement pas le comportement souhaité. La variable search_path retrouvera sa valeur
+ initiale à la fin de l'exécution de la commande CREATE EXTENSION.
- The target schema is determined by the schema parameter in
- the control file if that is given, otherwise by the SCHEMA
- option of CREATE EXTENSION if that is given, otherwise the
- current default object creation schema (the first one in the caller's
- search_path). When the control file schema
- parameter is used, the target schema will be created if it doesn't
- already exist, but in the other two cases it must already exist.
+ Le schéma cible est déterminé par le paramètre schema dans le
+ fichier de contrôle s'il est précisé, sinon par l'option SCHEMA
+ de la commande CREATE EXTENSION s'il elle est spécifiée, sinon
+ par le schéma de création par défaut actuel (le premier rencontré en suivant le
+ chemin de recherche search_path de l'appelant). Quand le paramètre
+ schema du fichier de contrôle est utilisé, le schéma cible sera créé
+ s'il n'existe pas encore. Dans les autres cas, il devra exister au préalable.
- If any prerequisite extensions are listed in requires
- in the control file, their target schemas are appended to the initial
- setting of search_path. This allows their objects to be
- visible to the new extension's script file.
+ Si des extensions requises sont définies par requires dans le fichier
+ de contrôle, leur schéma cible est ajouté à la valeur initiale de search_path.
+ Cela permet à leurs objets d'être visibles dans le fichier de script de l'extension installée.
- Although a non-relocatable extension can contain objects spread across
- multiple schemas, it is usually desirable to place all the objects meant
- for external use into a single schema, which is considered the extension's
- target schema. Such an arrangement works conveniently with the default
- setting of search_path during creation of dependent
- extensions.
+ Une extension peut contenir des objets répartis dans plusieurs schémas.
+ Il est alors conseillé de regrouper dans un unique schéma l'ensemble des objets destinés à un usage
+ externe à l'extension, qui sera alors le schéma cible de l'extension. Une telle organisation est compatible
+ avec la définition par défaut de search_path pour la création d'extensions
+ qui en seront dépendantes.
- Extension Configuration Tables
+ Tables de configuration des extensions
- Some extensions include configuration tables, which contain data that
- might be added or changed by the user after installation of the
- extension. Ordinarily, if a table is part of an extension, neither
- the table's definition nor its content will be dumped by
- pg_dump. But that behavior is undesirable for a
- configuration table; any data changes made by the user need to be
- included in dumps, or the extension will behave differently after a dump
- and reload.
+ Certaines extensions incluent des tables de configuration, contenant
+ des données qui peuvent être ajoutées ou changées par l'utilisateur
+ après l'installation de l'extension. Normalement, si la table fait
+ partie de l'extension, ni la définition de la table, ni son contenu
+ ne sera sauvegardé par pg_dump. Mais
+ ce comportement n'est pas celui attendu pour une table de configuration.
+ Les données modifiées par un utilisateur nécessitent d'être sauvegardées,
+ ou l'extension aura un comportement différent après rechargement.
- To solve this problem, an extension's script file can mark a table
- it has created as a configuration table, which will cause
- pg_dump to include the table's contents (not its
- definition) in dumps. To do that, call the function
- pg_extension_config_dump(regclass, text) after creating the
- table, for example
+ Pour résoudre ce problème, un fichier de script d'extension peut marquer
+ une table comme étant une table de configuration, ce qui indiquera à pg_dump
+ d'inclure le contenu de la table (et non sa définition) dans la sauvegarde. Pour cela, il s'agit d'appeler
+ la fonction pg_extension_config_dump(regclass, text) après avoir
+ créé la table, par exemple
CREATE TABLE my_config (key text, value text);
SELECT pg_catalog.pg_extension_config_dump('my_config', '');
- Any number of tables can be marked this way.
+ Cette fonction permet de marquer autant de tables que nécessaire.
- When the second argument of pg_extension_config_dump is
- an empty string, the entire contents of the table are dumped by
- pg_dump. This is usually only correct if the table
- is initially empty as created by the extension script. If there is
- a mixture of initial data and user-provided data in the table,
- the second argument of pg_extension_config_dump provides
- a WHERE condition that selects the data to be dumped.
- For example, you might do
+ Si le second argument de pg_extension_config_dump est une
+ chaîne vide, le contenu entier de la table sera sauvegardé par l'application
+ pg_dump. Cela n'est correct que si la table
+ était initialement vide après l'installation du script. Si un mélange de données
+ initiales et de données ajoutées par l'utilisateur est présent dans la table,
+ le second argument de pg_extension_config_dump permet de
+ spécifier une condition WHERE qui selectionne les données à
+ sauvegarder.
+ Par exemple, vous pourriez faire
CREATE TABLE my_config (key text, value text, standard_entry boolean);
SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entry');
- and then make sure that standard_entry is true only
- in the rows created by the extension's script.
+ et vous assurer que la valeur de standard_entry soit
+ true uniquement lorsque les lignes ont été créées par le script de l'extension.
- More complicated situations, such as initially-provided rows that might
- be modified by users, can be handled by creating triggers on the
- configuration table to ensure that modified rows are marked correctly.
+ Des situations plus compliquées, comme des données initiales qui peuvent être modifiées
+ par l'utilisateur, peuvent être prises en charge en créant des triggers sur la table de configuration
+ pour s'assurer que les lignes ont été marquées correctement.
- Extension Updates
+ Mise à jour d'extension
- One advantage of the extension mechanism is that it provides convenient
- ways to manage updates to the SQL commands that define an extension's
- objects. This is done by associating a version name or number with
- each released version of the extension's installation script.
- In addition, if you want users to be able to update their databases
- dynamically from one version to the next, you should provide
- update scripts that make the necessary changes to go from
- one version to the next. Update scripts have names following the pattern
- extension--oldversion--newversion.sql
- (for example, foo--1.0--1.1.sql contains the commands to modify
- version 1.0 of extension foo into version
- 1.1).
+ Un des avantages du mécanisme d'extension est de proposer un moyen
+ simple de gérer la mise à jour des commandes SQL qui définissent les objets
+ de l'extension. Cela est rendu possible par l'association d'un nom ou d'un numéro
+ de version à chaque nouvelle version du script d'installation de l'extension.
+ En complément, si vous voulez qu'un utilisateur soit capable de mettre à jour
+ sa base de données dynamiquement d'une version à une autre, vous pouvez
+ fournir des scripts de mise à jour qui feront les
+ modifications nécessaires. Les scripts de mise à jour ont un nom qui correspond au format
+ extension--oldversion--newversion.sql
+ (par exemple, foo--1.0--1.1.sql contient les commandes pour modifier
+ la version 1.0 de l'extension foo en la version
+ 1.1).
- Given that a suitable update script is available, the command
- ALTER EXTENSION UPDATE will update an installed extension
- to the specified new version. The update script is run in the same
- environment that CREATE EXTENSION provides for installation
- scripts: in particular, search_path is set up in the same
- way, and any new objects created by the script are automatically added
- to the extension.
+ En admettant qu'un tel script de mise à jour soit disponible, la commande
+ ALTER EXTENSION UPDATE mettra à jour une extension installée
+ vers la nouvelle version spécifiée. Le script de mise à jour est exécuté dans le
+ même environnement que celui que la commande CREATE EXTENSION
+ fourni pour l'installation de scripts : en particulier, la variable search_path
+ est définie de la même façon et tout nouvel objet créé par le script est automatiquement
+ ajouté à l'extension.
- If an extension has secondary control files, the control parameters
- that are used for an update script are those associated with the script's
- target (new) version.
+ Si une extension a un fichier de contrôle secondaire, les paramètres de contrôle qui
+ sont utilisés par un script de mise à jour sont ceux définis par le script de la version
+ cible.
- The update mechanism can be used to solve an important special case:
- converting a loose
collection of objects into an extension.
- Before the extension mechanism was added to
- PostgreSQL (in 9.1), many people wrote
- extension modules that simply created assorted unpackaged objects.
- Given an existing database containing such objects, how can we convert
- the objects into a properly packaged extension? Dropping them and then
- doing a plain CREATE EXTENSION is one way, but it's not
- desirable if the objects have dependencies (for example, if there are
- table columns of a data type created by the extension). The way to fix
- this situation is to create an empty extension, then use ALTER
- EXTENSION ADD to attach each pre-existing object to the extension,
- then finally create any new objects that are in the current extension
- version but were not in the unpackaged release. CREATE
- EXTENSION supports this case with its FROM old_version option, which causes it to not run the
- normal installation script for the target version, but instead the update
- script named
- extension--old_version--target_version.sql.
- The choice of the dummy version name to use as old_version is up to the extension author, though
- unpackaged is a common convention. If you have multiple
- prior versions you need to be able to update into extension style, use
- multiple dummy version names to identify them.
+ Le mécanisme de mise à jour peut être utilisé pour résoudre un cas particulier important :
+ convertir une collection éparse d'objets en une extension.
+ Avant que le mécanisme d'extension ne soit introduit à PostgreSQL
+ (dans la version 9.1), de nombreuses personnes écrivaient des modules d'extension qui créaient
+ simplement un assortiment d'objets non empaquetés.
+ Etant donné une base de donnée existante contenant de tels objets, comment convertir ces objets
+ en des extensions proprement empaquetées ? Les supprimer puis exécuter la commande
+ CREATE EXTENSION est une première méthode, mais elle n'est pas envisageable lorsque
+ les objets ont des dépendances (par exemple, s'il y a des colonnes de table dont le type de
+ données appartient à une extension). Le moyen proposé pour résoudre ce problème est de créer
+ une extension vide, d'utiliser la commande ALTER EXTENSION ADD pour lier
+ chaque objet pré-existant à l'extension, et finalement créer les nouveaux objets présents dans
+ la nouvelle extension mais absents de celle non empaquetée. La commande CREATE EXTENSION
+ prend en charge cette fonction avec son option FROM old_version,
+ qui permet de ne pas charger le script d'installation par défaut pour la version ciblée, mais celui nommé
+ extension--old_version--target_version.sql.
+ Le choix de la valeur de old_version
+ relève de la responsabilité de l'auteur de l'extension, même si unpackaged est souvent rencontré.
+ Il est aussi possible de multiplier les valeurs de old_version pour prendre en compte
+ une mise à jour depuis différentes anciennes versions.
- ALTER EXTENSION is able to execute sequences of update
- script files to achieve a requested update. For example, if only
- foo--1.0--1.1.sql and foo--1.1--2.0.sql are
- available, ALTER EXTENSION will apply them in sequence if an
- update to version 2.0 is requested when 1.0 is
- currently installed.
+ La commande ALTER EXTENSION peut exécuter des mises à jour en séquence pour
+ réussir une mise à jour. Par exemple, si seuls les fichiers foo--1.0--1.1.sql
+ et foo--1.1--2.0.sql sont disponibles, la commande ALTER
+ EXTENSION les exécutera séquentiellement si une mise à jour vers la version 2.0
+ est demandée alors que la version 1.0 est installée.
- PostgreSQL doesn't assume anything about the properties
- of version names: for example, it does not know whether 1.1
- follows 1.0. It just matches up the available version names
- and follows the path that requires applying the fewest update scripts.
- (A version name can actually be any string that doesn't contain
- -- or leading or trailing -.)
+ PostgreSQL ne suppose rien au sujet des noms de version.
+ Par exemple, il ne sait pas si 1.1 suit 1.0.
+ Il effectue juste une correspondance entre les noms de version et suit un chemin
+ qui nécessite d'appliquer le moins de fichier de script possible.
+ Un nom de version peut en réalité être toute chaîne qui ne contiendrait pas
+ -- ou qui ne commencerait ou ne finirait pas par -.
- Sometimes it is useful to provide downgrade
scripts, for
- example foo--1.1--1.0.sql to allow reverting the changes
- associated with version 1.1. If you do that, be careful
- of the possibility that a downgrade script might unexpectedly
- get applied because it yields a shorter path. The risky case is where
- there is a fast path
update script that jumps ahead several
- versions as well as a downgrade script to the fast path's start point.
- It might take fewer steps to apply the downgrade and then the fast
- path than to move ahead one version at a time. If the downgrade script
- drops any irreplaceable objects, this will yield undesirable results.
+ Il peut parfois être utile de fournir des scripts de retour en arrière, comme par exemple
+ foo--1.1--1.0.sql pour autoriser d'inverser les modifications effectuées
+ par la mise à jour en version 1.1. Si vous procédez ainsi, ayez conscience
+ de la possibilité laissée à PostgreSQL d'exécuter un tel script de retour
+ en arrière s'il permet d'atteindre la version cible d'une mise à jour en un nombre réduit d'étapes.
+ La cause du risque se trouve dans les scripts de mise à jour optimisés permettant de passer
+ plusieurs versions en un seul script. La longueur du chemin commençant par un retour en
+ arrière suivi d'un script optimisé pourrait être inférieure à la longueur du chemin qui monterait
+ de version une par une. Si le script de retour en arrière supprime un objet irremplaçable, les conséquences
+ pourraient en être facheuses.
- To check for unexpected update paths, use this command:
+ Pour vérifier que vous ne serez pas confronté à des chemins de mise à jour innatendus, utilisez cette commande :
SELECT * FROM pg_extension_update_paths('extension_name');
- This shows each pair of distinct known version names for the specified
- extension, together with the update path sequence that would be taken to
- get from the source version to the target version, or NULL if
- there is no available update path. The path is shown in textual form
- with -- separators. You can use
- regexp_split_to_array(path,'--') if you prefer an array
- format.
+ Cette commande permet d'afficher chaque paire de noms de version connues pour l'extension spécifiée, ainsi
+ que le chemin de mise à jour qui serait suivi depuis la version de départ jusque la version cible, ou la valeur
+ NULL si aucun chemin valable n'est disponible. Le chemin est affiché sous une forme textuelle
+ avec des séparateurs --. Vous pouvez utiliser regexp_split_to_array(path,'--')
+ si vous préférez le format tableau.
- Extension Example
+ Exemples d'extensions
- Here is a complete example of an SQL-only
- extension, a two-element composite type that can store any type of value
- in its slots, which are named k
and v
. Non-text
- values are automatically coerced to text for storage.
+ Ci-après, un exemple complet d'une extension écrite uniquement en SQL,
+ un type composite de deux éléments qui peut stocker n'importe quelle valeur dans chaque
+ emplacement, qui sont nommés k
et v
. Les valeurs non textuelles
+ sont automatiquement changées en texte avant stockage.
- The script file pair--1.0.sql looks like this:
+ Le fichier de script pair--1.0.sql ressemble à ceci:
(LEFTARG = text, RIGHTARG = text, PROCEDURE = pair);
- The control file pair.control looks like this:
+ Le fichier de contrôle pair.control ressemble à ceci:
# pair extension
-comment = 'A key/value pair data type'
+comment = 'Un type de data representant un couple clef/valeur'
default_version = '1.0'
relocatable = true
- While you hardly need a makefile to install these two files into the
- correct directory, you could use a Makefile containing this:
+ Si vous nécessitez un fichier d'installation pour installer ces deux fichiers dans le bon répertoire,
+ vous pouvez utiliser le fichier Makefile qui suit :
EXTENSION = pair
@@ -863,53 +849,43 @@ PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)
- This makefile relies on PGXS, which is described
- in . The command make install
- will install the control and script files into the correct
- directory as reported by pg_config.
+ Ce fichier d'installation s'appuye sur PGXS, qui est décrit dans .
+ La commande make install va installer les fichiers de contrôle et de script dans le
+ répertoire adéquat tel qu'indiqué par pg_config.
- Once the files are installed, use the
- command to load the objects into
- any particular database.
+ Une fois les fichiers installés, utilisez la commande pour charger
+ les objets dans une base de donnée.
- Extension Building Infrastructure
+ Outils de construction d'extension
pgxs
- If you are thinking about distributing your
- PostgreSQL extension modules, setting up a
- portable build system for them can be fairly difficult. Therefore
- the PostgreSQL installation provides a build
- infrastructure for extensions, called PGXS, so
- that simple extension modules can be built simply against an
- already installed server. PGXS is mainly intended
- for extensions that include C code, although it can be used for
- pure-SQL extensions too. Note that PGXS is not
- intended to be a universal build system framework that can be used
- to build any software interfacing to PostgreSQL;
- it simply automates common build rules for simple server extension
- modules. For more complicated packages, you might need to write your
- own build system.
+ Si vous comptez distribuer vos propres modules d'extension PostgreSQL,
+ la mise en oeuvre d'un système de construction multiplateforme sera réellement difficile.
+ Cependant, PostgreSQL met à disposition des outils pour construire
+ des extensions, appelés PGXS, permettant à de simples extensions d'être
+ construites sur un serveur déjà installé. PGXS est principalement destiné
+ aux extensions qui incluent du code C, bien qu'il puisse être utilisé aussi pour des extensions composées
+ exclusivement de code SQL. PGXS n'a pas toutefois été conçu pour être un framework
+ de construction universel qui pourrait construire tout logiciel s'interfaçant avec PostgreSQL.
+ Il automatise simplement des règles de construction communes pour des extensions simples. Pour des paquetages
+ plus complexes, vous aurez toujours besoin d'écrire vos propres systèmes de construction.
- To use the PGXS infrastructure for your extension,
- you must write a simple makefile.
- In the makefile, you need to set some variables
- and finally include the global PGXS makefile.
- Here is an example that builds an extension module named
- isbn_issn, consisting of a shared library containing
- some C code, an extension control file, a SQL script, and a documentation
- text file:
+ Pour utiliser le système PGXS pour votre extension, vous devez écrire un simple makefile.
+ Dans ce makefile, vous devez définir plusieurs variables et inclure le makefile de PGXS.
+ Voici un exemple qu construit une extension nommée isbn_issn, qui consiste en une librairie
+ qui contient du code C, un fichier de contrôle d'extension, un script SQL, et une documentation texte :
MODULES = isbn_issn
EXTENSION = isbn_issn
@@ -920,21 +896,19 @@ PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)
- The last three lines should always be the same. Earlier in the
- file, you assign variables or add custom
- make rules.
+ Les trois dernières lignes devraient toujours être les mêmes. Plus tôt dans le fichier, vous pouvez assigner des variables
+ ou ajouter des règles make personnalisées.
- Set one of these three variables to specify what is built:
+ Définissez une de ces trois variables pour spécifier ce qui est construit:
MODULES
- list of shared-library objects to be built from source files with same
- stem (do not include library suffixes in this list)
+ liste des librairies à constuire depuis les fichiers sources communs (ne pas inclure les suffixes de librairies dans la liste)
@@ -943,8 +917,8 @@ include $(PGXS)
MODULE_big
- a shared library to build from multiple source files
- (list object files in OBJS)
+ Une librairie à construire depuis plusieurs fichiers source
+ (listez les fichiers objets dans la variable OBJS).
@@ -953,23 +927,23 @@ include $(PGXS)
PROGRAM
- an executable program to build
- (list object files in OBJS)
+ Un programme exécutable à construire
+ (listez les fichiers objet dans la variable OBJS).
- The following variables can also be set:
+ Les variables suivantes peuvent aussi être définies:
EXTENSION
- extension name(s); for each name you must provide an
- extension.control file,
- which will be installed into
+ Nom(s) de l'extension ; Pour chaque nom, vous devez fourni un fichier
+ extension.control,
+ qui sera installé dans le répertoire
prefix/share/extension
@@ -979,11 +953,11 @@ include $(PGXS)
MODULEDIR
- subdirectory of prefix/share
- into which DATA and DOCS files should be installed
- (if not set, default is extension if
- EXTENSION is set,
- or contrib if not)
+ sous-répertoire de prefix/share
+ dans lequel les fichiers DATA est DOCS seront installés
+ (s'il n'est pas défini, la valeur par défaut est extension si
+ EXTENSION est défini,
+ ou contrib sinon)
@@ -992,7 +966,7 @@ include $(PGXS)
DATA
- random files to install into prefix/share/$MODULEDIR
+ les fichiers divers à installer dans prefix/share/$MODULEDIR
@@ -1001,9 +975,9 @@ include $(PGXS)
DATA_built
- random files to install into
+ les fichiers divers à installer dans
prefix/share/$MODULEDIR,
- which need to be built first
+ qui nécessitent d'être construit au préalable
@@ -1012,7 +986,7 @@ include $(PGXS)
DATA_TSEARCH
- random files to install under
+ fichiers divers à installer dans
prefix/share/tsearch_data
@@ -1022,7 +996,7 @@ include $(PGXS)
DOCS
- random files to install under
+ fichiers divers à installer dans
prefix/doc/$MODULEDIR
@@ -1032,7 +1006,7 @@ include $(PGXS)
SCRIPTS
- script files (not binaries) to install into
+ fichiers de scripts (non binaires) à installer dans
prefix/bin
@@ -1042,9 +1016,9 @@ include $(PGXS)
SCRIPTS_built
- script files (not binaries) to install into
+ fichiers de script (non binaires) à installer dans
prefix/bin,
- which need to be built first
+ qui nécessitent d'être construit au préalable.
@@ -1053,7 +1027,7 @@ include $(PGXS)
REGRESS
- list of regression test cases (without suffix), see below
+ liste de tests de regression (sans suffixe), voir plus bas
@@ -1062,7 +1036,7 @@ include $(PGXS)
EXTRA_CLEAN
- extra files to remove in make clean
+ fichiers supplémentaire à supprimer par la commande make clean
@@ -1071,7 +1045,7 @@ include $(PGXS)
PG_CPPFLAGS
- will be added to CPPFLAGS
+ sera ajouté à CPPFLAGS
@@ -1080,7 +1054,7 @@ include $(PGXS)
PG_LIBS
- will be added to PROGRAM link line
+ sera ajouté à la ligne d'édition de lien de PROGRAM
@@ -1089,7 +1063,7 @@ include $(PGXS)
SHLIB_LINK
- will be added to MODULE_big link line
+ sera ajouté à la ligne d'édition de lien de MODULE_big
@@ -1098,10 +1072,10 @@ include $(PGXS)
PG_CONFIG
- path to pg_config program for the
- PostgreSQL installation to build against
- (typically just pg_config to use the first one in your
- PATH)
+ chemin vers le programme pg_config de l'installation
+ de PostgreSQL pour laquelle construire la librairie ou le binaire
+ (l'utilisation de pg_config seul permet d'utiliser le premier accessible par votre
+ PATH)
@@ -1109,56 +1083,51 @@ include $(PGXS)
- Put this makefile as Makefile in the directory
- which holds your extension. Then you can do
- make to compile, and then make
- install to install your module. By default, the extension is
- compiled and installed for the
- PostgreSQL installation that
- corresponds to the first pg_config program
- found in your PATH. You can use a different installation by
- setting PG_CONFIG to point to its
- pg_config program, either within the makefile
- or on the make command line.
+ Placez ce fichier de construction comme Makefile dans le répertoire
+ qui contient votre extension. Puis vous pouvez exécuter la commande make
+ pour compiler, et ensuite make install pour déployer le module. Par défaut,
+ l'extension est compilée et installée pour l'installation de PostgreSQL
+ qui correspond au premier programme pg_config trouvé dans votre PATH.
+ Vous pouvez utiliser une installation différente en définissant PG_CONFIG pour pointer
+ sur le programme pg_config de votre choix, soit dans le fichier makefile, soit
+ à partir de la ligne de commande de la commande make.
- Changing PG_CONFIG only works when building
- against PostgreSQL 8.3 or later.
- With older releases it does not work to set it to anything except
- pg_config; you must alter your PATH
- to select the installation to build against.
+ Modifier la variable PG_CONFIG ne fonctionne que lorsque l'on
+ compile pour PostgreSQL 8.3 et au delà.
+ Avec des versions plus anciennes, il n'est possible de spécifier que
+ pg_config. Vous devez modifier votre PATH
+ pour choisir l'installation souhaitée.
- The scripts listed in the REGRESS variable are used for
- regression testing of your module, which can be invoked by make
- installcheck after doing make install. For this to
- work you must have a running PostgreSQL server.
- The script files listed in REGRESS must appear in a
- subdirectory named sql/ in your extension's directory.
- These files must have extension .sql, which must not be
- included in the REGRESS list in the makefile. For each
- test there should also be a file containing the expected output in a
- subdirectory named expected/, with the same stem and
- extension .out. make installcheck
- executes each test script with psql, and compares the
- resulting output to the matching expected file. Any differences will be
- written to the file regression.diffs in diff
- -c format. Note that trying to run a test that is missing its
- expected file will be reported as trouble
, so make sure you
- have all expected files.
+ Les scripts listés dans la variable REGRESS sont utilisés pour
+ des tests de regression de votre module, qui peut être invoqué par make
+ installcheck après avoir effectué make install. Pour que
+ cela fonctionne, vous devez lancer le serveur PosgreSQL préalablement.
+ Les fichiers de script listés dans la variable REGRESS doivent
+ apparaître dans le sous-répertoire appelé sql/ du répertoire
+ de votre extension. Ces fichiers doivent avoir l'extension .sql,
+ qui ne doit pas être inclus dans la liste REGRESS du makefile.
+ Pour chaque test, il doit aussi y avoir un fichier qui contient les résultats attendus
+ dans un sous-répertoire nommé expected, avec le même nom mais l'extension
+ .out. La commande make installcheck exécute chaque
+ script de test avec psql, et compare la sortie resultante
+ au fichier de résultat correspondant. Toute différence sera écrite dans le fichier
+ regression.diffs au format diff -c. Notez que
+ l'exécution d'un test qui ne dispose pas des fichiers nécessaires sera rapportée comme
+ une erreur dans le test, donc soyez sûr que tous les fichiers nécessaires soient présents.
- The easiest way to create the expected files is to create empty files,
- then do a test run (which will of course report differences). Inspect
- the actual result files found in the results/
- directory, then copy them to expected/ if they match
- what you expect from the test.
+ Le moyen le plus simple de créer les fichiers nécessaires est de créer des fichiers vides,
+ puis d'effectuer un jeu d'essai (qui bien sûr retournera des anomalies). Etudiez les
+ résultats trouvés dans le répertoire results, et copiez-les dans le répertoire
+ expected/ s'ils correspondent à ce que vous attendiez du test correspondant.