diff options
Diffstat (limited to 'doc/src/sgml/man3/dblink_get_result.3')
| -rw-r--r-- | doc/src/sgml/man3/dblink_get_result.3 | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/doc/src/sgml/man3/dblink_get_result.3 b/doc/src/sgml/man3/dblink_get_result.3 new file mode 100644 index 0000000..951a233 --- /dev/null +++ b/doc/src/sgml/man3/dblink_get_result.3 @@ -0,0 +1,143 @@ +'\" t +.\" Title: dblink_get_result +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DBLINK_GET_RESULT" "3" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +dblink_get_result \- gets an async query result +.SH "SYNOPSIS" +.sp +.nf +dblink_get_result(text connname [, bool fail_on_error]) returns setof record +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_get_result\fR +collects the results of an asynchronous query previously sent with +\fBdblink_send_query\fR\&. If the query is not already completed, +\fBdblink_get_result\fR +will wait until it is\&. +.SH "ARGUMENTS" +.PP +\fIconnname\fR +.RS 4 +Name of the connection to use\&. +.RE +.PP +\fIfail_on_error\fR +.RS 4 +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\&. +.RE +.SH "RETURN VALUE" +.PP +For an async query (that is, an SQL statement returning rows), the function returns the row(s) produced by the query\&. To use this function, you will need to specify the expected set of columns, as previously discussed for +\fBdblink\fR\&. +.PP +For an async command (that is, an SQL statement not returning rows), the function returns a single row with a single text column containing the command\*(Aqs status string\&. It is still necessary to specify that the result will have a single text column in the calling +FROM +clause\&. +.SH "NOTES" +.PP +This function +\fImust\fR +be called if +\fBdblink_send_query\fR +returned 1\&. It must be called once for each query sent, and one additional time to obtain an empty set result, before the connection can be used again\&. +.PP +When using +\fBdblink_send_query\fR +and +\fBdblink_get_result\fR, +dblink +fetches the entire remote query result before returning any of it to the local query processor\&. If the query returns a large number of rows, this can result in transient memory bloat in the local session\&. It may be better to open such a query as a cursor with +\fBdblink_open\fR +and then fetch a manageable number of rows at a time\&. Alternatively, use plain +\fBdblink()\fR, which avoids memory bloat by spooling large result sets to disk\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +contrib_regression=# SELECT dblink_connect(\*(Aqdtest1\*(Aq, \*(Aqdbname=contrib_regression\*(Aq); + dblink_connect +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) + +contrib_regression=# SELECT * FROM +contrib_regression\-# dblink_send_query(\*(Aqdtest1\*(Aq, \*(Aqselect * from foo where f1 < 3\*(Aq) AS t1; + t1 +\-\-\-\- + 1 +(1 row) + +contrib_regression=# SELECT * FROM dblink_get_result(\*(Aqdtest1\*(Aq) AS t1(f1 int, f2 text, f3 text[]); + f1 | f2 | f3 +\-\-\-\-+\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\- + 0 | a | {a0,b0,c0} + 1 | b | {a1,b1,c1} + 2 | c | {a2,b2,c2} +(3 rows) + +contrib_regression=# SELECT * FROM dblink_get_result(\*(Aqdtest1\*(Aq) AS t1(f1 int, f2 text, f3 text[]); + f1 | f2 | f3 +\-\-\-\-+\-\-\-\-+\-\-\-\- +(0 rows) + +contrib_regression=# SELECT * FROM +contrib_regression\-# dblink_send_query(\*(Aqdtest1\*(Aq, \*(Aqselect * from foo where f1 < 3; select * from foo where f1 > 6\*(Aq) AS t1; + t1 +\-\-\-\- + 1 +(1 row) + +contrib_regression=# SELECT * FROM dblink_get_result(\*(Aqdtest1\*(Aq) AS t1(f1 int, f2 text, f3 text[]); + f1 | f2 | f3 +\-\-\-\-+\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\- + 0 | a | {a0,b0,c0} + 1 | b | {a1,b1,c1} + 2 | c | {a2,b2,c2} +(3 rows) + +contrib_regression=# SELECT * FROM dblink_get_result(\*(Aqdtest1\*(Aq) AS t1(f1 int, f2 text, f3 text[]); + f1 | f2 | f3 +\-\-\-\-+\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 7 | h | {a7,b7,c7} + 8 | i | {a8,b8,c8} + 9 | j | {a9,b9,c9} + 10 | k | {a10,b10,c10} +(4 rows) + +contrib_regression=# SELECT * FROM dblink_get_result(\*(Aqdtest1\*(Aq) AS t1(f1 int, f2 text, f3 text[]); + f1 | f2 | f3 +\-\-\-\-+\-\-\-\-+\-\-\-\- +(0 rows) +.fi +.if n \{\ +.RE +.\} |