From 7c5d0ae7078456bfeedb2103c45b9a32285c2631 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sun, 20 Feb 2011 14:06:59 -0500
Subject: Add contrib/file_fdw foreign-data wrapper for reading files via COPY.

This is both very useful in its own right, and an important test case
for the core FDW support.

This commit includes a small refactoring of copy.c to expose its option
checking code as a separately callable function.  The original patch
submission duplicated hundreds of lines of that code, which seemed pretty
unmaintainable.

Shigeru Hanada, reviewed by Itagaki Takahiro and Tom Lane
---
 doc/src/sgml/contrib.sgml  |   1 +
 doc/src/sgml/file-fdw.sgml | 127 +++++++++++++++++++++++++++++++++++++++++++++
 doc/src/sgml/filelist.sgml |   1 +
 3 files changed, 129 insertions(+)
 create mode 100644 doc/src/sgml/file-fdw.sgml

(limited to 'doc/src')

diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index 4504ab1749d..adf09ca872d 100644
--- a/doc/src/sgml/contrib.sgml
+++ b/doc/src/sgml/contrib.sgml
@@ -100,6 +100,7 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
  &dict-xsyn;
  &dummy-seclabel;
  &earthdistance;
+ &file-fdw;
  &fuzzystrmatch;
  &hstore;
  &intagg;
diff --git a/doc/src/sgml/file-fdw.sgml b/doc/src/sgml/file-fdw.sgml
new file mode 100644
index 00000000000..e2921667184
--- /dev/null
+++ b/doc/src/sgml/file-fdw.sgml
@@ -0,0 +1,127 @@
+<!-- doc/src/sgml/file-fdw.sgml -->
+
+<sect1 id="file-fdw">
+ <title>file_fdw</title>
+
+ <indexterm zone="file-fdw">
+  <primary>file_fdw</primary>
+ </indexterm>
+
+ <para>
+  The <filename>file_fdw</> module provides the foreign-data wrapper
+  <function>file_fdw</function>, which can be used to access data
+  files in the server's filesystem.  Data files must be in a format
+  that can be read by <command>COPY FROM</command>;
+  see <xref linkend="sql-copy"> for details.
+ </para>
+
+ <para>
+  A foreign table created using this wrapper can have the following options:
+ </para>
+
+ <variablelist>
+
+  <varlistentry>
+   <term><literal>filename</literal></term>
+
+   <listitem>
+    <para>
+     Specifies the file to be read.  Required.  Must be an absolute path name.
+    </para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><literal>format</literal></term>
+
+   <listitem>
+    <para>
+     Specifies the file's format,
+     the same as <command>COPY</>'s <literal>FORMAT</literal> option.
+    </para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><literal>header</literal></term>
+
+   <listitem>
+    <para>
+     Specifies whether the file has a header line,
+     the same as <command>COPY</>'s <literal>HEADER</literal> option.
+    </para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><literal>delimiter</literal></term>
+
+   <listitem>
+    <para>
+     Specifies the file's delimiter character,
+     the same as <command>COPY</>'s <literal>DELIMITER</literal> option.
+    </para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><literal>quote</literal></term>
+
+   <listitem>
+    <para>
+     Specifies the file's quote character,
+     the same as <command>COPY</>'s <literal>QUOTE</literal> option.
+    </para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><literal>escape</literal></term>
+
+   <listitem>
+    <para>
+     Specifies the file's escape character,
+     the same as <command>COPY</>'s <literal>ESCAPE</literal> option.
+    </para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry>
+   <term><literal>null</literal></term>
+
+   <listitem>
+    <para>
+     Specifies the file's null string,
+     the same as <command>COPY</>'s <literal>NULL</literal> option.
+    </para>
+   </listitem>
+  </varlistentry>
+
+ </variablelist>
+
+ <para>
+  <command>COPY</>'s <literal>OIDS</literal>, <literal>FORCE_QUOTE</literal>,
+  and <literal>FORCE_NOT_NULL</literal> options are currently not supported by
+  <literal>file_fdw</>.
+ </para>
+
+ <para>
+  These options can only be specified for a foreign table, not in the
+  options of the <literal>file_fdw</> foreign-data wrapper, nor in the
+  options of a server or user mapping using the wrapper.
+ </para>
+
+ <para>
+  Changing table-level options requires superuser privileges, for security
+  reasons: only a superuser should be able to determine which file is read.
+  In principle non-superusers could be allowed to change the other options,
+  but that's not supported at present.
+ </para>
+
+ <para>
+  For a foreign table using <literal>file_fdw</>, <command>EXPLAIN</> shows
+  the name of the file to be read.  Unless <literal>COSTS OFF</> is
+  specified, the file size (in bytes) is shown as well.
+ </para>
+
+</sect1>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 659bcba7c78..1a6079639f5 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -106,6 +106,7 @@
 <!entity dict-xsyn       SYSTEM "dict-xsyn.sgml">
 <!entity dummy-seclabel  SYSTEM "dummy-seclabel.sgml">
 <!entity earthdistance   SYSTEM "earthdistance.sgml">
+<!entity file-fdw        SYSTEM "file-fdw.sgml">
 <!entity fuzzystrmatch   SYSTEM "fuzzystrmatch.sgml">
 <!entity hstore          SYSTEM "hstore.sgml">
 <!entity intagg          SYSTEM "intagg.sgml">
-- 
cgit v1.2.3