'\" t
.\"     Title: dblink_connect
.\"    Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 2016
.\"    Manual: PostgreSQL 9.5.2 Documentation
.\"    Source: PostgreSQL 9.5.2
.\"  Language: English
.\"
.TH "DBLINK_CONNECT" "3" "2016" "PostgreSQL 9.5.2" "PostgreSQL 9.5.2 Documentation"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
dblink_connect \- opens a persistent connection to a remote database
.SH "SYNOPSIS"
.sp
.nf
dblink_connect(text connstr) returns text
dblink_connect(text connname, text connstr) returns text
.fi
.SH "DESCRIPTION"
.PP

\fBdblink_connect()\fR
establishes a connection to a remote
PostgreSQL
database\&. The server and database to be contacted are identified through a standard
libpq
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\&.
.PP
The connection string may also be the name of an existing foreign server\&. It is recommended to use the foreign\-data wrapper
dblink_fdw
when defining the foreign server\&. See the example below, as well as
CREATE SERVER (\fBCREATE_SERVER\fR(5))
and
CREATE USER MAPPING (\fBCREATE_USER_MAPPING\fR(5))\&.
.SH "ARGUMENTS"
.PP
\fIconnname\fR
.RS 4
The name to use for this connection; if omitted, an unnamed connection is opened, replacing any existing unnamed connection\&.
.RE
.PP
\fIconnstr\fR
.RS 4
libpq\-style connection info string, for example
hostaddr=127\&.0\&.0\&.1 port=5432 dbname=mydb user=postgres password=mypasswd\&. For details see
Section 31.1.1, \(lqConnection Strings\(rq, in the documentation\&. Alternatively, the name of a foreign server\&.
.RE
.SH "RETURN VALUE"
.PP
Returns status, which is always
OK
(since any error causes the function to throw an error instead of returning)\&.
.SH "NOTES"
.PP
Only superusers may use
\fBdblink_connect\fR
to create non\-password\-authenticated connections\&. If non\-superusers need this capability, use
\fBdblink_connect_u\fR
instead\&.
.PP
It is unwise to choose connection names that contain equal signs, as this opens a risk of confusion with connection info strings in other
dblink
functions\&.
.SH "EXAMPLES"
.sp
.if n \{\
.RS 4
.\}
.nf
SELECT dblink_connect(\(aqdbname=postgres\(aq);
 dblink_connect
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 OK
(1 row)

SELECT dblink_connect(\(aqmyconn\(aq, \(aqdbname=postgres\(aq);
 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\(aqs authentication method must be changed\&.

CREATE SERVER fdtest FOREIGN DATA WRAPPER dblink_fdw OPTIONS (hostaddr \(aq127\&.0\&.0\&.1\(aq, dbname \(aqcontrib_regression\(aq);

CREATE USER dblink_regression_test WITH PASSWORD \(aqsecret\(aq;
CREATE USER MAPPING FOR dblink_regression_test SERVER fdtest OPTIONS (user \(aqdblink_regression_test\(aq, password \(aqsecret\(aq);
GRANT USAGE ON FOREIGN SERVER fdtest TO dblink_regression_test;
GRANT SELECT ON TABLE foo TO dblink_regression_test;

\eset ORIGINAL_USER :USER
\ec \- dblink_regression_test
SELECT dblink_connect(\(aqmyconn\(aq, \(aqfdtest\(aq);
 dblink_connect 
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 OK
(1 row)

SELECT * FROM dblink(\(aqmyconn\(aq,\(aqSELECT * FROM foo\(aq) 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)

\ec \- :ORIGINAL_USER
REVOKE USAGE ON FOREIGN SERVER fdtest FROM dblink_regression_test;
REVOKE SELECT ON TABLE foo FROM dblink_regression_test;
DROP USER MAPPING FOR dblink_regression_test SERVER fdtest;
DROP USER dblink_regression_test;
DROP SERVER fdtest;
.fi
.if n \{\
.RE
.\}