granicus.if.org Git - postgresql/blob - doc/src/sgml/file-fdw.sgml

   1 <!-- doc/src/sgml/file-fdw.sgml -->
   2
   3 <sect1 id="file-fdw" xreflabel="file_fdw">
   4  <title>file_fdw</title>
   5
   6  <indexterm zone="file-fdw">
   7   <primary>file_fdw</primary>
   8  </indexterm>
   9
  10  <para>
  11   The <filename>file_fdw</> module provides the foreign-data wrapper
  12   <function>file_fdw</function>, which can be used to access data
  13   files in the server's file system, or to execute programs on the server
  14   and read their output.  The data file or program output must be in a format
  15   that can be read by <command>COPY FROM</command>;
  16   see <xref linkend="sql-copy"> for details.
  17   Access to data files is currently read-only.
  18  </para>
  19
  20  <para>
  21   A foreign table created using this wrapper can have the following options:
  22  </para>
  23
  24  <variablelist>
  25
  26   <varlistentry>
  27    <term><literal>filename</literal></term>
  28
  29    <listitem>
  30     <para>
  31      Specifies the file to be read.  Must be an absolute path name.
  32      Either <literal>filename</literal> or <literal>program</literal> must be
  33      specified, but not both.
  34     </para>
  35    </listitem>
  36   </varlistentry>
  37
  38   <varlistentry>
  39    <term><literal>program</literal></term>
  40
  41    <listitem>
  42     <para>
  43      Specifies the command to be executed.  The standard output of this
  44      command will be read as though <command>COPY FROM PROGRAM</> were used.
  45      Either <literal>program</literal> or <literal>filename</literal> must be
  46      specified, but not both.
  47     </para>
  48    </listitem>
  49   </varlistentry>
  50
  51   <varlistentry>
  52    <term><literal>format</literal></term>
  53
  54    <listitem>
  55     <para>
  56      Specifies the data format,
  57      the same as <command>COPY</>'s <literal>FORMAT</literal> option.
  58     </para>
  59    </listitem>
  60   </varlistentry>
  61
  62   <varlistentry>
  63    <term><literal>header</literal></term>
  64
  65    <listitem>
  66     <para>
  67      Specifies whether the data has a header line,
  68      the same as <command>COPY</>'s <literal>HEADER</literal> option.
  69     </para>
  70    </listitem>
  71   </varlistentry>
  72
  73   <varlistentry>
  74    <term><literal>delimiter</literal></term>
  75
  76    <listitem>
  77     <para>
  78      Specifies the data delimiter character,
  79      the same as <command>COPY</>'s <literal>DELIMITER</literal> option.
  80     </para>
  81    </listitem>
  82   </varlistentry>
  83
  84   <varlistentry>
  85    <term><literal>quote</literal></term>
  86
  87    <listitem>
  88     <para>
  89      Specifies the data quote character,
  90      the same as <command>COPY</>'s <literal>QUOTE</literal> option.
  91     </para>
  92    </listitem>
  93   </varlistentry>
  94
  95   <varlistentry>
  96    <term><literal>escape</literal></term>
  97
  98    <listitem>
  99     <para>
 100      Specifies the data escape character,
 101      the same as <command>COPY</>'s <literal>ESCAPE</literal> option.
 102     </para>
 103    </listitem>
 104   </varlistentry>
 105
 106   <varlistentry>
 107    <term><literal>null</literal></term>
 108
 109    <listitem>
 110     <para>
 111      Specifies the data null string,
 112      the same as <command>COPY</>'s <literal>NULL</literal> option.
 113     </para>
 114    </listitem>
 115   </varlistentry>
 116
 117   <varlistentry>
 118    <term><literal>encoding</literal></term>
 119
 120    <listitem>
 121     <para>
 122      Specifies the data encoding,
 123      the same as <command>COPY</>'s <literal>ENCODING</literal> option.
 124     </para>
 125    </listitem>
 126   </varlistentry>
 127
 128  </variablelist>
 129
 130  <para>
 131   Note that while <command>COPY</> allows options such as <literal>HEADER</>
 132   to be specified without a corresponding value, the foreign table option
 133   syntax requires a value to be present in all cases.  To activate
 134   <command>COPY</> options typically written without a value, you can pass
 135   the value TRUE, since all such options are Booleans.
 136  </para>
 137
 138  <para>
 139   A column of a foreign table created using this wrapper can have the
 140   following options:
 141  </para>
 142
 143  <variablelist>
 144
 145   <varlistentry>
 146    <term><literal>force_not_null</literal></term>
 147
 148    <listitem>
 149     <para>
 150      This is a Boolean option.  If true, it specifies that values of the
 151      column should not be matched against the null string (that is, the
 152      table-level <literal>null</literal> option).  This has the same effect
 153      as listing the column in <command>COPY</>'s
 154      <literal>FORCE_NOT_NULL</literal> option.
 155     </para>
 156    </listitem>
 157   </varlistentry>
 158
 159   <varlistentry>
 160    <term><literal>force_null</literal></term>
 161
 162    <listitem>
 163     <para>
 164      This is a Boolean option.  If true, it specifies that values of the
 165      column which match the null string are returned as <literal>NULL</>
 166      even if the value is quoted. Without this option, only unquoted
 167      values matching the null string are returned as <literal>NULL</>.
 168      This has the same effect  as listing the column in
 169      <command>COPY</>'s <literal>FORCE_NULL</literal> option.
 170     </para>
 171    </listitem>
 172   </varlistentry>
 173
 174  </variablelist>
 175
 176  <para>
 177   <command>COPY</>'s <literal>OIDS</literal> and
 178   <literal>FORCE_QUOTE</literal> options are currently not supported by
 179   <literal>file_fdw</>.
 180  </para>
 181
 182  <para>
 183   These options can only be specified for a foreign table or its columns, not
 184   in the options of the <literal>file_fdw</> foreign-data wrapper, nor in the
 185   options of a server or user mapping using the wrapper.
 186  </para>
 187
 188  <para>
 189   Changing table-level options requires superuser privileges, for security
 190   reasons: only a superuser should be able to control which file is read
 191   or which program is run.  In principle non-superusers could be allowed to
 192   change the other options, but that's not supported at present.
 193  </para>
 194
 195  <para>
 196   When specifying the <literal>program</> option, keep in mind that the option
 197   string is executed by the shell.  If you need to pass any arguments to the
 198   command that come from an untrusted source, you must be careful to strip or
 199   escape any characters that might have special meaning to the shell.
 200   For security reasons, it is best to use a fixed command string, or at least
 201   avoid passing any user input in it.
 202  </para>
 203
 204  <para>
 205   For a foreign table using <literal>file_fdw</>, <command>EXPLAIN</> shows
 206   the name of the file to be read or program to be run.
 207   For a file, unless <literal>COSTS OFF</> is
 208   specified, the file size (in bytes) is shown as well.
 209  </para>
 210
 211  <example>
 212  <title id="csvlog-fdw">Create a Foreign Table for PostgreSQL CSV Logs</title>
 213
 214   <para>
 215    One of the obvious uses for <literal>file_fdw</> is to make
 216    the PostgreSQL activity log available as a table for querying.  To
 217    do this, first you must be logging to a CSV file, which here we
 218    will call <literal>pglog.csv</>.  First, install <literal>file_fdw</>
 219    as an extension:
 220   </para>
 221
 222 <programlisting>
 223 CREATE EXTENSION file_fdw;
 224 </programlisting>
 225
 226   <para>
 227    Then create a foreign server:
 228
 229 <programlisting>
 230 CREATE SERVER pglog FOREIGN DATA WRAPPER file_fdw;
 231 </programlisting>
 232   </para>
 233
 234   <para>
 235    Now you are ready to create the foreign data table.  Using the
 236    <command>CREATE FOREIGN TABLE</> command, you will need to define
 237    the columns for the table, the CSV file name, and its format:
 238
 239 <programlisting>
 240 CREATE FOREIGN TABLE pglog (
 241   log_time timestamp(3) with time zone,
 242   user_name text,
 243   database_name text,
 244   process_id integer,
 245   connection_from text,
 246   session_id text,
 247   session_line_num bigint,
 248   command_tag text,
 249   session_start_time timestamp with time zone,
 250   virtual_transaction_id text,
 251   transaction_id bigint,
 252   error_severity text,
 253   sql_state_code text,
 254   message text,
 255   detail text,
 256   hint text,
 257   internal_query text,
 258   internal_query_pos integer,
 259   context text,
 260   query text,
 261   query_pos integer,
 262   location text,
 263   application_name text
 264 ) SERVER pglog
 265 OPTIONS ( filename '/home/josh/data/log/pglog.csv', format 'csv' );
 266 </programlisting>
 267   </para>
 268
 269   <para>
 270    That's it &mdash; now you can query your log directly. In production, of
 271    course, you would need to define some way to deal with log rotation.
 272   </para>
 273  </example>
 274
 275 </sect1>