doc-exports/docs/dws/dev/dws_04_0093.html

<a name="EN-US_TOPIC_0000001188163678"></a><a name="EN-US_TOPIC_0000001188163678"></a>

<h1 class="topictitle1">Connecting to a Database</h1>
<div id="body8662426"><p id="EN-US_TOPIC_0000001188163678__en-us_topic_0059779354_p948818398417">After a database is connected, you can run SQL statements the database to perform operations on data.</p>
<div class="note" id="EN-US_TOPIC_0000001188163678__note19342720153419"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="EN-US_TOPIC_0000001188163678__p2065920386471">If you use an open-source Java Database Connectivity (JDBC) driver, ensure that the database parameter <strong id="EN-US_TOPIC_0000001188163678__b651711913327">password_encryption_type</strong> is set to <strong id="EN-US_TOPIC_0000001188163678__b1152319199321">1</strong>. If the value is not 1, the connection may fail. A typical error message is "none of the server's SASL authentication mechanisms are supported." To avoid such problems, perform the following operations:</p>
<ol id="EN-US_TOPIC_0000001188163678__ol1867461614519"><li id="EN-US_TOPIC_0000001188163678__li18674101613513">Set <strong id="EN-US_TOPIC_0000001188163678__b314515199521">password_encryption_type</strong> to <strong id="EN-US_TOPIC_0000001188163678__b10146141955212">1</strong>. For details, see "Modifying Database Parameters" in <em id="EN-US_TOPIC_0000001188163678__i114681945217">User Guide</em>.</li><li id="EN-US_TOPIC_0000001188163678__li8674191619518">Create a new database user for connection or reset the password of the existing database user.<ul id="EN-US_TOPIC_0000001188163678__ul136741416145115"><li id="EN-US_TOPIC_0000001188163678__li867431618515">If you use an administrator account, reset the password. For details, see "Resetting a Password" in <em id="EN-US_TOPIC_0000001188163678__i172682043125616">User Guide</em>.</li><li id="EN-US_TOPIC_0000001188163678__li1745295113575">If you are a common user, use another client tool (such as Data Studio) to connect to the database and run the <strong id="EN-US_TOPIC_0000001188163678__b16424510193312">ALTER USER</strong> statement to change your password.</li></ul>
</li><li id="EN-US_TOPIC_0000001188163678__li176328710583">Connect to the database.</li></ol>
<p id="EN-US_TOPIC_0000001188163678__p24118503415"></p>
<p id="EN-US_TOPIC_0000001188163678__p20733151055215">Here are the reasons why you need to perform these operations:</p>
<ul id="EN-US_TOPIC_0000001188163678__ul9472201514422"><li id="EN-US_TOPIC_0000001188163678__li5472715124217">MD5 algorithms may by vulnerable to collision attacks and cannot be used for password verification. Currently, GaussDB(DWS) uses the default security design. By default, MD5 password verification is disabled, but MD5 is required by the open-source libpq communication protocol of PostgreSQL. For connectivity purposes, you need to adjust the cryptographic algorithm parameter <strong id="EN-US_TOPIC_0000001188163678__b195330428234">password_encryption_type</strong> and enable the MD5 algorithm.</li><li id="EN-US_TOPIC_0000001188163678__li1847220158427">The database stores the hash digest of passwords instead of password text. During password verification, the system compares the hash digest with the password digest sent from the client (salt operations are involved). If you change your cryptographic algorithm policy, the database cannot generate a new MD5 hash digest for your existing password. For connectivity purposes, you must manually change your password or create a new user. The new password will be encrypted using the hash algorithm and stored for authentication in the next connection.</li></ul>
</div></div>
<div class="section" id="EN-US_TOPIC_0000001188163678__s57807bb88f8443d89adad8e3f8ee5264"><h4 class="sectiontitle">Function Prototype</h4><p id="EN-US_TOPIC_0000001188163678__a1290a21c3f4a42fe8ed5b87a7fa27bea">JDBC provides the following three database connection methods:</p>
<ul id="EN-US_TOPIC_0000001188163678__u88b2b87027a6476e83080b599bf37529"><li id="EN-US_TOPIC_0000001188163678__le6dca7e0a8ef4394a6e497986423f777">DriverManager.getConnection(String url);</li><li id="EN-US_TOPIC_0000001188163678__l20aec76f8c1043558cd368166daa9aa6">DriverManager.getConnection(String url, Properties info);</li><li id="EN-US_TOPIC_0000001188163678__l6efd1f62c2ae49bcbb0e6bd6e1768aeb">DriverManager.getConnection(String url, String user, String password);</li></ul>
</div>
<div class="section" id="EN-US_TOPIC_0000001188163678__s3f963f87690b40dc8d480e5acca94eb4"><h4 class="sectiontitle">Parameter</h4>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="EN-US_TOPIC_0000001188163678__t6e91fcf016964232ae79f17e8160e7ce" frame="border" border="1" rules="all"><caption><b>Table 1 </b>Database connection parameters</caption><thead align="left"><tr id="EN-US_TOPIC_0000001188163678__r51e724f205e64ddc99f18495764e935a"><th align="left" class="cellrowborder" valign="top" width="13%" id="mcps1.3.4.2.2.3.1.1"><p id="EN-US_TOPIC_0000001188163678__aef564c8a17fd44b799850596b376c501">Parameter</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="87%" id="mcps1.3.4.2.2.3.1.2"><p id="EN-US_TOPIC_0000001188163678__a45a65a35a7374832ad0b76f1590eae48">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="EN-US_TOPIC_0000001188163678__r93dfa37ce5944dedba6aa61c568a1f91"><td class="cellrowborder" valign="top" width="13%" headers="mcps1.3.4.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001188163678__add7cddadf9d44578925be52df2dfe367">url</p>
</td>
<td class="cellrowborder" valign="top" width="87%" headers="mcps1.3.4.2.2.3.1.2 "><p id="EN-US_TOPIC_0000001188163678__a1cf0afcb331646d887bdf79d72ad4b88"><strong id="EN-US_TOPIC_0000001188163678__b16015422218">gsjdbc4.jar</strong> database connection descriptor. The descriptor format can be:</p>
<ul id="EN-US_TOPIC_0000001188163678__ude90174d20344cc1aa2bffac0ce922db"><li id="EN-US_TOPIC_0000001188163678__l9de386d881f2401da4ee43320fb31dc7">jdbc:postgresql:database</li><li id="EN-US_TOPIC_0000001188163678__l73b378cf34d34098a3c3f7f7a428a0f0">jdbc:postgresql://host/database</li><li id="EN-US_TOPIC_0000001188163678__l2d519f1cef1a4e90b2c85191716f6980">jdbc:postgresql://host:port/database</li><li id="EN-US_TOPIC_0000001188163678__li139771853413">jdbc:postgresql://host:port[,host:port][...]/database</li></ul>
<div class="note" id="EN-US_TOPIC_0000001188163678__n16fc25d92c244d68817e6df6d768bbc9"><span class="notetitle"> NOTE: </span><div class="notebody"><p id="EN-US_TOPIC_0000001188163678__p1069826216120">If <strong id="EN-US_TOPIC_0000001188163678__b13149538225">gsjdbc200.jar</strong> is used, replace <strong id="EN-US_TOPIC_0000001188163678__b3755717230">jdbc:postgresql</strong> with <strong id="EN-US_TOPIC_0000001188163678__b118051110234">jdbc:gaussdb</strong>.</p>
<ul id="EN-US_TOPIC_0000001188163678__ue24edf2cc0a9448495fbf4a286ba0e10"><li id="EN-US_TOPIC_0000001188163678__l817d6a9711c24629bb836d2812711c69"><strong id="EN-US_TOPIC_0000001188163678__b84235270610641">database</strong>: indicates the name of the database to be connected.</li><li id="EN-US_TOPIC_0000001188163678__lcdc7dc18e83e43d08a39fac766e1f87c"><strong id="EN-US_TOPIC_0000001188163678__b170226591742047">host</strong> indicates the name or IP address of the database server. <span id="EN-US_TOPIC_0000001188163678__ph109147048042047">If an ELB is bound to the cluster, set <strong id="EN-US_TOPIC_0000001188163678__b145551199442047">host</strong> to the IP address of the ELB.</span></li><li id="EN-US_TOPIC_0000001188163678__lb7a87e31c5f84c8b98d83b732a43f16e"><strong id="EN-US_TOPIC_0000001188163678__b81921558103110">port</strong>: indicates the port number of a database server. By default, the database on port <strong id="EN-US_TOPIC_0000001188163678__b1283118480416"><span id="EN-US_TOPIC_0000001188163678__text1768017568445">8000</span></strong> of the local host is connected.</li><li id="EN-US_TOPIC_0000001188163678__li66014152254">Multiple IP addresses and ports can be configured. JDBC balances load by random access and failover, and will automatically ignore unreachable IP addresses.<p id="EN-US_TOPIC_0000001188163678__p1949891512518"><a name="EN-US_TOPIC_0000001188163678__li66014152254"></a><a name="li66014152254"></a>IP addresses are separated using commas. Example: <strong id="EN-US_TOPIC_0000001188163678__b687022213512">jdbc:postgresql://10.10.0.13:<span id="EN-US_TOPIC_0000001188163678__text1069617386148">8000</span>,10.10.0.14:<span id="EN-US_TOPIC_0000001188163678__text15636648121416">8000</span>/database</strong></p>
</li><li id="EN-US_TOPIC_0000001188163678__li817864135715">If JDBC is used to connect to a cluster, only JDBC connection parameters can be configured in a cluster address. Variables cannot be added.</li></ul>
</div></div>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188163678__re8422e921f2545ef81f269251b095386"><td class="cellrowborder" valign="top" width="13%" headers="mcps1.3.4.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001188163678__a4cc9c4f2d6ad4a438da6b4be4a0bbb49">info</p>
</td>
<td class="cellrowborder" valign="top" width="87%" headers="mcps1.3.4.2.2.3.1.2 "><p id="EN-US_TOPIC_0000001188163678__a3fac73fcef9f445e90ab567819781679">Database connection properties. Common properties include:</p>
<ul id="EN-US_TOPIC_0000001188163678__ue7508e5a1b3a4615a5eff8dc9eac753a"><li id="EN-US_TOPIC_0000001188163678__l95f308a3ce844132917dd5e8cb23952a"><strong id="EN-US_TOPIC_0000001188163678__b2861061114423">user</strong>: string type. It indicates the database user establishing a connection.</li><li id="EN-US_TOPIC_0000001188163678__lda3b1ec2df6a4266883da278e93624d6"><strong id="EN-US_TOPIC_0000001188163678__b6391245314423">password</strong>: string type. It indicates the password of a database user.</li><li id="EN-US_TOPIC_0000001188163678__lc5eb481b22754604b1c4d476f1c2a7bd"><strong id="EN-US_TOPIC_0000001188163678__b2319919214423">ssl</strong>: Boolean type. It indicates whether the Secure Socket Layer (SSL) is used.</li><li id="EN-US_TOPIC_0000001188163678__li87792117464"><strong id="EN-US_TOPIC_0000001188163678__b923522303920">loggerLevel</strong>: string type. It indicates the amount of information that the driver logs and prints to the LogStream or LogWriter specified in the DriverManager. Currently, <strong id="EN-US_TOPIC_0000001188163678__b8456181454015">OFF</strong>, <strong id="EN-US_TOPIC_0000001188163678__b173895164401">DEBUG</strong>, and <strong id="EN-US_TOPIC_0000001188163678__b105641319204016">TRACE</strong> are supported. <strong id="EN-US_TOPIC_0000001188163678__b880513515404">DEBUG</strong> indicates that only logs of the <strong id="EN-US_TOPIC_0000001188163678__b284119512400">DEBUG</strong> or higher level are printed, generating a few log information. <strong id="EN-US_TOPIC_0000001188163678__b479283415413">TRACE</strong> indicates that logs of the <strong id="EN-US_TOPIC_0000001188163678__b6739542423">DEBUG</strong> and <strong id="EN-US_TOPIC_0000001188163678__b8415168154219">TRACE</strong> levels are printed, generating detailed log information. The default value is <strong id="EN-US_TOPIC_0000001188163678__b9451161111447">OFF</strong>, indicating that no information will be logged.</li><li id="EN-US_TOPIC_0000001188163678__lc810077008fa4d9798ae733ee402cccf"><strong id="EN-US_TOPIC_0000001188163678__b3452109514423">prepareThreshold</strong>: integer type. It indicates the number of <strong id="EN-US_TOPIC_0000001188163678__b5430114423">PreparedStatement</strong> executions required before SQL statements are switched over to servers as prepared statements. The default value is <strong id="EN-US_TOPIC_0000001188163678__b842352706101416">5</strong>.</li><li id="EN-US_TOPIC_0000001188163678__li62157221239"><strong id="EN-US_TOPIC_0000001188163678__b16976118111310">batchMode</strong>: boolean type. It indicates whether to connect the database in batch mode.</li><li id="EN-US_TOPIC_0000001188163678__li198011645489"><strong id="EN-US_TOPIC_0000001188163678__b16844342121812">fetchsize</strong>: integer type. It indicates the default fetchsize for statements in the created connection.</li><li id="EN-US_TOPIC_0000001188163678__li1580508012022"><strong id="EN-US_TOPIC_0000001188163678__b1871763815910">ApplicationName</strong>: string type. It indicates an application name. The default value is <strong id="EN-US_TOPIC_0000001188163678__b1840414470017">PostgreSQL JDBC Driver</strong>.</li><li id="EN-US_TOPIC_0000001188163678__li20991068101733"><strong id="EN-US_TOPIC_0000001188163678__b14549207114">allowReadOnly</strong>: boolean type. It indicates whether to enable the read-only mode for connection. The default value is <strong id="EN-US_TOPIC_0000001188163678__b95739222242">false</strong>. If the value is not changed to <strong id="EN-US_TOPIC_0000001188163678__b113685119218">true</strong>, the execution of <strong id="EN-US_TOPIC_0000001188163678__b10247139224">connection.setReadOnly</strong> does not take effect.</li><li id="EN-US_TOPIC_0000001188163678__li58920766163137"><strong id="EN-US_TOPIC_0000001188163678__b121531640883">blobMode</strong>: string type. It is used to set the setBinaryStream method to assign values to different data types. The value <strong id="EN-US_TOPIC_0000001188163678__b2062210518193">on</strong> indicates that values are assigned to the BLOB data type and <strong id="EN-US_TOPIC_0000001188163678__b1840811184209">off</strong> indicates that values are assigned to the bytea data type. The default value is <strong id="EN-US_TOPIC_0000001188163678__b149051051202012">on</strong>.</li><li id="EN-US_TOPIC_0000001188163678__li14943122819372"><strong id="EN-US_TOPIC_0000001188163678__b432619279322">connectionExtraInfo</strong>: boolean type. It indicates whether the JDBC driver reports the driver deployment path and process owner to the database.<div class="note" id="EN-US_TOPIC_0000001188163678__note177665024418"><span class="notetitle"> NOTE: </span><div class="notebody"><p id="EN-US_TOPIC_0000001188163678__p197674018449">The value can be <strong id="EN-US_TOPIC_0000001188163678__b10391181463613">true</strong> or <strong id="EN-US_TOPIC_0000001188163678__b17398141483616">false</strong>. The default value is <strong id="EN-US_TOPIC_0000001188163678__b239841433620">true</strong>. If <strong id="EN-US_TOPIC_0000001188163678__b58331329323">connectionExtraInfo</strong> is set to <strong id="EN-US_TOPIC_0000001188163678__b1483413328329">true</strong>, the JDBC driver reports the driver deployment path and process owner to the database and displays the information in the <strong id="EN-US_TOPIC_0000001188163678__b148341032163210">connection_info</strong> parameter (see <a href="dws_04_0889.html#EN-US_TOPIC_0000001188482316__section4834457114318">connection_info</a>). In this case, you can query the information from <a href="dws_04_0755.html">PG_STAT_ACTIVITY</a> or <a href="dws_04_0820.html">PGXC_STAT_ACTIVITY</a>.</p>
</div></div>
</li></ul>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188163678__r223c3793463b444e8a1683caf4a924db"><td class="cellrowborder" valign="top" width="13%" headers="mcps1.3.4.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001188163678__abcc03c869ece4e74bcb4076fd9069460">user</p>
</td>
<td class="cellrowborder" valign="top" width="87%" headers="mcps1.3.4.2.2.3.1.2 "><p id="EN-US_TOPIC_0000001188163678__a878f4a74845e43a193e472f0e1793648">Indicates a database user.</p>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188163678__r1831a5c112ff497cb01f3fd429381fe5"><td class="cellrowborder" valign="top" width="13%" headers="mcps1.3.4.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001188163678__a96330c6820aa4816bc5ec7468a0adb9d">password</p>
</td>
<td class="cellrowborder" valign="top" width="87%" headers="mcps1.3.4.2.2.3.1.2 "><p id="EN-US_TOPIC_0000001188163678__a222b29624efe4ae49abbae1bc5e01e1a">Indicates the password of a database user.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="EN-US_TOPIC_0000001188163678__s2157acc2f22b412795a8d0d62ab83478"><h4 class="sectiontitle">Examples</h4><div class="codecoloring" codetype="Java" id="EN-US_TOPIC_0000001188163678__sffed43fecea943d5854883c3e205febc"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span>
<span class="normal">15</span>
<span class="normal">16</span>
<span class="normal">17</span>
<span class="normal">18</span>
<span class="normal">19</span>
<span class="normal">20</span>
<span class="normal">21</span>
<span class="normal">22</span>
<span class="normal">23</span>
<span class="normal">24</span>
<span class="normal">25</span>
<span class="normal">26</span>
<span class="normal">27</span>
<span class="normal">28</span>
<span class="normal">29</span></pre></div></td><td class="code"><div><pre><span></span><span class="c1">//gsjdbc4.jar is used as an example.</span>
<span class="c1">//The following code encapsulates database connection operations into an interface. The database can then be connected using an authorized username and password.</span>

