begriffs open source - ai-pg/blob - full-docs/man3/dblink_connect.3

   1 '\" t
   2 .\"     Title: dblink_connect
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "DBLINK_CONNECT" "3" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 dblink_connect \- opens a persistent connection to a remote database
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 dblink_connect(text connstr) returns text
  36 dblink_connect(text connname, text connstr) returns text
  37 .fi
  38 .SH "DESCRIPTION"
  39 .PP
  40 \fBdblink_connect()\fR
  41 establishes a connection to a remote
  42 PostgreSQL
  43 database\&. The server and database to be contacted are identified through a standard
  44 libpq
  45 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\&.
  46 .PP
  47 The connection string may also be the name of an existing foreign server\&. It is recommended to use the foreign\-data wrapper
  48 dblink_fdw
  49 when defining the foreign server\&. See the example below, as well as
  50 CREATE SERVER (\fBCREATE_SERVER\fR(7))
  51 and
  52 CREATE USER MAPPING (\fBCREATE_USER_MAPPING\fR(7))\&.
  53 .SH "ARGUMENTS"
  54 .PP
  55 \fIconnname\fR
  56 .RS 4
  57 The name to use for this connection; if omitted, an unnamed connection is opened, replacing any existing unnamed connection\&.
  58 .RE
  59 .PP
  60 \fIconnstr\fR
  61 .RS 4
  62 libpq\-style connection info string, for example
  63 hostaddr=127\&.0\&.0\&.1 port=5432 dbname=mydb user=postgres password=mypasswd options=\-csearch_path=\&. For details see
  64 Section\ \&32.1.1\&. Alternatively, the name of a foreign server\&.
  65 .RE
  66 .SH "RETURN VALUE"
  67 .PP
  68 Returns status, which is always
  69 OK
  70 (since any error causes the function to throw an error instead of returning)\&.
  71 .SH "NOTES"
  72 .PP
  73 If untrusted users have access to a database that has not adopted a
  74 secure schema usage pattern, begin each session by removing publicly\-writable schemas from
  75 \fIsearch_path\fR\&. One could, for example, add
  76 options=\-csearch_path=
  77 to
  78 \fIconnstr\fR\&. This consideration is not specific to
  79 dblink; it applies to every interface for executing arbitrary SQL commands\&.
  80 .PP
  81 The foreign\-data wrapper
  82 dblink_fdw
  83 has an additional Boolean option
  84 use_scram_passthrough
  85 that controls whether
  86 dblink
  87 will use the SCRAM pass\-through authentication to connect to the remote database\&. With SCRAM pass\-through authentication,
  88 dblink
  89 uses SCRAM\-hashed secrets instead of plain\-text user passwords to connect to the remote server\&. This avoids storing plain\-text user passwords in PostgreSQL system catalogs\&. See the documentation of the equivalent
  90 use_scram_passthrough
  91 option of postgres_fdw for further details and restrictions\&.
  92 .PP
  93 Only superusers may use
  94 \fBdblink_connect\fR
  95 to create connections that use neither password authentication, SCRAM pass\-through, nor GSSAPI\-authentication\&. If non\-superusers need this capability, use
  96 \fBdblink_connect_u\fR
  97 instead\&.
  98 .PP
  99 It is unwise to choose connection names that contain equal signs, as this opens a risk of confusion with connection info strings in other
 100 dblink
 101 functions\&.
 102 .SH "EXAMPLES"
 103 .sp
 104 .if n \{\
 105 .RS 4
 106 .\}
 107 .nf
 108 SELECT dblink_connect(\*(Aqdbname=postgres options=\-csearch_path=\*(Aq);
 109  dblink_connect
 110 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 111  OK
 112 (1 row)
 113
 114 SELECT dblink_connect(\*(Aqmyconn\*(Aq, \*(Aqdbname=postgres options=\-csearch_path=\*(Aq);
 115  dblink_connect
 116 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 117  OK
 118 (1 row)
 119
 120 \-\- FOREIGN DATA WRAPPER functionality
 121 \-\- Note: local connections that don\*(Aqt use SCRAM pass\-through require password
 122 \-\-       authentication for this to work properly\&. Otherwise, you will receive
 123 \-\-       the following error from dblink_connect():
 124 \-\-       ERROR:  password is required
 125 \-\-       DETAIL:  Non\-superuser cannot connect if the server does not request a password\&.
 126 \-\-       HINT:  Target server\*(Aqs authentication method must be changed\&.
 127
 128 CREATE SERVER fdtest FOREIGN DATA WRAPPER dblink_fdw OPTIONS (hostaddr \*(Aq127\&.0\&.0\&.1\*(Aq, dbname \*(Aqcontrib_regression\*(Aq);
 129
 130 CREATE USER regress_dblink_user WITH PASSWORD \*(Aqsecret\*(Aq;
 131 CREATE USER MAPPING FOR regress_dblink_user SERVER fdtest OPTIONS (user \*(Aqregress_dblink_user\*(Aq, password \*(Aqsecret\*(Aq);
 132 GRANT USAGE ON FOREIGN SERVER fdtest TO regress_dblink_user;
 133 GRANT SELECT ON TABLE foo TO regress_dblink_user;
 134
 135 \eset ORIGINAL_USER :USER
 136 \ec \- regress_dblink_user
 137 SELECT dblink_connect(\*(Aqmyconn\*(Aq, \*(Aqfdtest\*(Aq);
 138  dblink_connect
 139 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 140  OK
 141 (1 row)
 142
 143 SELECT * FROM dblink(\*(Aqmyconn\*(Aq, \*(AqSELECT * FROM foo\*(Aq) AS t(a int, b text, c text[]);
 144  a  | b |       c
 145 \-\-\-\-+\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 146   0 | a | {a0,b0,c0}
 147   1 | b | {a1,b1,c1}
 148   2 | c | {a2,b2,c2}
 149   3 | d | {a3,b3,c3}
 150   4 | e | {a4,b4,c4}
 151   5 | f | {a5,b5,c5}
 152   6 | g | {a6,b6,c6}
 153   7 | h | {a7,b7,c7}
 154   8 | i | {a8,b8,c8}
 155   9 | j | {a9,b9,c9}
 156  10 | k | {a10,b10,c10}
 157 (11 rows)
 158
 159 \ec \- :ORIGINAL_USER
 160 REVOKE USAGE ON FOREIGN SERVER fdtest FROM regress_dblink_user;
 161 REVOKE SELECT ON TABLE foo FROM regress_dblink_user;
 162 DROP USER MAPPING FOR regress_dblink_user SERVER fdtest;
 163 DROP USER regress_dblink_user;
 164 DROP SERVER fdtest;
 165 .fi
 166 .if n \{\
 167 .RE
 168 .\}