Foreign table docs.

docs/en_US/foreign_table_dialog.rst

@@ -0,0 +1,109 @@
+.. _foreign_table_dialog:
+
+************************
+The Foreign Table Dialog
+************************
+
+Use the *Foreign Table* dialog to define a foreign table in the current database. Foreign tables define the structure of an external data source that resides on a foreign server.
+
+The *Foreign Table* dialog organizes the development of a foreign table through the following dialog tabs: *General*, *Definition*, *Columns*, *Constraints*, *Options*, and *Security*. The *SQL* tab displays the SQL code generated by dialog selections. 
+
+.. image:: images/foreign_table_general.png
+
+Use the fields in the *General* tab to identify the foreign table:
+
+* Use the *Name* field to add a descriptive name for the foreign table. The name of the foreign table must be distinct from the name of any other foreign table, table, sequence, index, view, existing data type, or materialized view in the same schema. The name will be displayed in the *pgAdmin* tree control.
+* Use the drop-down listbox next to *Owner* to select the name of the role that will own the foreign table.
+* Select the name of the schema in which the foreign table will reside from the drop-down listbox in the *Schema* field.
+* Store notes about the foreign table in the *Comment* field.
+
+Click the *Definition* tab to continue.
+
+.. image:: images/foreign_table_definition.png
+
+Use the fields in the *Definition* tab to define the external data source:
+
+* Use the drop-down listbox next to *Foreign server* to select a foreign server. This list is populated with servers defined through the *Foreign Server* dialog.
+* Use the drop-down listbox next to *Inherits* to specify a parent table. The foreign table will inherit all of its columns. This field is optional.  
+
+Click the *Columns* tab to continue.
+
+.. image:: images/foreign_table_columns.png
+
+Use the fields in the *Columns* tab to to add columns and their attributes to the table. Click *Add* to define a column:
+
+* Use the *Name* field to add a descriptive name for the column.
+* Use the drop-down listbox next to *Data Type* to select a data type for the column. This can include array specifiers. For more information on which data types are supported by PostgreSQL, refer to Chapter 8 of the core documentation.
+* Use the *Length* field to specify the length of a data string.
+* Use the *Precision* field to specify the total number of significant digits.
+* Use the *Default* field to specify a default data value.
+* Check the *Not Null* checkbox to specify the column may not contain null values.
+* Use the *Statistics* field to specify *true* or *false* if the foreign data wrapper can collect statistics for the foreign table. 
+* Use the drop-down listbox next to *Collation* to apply a collation setting to the foreign table.
+
+Click *Add* to specify each additional column; to discard a column, click the trash icon to the left of the row and confirm deletion in the *Delete Row* popup.
+
+Click the *Constraints* tab to continue.
+
+.. image:: images/foreign_table_constraints.png
+
+Use the fields in the *Constraints* tab to apply a table constraint to the foreign table. Click *Add* to define a constraint:
+
+* Use the *Name* field to add a descriptive name for the constraint. If the constraint is violated, the constraint name is present in error messages, so constraint names like *col must be positive* can be used to communicate helpful information.
+* Use the *Check* field to write a check expression producing a Boolean result. Each row in the foreign table is expected to satisfy the check expression.
+* Check the *No Inherit* checkbox to specify that the constraint will not propagate to child tables.
+* Uncheck the *Validate* checkbox to disable validation. The database will not assume that the constraint holds for all rows in the table.
+
+Click *Add* to specify each additional constraint; to discard a constraint, click the trash icon to the left of the row and confirm deletion in the *Delete Row* popup.
+
+Click the *Options* tab to continue.
+
+.. image:: images/foreign_table_options.png
+
+Use the fields in the *Options* tab to specify options to be associated with the new foreign table or one of its columns; the accepted option names and values are specific to the foreign data wrapper associated with the foreign server. Click the *Add* button to add an option/value pair. 
+
+* Specify the option name in the *Option* field. Duplicate option names are not allowed.
+* Provide a corresponding value in the *Value* field.  
+
+Click *Add* to specify each additional option/value pair; to discard an option, click the trash icon to the left of the row and confirm deletion in the *Delete Row* popup.
+
+Click the *Security* tab to continue.
+
+.. image:: images/foreign_table_security.png
+
+Use the *Security* tab to assign privileges and define security labels.  
+
+Use the *Privileges* panel to assign privileges to a role. Click *Add* to set privileges for database objects:
+
+* Select the name of the role to which privileges will be assigned from the drop-down listbox in the *Grantee* field.
+* Click inside the *Privileges* field. Check the boxes to the left of one or more privileges to grant the selected privilege to the specified user.
+* Select the name of the role that owns the foreign table from the drop-down listbox in the *Grantor* field. The default grantor is the owner of the database.
+
+Click *Add* to assign additional privileges; to discard a privilege, click the trash icon to the left of the row and confirm deletion in the *Delete Row* popup.
+
+Use the *Security Labels* panel to define security labels applied to the function. Click *Add* to add each security label selection: 
+
+* Specify a security label provider in the *Provider* field. The named provider must be loaded and must consent to the proposed labeling operation.
+* Specify a a security label in the *Security Label* field. The meaning of a given label is at the discretion of the label provider. PostgreSQL places no restrictions on whether or how a label provider must interpret security labels; it merely provides a mechanism for storing them. 
+
+Click *Add* to assign additional security labels; to discard a security label, click the trash icon to the left of the row and confirm deletion in the *Delete Row* popup.
+
+Click the *SQL* tab to continue.
+
+Your entries in the *Foreign Table* dialog generate a SQL command (see an example below). Use the *SQL* tab for review; revisit or switch tabs to make any changes to the SQL command. 
+
+**Example**
+
+The following is an example of the sql command generated by user selections in the *Foreign Table* dialog: 
+
+.. image:: images/foreign_table_sql.png
+
+The example shown demonstrates creating a foreign table *weblogs* with multiple columns and two options.
+
+ 
+* Click the *Info* button (i) to access online help. View context-sensitive help in the *Tabbed browser*, where a new tab displays the PostgreSQL core documentation.
+* Click the *Save* button to save work.
+* Click the *Cancel* button to exit without saving work.
+* Click the *Reset* button to restore configuration parameters.
+
+

