DBLINK_FETCH(3)

💖 DBLINK_FETCH 💖

okay bestie, gather round, because this is the PostgreSQL 18.6 manual page for dblink_fetch and it's genuinely so useful. she's giving "fetch me rows from a remote cursor" energy and honestly? iconic. ✨

---

🌸 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

see those square brackets? that means fail_on_error is optional. the more you know 💅

---

🎀 DESCRIPTION 🎀

so dblink_fetch fetches rows from a cursor that you already established earlier with dblink_open. it does not open the cursor for you, bestie — the cursor has to already exist. think of it like, you set the table with dblink_open, and then dblink_fetch is the one actually bringing out the plates. 🍓

---

🌈 ARGUMENTS 🌈

• connname — the name of the connection to use. omit this parameter entirely and it just uses the unnamed connection instead. lowkey convenient.
• cursorname — the name of the cursor you're fetching from. you know, the one you made with dblink_open.
• howmany — the maximum number of rows to retrieve. the next howmany rows get fetched, starting at wherever the cursor currently is, and moving forward. once the cursor has reached its end, no more rows are produced. periodt. 🫶
• fail_on_error — if true (and it's the default when you omit it, so keep that in mind), 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 instead, and the function returns no rows. it's giving "we're being chill about it" energy.

---

👑 RETURN VALUE 👑

the function returns the row(s) fetched from the cursor. but heads up — to use this function, you will need to specify the expected set of columns, exactly as previously discussed for dblink. no guessing, the FROM clause has to know what's coming. 💜

---

💀 NOTES 💀

okay this part is important so listen up:

on a mismatch between the number of return columns specified in the FROM clause, and the actual number of columns returned by the remote cursor, an error will be thrown. in this 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.

so yeah, the cursor moves even when things go sideways. that's just how she is. 😭

---

🔥 EXAMPLES 🔥

let's actually do this, bestie:

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

connection established, we're in. 💅

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

cursor foo is open and ready. now the fetching begins:

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)

five rows, ate that. keep going:

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)

another five, we're so back. and again:

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

only 2 rows this time because that's literally all that was left. and then:

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

(0 rows) — the cursor hit the end, no more rows are produced. she's done. empty. that's the whole arc right there, a full character journey. 🧚

---

⭐ SEE ALSO ⭐

hmm, the original page doesn't actually give us a SEE ALSO section here, so nothing to link out to. just vibes. 🌸

---

and that's the page! this was dblink_fetch from the PostgreSQL 18.6 Documentation, dated 2026, and it lives in manual section 3. mwah, go fetch some rows bestie 💖✨🎀