PostgreSQLLa base de données la plus sophistiquée au monde.
Documentation PostgreSQL 17.0 » Annexes » Modules et extensions supplémentaires fournis » file_fdw -- accéder aux fichiers de données sur le système de fichiers du serveur

F.15. file_fdw -- accéder aux fichiers de données sur le système de fichiers du serveur #

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 programme sur le serveur et lire leur sortie. Les fichiers de données or 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 colonne 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 cque 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 passez 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.


Exemple F.2. Créer une table externe avec une option sur une colonne

Pour configurer l'option force_null pour une colonne, utilisez le mot-clé OPTIONS.

CREATE FOREIGN TABLE films (
 code char(5) NOT NULL,
 title text NOT NULL,
 rating text OPTIONS (force_null 'true')
) SERVER film_server
OPTIONS ( filename 'films/db.csv', format 'csv' );