DBLINK_EXEC(3)

💅 DBLINK_EXEC(3) — bestie's guide to running commands remotely

okay so real talk: this is the dblink_exec page from the PostgreSQL 13.23 Documentation, and it's lowkey one of the most useful things ever. buckle up 🎀

---

✨ NAME ✨

dblink_exec — executes a command in a remote database. that's it, that's the whole vibe. 👑

---

🦋 SYNOPSIS 🦋

dblink_exec(text connname, text sql [, bool fail_on_error]) returns text
dblink_exec(text connstr, text sql [, bool fail_on_error]) returns text
dblink_exec(text sql [, bool fail_on_error]) returns text

three whole forms, and yes bestie, you do need to know which one you're using 💀

---

🌸 DESCRIPTION 🌸

so dblink_exec executes a command — and by "command" we mean any SQL statement that doesn't return rows — in a remote database. it's giving "i don't want receipts, i just want it done" energy. 🔥

and here's the cute part: when you pass two text arguments, the first one gets looked up as a persistent connection's name first. if it's found, the command runs on that connection, slay. if it's not found, then the first argument gets treated as a connection info string — exactly like the one for dblink_connect — and the indicated connection is made just for the duration of this command. so it's like a little pop-up connection that vanishes when it's done, very main character. ✨

---

🫶 ARGUMENTS 🫶

• connname — the name of the connection to use. omit this parameter and you get the unnamed connection instead, no biggie.
• connstr — a connection info string, as previously described for dblink_connect. it's the whole "where am i going and how do i get in" of it all.
• sql — the SQL command that you wish to execute in the remote database. for example, insert into foo values(0, 'a', '{"a0","b0","c0"}'). look at that nested-quote situation, iykyk 😭
• fail_on_error — if true (which is the default when omitted, so don't even worry about it) then an error thrown on the remote side of the connection causes an error to also be thrown locally. if false, the remote error is locally reported as a NOTICE, and the function's return value is set to ERROR. so basically: drama by default, chill mode on request. 💅

---

👑 RETURN VALUE 👑

returns status, either the command's status string or ERROR. that's the whole deal. 🎀

---

🌈 EXAMPLES 🌈

okay these are iconic, watch closely:

    SELECT dblink_connect('dbname=dblink_test_standby');
     dblink_connect
    ----------------
     OK
    (1 row)

connected, we love to see it ✨ then:

    SELECT dblink_exec('insert into foo values(21, ''z'', ''{"a0","b0","c0"}'');');
       dblink_exec
    -----------------
     INSERT 943366 1
    (1 row)

ate. then we do the named-connection era:

    SELECT dblink_connect('myconn', 'dbname=regression');
     dblink_connect
    ----------------
     OK
    (1 row)

    SELECT dblink_exec('myconn', 'insert into foo values(21, ''z'', ''{"a0","b0","c0"}'');');
       dblink_exec
    ------------------
     INSERT 6432584 1
    (1 row)

and now the chaotic one — fail_on_error set to false, so instead of everything exploding, you get a NOTICE and an ERROR return value: 🙈

    SELECT dblink_exec('myconn', 'insert into pg_class values (''foo'')',false);
    NOTICE:  sql error
    DETAIL:  ERROR:  null value in column "relnamespace" violates not-null constraint

     dblink_exec
    -------------
     ERROR
    (1 row)

see how the vibe stayed intact? no crash, just a lil note. 💀✨

---

word of warning bestie: that false path means the remote error does not blow up locally — it's reported as a NOTICE and the return value becomes ERROR. so if you're checking for success, check the return value, fr fr. 🫶

---

💜 sign-off 💜

that's the whole page, no cap — straight from the PostgreSQL 13.23 Documentation, dated 2025, and yeah the manual page source is DBLINK_EXEC(3). go forth and execute remotely, bestie, you're gonna slay 🧚🌸