begriffs open source - ai-pg/blob - full-docs/man3/dblink_fetch.3

   1 '\" t
   2 .\"     Title: dblink_fetch
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "DBLINK_FETCH" "3" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 dblink_fetch \- returns rows from an open cursor in a remote database
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 dblink_fetch(text cursorname, int howmany [, bool fail_on_error]) returns setof record
  36 dblink_fetch(text connname, text cursorname, int howmany [, bool fail_on_error]) returns setof record
  37 .fi
  38 .SH "DESCRIPTION"
  39 .PP
  40 \fBdblink_fetch\fR
  41 fetches rows from a cursor previously established by
  42 \fBdblink_open\fR\&.
  43 .SH "ARGUMENTS"
  44 .PP
  45 \fIconnname\fR
  46 .RS 4
  47 Name of the connection to use; omit this parameter to use the unnamed connection\&.
  48 .RE
  49 .PP
  50 \fIcursorname\fR
  51 .RS 4
  52 The name of the cursor to fetch from\&.
  53 .RE
  54 .PP
  55 \fIhowmany\fR
  56 .RS 4
  57 The maximum number of rows to retrieve\&. The next
  58 \fIhowmany\fR
  59 rows are fetched, starting at the current cursor position, moving forward\&. Once the cursor has reached its end, no more rows are produced\&.
  60 .RE
  61 .PP
  62 \fIfail_on_error\fR
  63 .RS 4
  64 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\&.
  65 .RE
  66 .SH "RETURN VALUE"
  67 .PP
  68 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
  69 \fBdblink\fR\&.
  70 .SH "NOTES"
  71 .PP
  72 On a mismatch between the number of return columns specified in the
  73 FROM
  74 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
  75 \fBFETCH\fR
  76 has been done\&.
  77 .SH "EXAMPLES"
  78 .sp
  79 .if n \{\
  80 .RS 4
  81 .\}
  82 .nf
  83 SELECT dblink_connect(\*(Aqdbname=postgres options=\-csearch_path=\*(Aq);
  84  dblink_connect
  85 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
  86  OK
  87 (1 row)
  88
  89 SELECT dblink_open(\*(Aqfoo\*(Aq, \*(Aqselect proname, prosrc from pg_proc where proname like \*(Aq\*(Aqbytea%\*(Aq\*(Aq\*(Aq);
  90  dblink_open
  91 \-\-\-\-\-\-\-\-\-\-\-\-\-
  92  OK
  93 (1 row)
  94
  95 SELECT * FROM dblink_fetch(\*(Aqfoo\*(Aq, 5) AS (funcname name, source text);
  96  funcname |  source
  97 \-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-
  98  byteacat | byteacat
  99  byteacmp | byteacmp
 100  byteaeq  | byteaeq
 101  byteage  | byteage
 102  byteagt  | byteagt
 103 (5 rows)
 104
 105 SELECT * FROM dblink_fetch(\*(Aqfoo\*(Aq, 5) AS (funcname name, source text);
 106  funcname  |  source
 107 \-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-
 108  byteain   | byteain
 109  byteale   | byteale
 110  bytealike | bytealike
 111  bytealt   | bytealt
 112  byteane   | byteane
 113 (5 rows)
 114
 115 SELECT * FROM dblink_fetch(\*(Aqfoo\*(Aq, 5) AS (funcname name, source text);
 116   funcname  |   source
 117 \-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-
 118  byteanlike | byteanlike
 119  byteaout   | byteaout
 120 (2 rows)
 121
 122 SELECT * FROM dblink_fetch(\*(Aqfoo\*(Aq, 5) AS (funcname name, source text);
 123  funcname | source
 124 \-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-
 125 (0 rows)
 126 .fi
 127 .if n \{\
 128 .RE
 129 .\}