diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/catalogs.sgml | 64 | ||||
| -rw-r--r-- | doc/src/sgml/information_schema.sgml | 131 | ||||
| -rw-r--r-- | doc/src/sgml/ref/allfiles.sgml | 3 | ||||
| -rw-r--r-- | doc/src/sgml/ref/alter_default_privileges.sgml | 4 | ||||
| -rw-r--r-- | doc/src/sgml/ref/alter_foreign_table.sgml | 315 | ||||
| -rw-r--r-- | doc/src/sgml/ref/comment.sgml | 8 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_foreign_table.sgml | 188 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_sequence.sgml | 2 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_table.sgml | 4 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_view.sgml | 2 | ||||
| -rw-r--r-- | doc/src/sgml/ref/drop_foreign_table.sgml | 112 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pg_dump.sgml | 6 | ||||
| -rw-r--r-- | doc/src/sgml/ref/psql-ref.sgml | 35 | ||||
| -rw-r--r-- | doc/src/sgml/ref/security_label.sgml | 5 | ||||
| -rw-r--r-- | doc/src/sgml/reference.sgml | 3 |
15 files changed, 856 insertions, 26 deletions
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 0eeb499207e..67ba3400da2 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -149,6 +149,11 @@ </row> <row> + <entry><link linkend="catalog-pg-foreign-table"><structname>pg_foreign_table</structname></link></entry> + <entry>additional foreign table information</entry> + </row> + + <row> <entry><link linkend="catalog-pg-index"><structname>pg_index</structname></link></entry> <entry>additional index information</entry> </row> @@ -1656,8 +1661,8 @@ <entry> <literal>r</> = ordinary table, <literal>i</> = index, <literal>S</> = sequence, <literal>v</> = view, <literal>c</> = - composite type, <literal>t</> = TOAST - table + composite type, <literal>t</> = TOAST table, + <literal>f</> = foreign table </entry> </row> @@ -2932,6 +2937,61 @@ </sect1> + <sect1 id="catalog-pg-foreign-table"> + <title><structname>pg_foreign_table</structname></title> + + <indexterm zone="catalog-pg-foreign-table"> + <primary>pg_foreign_table</primary> + </indexterm> + + <para> + The catalog <structname>pg_foreign_table</structname> contains part + of the information about foreign tables. + The rest is mostly in <structname>pg_class</structname>. + </para> + + <table> + <title><structname>pg_foreign_table</> Columns</title> + + <tgroup cols="4"> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>References</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><structfield>ftrelid</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry> + <entry>The OID of the <structname>pg_class</> entry for this foreign table</entry> + </row> + + <row> + <entry><structfield>ftserver</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-foreign-server"><structname>pg_foreign_server</structname></link>.oid</literal></entry> + <entry>The OID of the foreign server for this foreign table</entry> + </row> + + <row> + <entry><structfield>ftoptions</structfield></entry> + <entry><type>text[]</type></entry> + <entry></entry> + <entry> + Foreign table options, as <quote>keyword=value</> strings. + </entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + + <sect1 id="catalog-pg-index"> <title><structname>pg_index</structname></title> diff --git a/doc/src/sgml/information_schema.sgml b/doc/src/sgml/information_schema.sgml index 9d30949aa77..962b85b8e4b 100644 --- a/doc/src/sgml/information_schema.sgml +++ b/doc/src/sgml/information_schema.sgml @@ -2384,6 +2384,132 @@ ORDER BY c.ordinal_position; </table> </sect1> + <sect1 id="infoschema-foreign-table-options"> + <title><literal>foreign_table_options</literal></title> + + <para> + The view <literal>foreign_table_options</literal> contains all the + options defined for foreign tables in the current database. Only + those foreign tables are shown that the current user has access to + (by way of being the owner or having some privilege). + </para> + + <table> + <title><literal>foreign_table_options</literal> Columns</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Name</entry> + <entry>Data Type</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>foreign_table_catalog</literal></entry> + <entry><type>sql_identifier</type></entry> + <entry>Name of the database that contains the foreign table (always the current database)</entry> + </row> + + <row> + <entry><literal>foreign_table_schema</literal></entry> + <entry><type>sql_identifier</type></entry> + <entry>Name of the schema that contains the foreign table</entry> + </row> + + <row> + <entry><literal>foreign_table_name</literal></entry> + <entry><type>sql_identifier</type></entry> + <entry>Name of the foreign table</entry> + </row> + + <row> + <entry><literal>foreign_server_catalog</literal></entry> + <entry><type>sql_identifier</type></entry> + <entry>Name of the database that the foreign server is defined in (always the current database)</entry> + </row> + + <row> + <entry><literal>foreign_server_name</literal></entry> + <entry><type>sql_identifier</type></entry> + <entry>Name of the foreign server</entry> + </row> + + <row> + <entry><literal>option_name</literal></entry> + <entry><type>sql_identifier</type></entry> + <entry>Name of an option</entry> + </row> + + <row> + <entry><literal>option_value</literal></entry> + <entry><type>character_data</type></entry> + <entry>Value of the option</entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + + <sect1 id="infoschema-foreign-tables"> + <title><literal>foreign_tables</literal></title> + + <para> + The view <literal>foreign_tables</literal> contains all foreign + tables defined in the current database. Only those foreign + tables are shown that the current user has access to (by way of + being the owner or having some privilege). + </para> + + <table> + <title><literal>foreign_tables</literal> Columns</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Name</entry> + <entry>Data Type</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>foreign_table_catalog</literal></entry> + <entry><type>sql_identifier</type></entry> + <entry>Name of the database that the foreign table is defined in (always the current database)</entry> + </row> + + <row> + <entry><literal>foreign_table_schema</literal></entry> + <entry><type>sql_identifier</type></entry> + <entry>Name of the schema that contains the foreign table</entry> + </row> + + <row> + <entry><literal>foreign_table_name</literal></entry> + <entry><type>sql_identifier</type></entry> + <entry>Name of the foreign table</entry> + </row> + + <row> + <entry><literal>foreign_server_catalog</literal></entry> + <entry><type>sql_identifier</type></entry> + <entry>Name of the database that the foreign server is defined in (always the current database)</entry> + </row> + + <row> + <entry><literal>foreign_server_name</literal></entry> + <entry><type>sql_identifier</type></entry> + <entry>Name of the foreign server</entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + <sect1 id="infoschema-key-column-usage"> <title><literal>key_column_usage</literal></title> @@ -4730,8 +4856,9 @@ ORDER BY c.ordinal_position; <entry> Type of the table: <literal>BASE TABLE</literal> for a persistent base table (the normal table type), - <literal>VIEW</literal> for a view, or <literal>LOCAL - TEMPORARY</literal> for a temporary table + <literal>VIEW</literal> for a view, <literal>FOREIGN TABLE</literal> + for a foreign table, or + <literal>LOCAL TEMPORARY</literal> for a temporary table </entry> </row> diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index a352a431419..f40fa9dd8b2 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -12,6 +12,7 @@ Complete list of usable sgml source files in this directory. <!entity alterDefaultPrivileges system "alter_default_privileges.sgml"> <!entity alterDomain system "alter_domain.sgml"> <!entity alterForeignDataWrapper system "alter_foreign_data_wrapper.sgml"> +<!entity alterForeignTable system "alter_foreign_table.sgml"> <!entity alterFunction system "alter_function.sgml"> <!entity alterGroup system "alter_group.sgml"> <!entity alterIndex system "alter_index.sgml"> @@ -50,6 +51,7 @@ Complete list of usable sgml source files in this directory. <!entity createDatabase system "create_database.sgml"> <!entity createDomain system "create_domain.sgml"> <!entity createForeignDataWrapper system "create_foreign_data_wrapper.sgml"> +<!entity createForeignTable system "create_foreign_table.sgml"> <!entity createFunction system "create_function.sgml"> <!entity createGroup system "create_group.sgml"> <!entity createIndex system "create_index.sgml"> @@ -85,6 +87,7 @@ Complete list of usable sgml source files in this directory. <!entity dropDatabase system "drop_database.sgml"> <!entity dropDomain system "drop_domain.sgml"> <!entity dropForeignDataWrapper system "drop_foreign_data_wrapper.sgml"> +<!entity dropForeignTable system "drop_foreign_table.sgml"> <!entity dropFunction system "drop_function.sgml"> <!entity dropGroup system "drop_group.sgml"> <!entity dropIndex system "drop_index.sgml"> diff --git a/doc/src/sgml/ref/alter_default_privileges.sgml b/doc/src/sgml/ref/alter_default_privileges.sgml index c27466fbef9..cc4f3636a25 100644 --- a/doc/src/sgml/ref/alter_default_privileges.sgml +++ b/doc/src/sgml/ref/alter_default_privileges.sgml @@ -71,8 +71,8 @@ REVOKE [ GRANT OPTION FOR ] <command>ALTER DEFAULT PRIVILEGES</> allows you to set the privileges that will be applied to objects created in the future. (It does not affect privileges assigned to already-existing objects.) Currently, - only the privileges for tables (including views), sequences, and - functions can be altered. + only the privileges for tables (including views and foreign tables), + sequences, and functions can be altered. </para> <para> diff --git a/doc/src/sgml/ref/alter_foreign_table.sgml b/doc/src/sgml/ref/alter_foreign_table.sgml new file mode 100644 index 00000000000..9d14b195809 --- /dev/null +++ b/doc/src/sgml/ref/alter_foreign_table.sgml @@ -0,0 +1,315 @@ +<!-- +doc/src/sgml/rel/alter_foreign_table.sgml +PostgreSQL documentation +--> + +<refentry id="SQL-ALTERFOREIGNTABLE"> + <refmeta> + <refentrytitle>ALTER FOREIGN TABLE</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>ALTER FOREIGN TABLE</refname> + <refpurpose>change the definition of a foreign table</refpurpose> + </refnamediv> + + <indexterm zone="sql-alterforeigntable"> + <primary>ALTER FOREIGN TABLE</primary> + </indexterm> + + <refsynopsisdiv> +<synopsis> +ALTER FOREIGN TABLE <replaceable class="PARAMETER">name</replaceable> + <replaceable class="PARAMETER">action</replaceable> [, ... ] +ALTER FOREIGN TABLE <replaceable class="PARAMETER">name</replaceable> + RENAME [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> TO <replaceable class="PARAMETER">new_column</replaceable> +ALTER FOREIGN TABLE <replaceable class="PARAMETER">name</replaceable> + RENAME TO <replaceable class="PARAMETER">new_name</replaceable> +ALTER FOREIGN TABLE <replaceable class="PARAMETER">name</replaceable> + SET SCHEMA <replaceable class="PARAMETER">new_schema</replaceable> + +<phrase>where <replaceable class="PARAMETER">action</replaceable> is one of:</phrase> + + ADD [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> <replaceable class="PARAMETER">type</replaceable> + DROP [ COLUMN ] [ IF EXISTS ] <replaceable class="PARAMETER">column</replaceable> [ RESTRICT | CASCADE ] + ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> [ SET DATA ] TYPE <replaceable class="PARAMETER">type</replaceable> + ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> { SET | DROP } NOT NULL + OWNER TO <replaceable class="PARAMETER">new_owner</replaceable> + OPTIONS ( [ ADD | SET | DROP ] <replaceable class="PARAMETER">option</replaceable> ['<replaceable class="PARAMETER">value</replaceable>'] [, ... ]) +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>ALTER FOREIGN TABLE</command> changes the definition of an + existing foreign table. There are several subforms: + + <variablelist> + <varlistentry> + <term><literal>ADD COLUMN</literal></term> + <listitem> + <para> + This form adds a new column to the foreign table, using the same syntax as + <xref linkend="SQL-CREATEFOREIGNTABLE">. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>DROP COLUMN [ IF EXISTS ]</literal></term> + <listitem> + <para> + This form drops a column from a foreign table. + You will need to say <literal>CASCADE</> if + anything outside the table depends on the column; for example, + views. + If <literal>IF EXISTS</literal> is specified and the column + does not exist, no error is thrown. In this case a notice + is issued instead. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>SET DATA TYPE</literal></term> + <listitem> + <para> + This form changes the type of a column of a foreign table. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>SET</literal>/<literal>DROP NOT NULL</literal></term> + <listitem> + <para> + Mark a column as allowing, or not allowing, null values. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>OWNER</literal></term> + <listitem> + <para> + This form changes the owner of the foreign table to the + specified user. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RENAME</literal></term> + <listitem> + <para> + The <literal>RENAME</literal> forms change the name of a foreign table + or the name of an individual column in a foreign table. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>SET SCHEMA</literal></term> + <listitem> + <para> + This form moves the foreign table into another schema. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>OPTIONS ( [ ADD | SET | DROP ] <replaceable class="PARAMETER">option</replaceable> ['<replaceable class="PARAMETER">value</replaceable>'] [, ... ] )</literal></term> + <listitem> + <para> + Change options for the foreign table or the column of the foreign table. + <literal>ADD</>, <literal>SET</>, and <literal>DROP</> + specify the action to be performed. <literal>ADD</> is assumed + if no operation is explicitly specified. Option names must be + unique; names and values are also validated using the foreign + data wrapper library. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + + <para> + All the actions except <literal>RENAME</literal> and <literal>SET SCHEMA</> + can be combined into + a list of multiple alterations to apply in parallel. For example, it + is possible to add several columns and/or alter the type of several + columns in a single command. + </para> + + <para> + You must own the table to use <command>ALTER FOREIGN TABLE</>. + To change the schema of a foreign table, you must also have + <literal>CREATE</literal> privilege on the new schema. + To add the table as a new child of a parent table, you must own the + parent table as well. + To alter the owner, you must also be a direct or indirect member of the new + owning role, and that role must have <literal>CREATE</literal> privilege on + the table's schema. (These restrictions enforce that altering the owner + doesn't do anything you couldn't do by dropping and recreating the table. + However, a superuser can alter ownership of any table anyway.) + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + + <varlistentry> + <term><replaceable class="PARAMETER">name</replaceable></term> + <listitem> + <para> + The name (possibly schema-qualified) of an existing foreign table to + alter. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">column</replaceable></term> + <listitem> + <para> + Name of a new or existing column. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">new_column</replaceable></term> + <listitem> + <para> + New name for an existing column. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">new_name</replaceable></term> + <listitem> + <para> + New name for the table. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">type</replaceable></term> + <listitem> + <para> + Data type of the new column, or new data type for an existing + column. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the dropped column + (for example, views referencing the column). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the column if there are any dependent + objects. This is the default behavior. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">new_owner</replaceable></term> + <listitem> + <para> + The user name of the new owner of the table. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">new_schema</replaceable></term> + <listitem> + <para> + The name of the schema to which the table will be moved. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + The key word <literal>COLUMN</literal> is noise and can be omitted. + </para> + + <para> + Consistency with the foreign server is not checked when a column is + added or removed with <literal>ADD COLUMN</literal> or + <literal>DROP COLUMN</literal>, a system <literal>oid</> column is added + or removed, a <literal>CHECK</> or <literal>NOT NULL</> constraint is + added, or column type is changed with <literal>ALTER TYPE</>. It is the + user's responsibility to ensure that the table definition matches the + remote side. + </para> + + <para> + Refer to <xref linkend="sql-createforeigntable"> for a further description of valid + parameters. + </para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + To mark a column as not-null: +<programlisting> +ALTER FOREIGN TABLE distributors ALTER COLUMN street SET NOT NULL; +</programlisting> + </para> + + <para> + To change options of a foreign table: +<programlisting> +ALTER FOREIGN TABLE myschema.distributors OPTIONS (ADD opt1 'value', SET opt2, 'value2', DROP opt3 'value3'); +</programlisting> + </para> + + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + The forms <literal>ADD</literal>, <literal>DROP</>, + and <literal>SET DATA TYPE</literal> + conform with the SQL standard. The other forms are + <productname>PostgreSQL</productname> extensions of the SQL standard. + Also, the ability to specify more than one manipulation in a single + <command>ALTER FOREIGN TABLE</> command is an extension. + </para> + + <para> + <command>ALTER FOREIGN TABLE DROP COLUMN</> can be used to drop the only + column of a foreign table, leaving a zero-column table. This is an + extension of SQL, which disallows zero-column foreign tables. + </para> + </refsect1> +</refentry> diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml index d81fd726414..f1a1605df3c 100644 --- a/doc/src/sgml/ref/comment.sgml +++ b/doc/src/sgml/ref/comment.sgml @@ -31,6 +31,7 @@ COMMENT ON CONVERSION <replaceable class="PARAMETER">object_name</replaceable> | DATABASE <replaceable class="PARAMETER">object_name</replaceable> | DOMAIN <replaceable class="PARAMETER">object_name</replaceable> | + FOREIGN TABLE <replaceable class="PARAMETER">object_name</replaceable> | FUNCTION <replaceable class="PARAMETER">function_name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) | INDEX <replaceable class="PARAMETER">object_name</replaceable> | LARGE OBJECT <replaceable class="PARAMETER">large_object_oid</replaceable> | @@ -96,9 +97,9 @@ COMMENT ON <listitem> <para> The name of the object to be commented. Names of tables, - aggregates, domains, functions, indexes, operators, operator classes, - operator families, sequences, text search objects, types, and views can - be schema-qualified. + aggregates, domains, foreign tables, functions, indexes, operators, + operator classes, operator families, sequences, text search objects, + types, and views can be schema-qualified. </para> </listitem> </varlistentry> @@ -247,6 +248,7 @@ COMMENT ON COLUMN my_table.my_column IS 'Employee ID number'; COMMENT ON CONVERSION my_conv IS 'Conversion to UTF8'; COMMENT ON DATABASE my_database IS 'Development Database'; COMMENT ON DOMAIN my_domain IS 'Email Address Domain'; +COMMENT ON FOREIGN TABLE my_foreign_table IS 'Employee Information in other database'; COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral'; COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID'; COMMENT ON LANGUAGE plpython IS 'Python support for stored procedures'; diff --git a/doc/src/sgml/ref/create_foreign_table.sgml b/doc/src/sgml/ref/create_foreign_table.sgml new file mode 100644 index 00000000000..ac2e1393e38 --- /dev/null +++ b/doc/src/sgml/ref/create_foreign_table.sgml @@ -0,0 +1,188 @@ +<!-- doc/src/sgml/ref/create_foreign_table.sgml --> + +<refentry id="SQL-CREATEFOREIGNTABLE"> + <refmeta> + <refentrytitle>CREATE FOREIGN TABLE</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>CREATE FOREIGN TABLE</refname> + <refpurpose>define a new foreign table</refpurpose> + </refnamediv> + + <indexterm zone="sql-createforeigntable"> + <primary>CREATE FOREIGN TABLE</primary> + </indexterm> + + <refsynopsisdiv> +<synopsis> +CREATE FOREIGN TABLE [ IF NOT EXISTS ] <replaceable class="PARAMETER">table_name</replaceable> ( [ + { <replaceable class="PARAMETER">column_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [ NULL | NOT NULL ] } + [, ... ] +] ) + SERVER <replaceable class="parameter">server_name</replaceable> +[ OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] ) ] + +</synopsis> + </refsynopsisdiv> + + <refsect1 id="SQL-CREATEFOREIGNTABLE-description"> + <title>Description</title> + + <para> + <command>CREATE FOREIGN TABLE</command> will create a new foreign table + in the current database. The table will be owned by the user issuing the + command. + </para> + + <para> + If a schema name is given (for example, <literal>CREATE FOREIGN TABLE + myschema.mytable ...</>) then the table is created in the specified + schema. Otherwise it is created in the current schema. + The name of the foreign table must be + distinct from the name of any other foreign table, table, sequence, index, + or view in the same schema. + </para> + + <para> + <command>CREATE FOREIGN TABLE</command> also automatically creates a data + type that represents the composite type corresponding to one row of + the foreign table. Therefore, foreign tables cannot have the same + name as any existing data type in the same schema. + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + + <varlistentry> + <term><literal>IF NOT EXISTS</></term> + <listitem> + <para> + Do not throw an error if a relation with the same name already exists. + A notice is issued in this case. Note that there is no guarantee that + the existing relation is anything like the one that would have been + created. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">table_name</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of the table to be created. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">column_name</replaceable></term> + <listitem> + <para> + The name of a column to be created in the new table. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">data_type</replaceable></term> + <listitem> + <para> + The data type of the column. This can include array + specifiers. For more information on the data types supported by + <productname>PostgreSQL</productname>, refer to <xref + linkend="datatype">. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>NOT NULL</></term> + <listitem> + <para> + The column is not allowed to contain null values. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>NULL</></term> + <listitem> + <para> + The column is allowed to contain null values. This is the default. + </para> + + <para> + This clause is only provided for compatibility with + non-standard SQL databases. Its use is discouraged in new + applications. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>OPTIONS ( <replaceable class="PARAMETER">option</replaceable> = '<replaceable class="PARAMETER">value</replaceable>' [, ...] )</literal></term> + <listitem> + <para> + Options to be associated with the new foreign table. + The allowed option names and values are specific to each foreign + data wrapper and are validated using the foreign-data wrapper + library. Option names must be unique. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + + <refsect1 id="SQL-CREATEFOREIGNTABLE-examples"> + <title>Examples</title> + + <para> + Create foreign table <structname>films</> with <structname>film_server</>: + +<programlisting> +CREATE FOREIGN TABLE films ( + code char(5) NOT NULL, + title varchar(40) NOT NULL, + did integer NOT NULL, + date_prod date, + kind varchar(10), + len interval hour to minute +) +SERVER film_server; +</programlisting> + </para> + + </refsect1> + + <refsect1 id="SQL-CREATEFOREIGNTABLE-compatibility"> + <title id="SQL-CREATEFOREIGNTABLE-compatibility-title">Compatibility</title> + + <para> + The <command>CREATE FOREIGN TABLE</command> command largely conforms to the + <acronym>SQL</acronym> standard; however, much as with + <link linkend="sql-createtable"><command>CREATE TABLE</></link>, + <literal>NULL</> constraints and zero-column foreign tables are permitted. + </para> + + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-alterforeigntable"></member> + <member><xref linkend="sql-dropforeigntable"></member> + <member><xref linkend="sql-createtable"></member> + <member><xref linkend="sql-createserver"></member> + </simplelist> + </refsect1> +</refentry> diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml index 7f94d24865d..f36b616db0e 100644 --- a/doc/src/sgml/ref/create_sequence.sgml +++ b/doc/src/sgml/ref/create_sequence.sgml @@ -45,7 +45,7 @@ CREATE [ TEMPORARY | TEMP ] SEQUENCE <replaceable class="parameter">name</replac Temporary sequences exist in a special schema, so a schema name cannot be given when creating a temporary sequence. The sequence name must be distinct from the name of any other sequence, - table, index, or view in the same schema. + table, index, view, or foreign table in the same schema. </para> <para> diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index efb4b1aca18..e2967bf0ca0 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -97,8 +97,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI schema. Otherwise it is created in the current schema. Temporary tables exist in a special schema, so a schema name cannot be given when creating a temporary table. The name of the table must be - distinct from the name of any other table, sequence, index, or view - in the same schema. + distinct from the name of any other table, sequence, index, view, + or foreign table in the same schema. </para> <para> diff --git a/doc/src/sgml/ref/create_view.sgml b/doc/src/sgml/ref/create_view.sgml index 6676383ab07..dd155078111 100644 --- a/doc/src/sgml/ref/create_view.sgml +++ b/doc/src/sgml/ref/create_view.sgml @@ -50,7 +50,7 @@ CREATE [ OR REPLACE ] [ TEMP | TEMPORARY ] VIEW <replaceable class="PARAMETER">n schema. Otherwise it is created in the current schema. Temporary views exist in a special schema, so a schema name cannot be given when creating a temporary view. The name of the view must be - distinct from the name of any other view, table, sequence, or index + distinct from the name of any other view, table, sequence, index or foreign table in the same schema. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_foreign_table.sgml b/doc/src/sgml/ref/drop_foreign_table.sgml new file mode 100644 index 00000000000..71f26465bb6 --- /dev/null +++ b/doc/src/sgml/ref/drop_foreign_table.sgml @@ -0,0 +1,112 @@ +<!-- doc/src/sggml/ref/drop_foreign_table.sgml --> + +<refentry id="SQL-DROPFOREIGNTABLE"> + <refmeta> + <refentrytitle>DROP FOREIGN TABLE</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>DROP FOREIGN TABLE</refname> + <refpurpose>remove a foreign table</refpurpose> + </refnamediv> + + <indexterm zone="sql-dropforeigntable"> + <primary>DROP FOREIGN TABLE</primary> + </indexterm> + + <refsynopsisdiv> +<synopsis> +DROP FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [, ...] [ CASCADE | RESTRICT ] +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>DROP FOREIGN TABLE</command> removes a foreign table. + Only the owner of a foreign table can remove it. + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><literal>IF EXISTS</literal></term> + <listitem> + <para> + Do not throw an error if the foreign table does not exist. + A notice is issued in this case. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">name</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of the foreign table to drop. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the foreign table (such as + views). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the foreign table if any objects depend on it. This is + the default. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + To destroy two foreign tables, <literal>films</literal> and + <literal>distributors</literal>: + +<programlisting> +DROP FOREIGN TABLE films, distributors; +</programlisting> + </para> + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + This command conforms to the ISO/IEC 9075-9 (SQL/MED), except that the + standard only allows one foreign table to be dropped per command, and apart + from the <literal>IF EXISTS</> option, which is a <productname>PostgreSQL</> + extension. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-alterforeigntable"></member> + <member><xref linkend="sql-createforeigntable"></member> + </simplelist> + </refsect1> + +</refentry> diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index b291a257ea7..de4968c5a03 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -408,9 +408,9 @@ PostgreSQL documentation <term><option>--table=<replaceable class="parameter">table</replaceable></option></term> <listitem> <para> - Dump only tables (or views or sequences) matching <replaceable - class="parameter">table</replaceable>. Multiple tables can be - selected by writing multiple <option>-t</> switches. Also, the + Dump only tables (or views or sequences or foreign tables) matching + <replaceable class="parameter">table</replaceable>. Multiple tables + can be selected by writing multiple <option>-t</> switches. Also, the <replaceable class="parameter">table</replaceable> parameter is interpreted as a pattern according to the same rules used by <application>psql</>'s <literal>\d</> commands (see <xref diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index d44fc56b37e..0c658d1f5b3 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -867,12 +867,14 @@ testdb=> <listitem> <para> - For each relation (table, view, index, or sequence) matching the + For each relation (table, view, index, sequence or foreign table) + matching the <replaceable class="parameter">pattern</replaceable>, show all columns, their types, the tablespace (if not the default) and any special attributes such as <literal>NOT NULL</literal> or defaults. Associated indexes, constraints, rules, and triggers are - also shown. + also shown. For foreign tables, the associated foreign + server is shown as well. (<quote>Matching the pattern</> is defined in <xref linkend="APP-PSQL-patterns" endterm="APP-PSQL-patterns-title"> below.) @@ -882,7 +884,8 @@ testdb=> The command form <literal>\d+</literal> is identical, except that more information is displayed: any comments associated with the columns of the table are shown, as is the presence of OIDs in the - table, and the view definition if the relation is a view. + table, the view definition if the relation is a view, and the generic + options if the relation is a foreign table. </para> <para> @@ -895,9 +898,9 @@ testdb=> <para> If <command>\d</command> is used without a <replaceable class="parameter">pattern</replaceable> argument, it is - equivalent to <command>\dtvs</command> which will show a list of - all visible tables, views, and sequences. This is purely a convenience - measure. + equivalent to <command>\dtvsE</command> which will show a list of + all visible tables, views, sequences and foreign tables. + This is purely a convenience measure. </para> </note> </listitem> @@ -1035,6 +1038,20 @@ testdb=> <varlistentry> + <term><literal>\det[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term> + <listitem> + <para> + Lists foreign tables (mnemonic: <quote>external tables</quote>). + If <replaceable class="parameter">pattern</replaceable> is + specified, only entries whose table name or schema name matches + the pattern are listed. If the form <literal>\det+</literal> + is used, generic options are also displayed. + </para> + </listitem> + </varlistentry> + + + <varlistentry> <term><literal>\des[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term> <listitem> <para> @@ -1197,13 +1214,15 @@ testdb=> <term><literal>\ds[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term> <term><literal>\dt[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term> <term><literal>\dv[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term> + <term><literal>\dE[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term> <listitem> <para> In this group of commands, the letters <literal>i</literal>, <literal>s</literal>, - <literal>t</literal>, and <literal>v</literal> - stand for index, sequence, table, and view, respectively. + <literal>t</literal>, <literal>v</literal>, and <literal>E</literal> + stand for index, sequence, table, view, and foreign table, + respectively. You can specify any or all of these letters, in any order, to obtain a listing of objects of these types. For example, <literal>\dit</> lists indexes diff --git a/doc/src/sgml/ref/security_label.sgml b/doc/src/sgml/ref/security_label.sgml index ca9d63ee772..74169d04e3e 100644 --- a/doc/src/sgml/ref/security_label.sgml +++ b/doc/src/sgml/ref/security_label.sgml @@ -27,6 +27,7 @@ SECURITY LABEL [ FOR <replaceable class="PARAMETER">provider</replaceable> ] ON COLUMN <replaceable class="PARAMETER">table_name</replaceable>.<replaceable class="PARAMETER">column_name</replaceable> | AGGREGATE <replaceable class="PARAMETER">agg_name</replaceable> (<replaceable class="PARAMETER">agg_type</replaceable> [, ...] ) | DOMAIN <replaceable class="PARAMETER">object_name</replaceable> | + FOREIGN TABLE <replaceable class="PARAMETER">object_name</replaceable> FUNCTION <replaceable class="PARAMETER">function_name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) | LARGE OBJECT <replaceable class="PARAMETER">large_object_oid</replaceable> | [ PROCEDURAL ] LANGUAGE <replaceable class="PARAMETER">object_name</replaceable> | @@ -82,8 +83,8 @@ SECURITY LABEL [ FOR <replaceable class="PARAMETER">provider</replaceable> ] ON <listitem> <para> The name of the object to be commented. Names of tables, - aggregates, domains, functions, sequences, types, and views can - be schema-qualified. + aggregates, domains, foreign tables, functions, sequences, types, and + views can be schema-qualified. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index 13de0027925..84babf61c00 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -40,6 +40,7 @@ &alterDefaultPrivileges; &alterDomain; &alterForeignDataWrapper; + &alterForeignTable; &alterFunction; &alterGroup; &alterIndex; @@ -78,6 +79,7 @@ &createDatabase; &createDomain; &createForeignDataWrapper; + &createForeignTable; &createFunction; &createGroup; &createIndex; @@ -113,6 +115,7 @@ &dropDatabase; &dropDomain; &dropForeignDataWrapper; + &dropForeignTable; &dropFunction; &dropGroup; &dropIndex; |