Documentation PostgreSQL 15.15 » Annexes » Modules supplémentaires fournis » file_fdw

Précédent | Niveau supérieur | Suivant
F.15. earthdistance | Sommaire | F.17. fuzzystrmatch

## F.16. file_fdw

Le module `file_fdw` fournit le wrapper de données distantes `file_fdw`, qui peut être utilisé pour accéder à des fichiers de données situées sur le système de fichiers du serveur, ou pour exécuter des programmes sur le serveur et lire leur sortie. Les fichiers de données ou program output doivent être dans un format qui puisse être lu par `COPY FROM`; voyez COPY pour les détails. L'accès à ce type de fichier se fait uniquement en lecture seule.

Une table distante créée en utilisant ce wrapper peut avoir les options suivantes:

`filename`

  Spécifie le fichier devant être lu. Les chemins relatifs sont relatifs au répertoire principal des données. `filename` ou `program` doit être spécifié, mais pas les deux en même temps.

`program`

  Spécifie la commande à exécuter. La sortie standard de cette commande sera lue comme si `COPY FROM PROGRAM` était utilisé. Il est nécessaire d'indiquer soit `program` soit `filename` mais pas les deux.

`force_null`

  C'est une option booléenne. Si elle vaut vrai, cela signifie que les valeurs de la colonne qui correspondent à la chaîne NULL sont retournées comme `NULL` même si la valeur est entourée de guillemets. Sans cette option, seules les valeurs non entourées de guillemets qui correspondent à la chaîne NULL seront retournées comme `NULL`. Cela a le même effet que de spécifier les colonnes dans l'option `FORCE_NULL` de la commande `COPY`.

`format`

  Spécifie le format des données, comme dans l'option `FORMAT` de la commande `COPY`.

`header`

  Spécifie si les données ont une ligne d'entête, comme l'option `HEADER` de la commande `COPY`.

`delimiter`

  Spécifie le caractère délimiteur des données, comme l'option `DELIMITER` de la commande `COPY`.

`quote`

  Spécifie le caractère guillemet, comme l'option `QUOTE` de la commande `COPY`.

`escape`

  Spécifie le caractère d'échappement des données, comme l'option `ESCAPE` de la commande `COPY`.

`null`

  Spécifie la chaîne null des données, comme l'option `NULL` de la commande `COPY`.

`encoding`

  Spécifie l'encodage des données, comme l'option `ENCODING` de la commande `COPY`.

Notez que, bien que `COPY` autorise la spécification d'options comme `HEADER` sans valeur correspondante, la syntaxe des options de la table externe requiert la présence d'une valeur dans tous les cas. Pour activer les options de `COPY` sans valeur, vous pouvez donner la valeur TRUE à la place, since all such options are Booleans.

Une colonne d'une table distante créée en utilisant ce wrapper peut avoir les options suivantes :

`force_not_null`

  C'est une option booléenne. Si elle vaut true, cela signifie que les valeurs de la colonne ne doivent pas être comparées à celle de la chaîne NULL (autrement dit, l'option `null` au niveau de la table). Ceci a le même effet que de lister la colonne dans l'option `FORCE_NOT_NULL` de `COPY`.

L'option `FORCE_QUOTE` de `COPY` n'est pas supportée par `file_fdw` pour le moment.

Ces options ne peuvent être spécifiées que pour une table distante ou ses colonnes, pas comme options du wrapper de données distantes `file_fdw`, pas plus que comme des options d'un serveur ou d'un mapping d'utilisateur utilisant le wrapper.

Changer les options au niveau des tables nécessite l'attribut SUPERUSER ou avoir les droits du rôle `pg_read_server_files` (pour utiliser un fichier) ou du rôle `pg_execute_server_program` (pour utiliser un programme), pour des raisons de sécurité : seuls certains utilisateurs devraient pouvoir contrôler quel fichier est lu ou quel programme est exécuté. En principe, des utilisateurs standards devraient pouvoir modifier les autres options, mais ceci n'est pas supporté pour le moment.

Lorsque l'option `program` est spécifiée, gardez à l'esprit que la chaîne de texte est exécutée par le shell. Si vous devez passer des arguments à la commande qui viennent d'une source non approuvée, vous devez prendre soin de supprimer ou échapper des caractères qui pourraient avoir une signification spéciale pour le shell. Pour raisons de sécurité, il est préférable d'utiliser une chaîne de commande fixe comme argument, ou au moins d'éviter d'y fournir des données saisies par des utilisateurs.

Pour une table utilisant `file_fdw`, `EXPLAIN` montre le nom du fichier devant être lu ou le programme à exécuter. Pour un fichier, à moins que `COSTS OFF` soit spécifié, la taille du fichier (en octets) est affichée aussi.

Exemple F.1. Créer une table distante pour les journaux applicatifs PostgreSQL au format CSV

Une des utilisations évidentes de `file_fdw` est de rendre les journaux applicatifs de PostgreSQL disponibles sous la forme d'une table. Pour faire cela, vous devez tout d'abord enregistrer les traces au format CSV. Nous appelerons le fichier de traces `pglog.csv`. Tout d'abord, installez l'extension `file_fdw` :

    CREATE EXTENSION file_fdw;

Ensuite créez un serveur de données distantes :

    CREATE SERVER pglog FOREIGN DATA WRAPPER file_fdw;

Maintenant, vous pouvez créer la table de données distantes. En utilisant la commande `CREATE FOREIGN TABLE`, vous devez définir les colonnes de la table, le nom du fichier CSV, et son format :

    CREATE FOREIGN TABLE pglog (
      log_time timestamp(3) with time zone,
      user_name text,
      database_name text,
      process_id integer,
      connection_from text,
      session_id text,
      session_line_num bigint,
      command_tag text,
      session_start_time timestamp with time zone,
      virtual_transaction_id text,
      transaction_id bigint,
      error_severity text,
      sql_state_code text,
      message text,
      detail text,
      hint text,
      internal_query text,
      internal_query_pos integer,
      context text,
      query text,
      query_pos integer,
      location text,
      application_name text,
      backend_type text,
      leader_pid integer,
      query_id bigint
    ) SERVER pglog
    OPTIONS ( filename 'log/pglog.csv', format 'csv' );

C'est tout -- maintenant, vous pouvez lire le fichier en exécutant une requête sur cette table. Bien sûr, en production, vous aurez besoin de définir un moyen pour tenir compte de la rotation du fichier de traces.