docs - pxf jdbc cfg supports connection- and session-level properties (#7571)

* docs - jdbc cfg supports connection- and session-level properties

* some edits requested by david

* reword jdbc server cfg opening paragraph

* clarify rejected session prop/value chars as requested by ivan

gpdb-doc/markdown/pxf/jdbc_cfg.html.md.erb

@@ -23,9 +23,9 @@ The PXF JDBC connector is installed with the `postgresql-8.4-702.jdbc4.jar` JAR
 
 ### <a id="cfg_server"></a>JDBC Server Configuration
 
-PXF provides a template configuration file for the JDBC Connector. This server template configuration file, located in `$PXF_CONF/templates/jdbc-site.xml`, identifies the minimum set of properties that you must configure to use the PXF JDBC Connector.
+PXF provides a template configuration file for the JDBC Connector. This server template configuration file, located in `$PXF_CONF/templates/jdbc-site.xml`, identifies properties that you can configure to establish a connection to the external SQL database. The template also includes optional properties that you can set before query execution in the external database session.
 
-The properties in the `jdbc-site.xml` server template file follow:
+The base properties in the `jdbc-site.xml` server template file follow:
 
 | Property       | Description                                | Value |
 |----------------|--------------------------------------------|-------|
@@ -36,6 +36,50 @@ The properties in the `jdbc-site.xml` server template file follow:
 
 <div class="note">When you configure a PXF JDBC server, you specify the external database user credentials to PXF in clear text in a configuration file.</div>
 
+#### <a id="connprop"></a>Connection-Level Properties
+
+To set additional JDBC connection-level properties, add `jdbc.connection.property.<CPROP_NAME>` properties to `jdbc-site.xml`. PXF passes these properties to the JDBC driver when it establishes the connection to the external SQL database (`DriverManager.getConnection()`).
+
+Replace `<CPROP_NAME>` with the connection property name and specify its value:
+
+| Property       | Description                                | Value |
+|----------------|--------------------------------------------|-------|
+| jdbc.connection.property.\<CPROP_NAME\> | The name of a property (\<CPROP_NAME\>) to pass to the JDBC driver when PXF establishes the connection to the external SQL database.  | The value of the \<CPROP_NAME\> property. |
+
+Example: To set the `createDatabaseIfNotExist` connection property on a JDBC connection to a MySQL database, include the following property block in `jdbc-site.xml`:
+
+``` xml
+<property>
+    <name>jdbc.connection.property.createDatabaseIfNotExist</name>
+    <value>true</value>
+ </property>
+```
+
+#### <a id="sessprop"></a>Session-Level Properties
+
+To set session-level properties, add the `jdbc.session.property.<SPROP_NAME>` property to `jdbc-site.xml`. PXF will `SET` these properties in the external database before executing a query.
+
+ Replace `<SPROP_NAME>` with the session property name and specify its value:
+
+| Property       | Description                                | Value |
+|----------------|--------------------------------------------|-------|
+| jdbc.session.property.\<SPROP_NAME\> | The name of a session property (\<SPROP_NAME\>) to set before query execution. | The value of the \<SPROP_NAME\> property. |
+
+**Note**: The PXF JDBC Connector passes both the session property name and property value to the external SQL database exactly as specified in the `jdbc-site.xml` server configuration file. To limit the potential threat of SQL injection, the Connector rejects any property name or value that contains the `;`, `\n`, `\b`, or `\0` characters.
+
+The PXF JDBC Connector handles the session property `SET` syntax for all supported external SQL databases.
+
+Example: To set the `search_path` parameter before running a query in a PostgreSQL database, add the following property block to `jdbc-site.xml`:
+
+``` xml
+<property>
+    <name>jdbc.session.property.search_path</name>
+    <value>public</value>
+</property>
+```
+
+## <a id="cfg_server_proc"></a>Configuration Procedure
+
 When you configure the PXF JDBC Connector to access an external SQL database, you add at least one named PXF server configuration for the connector. You:
 
 1. Choose a name for the server configuration.
@@ -55,9 +99,9 @@ FORMAT 'TEXT' (delimiter=E',');
 
 <div class="note info">A Greenplum Database user who queries or writes to an external table that specifies a server name accesses the external SQL database with the credentials configured for that server.</div>
 
-While not recommended, you can override a JDBC server configuration by directly specifying the driver, database URL, and/or user credentials via custom options in the `CREATE EXTERNAL TABLE` command `LOCATION` clause. Refer to [Accessing an SQL Database with JDBC](jdbc_pxf.html) for additional information.
+While not recommended, you can override a JDBC server configuration by directly specifying the driver, database URL, and/or user credentials via custom options in the `CREATE EXTERNAL TABLE` command `LOCATION` clause. Refer to [Overriding the JDBC Server Configuration](jdbc_pxf.html#jdbc_override) for additional information.
 
-## <a id="cfg_proc"></a>Example Configuration Procedure
+### <a id="cfg_proc" class="no-quick-link"></a>Example
 
 Ensure that you have initialized PXF before you configure a JDBC Connector server.
 

gpdb-doc/markdown/pxf/jdbc_pxf.html.md.erb

@@ -74,7 +74,7 @@ The specific keywords and values used in the [CREATE EXTERNAL TABLE](../ref_guid
 | \<external&#8209;table&#8209;name\>    | The full name of the external table. Depends on the external SQL database, may include a schema name and a table name. |
 | PROFILE    | The `PROFILE` keyword value must specify `Jdbc`. |
 | SERVER=\<servername\>   | The named server configuration that PXF uses to access the external SQL database. |
-| \<custom&#8209;option\>  | \<custom-option\> is profile-specific. `Jdbc` profile-specific options are discussed in the next section.|
+| \<custom&#8209;option\>=\<value\>  | \<custom-option\> is profile-specific. `Jdbc` profile-specific options are discussed in the next section.|
 | FORMAT 'CUSTOM' | The JDBC `CUSTOM` `FORMAT` supports the built-in `'pxfwritable_import'` `FORMATTER` function for read operations and the built-in `'pxfwritable_export'` function for write operations. |
 
 **Note**: You cannot use the `HEADER` option in your `FORMAT` specification when you create a PXF external table.
@@ -82,27 +82,7 @@ The specific keywords and values used in the [CREATE EXTERNAL TABLE](../ref_guid
 
 ### <a id="jdbcoptions"></a>JDBC Custom Options
 
-You include JDBC connector custom options in the `LOCATION` URI, prefacing each option with an ampersand `&`.
-
-The `Jdbc` profile supports the following connection-related \<custom-option\>s:
-
-| Custom Option Name   | jdbc-site.xml Property Name | Description
-|----------------------|-----------------------------|--------|
-| JDBC_DRIVER | jdbc.driver | The JDBC driver class name. (Required) |
-| DB_URL | jdbc.url | The external database URL. Depends on the external SQL database, typically includes at least the hostname, port, and database name. (Required) |
-| USER | jdbc.user | The database user name. Required if `PASS` is provided. |
-| PASS | jdbc.password | The database password for `USER`. Required if `USER` is provided. |
-
-<div class="note">If you provide a <code>SERVER=&lt;servername></code> in the <code>CREATE EXTERNAL TABLE</code> <code>LOCATION</code> clause, any connection option that you include in the <code>LOCATION</code> clause overrides the value that you specified in the <code>&lt;servername></code>'s <code>jdbc-site.xml</code> configuration file.</div>
-
-Example JDBC \<custom-option\> connection strings:
-
-``` pre
-&JDBC_DRIVER=org.postgresql.Driver&DB_URL=jdbc:postgresql://gpmaster:5432/pgtestdb&USER=pguser1&PASS=changeme
-&JDBC_DRIVER=com.mysql.jdbc.Driver&DB_URL=jdbc:mysql://mysqlhost:3306/testdb&USER=user1&PASS=changeme
-```
-
-Additional `CREATE EXTERNAL TABLE` \<custom-option\>s supported by the `Jdbc` profile include:
+You include JDBC connector custom options in the `LOCATION` URI, prefacing each option with an ampersand `&`. `CREATE EXTERNAL TABLE` \<custom-option\>s supported by the `Jdbc` profile include:
 
 | Option Name   | Operation | Description
 |---------------|------------|--------|
@@ -329,3 +309,27 @@ Perform the following procedure to insert some data into the `forpxf_table1` Pos
     (6 rows)
     ```
 
+## <a id="jdbc_override"></a>Overriding the JDBC Server Configuration
+
+If you are accessing an external SQL database, you can override the JDBC server configuration connection parameters by directly specifying these custom options in the `CREATE EXTERNAL TABLE` `LOCATION` clause:
+
+| Custom Option Name   | jdbc-site.xml Property Name | Description
+|----------------------|-----------------------------|--------|
+| JDBC_DRIVER | jdbc.driver | The JDBC driver class name. (Required) |
+| DB_URL | jdbc.url | The external database URL. Depends on the external SQL database, typically includes at least the hostname, port, and database name. (Required) |
+| USER | jdbc.user | The database user name. Required if `PASS` is provided. |
+| PASS | jdbc.password | The database password for `USER`. Required if `USER` is provided. |
+
+Example JDBC \<custom-option\> connection strings:
+
+``` pre
+&JDBC_DRIVER=org.postgresql.Driver&DB_URL=jdbc:postgresql://pgserverhost:5432/pgtestdb&USER=pguser1&PASS=changeme
+&JDBC_DRIVER=com.mysql.jdbc.Driver&DB_URL=jdbc:mysql://mysqlhost:3306/testdb&USER=user1&PASS=changeme
+```
+For example:
+<pre>CREATE EXTERNAL TABLE pxf_pgtbl(name text, orders int)
+  LOCATION ('pxf://public.forpxf_table1?PROFILE=Jdbc<b>&JDBC_DRIVER=org.postgresql.Driver&DB_URL=jdbc:postgresql://pgserverhost:5432/pgtestdb&USER=pxfuser1&PASS=changeme</b>')
+FORMAT 'CUSTOM' (FORMATTER='pxfwritable_export');</pre>
+
+<div class="note warning">Credentials that you provide in this manner are visible as part of the external table definition. Do not use this method of passing credentials in a production environment.</div>
+