<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >dblink_connect</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK REV="MADE" HREF="mailto:pgsql-docs@postgresql.org"><LINK REL="HOME" TITLE="PostgreSQL 9.6.19 Documentation" HREF="index.html"><LINK REL="UP" TITLE="dblink" HREF="dblink.html"><LINK REL="PREVIOUS" TITLE="dblink" HREF="dblink.html"><LINK REL="NEXT" TITLE="dblink_connect_u" HREF="contrib-dblink-connect-u.html"><LINK REL="STYLESHEET" TYPE="text/css" HREF="stylesheet.css"><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"><META NAME="creation" CONTENT="2020-09-02T07:27:19"></HEAD ><BODY CLASS="REFENTRY" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="4" ALIGN="center" VALIGN="bottom" ><A HREF="index.html" >PostgreSQL 9.6.19 Documentation</A ></TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A TITLE="dblink" HREF="dblink.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A HREF="dblink.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="60%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="20%" ALIGN="right" VALIGN="top" ><A TITLE="dblink_connect_u" HREF="contrib-dblink-connect-u.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><H1 ><A NAME="CONTRIB-DBLINK-CONNECT" ></A >dblink_connect</H1 ><DIV CLASS="REFNAMEDIV" ><A NAME="AEN137185" ></A ><H2 >Name</H2 >dblink_connect -- opens a persistent connection to a remote database</DIV ><DIV CLASS="REFSYNOPSISDIV" ><A NAME="AEN137188" ></A ><H2 >Synopsis</H2 ><PRE CLASS="SYNOPSIS" >dblink_connect(text connstr) returns text dblink_connect(text connname, text connstr) returns text</PRE ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN137190" ></A ><H2 >Description</H2 ><P > <CODE CLASS="FUNCTION" >dblink_connect()</CODE > establishes a connection to a remote <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > database. The server and database to be contacted are identified through a standard <SPAN CLASS="APPLICATION" >libpq</SPAN > connection string. Optionally, a name can be assigned to the connection. Multiple named connections can be open at once, but only one unnamed connection is permitted at a time. The connection will persist until closed or until the database session is ended. </P ><P > The connection string may also be the name of an existing foreign server. It is recommended to use the foreign-data wrapper <TT CLASS="LITERAL" >dblink_fdw</TT > when defining the foreign server. See the example below, as well as <A HREF="sql-createserver.html" >CREATE SERVER</A > and <A HREF="sql-createusermapping.html" >CREATE USER MAPPING</A >. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN137200" ></A ><H2 >Arguments</H2 ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT ><TT CLASS="PARAMETER" >connname</TT ></DT ><DD ><P > The name to use for this connection; if omitted, an unnamed connection is opened, replacing any existing unnamed connection. </P ></DD ><DT ><TT CLASS="PARAMETER" >connstr</TT ></DT ><DD ><P ><SPAN CLASS="APPLICATION" >libpq</SPAN >-style connection info string, for example <TT CLASS="LITERAL" >hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres password=mypasswd options=-csearch_path=</TT >. For details see <A HREF="libpq-connect.html#LIBPQ-CONNSTRING" >Section 32.1.1</A >. Alternatively, the name of a foreign server. </P ></DD ></DL ></DIV ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN137216" ></A ><H2 >Return Value</H2 ><P > Returns status, which is always <TT CLASS="LITERAL" >OK</TT > (since any error causes the function to throw an error instead of returning). </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN137220" ></A ><H2 >Notes</H2 ><P > If untrusted users have access to a database that has not adopted a <A HREF="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" >secure schema usage pattern</A >, begin each session by removing publicly-writable schemas from <TT CLASS="VARNAME" >search_path</TT >. One could, for example, add <TT CLASS="LITERAL" >options=-csearch_path=</TT > to <TT CLASS="PARAMETER" >connstr</TT >. This consideration is not specific to <TT CLASS="FILENAME" >dblink</TT >; it applies to every interface for executing arbitrary SQL commands. </P ><P > Only superusers may use <CODE CLASS="FUNCTION" >dblink_connect</CODE > to create non-password-authenticated connections. If non-superusers need this capability, use <CODE CLASS="FUNCTION" >dblink_connect_u</CODE > instead. </P ><P > It is unwise to choose connection names that contain equal signs, as this opens a risk of confusion with connection info strings in other <TT CLASS="FILENAME" >dblink</TT > functions. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN137233" ></A ><H2 >Examples</H2 ><PRE CLASS="SCREEN" >SELECT dblink_connect('dbname=postgres options=-csearch_path='); dblink_connect ---------------- OK (1 row) SELECT dblink_connect('myconn', 'dbname=postgres options=-csearch_path='); dblink_connect ---------------- OK (1 row) -- FOREIGN DATA WRAPPER functionality -- Note: local connection must require password authentication for this to work properly -- Otherwise, you will receive the following error from dblink_connect(): -- ---------------------------------------------------------------------- -- ERROR: password is required -- DETAIL: Non-superuser cannot connect if the server does not request a password. -- HINT: Target server's authentication method must be changed. CREATE SERVER fdtest FOREIGN DATA WRAPPER dblink_fdw OPTIONS (hostaddr '127.0.0.1', dbname 'contrib_regression'); CREATE USER regress_dblink_user WITH PASSWORD 'secret'; CREATE USER MAPPING FOR regress_dblink_user SERVER fdtest OPTIONS (user 'regress_dblink_user', password 'secret'); GRANT USAGE ON FOREIGN SERVER fdtest TO regress_dblink_user; GRANT SELECT ON TABLE foo TO regress_dblink_user; \set ORIGINAL_USER :USER \c - regress_dblink_user SELECT dblink_connect('myconn', 'fdtest'); dblink_connect ---------------- OK (1 row) SELECT * FROM dblink('myconn','SELECT * FROM foo') AS t(a int, b text, c text[]); a | b | c ----+---+--------------- 0 | a | {a0,b0,c0} 1 | b | {a1,b1,c1} 2 | c | {a2,b2,c2} 3 | d | {a3,b3,c3} 4 | e | {a4,b4,c4} 5 | f | {a5,b5,c5} 6 | g | {a6,b6,c6} 7 | h | {a7,b7,c7} 8 | i | {a8,b8,c8} 9 | j | {a9,b9,c9} 10 | k | {a10,b10,c10} (11 rows) \c - :ORIGINAL_USER REVOKE USAGE ON FOREIGN SERVER fdtest FROM regress_dblink_user; REVOKE SELECT ON TABLE foo FROM regress_dblink_user; DROP USER MAPPING FOR regress_dblink_user SERVER fdtest; DROP USER regress_dblink_user; DROP SERVER fdtest;</PRE ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="dblink.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="contrib-dblink-connect-u.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >dblink</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="dblink.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >dblink_connect_u</TD ></TR ></TABLE ></DIV ></BODY ></HTML >