DBLINK_FETCH(3)

✨ NAME ✨

okay bestie, welcome to DBLINK_FETCH(3) from the PostgreSQL 16.15 Documentation! 💅 This one is all about dblink_fetch — returns rows from an open cursor in a remote database. yes, remote cursor row-fetching realness. 🦋

🦋 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

💖 DESCRIPTION 💖

dblink_fetch fetches rows from a cursor previously established by dblink_open. That's the whole vibe: you opened a cursor remotely, now you're grabbing the next batch of rows. no cap. ✨

🎀 ARGUMENTS 🎀

• connname — name of the connection to use; omit this parameter to use the unnamed connection. 👑
• cursorname — the name of the cursor to fetch from. 🎯
• howmany — the maximum number of rows to retrieve. The next howmany rows are fetched, starting at the current cursor position, moving forward. Once the cursor has reached its end, no more rows are produced. literally the row budget. 🍓
• fail_on_error — if true (the default when omitted) 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 returns no rows. 😭 so true = loud local error, false = notice plus zero rows.

🌈 RETURN VALUE 🌈

The function returns the row(s) fetched from the cursor. To use this function, you will need to specify the expected set of columns, as previously discussed for dblink. 💖 iykyk: declare that expected set of columns, just like we talked about for dblink.

🔥 NOTES 🔥

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 yes, the cursor can move even when things go sideways — noted, bestie.

🧚 EXAMPLES 🧚

here's the full example block, verbatim, because we do not mess with commands and output around here 💅:

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

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

           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)

           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)

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

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

that's the whole page, bestie! this manual page is from PostgreSQL 16.15, dated 2026, and its name is DBLINK_FETCH(3). mwah 💅🎀🦋