DBLINK_FETCH(3)

💅 dblink_fetch — like, the manual page, bestie

okay so this is dblink_fetch(3), straight out of the PostgreSQL 17.11 docs, and I'm gonna walk you through it like we're texting at 2am 🫶

---

🌸 NAME 🌸

dblink_fetch — returns rows from an open cursor in a remote database. that's it, that's the whole vibe ✨

---

🎀 SYNOPSIS 🎀

dblink_fetch(text cursorname, int howmany [, bool fail_on_error]) returns setof record
dblink_fetch(text connname, text cursorname, int howmany [, bool fail_on_error]) returns setof record

two whole signatures, pick your fighter 💖

---

🦋 DESCRIPTION 🦋

so dblink_fetch fetches rows from a cursor that you already established earlier with dblink_open. like, cursor first, fetch second — that's the order, no skipping steps babe 💅

---

✨ ARGUMENTS ✨

• connname — the name of the connection you wanna use. omit this parameter and it'll use the unnamed connection instead, no big deal 🎀
• cursorname — the name of the cursor you're fetching from. literally the whole point lmao
• howmany — the maximum number of rows to retrieve. the next howmany rows get fetched, starting at the current cursor position, and moving forward. and once the cursor has reached its end, no more rows are produced — it's giving "we're done here" 💀
• fail_on_error — if true (which is the default when you omit 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 instead locally reported as a NOTICE, and the function returns no rows. so like, softer failure, y'know?

---

👑 RETURN VALUE 👑

the function returns the row(s) fetched from the cursor. and to use this function you will need to specify the expected set of columns — exactly like we previously discussed for dblink. don't skip that part, it's not optional, i don't make the rules 🌈

---

⭐ NOTES ⭐

okay so listen, important one 🔥 — if there's a mismatch between the number of return columns you specified in the FROM clause and the actual number of columns returned by the remote cursor, an error will be thrown. and here's the spicy part: in that event, the remote cursor is still advanced by as many rows as it would have been if the error had not occurred 😭 the same is true for any other error occurring in the local query after the remote FETCH has been done. like, the damage is done, the cursor moved, periodt.

---

🌈 EXAMPLES 🌈

first, connect:

SELECT dblink_connect('dbname=postgres options=-csearch_path=');
 dblink_connect
----------------
 OK
(1 row)

then open a cursor named foo:

SELECT dblink_open('foo', 'select proname, prosrc from pg_proc where proname like ''bytea%''');
 dblink_open
-------------
 OK
(1 row)

and now we fetch 5 rows at a time, slay:

SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text);
 funcname |  source
----------+----------
 byteacat | byteacat
 byteacmp | byteacmp
 byteaeq  | byteaeq
 byteage  | byteage
 byteagt  | byteagt
(5 rows)

again ✨:

SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text);
 funcname  |  source
-----------+-----------
 byteain   | byteain
 byteale   | byteale
 bytealike | bytealike
 bytealt   | bytealt
 byteane   | byteane
(5 rows)

again 💖 — and look, only 2 this time:

SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text);
  funcname  |   source
------------+------------
 byteanlike | byteanlike
 byteaout   | byteaout
(2 rows)

and one more time — empty, bestie, the cursor is done 🧚:

SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text);
 funcname | source
----------+--------
(0 rows)

---

ngl the "0 rows" moment is lowkey iconic. cursor said "i have nothing left to give" 💀

---

and that's the whole page! this lil gem was brought to you by PostgreSQL 17.11, dated 2026, and it lives at the address DBLINK_FETCH(3) — go off, king 👑💜