DBLINK_CONNECT(3)

💖 NAME 💖

okay so bestie, this is the dblink_connect page from the PostgreSQL 17.11 docs, and it's literally all about opening a persistent connection to a remote database. no cap, it's a whole vibe. 💅✨

---

✨ SYNOPSIS ✨

       dblink_connect(text connstr) returns text
       dblink_connect(text connname, text connstr) returns text

🌸 DESCRIPTION 🌸

okay so dblink_connect() establishes a connection to a remote PostgreSQL database. the server and database you're contacting are identified through a standard libpq connection string. optionally, you can assign a name 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 it's closed or until the database session ends. periodt. ✨

and get this: the connection string can also be the name of an existing foreign server. it's recommended to use the foreign-data wrapper dblink_fdw when defining the foreign server. see the example below, and also check out CREATE SERVER (CREATE_SERVER(7)) and CREATE USER MAPPING (CREATE_USER_MAPPING(7)). 💅

🎀 ARGUMENTS 🎀

• connname — the name to use for this connection. if you omit it, an unnamed connection is opened, replacing any existing unnamed connection. 🙈
• connstr — libpq-style connection info string, for example hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres password=mypasswd options=-csearch_path=. for details see Section 32.1.1. alternatively, the name of a foreign server. 🌈

⭐ RETURN VALUE ⭐

returns status, which is always OK (since any error causes the function to throw an error instead of returning). so like, if it doesn't throw, you're golden. 💖

🔥 NOTES 🔥

okay so if untrusted users have access to a database that hasn't adopted a secure schema usage pattern, begin each session by removing publicly-writable schemas from search_path. one could, for example, add options=-csearch_path= to connstr. this consideration is not specific to dblink; it applies to every interface for executing arbitrary SQL commands. so like, be careful bestie. 😭

only superusers may use dblink_connect to create non-password-authenticated and non-GSSAPI-authenticated connections. if non-superusers need this capability, use dblink_connect_u instead. no cap, that's the rule. 👑

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. so maybe don't do that? just saying. 💀

🦋 EXAMPLES 🦋

           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;

---

and that's the tea, bestie! this page is from PostgreSQL 17.11, dated 2026, and it's the dblink_connect(3) manual page. stay connected! 💖✨🦋