DBLINK_EXEC(3)

💅 DBLINK_EXEC(3) — the PostgreSQL 17.11 glow-up

okay so bestie, buckle up, because this is dblink_exec from the PostgreSQL 17.11 Documentation and she is that girl. no preamble needed, let's go 🫶

---

✨ NAME ✨

dblink_exec — executes a command in a remote database 🌈

---

🎀 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

like, three whole signatures. pick your fighter 💅

---

🦋 DESCRIPTION 🦋

okay so dblink_exec executes a command in a remote database. and by "command" we mean any SQL statement that doesn't return rows — no rows coming back, she just goes and does the thing. periodt. ✨

and here's the vibe check on how it picks where to run: when you give it two text arguments, the first one is first looked up as a persistent connection's name. if it's found, the command is executed on that connection. if it's not found, then that first argument gets treated as a connection info string, just like for dblink_connect, and the indicated connection is made just for the duration of this command — like a little pop-up connection, here for a good time not a long time 🧚

---

💖 ARGUMENTS 💖

• connname — the name of the connection to use. literally just omit this parameter if you wanna use the unnamed connection. no cap. 🎀
• connstr — a connection info string, as previously described for dblink_connect. iykyk 🔥
• sql — the SQL command that you wish to execute in the remote database, for example insert into foo values(0, 'a', '{"a0","b0","c0"}'). yes bestie, that's the shape of it 💜
• fail_on_error — if true (and that's the default when omitted, queen of defaults 👑) 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 like, you do still hear about it, she's just quieter about it 🙈

---

⭐ RETURN VALUE ⭐

Returns status — either the command's status string or ERROR. that's it, that's the whole tea ☕

---

🌸 EXAMPLES 🌸

here's where she really ate, look at these:

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

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

    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)

    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 last one has false for fail_on_error? remote error shows up as a NOTICE with a DETAIL, and the return value is ERROR. she told you, she just didn't scream it 😭💀

real talk: that last example is the one to remember — fail_on_error set to false means the remote error does not blow up locally, it gets reported as a NOTICE and ERROR comes back as the return value. lowkey iconic behavior 💅

---

🍓 SEE ALSO 🍓

hmm, this page doesn't give us a SEE ALSO section, so like... that's the whole page bestie, go forth and execute 🦋

---

and that's the whole thing, mwah 💋 — this was DBLINK_EXEC(3), signed off from PostgreSQL 17.11, dated 2026, and proud of it 👑✨