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.