docs/en_US/index.rst

@@ -34,6 +34,8 @@ Getting Started
 
 Before you can use the pgAdmin client to manage your Postgres installation, you must define a connection to the server.    
 
+Contents:
+
 .. toctree::
    :maxdepth: 1
 
@@ -45,15 +47,10 @@ Before you can use the pgAdmin client to manage your Postgres installation, you
 Creating Cluster Level Objects  
 ==============================
    
-Some object definitions reside at the cluster level: 
- 
-* Resource Groups
-* Roles
-* Tablespaces
-* Databases
-
-pgAdmin 4 provides dialogs that allow you to create these objects, manage them, and control their relationships to each other.  To access a dialog that allows you to create a database object, right-click on the object type in the pgAdmin tree control, and select the *Create* option for that object.  For example, to create a new database, right-click on the *Databases* node, and select *Create Database...*    
+Some object definitions reside at the cluster level; pgAdmin 4 provides dialogs that allow you to create these objects, manage them, and control their relationships to each other.  To access a dialog that allows you to create a database object, right-click on the object type in the pgAdmin tree control, and select the *Create* option for that object.  For example, to create a new database, right-click on the *Databases* node, and select *Create Database...*    
    
+Contents:
+
 .. toctree::
    :maxdepth: 2
 
@@ -70,6 +67,8 @@ pgAdmin 4 provides simple but powerful dialogs that you can use to design and cr
 
 To access a dialog that allows you to create a database object, right-click on the object type in the pgAdmin tree control, and select the *Create* option for that object.  For example, to create a new database, right-click on the *Casts* node, and select *Create Cast...*
 
+Contents:
+
 .. toctree::
    :maxdepth: 2
    
@@ -79,6 +78,7 @@ To access a dialog that allows you to create a database object, right-click on t
    event_trigger_dialog
    extension_dialog
    foreign_data_wrapper_dialog
+   foreign_table_dialog
    fts_parser_dialog
    fts_template_dialog
    function_dialog
@@ -93,6 +93,8 @@ pgAdmin 4 provides dialogs that allow you to modify all table properties and att
 
 To access a dialog that allows you to create a database object, right-click on the object type in the pgAdmin tree control, and select the *Create* option for that object.  For example, to create a new database, right-click on the *Casts* node, and select *Create Cast...*
 
+Contents:
+
 .. toctree::
    :maxdepth: 2
    
@@ -117,6 +119,8 @@ The configuration editor provides a graphical interface that allows a sufficient
 
 To modify the postgresql.conf or pg_hba.conf file, you must have sufficient privileges to modify and save files in the Postgres *data* directory.  Please note that incorrect configuration can slow performance, or prevent the server from restarting without reverting your changes.  Please consult the PostgreSQL core documentation for detailed information about configuring your server.
 
+Contents:
+
 .. toctree::
    :maxdepth: 2
    
@@ -129,6 +133,8 @@ Backup and Restore
 
 A powerful, but user-friendly Backup and Restore tool provides an easy way to use pg_dump, pg_dumpall, and pg_restore to take backups and create copies of databases or database objects for use in a development environment.
 
+Contents:
+
 .. toctree::
    :maxdepth: 2
    
@@ -141,6 +147,8 @@ Developer Tools
 
 The pgAdmin *Tools* menu displays a list of powerful developer tools that you can use to execute and analyze complex SQL commands, manage data, and debug PL/SQL code.
 
+Contents:
+
 .. toctree::
    :maxdepth: 2
    
@@ -155,6 +163,8 @@ pgAdmin Deployment
 
 Pre-compiled and configured installation packages for pgAdmin 4 are available for a number of desktop environments; we recommend using an installer whenever possible.  If you are interested in learning more about the project, or if a pgAdmin installer is not available for your environment, the pages listed below will provide detailed information about creating a custom deployment.  
 
+Contents:
+
 .. toctree::
    :maxdepth: 2