<span class="kd">public</span><span class="w"> </span><span class="kd">static</span><span class="w"> </span><span class="n">Connection</span><span class="w"> </span><span class="nf">GetConnection</span><span class="p">(</span><span class="n">String</span><span class="w"> </span><span class="n">username</span><span class="p">,</span><span class="w"> </span><span class="n">String</span><span class="w"> </span><span class="n">passwd</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">        </span><span class="c1">//Set the driver class.</span>
<span class="w">        </span><span class="n">String</span><span class="w"> </span><span class="n">driver</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;org.postgresql.Driver&quot;</span><span class="p">;</span>
<span class="w">        </span><span class="c1">//Database connection descriptor.</span>
<span class="w">        </span><span class="n">String</span><span class="w"> </span><span class="n">sourceURL</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;jdbc:postgresql://10.10.0.13:8000/postgres?currentSchema=test&quot;</span><span class="p">;</span>
<span class="w">        </span><span class="n">Connection</span><span class="w"> </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">null</span><span class="p">;</span>
<span class="w">        </span>
<span class="w">        </span><span class="k">try</span><span class="w"> </span><span class="p">{</span>
<span class="w">            </span><span class="c1">//Load the driver.</span>
<span class="w">            </span><span class="n">Class</span><span class="p">.</span><span class="na">forName</span><span class="p">(</span><span class="n">driver</span><span class="p">);</span>
<span class="w">        </span><span class="p">}</span><span class="w"> </span><span class="k">catch</span><span class="w"> </span><span class="p">(</span><span class="n">ClassNotFoundException</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">){</span>
<span class="w">            </span><span class="n">e</span><span class="p">.</span><span class="na">printStackTrace</span><span class="p">();</span>
<span class="w">            </span><span class="k">return</span><span class="w"> </span><span class="kc">null</span><span class="p">;</span>
<span class="w">        </span><span class="p">}</span>
<span class="w">        </span>
<span class="w">        </span><span class="k">try</span><span class="w"> </span><span class="p">{</span>
<span class="w">             </span><span class="c1">//Establish a connection.</span>
<span class="w">            </span><span class="n">conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">DriverManager</span><span class="p">.</span><span class="na">getConnection</span><span class="p">(</span><span class="n">sourceURL</span><span class="p">,</span><span class="w"> </span><span class="n">username</span><span class="p">,</span><span class="w"> </span><span class="n">passwd</span><span class="p">);</span>
<span class="w">            </span><span class="n">System</span><span class="p">.</span><span class="na">out</span><span class="p">.</span><span class="na">println</span><span class="p">(</span><span class="s">&quot;Connection succeed!&quot;</span><span class="p">);</span>
<span class="w">        </span><span class="p">}</span><span class="w"> </span><span class="k">catch</span><span class="w"> </span><span class="p">(</span><span class="n">SQLException</span><span class="w"> </span><span class="n">e</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">            </span><span class="n">e</span><span class="p">.</span><span class="na">printStackTrace</span><span class="p">();</span>
<span class="w">            </span><span class="k">return</span><span class="w"> </span><span class="kc">null</span><span class="p">;</span>
<span class="w">        </span><span class="p">}</span>
<span class="w">        </span>
<span class="w">        </span><span class="k">return</span><span class="w"> </span><span class="n">conn</span><span class="p">;</span>
<span class="w">    </span><span class="p">}</span>
</pre></div></td></tr></table></div>

</div>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="dws_04_0088.html">JDBC-Based Development</a></div>
</div>
</div>