diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-04 12:17:33 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-04 12:17:33 +0000 |
| commit | 5e45211a64149b3c659b90ff2de6fa982a5a93ed (patch) | |
| tree | 739caf8c461053357daa9f162bef34516c7bf452 /doc/src/sgml/man3 | |
| parent | Initial commit. (diff) | |
| download | postgresql-15-5e45211a64149b3c659b90ff2de6fa982a5a93ed.tar.xz postgresql-15-5e45211a64149b3c659b90ff2de6fa982a5a93ed.zip | |
Adding upstream version 15.5.upstream/15.5
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/src/sgml/man3')
75 files changed, 6317 insertions, 0 deletions
diff --git a/doc/src/sgml/man3/SPI_commit.3 b/doc/src/sgml/man3/SPI_commit.3 new file mode 100644 index 0000000..f99d516 --- /dev/null +++ b/doc/src/sgml/man3/SPI_commit.3 @@ -0,0 +1,52 @@ +'\" t +.\" Title: SPI_commit +.\" 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 "SPI_COMMIT" "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" +SPI_commit, SPI_commit_and_chain \- commit the current transaction +.SH "SYNOPSIS" +.sp +.nf +void SPI_commit(void) +.fi +.sp +.nf +void SPI_commit_and_chain(void) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_commit\fR +commits the current transaction\&. It is approximately equivalent to running the SQL command +\fBCOMMIT\fR\&. After the transaction is committed, a new transaction is automatically started using default transaction characteristics, so that the caller can continue using SPI facilities\&. If there is a failure during commit, the current transaction is instead rolled back and a new transaction is started, after which the error is thrown in the usual way\&. +.PP +\fBSPI_commit_and_chain\fR +is the same, but the new transaction is started with the same transaction characteristics as the just finished one, like with the SQL command +\fBCOMMIT AND CHAIN\fR\&. +.PP +These functions can only be executed if the SPI connection has been set as nonatomic in the call to +\fBSPI_connect_ext\fR\&. diff --git a/doc/src/sgml/man3/SPI_commit_and_chain.3 b/doc/src/sgml/man3/SPI_commit_and_chain.3 new file mode 100644 index 0000000..c127b9c --- /dev/null +++ b/doc/src/sgml/man3/SPI_commit_and_chain.3 @@ -0,0 +1 @@ +.so man3/SPI_commit.3 diff --git a/doc/src/sgml/man3/SPI_connect.3 b/doc/src/sgml/man3/SPI_connect.3 new file mode 100644 index 0000000..6fa03d1 --- /dev/null +++ b/doc/src/sgml/man3/SPI_connect.3 @@ -0,0 +1,69 @@ +'\" t +.\" Title: SPI_connect +.\" 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 "SPI_CONNECT" "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" +SPI_connect, SPI_connect_ext \- connect a C function to the SPI manager +.SH "SYNOPSIS" +.sp +.nf +int SPI_connect(void) +.fi +.sp +.nf +int SPI_connect_ext(int \fIoptions\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_connect\fR +opens a connection from a C function invocation to the SPI manager\&. You must call this function if you want to execute commands through SPI\&. Some utility SPI functions can be called from unconnected C functions\&. +.PP +\fBSPI_connect_ext\fR +does the same but has an argument that allows passing option flags\&. Currently, the following option values are available: +.PP +SPI_OPT_NONATOMIC +.RS 4 +Sets the SPI connection to be +nonatomic, which means that transaction control calls (\fBSPI_commit\fR, +\fBSPI_rollback\fR) are allowed\&. Otherwise, calling those functions will result in an immediate error\&. +.RE +.PP +SPI_connect() +is equivalent to +SPI_connect_ext(0)\&. +.SH "RETURN VALUE" +.PP +SPI_OK_CONNECT +.RS 4 +on success +.RE +.PP +SPI_ERROR_CONNECT +.RS 4 +on error +.RE diff --git a/doc/src/sgml/man3/SPI_connect_ext.3 b/doc/src/sgml/man3/SPI_connect_ext.3 new file mode 100644 index 0000000..51f12f5 --- /dev/null +++ b/doc/src/sgml/man3/SPI_connect_ext.3 @@ -0,0 +1 @@ +.so man3/SPI_connect.3 diff --git a/doc/src/sgml/man3/SPI_copytuple.3 b/doc/src/sgml/man3/SPI_copytuple.3 new file mode 100644 index 0000000..c764804 --- /dev/null +++ b/doc/src/sgml/man3/SPI_copytuple.3 @@ -0,0 +1,60 @@ +'\" t +.\" Title: SPI_copytuple +.\" 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 "SPI_COPYTUPLE" "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" +SPI_copytuple \- make a copy of a row in the upper executor context +.SH "SYNOPSIS" +.sp +.nf +HeapTuple SPI_copytuple(HeapTuple \fIrow\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_copytuple\fR +makes a copy of a row in the upper executor context\&. This is normally used to return a modified row from a trigger\&. In a function declared to return a composite type, use +\fBSPI_returntuple\fR +instead\&. +.PP +This function can only be used while connected to SPI\&. Otherwise, it returns NULL and sets +\fISPI_result\fR +to +SPI_ERROR_UNCONNECTED\&. +.SH "ARGUMENTS" +.PP +HeapTuple \fIrow\fR +.RS 4 +row to be copied +.RE +.SH "RETURN VALUE" +.PP +the copied row, or +NULL +on error (see +\fISPI_result\fR +for an error indication) diff --git a/doc/src/sgml/man3/SPI_cursor_close.3 b/doc/src/sgml/man3/SPI_cursor_close.3 new file mode 100644 index 0000000..6b13081 --- /dev/null +++ b/doc/src/sgml/man3/SPI_cursor_close.3 @@ -0,0 +1,50 @@ +'\" t +.\" Title: SPI_cursor_close +.\" 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 "SPI_CURSOR_CLOSE" "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" +SPI_cursor_close \- close a cursor +.SH "SYNOPSIS" +.sp +.nf +void SPI_cursor_close(Portal \fIportal\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_cursor_close\fR +closes a previously created cursor and releases its portal storage\&. +.PP +All open cursors are closed automatically at the end of a transaction\&. +\fBSPI_cursor_close\fR +need only be invoked if it is desirable to release resources sooner\&. +.SH "ARGUMENTS" +.PP +Portal \fIportal\fR +.RS 4 +portal containing the cursor +.RE diff --git a/doc/src/sgml/man3/SPI_cursor_fetch.3 b/doc/src/sgml/man3/SPI_cursor_fetch.3 new file mode 100644 index 0000000..ce26633 --- /dev/null +++ b/doc/src/sgml/man3/SPI_cursor_fetch.3 @@ -0,0 +1,73 @@ +'\" t +.\" Title: SPI_cursor_fetch +.\" 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 "SPI_CURSOR_FETCH" "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" +SPI_cursor_fetch \- fetch some rows from a cursor +.SH "SYNOPSIS" +.sp +.nf +void SPI_cursor_fetch(Portal \fIportal\fR, bool \fIforward\fR, long \fIcount\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_cursor_fetch\fR +fetches some rows from a cursor\&. This is equivalent to a subset of the SQL command +\fBFETCH\fR +(see +\fBSPI_scroll_cursor_fetch\fR +for more functionality)\&. +.SH "ARGUMENTS" +.PP +Portal \fIportal\fR +.RS 4 +portal containing the cursor +.RE +.PP +bool \fIforward\fR +.RS 4 +true for fetch forward, false for fetch backward +.RE +.PP +long \fIcount\fR +.RS 4 +maximum number of rows to fetch +.RE +.SH "RETURN VALUE" +.PP +\fISPI_processed\fR +and +\fISPI_tuptable\fR +are set as in +\fBSPI_execute\fR +if successful\&. +.SH "NOTES" +.PP +Fetching backward may fail if the cursor\*(Aqs plan was not created with the +CURSOR_OPT_SCROLL +option\&. diff --git a/doc/src/sgml/man3/SPI_cursor_find.3 b/doc/src/sgml/man3/SPI_cursor_find.3 new file mode 100644 index 0000000..e55bd6a --- /dev/null +++ b/doc/src/sgml/man3/SPI_cursor_find.3 @@ -0,0 +1,59 @@ +'\" t +.\" Title: SPI_cursor_find +.\" 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 "SPI_CURSOR_FIND" "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" +SPI_cursor_find \- find an existing cursor by name +.SH "SYNOPSIS" +.sp +.nf +Portal SPI_cursor_find(const char * \fIname\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_cursor_find\fR +finds an existing portal by name\&. This is primarily useful to resolve a cursor name returned as text by some other function\&. +.SH "ARGUMENTS" +.PP +const char * \fIname\fR +.RS 4 +name of the portal +.RE +.SH "RETURN VALUE" +.PP +pointer to the portal with the specified name, or +NULL +if none was found +.SH "NOTES" +.PP +Beware that this function can return a +Portal +object that does not have cursor\-like properties; for example it might not return tuples\&. If you simply pass the +Portal +pointer to other SPI functions, they can defend themselves against such cases, but caution is appropriate when directly inspecting the +Portal\&. diff --git a/doc/src/sgml/man3/SPI_cursor_move.3 b/doc/src/sgml/man3/SPI_cursor_move.3 new file mode 100644 index 0000000..899fe2d --- /dev/null +++ b/doc/src/sgml/man3/SPI_cursor_move.3 @@ -0,0 +1,65 @@ +'\" t +.\" Title: SPI_cursor_move +.\" 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 "SPI_CURSOR_MOVE" "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" +SPI_cursor_move \- move a cursor +.SH "SYNOPSIS" +.sp +.nf +void SPI_cursor_move(Portal \fIportal\fR, bool \fIforward\fR, long \fIcount\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_cursor_move\fR +skips over some number of rows in a cursor\&. This is equivalent to a subset of the SQL command +\fBMOVE\fR +(see +\fBSPI_scroll_cursor_move\fR +for more functionality)\&. +.SH "ARGUMENTS" +.PP +Portal \fIportal\fR +.RS 4 +portal containing the cursor +.RE +.PP +bool \fIforward\fR +.RS 4 +true for move forward, false for move backward +.RE +.PP +long \fIcount\fR +.RS 4 +maximum number of rows to move +.RE +.SH "NOTES" +.PP +Moving backward may fail if the cursor\*(Aqs plan was not created with the +CURSOR_OPT_SCROLL +option\&. diff --git a/doc/src/sgml/man3/SPI_cursor_open.3 b/doc/src/sgml/man3/SPI_cursor_open.3 new file mode 100644 index 0000000..072da84 --- /dev/null +++ b/doc/src/sgml/man3/SPI_cursor_open.3 @@ -0,0 +1,102 @@ +'\" t +.\" Title: SPI_cursor_open +.\" 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 "SPI_CURSOR_OPEN" "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" +SPI_cursor_open \- set up a cursor using a statement created with \fBSPI_prepare\fR +.SH "SYNOPSIS" +.sp +.nf +Portal SPI_cursor_open(const char * \fIname\fR, SPIPlanPtr \fIplan\fR, + Datum * \fIvalues\fR, const char * \fInulls\fR, + bool \fIread_only\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_cursor_open\fR +sets up a cursor (internally, a portal) that will execute a statement prepared by +\fBSPI_prepare\fR\&. The parameters have the same meanings as the corresponding parameters to +\fBSPI_execute_plan\fR\&. +.PP +Using a cursor instead of executing the statement directly has two benefits\&. First, the result rows can be retrieved a few at a time, avoiding memory overrun for queries that return many rows\&. Second, a portal can outlive the current C function (it can, in fact, live to the end of the current transaction)\&. Returning the portal name to the C function\*(Aqs caller provides a way of returning a row set as result\&. +.PP +The passed\-in parameter data will be copied into the cursor\*(Aqs portal, so it can be freed while the cursor still exists\&. +.SH "ARGUMENTS" +.PP +const char * \fIname\fR +.RS 4 +name for portal, or +NULL +to let the system select a name +.RE +.PP +SPIPlanPtr \fIplan\fR +.RS 4 +prepared statement (returned by +\fBSPI_prepare\fR) +.RE +.PP +Datum * \fIvalues\fR +.RS 4 +An array of actual parameter values\&. Must have same length as the statement\*(Aqs number of arguments\&. +.RE +.PP +const char * \fInulls\fR +.RS 4 +An array describing which parameters are null\&. Must have same length as the statement\*(Aqs number of arguments\&. +.sp +If +\fInulls\fR +is +NULL +then +\fBSPI_cursor_open\fR +assumes that no parameters are null\&. Otherwise, each entry of the +\fInulls\fR +array should be +\*(Aq\ \&\*(Aq +if the corresponding parameter value is non\-null, or +\*(Aqn\*(Aq +if the corresponding parameter value is null\&. (In the latter case, the actual value in the corresponding +\fIvalues\fR +entry doesn\*(Aqt matter\&.) Note that +\fInulls\fR +is not a text string, just an array: it does not need a +\*(Aq\e0\*(Aq +terminator\&. +.RE +.PP +bool \fIread_only\fR +.RS 4 +true +for read\-only execution +.RE +.SH "RETURN VALUE" +.PP +Pointer to portal containing the cursor\&. Note there is no error return convention; any error will be reported via +\fBelog\fR\&. diff --git a/doc/src/sgml/man3/SPI_cursor_open_with_args.3 b/doc/src/sgml/man3/SPI_cursor_open_with_args.3 new file mode 100644 index 0000000..5a87cab --- /dev/null +++ b/doc/src/sgml/man3/SPI_cursor_open_with_args.3 @@ -0,0 +1,130 @@ +'\" t +.\" Title: SPI_cursor_open_with_args +.\" 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 "SPI_CURSOR_OPEN_WITH_ARGS" "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" +SPI_cursor_open_with_args \- set up a cursor using a query and parameters +.SH "SYNOPSIS" +.sp +.nf +Portal SPI_cursor_open_with_args(const char *\fIname\fR, + const char *\fIcommand\fR, + int \fInargs\fR, Oid *\fIargtypes\fR, + Datum *\fIvalues\fR, const char *\fInulls\fR, + bool \fIread_only\fR, int \fIcursorOptions\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_cursor_open_with_args\fR +sets up a cursor (internally, a portal) that will execute the specified query\&. Most of the parameters have the same meanings as the corresponding parameters to +\fBSPI_prepare_cursor\fR +and +\fBSPI_cursor_open\fR\&. +.PP +For one\-time query execution, this function should be preferred over +\fBSPI_prepare_cursor\fR +followed by +\fBSPI_cursor_open\fR\&. If the same command is to be executed with many different parameters, either method might be faster, depending on the cost of re\-planning versus the benefit of custom plans\&. +.PP +The passed\-in parameter data will be copied into the cursor\*(Aqs portal, so it can be freed while the cursor still exists\&. +.PP +This function is now deprecated in favor of +\fBSPI_cursor_parse_open\fR, which provides equivalent functionality using a more modern API for handling query parameters\&. +.SH "ARGUMENTS" +.PP +const char * \fIname\fR +.RS 4 +name for portal, or +NULL +to let the system select a name +.RE +.PP +const char * \fIcommand\fR +.RS 4 +command string +.RE +.PP +int \fInargs\fR +.RS 4 +number of input parameters ($1, +$2, etc\&.) +.RE +.PP +Oid * \fIargtypes\fR +.RS 4 +an array of length +\fInargs\fR, containing the +OIDs of the data types of the parameters +.RE +.PP +Datum * \fIvalues\fR +.RS 4 +an array of length +\fInargs\fR, containing the actual parameter values +.RE +.PP +const char * \fInulls\fR +.RS 4 +an array of length +\fInargs\fR, describing which parameters are null +.sp +If +\fInulls\fR +is +NULL +then +\fBSPI_cursor_open_with_args\fR +assumes that no parameters are null\&. Otherwise, each entry of the +\fInulls\fR +array should be +\*(Aq\ \&\*(Aq +if the corresponding parameter value is non\-null, or +\*(Aqn\*(Aq +if the corresponding parameter value is null\&. (In the latter case, the actual value in the corresponding +\fIvalues\fR +entry doesn\*(Aqt matter\&.) Note that +\fInulls\fR +is not a text string, just an array: it does not need a +\*(Aq\e0\*(Aq +terminator\&. +.RE +.PP +bool \fIread_only\fR +.RS 4 +true +for read\-only execution +.RE +.PP +int \fIcursorOptions\fR +.RS 4 +integer bit mask of cursor options; zero produces default behavior +.RE +.SH "RETURN VALUE" +.PP +Pointer to portal containing the cursor\&. Note there is no error return convention; any error will be reported via +\fBelog\fR\&. diff --git a/doc/src/sgml/man3/SPI_cursor_open_with_paramlist.3 b/doc/src/sgml/man3/SPI_cursor_open_with_paramlist.3 new file mode 100644 index 0000000..3f8491d --- /dev/null +++ b/doc/src/sgml/man3/SPI_cursor_open_with_paramlist.3 @@ -0,0 +1,80 @@ +'\" t +.\" Title: SPI_cursor_open_with_paramlist +.\" 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 "SPI_CURSOR_OPEN_WITH_PARAMLIST" "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" +SPI_cursor_open_with_paramlist \- set up a cursor using parameters +.SH "SYNOPSIS" +.sp +.nf +Portal SPI_cursor_open_with_paramlist(const char *\fIname\fR, + SPIPlanPtr \fIplan\fR, + ParamListInfo \fIparams\fR, + bool \fIread_only\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_cursor_open_with_paramlist\fR +sets up a cursor (internally, a portal) that will execute a statement prepared by +\fBSPI_prepare\fR\&. This function is equivalent to +\fBSPI_cursor_open\fR +except that information about the parameter values to be passed to the query is presented differently\&. The +ParamListInfo +representation can be convenient for passing down values that are already available in that format\&. It also supports use of dynamic parameter sets via hook functions specified in +ParamListInfo\&. +.PP +The passed\-in parameter data will be copied into the cursor\*(Aqs portal, so it can be freed while the cursor still exists\&. +.SH "ARGUMENTS" +.PP +const char * \fIname\fR +.RS 4 +name for portal, or +NULL +to let the system select a name +.RE +.PP +SPIPlanPtr \fIplan\fR +.RS 4 +prepared statement (returned by +\fBSPI_prepare\fR) +.RE +.PP +ParamListInfo \fIparams\fR +.RS 4 +data structure containing parameter types and values; NULL if none +.RE +.PP +bool \fIread_only\fR +.RS 4 +true +for read\-only execution +.RE +.SH "RETURN VALUE" +.PP +Pointer to portal containing the cursor\&. Note there is no error return convention; any error will be reported via +\fBelog\fR\&. diff --git a/doc/src/sgml/man3/SPI_cursor_parse_open.3 b/doc/src/sgml/man3/SPI_cursor_parse_open.3 new file mode 100644 index 0000000..086a535 --- /dev/null +++ b/doc/src/sgml/man3/SPI_cursor_parse_open.3 @@ -0,0 +1,104 @@ +'\" t +.\" Title: SPI_cursor_parse_open +.\" 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 "SPI_CURSOR_PARSE_OPEN" "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" +SPI_cursor_parse_open \- set up a cursor using a query string and parameters +.SH "SYNOPSIS" +.sp +.nf +Portal SPI_cursor_parse_open(const char *\fIname\fR, + const char *\fIcommand\fR, + const SPIParseOpenOptions * \fIoptions\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_cursor_parse_open\fR +sets up a cursor (internally, a portal) that will execute the specified query string\&. This is comparable to +\fBSPI_prepare_cursor\fR +followed by +\fBSPI_cursor_open_with_paramlist\fR, except that parameter references within the query string are handled entirely by supplying a +ParamListInfo +object\&. +.PP +For one\-time query execution, this function should be preferred over +\fBSPI_prepare_cursor\fR +followed by +\fBSPI_cursor_open_with_paramlist\fR\&. If the same command is to be executed with many different parameters, either method might be faster, depending on the cost of re\-planning versus the benefit of custom plans\&. +.PP +The +\fIoptions\->params\fR +object should normally mark each parameter with the +PARAM_FLAG_CONST +flag, since a one\-shot plan is always used for the query\&. +.PP +The passed\-in parameter data will be copied into the cursor\*(Aqs portal, so it can be freed while the cursor still exists\&. +.SH "ARGUMENTS" +.PP +const char * \fIname\fR +.RS 4 +name for portal, or +NULL +to let the system select a name +.RE +.PP +const char * \fIcommand\fR +.RS 4 +command string +.RE +.PP +const SPIParseOpenOptions * \fIoptions\fR +.RS 4 +struct containing optional arguments +.RE +.PP +Callers should always zero out the entire +\fIoptions\fR +struct, then fill whichever fields they want to set\&. This ensures forward compatibility of code, since any fields that are added to the struct in future will be defined to behave backwards\-compatibly if they are zero\&. The currently available +\fIoptions\fR +fields are: +.PP +ParamListInfo \fIparams\fR +.RS 4 +data structure containing query parameter types and values; NULL if none +.RE +.PP +int \fIcursorOptions\fR +.RS 4 +integer bit mask of cursor options; zero produces default behavior +.RE +.PP +bool \fIread_only\fR +.RS 4 +true +for read\-only execution +.RE +.SH "RETURN VALUE" +.PP +Pointer to portal containing the cursor\&. Note there is no error return convention; any error will be reported via +\fBelog\fR\&. diff --git a/doc/src/sgml/man3/SPI_exec.3 b/doc/src/sgml/man3/SPI_exec.3 new file mode 100644 index 0000000..98240a8 --- /dev/null +++ b/doc/src/sgml/man3/SPI_exec.3 @@ -0,0 +1,61 @@ +'\" t +.\" Title: SPI_exec +.\" 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 "SPI_EXEC" "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" +SPI_exec \- execute a read/write command +.SH "SYNOPSIS" +.sp +.nf +int SPI_exec(const char * \fIcommand\fR, long \fIcount\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_exec\fR +is the same as +\fBSPI_execute\fR, with the latter\*(Aqs +\fIread_only\fR +parameter always taken as +false\&. +.SH "ARGUMENTS" +.PP +const char * \fIcommand\fR +.RS 4 +string containing command to execute +.RE +.PP +long \fIcount\fR +.RS 4 +maximum number of rows to return, or +0 +for no limit +.RE +.SH "RETURN VALUE" +.PP +See +\fBSPI_execute\fR\&. diff --git a/doc/src/sgml/man3/SPI_execp.3 b/doc/src/sgml/man3/SPI_execp.3 new file mode 100644 index 0000000..0d390ce --- /dev/null +++ b/doc/src/sgml/man3/SPI_execp.3 @@ -0,0 +1,99 @@ +'\" t +.\" Title: SPI_execp +.\" 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 "SPI_EXECP" "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" +SPI_execp \- execute a statement in read/write mode +.SH "SYNOPSIS" +.sp +.nf +int SPI_execp(SPIPlanPtr \fIplan\fR, Datum * \fIvalues\fR, const char * \fInulls\fR, long \fIcount\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_execp\fR +is the same as +\fBSPI_execute_plan\fR, with the latter\*(Aqs +\fIread_only\fR +parameter always taken as +false\&. +.SH "ARGUMENTS" +.PP +SPIPlanPtr \fIplan\fR +.RS 4 +prepared statement (returned by +\fBSPI_prepare\fR) +.RE +.PP +Datum * \fIvalues\fR +.RS 4 +An array of actual parameter values\&. Must have same length as the statement\*(Aqs number of arguments\&. +.RE +.PP +const char * \fInulls\fR +.RS 4 +An array describing which parameters are null\&. Must have same length as the statement\*(Aqs number of arguments\&. +.sp +If +\fInulls\fR +is +NULL +then +\fBSPI_execp\fR +assumes that no parameters are null\&. Otherwise, each entry of the +\fInulls\fR +array should be +\*(Aq\ \&\*(Aq +if the corresponding parameter value is non\-null, or +\*(Aqn\*(Aq +if the corresponding parameter value is null\&. (In the latter case, the actual value in the corresponding +\fIvalues\fR +entry doesn\*(Aqt matter\&.) Note that +\fInulls\fR +is not a text string, just an array: it does not need a +\*(Aq\e0\*(Aq +terminator\&. +.RE +.PP +long \fIcount\fR +.RS 4 +maximum number of rows to return, or +0 +for no limit +.RE +.SH "RETURN VALUE" +.PP +See +\fBSPI_execute_plan\fR\&. +.PP +\fISPI_processed\fR +and +\fISPI_tuptable\fR +are set as in +\fBSPI_execute\fR +if successful\&. diff --git a/doc/src/sgml/man3/SPI_execute.3 b/doc/src/sgml/man3/SPI_execute.3 new file mode 100644 index 0000000..80efbcd --- /dev/null +++ b/doc/src/sgml/man3/SPI_execute.3 @@ -0,0 +1,344 @@ +'\" t +.\" Title: SPI_execute +.\" 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 "SPI_EXECUTE" "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" +SPI_execute \- execute a command +.SH "SYNOPSIS" +.sp +.nf +int SPI_execute(const char * \fIcommand\fR, bool \fIread_only\fR, long \fIcount\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_execute\fR +executes the specified SQL command for +\fIcount\fR +rows\&. If +\fIread_only\fR +is +true, the command must be read\-only, and execution overhead is somewhat reduced\&. +.PP +This function can only be called from a connected C function\&. +.PP +If +\fIcount\fR +is zero then the command is executed for all rows that it applies to\&. If +\fIcount\fR +is greater than zero, then no more than +\fIcount\fR +rows will be retrieved; execution stops when the count is reached, much like adding a +LIMIT +clause to the query\&. For example, +.sp +.if n \{\ +.RS 4 +.\} +.nf +SPI_execute("SELECT * FROM foo", true, 5); +.fi +.if n \{\ +.RE +.\} +.sp +will retrieve at most 5 rows from the table\&. Note that such a limit is only effective when the command actually returns rows\&. For example, +.sp +.if n \{\ +.RS 4 +.\} +.nf +SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5); +.fi +.if n \{\ +.RE +.\} +.sp +inserts all rows from +bar, ignoring the +\fIcount\fR +parameter\&. However, with +.sp +.if n \{\ +.RS 4 +.\} +.nf +SPI_execute("INSERT INTO foo SELECT * FROM bar RETURNING *", false, 5); +.fi +.if n \{\ +.RE +.\} +.sp +at most 5 rows would be inserted, since execution would stop after the fifth +RETURNING +result row is retrieved\&. +.PP +You can pass multiple commands in one string; +\fBSPI_execute\fR +returns the result for the command executed last\&. The +\fIcount\fR +limit applies to each command separately (even though only the last result will actually be returned)\&. The limit is not applied to any hidden commands generated by rules\&. +.PP +When +\fIread_only\fR +is +false, +\fBSPI_execute\fR +increments the command counter and computes a new +snapshot +before executing each command in the string\&. The snapshot does not actually change if the current transaction isolation level is +SERIALIZABLE +or +REPEATABLE READ, but in +READ COMMITTED +mode the snapshot update allows each command to see the results of newly committed transactions from other sessions\&. This is essential for consistent behavior when the commands are modifying the database\&. +.PP +When +\fIread_only\fR +is +true, +\fBSPI_execute\fR +does not update either the snapshot or the command counter, and it allows only plain +\fBSELECT\fR +commands to appear in the command string\&. The commands are executed using the snapshot previously established for the surrounding query\&. This execution mode is somewhat faster than the read/write mode due to eliminating per\-command overhead\&. It also allows genuinely +stable +functions to be built: since successive executions will all use the same snapshot, there will be no change in the results\&. +.PP +It is generally unwise to mix read\-only and read\-write commands within a single function using SPI; that could result in very confusing behavior, since the read\-only queries would not see the results of any database updates done by the read\-write queries\&. +.PP +The actual number of rows for which the (last) command was executed is returned in the global variable +\fISPI_processed\fR\&. If the return value of the function is +SPI_OK_SELECT, +SPI_OK_INSERT_RETURNING, +SPI_OK_DELETE_RETURNING, or +SPI_OK_UPDATE_RETURNING, then you can use the global pointer +SPITupleTable *SPI_tuptable +to access the result rows\&. Some utility commands (such as +\fBEXPLAIN\fR) also return row sets, and +SPI_tuptable +will contain the result in these cases too\&. Some utility commands (\fBCOPY\fR, +\fBCREATE TABLE AS\fR) don\*(Aqt return a row set, so +SPI_tuptable +is NULL, but they still return the number of rows processed in +\fISPI_processed\fR\&. +.PP +The structure +SPITupleTable +is defined thus: +.sp +.if n \{\ +.RS 4 +.\} +.nf +typedef struct SPITupleTable +{ + /* Public members */ + TupleDesc tupdesc; /* tuple descriptor */ + HeapTuple *vals; /* array of tuples */ + uint64 numvals; /* number of valid tuples */ + + /* Private members, not intended for external callers */ + uint64 alloced; /* allocated length of vals array */ + MemoryContext tuptabcxt; /* memory context of result table */ + slist_node next; /* link for internal bookkeeping */ + SubTransactionId subid; /* subxact in which tuptable was created */ +} SPITupleTable; +.fi +.if n \{\ +.RE +.\} +.sp +The fields +tupdesc, +vals, and +numvals +can be used by SPI callers; the remaining fields are internal\&. +vals +is an array of pointers to rows\&. The number of rows is given by +numvals +(for somewhat historical reasons, this count is also returned in +\fISPI_processed\fR)\&. +tupdesc +is a row descriptor which you can pass to SPI functions dealing with rows\&. +.PP +\fBSPI_finish\fR +frees all +SPITupleTables allocated during the current C function\&. You can free a particular result table earlier, if you are done with it, by calling +\fBSPI_freetuptable\fR\&. +.SH "ARGUMENTS" +.PP +const char * \fIcommand\fR +.RS 4 +string containing command to execute +.RE +.PP +bool \fIread_only\fR +.RS 4 +true +for read\-only execution +.RE +.PP +long \fIcount\fR +.RS 4 +maximum number of rows to return, or +0 +for no limit +.RE +.SH "RETURN VALUE" +.PP +If the execution of the command was successful then one of the following (nonnegative) values will be returned: +.PP +SPI_OK_SELECT +.RS 4 +if a +\fBSELECT\fR +(but not +\fBSELECT INTO\fR) was executed +.RE +.PP +SPI_OK_SELINTO +.RS 4 +if a +\fBSELECT INTO\fR +was executed +.RE +.PP +SPI_OK_INSERT +.RS 4 +if an +\fBINSERT\fR +was executed +.RE +.PP +SPI_OK_DELETE +.RS 4 +if a +\fBDELETE\fR +was executed +.RE +.PP +SPI_OK_UPDATE +.RS 4 +if an +\fBUPDATE\fR +was executed +.RE +.PP +SPI_OK_MERGE +.RS 4 +if a +\fBMERGE\fR +was executed +.RE +.PP +SPI_OK_INSERT_RETURNING +.RS 4 +if an +\fBINSERT RETURNING\fR +was executed +.RE +.PP +SPI_OK_DELETE_RETURNING +.RS 4 +if a +\fBDELETE RETURNING\fR +was executed +.RE +.PP +SPI_OK_UPDATE_RETURNING +.RS 4 +if an +\fBUPDATE RETURNING\fR +was executed +.RE +.PP +SPI_OK_UTILITY +.RS 4 +if a utility command (e\&.g\&., +\fBCREATE TABLE\fR) was executed +.RE +.PP +SPI_OK_REWRITTEN +.RS 4 +if the command was rewritten into another kind of command (e\&.g\&., +\fBUPDATE\fR +became an +\fBINSERT\fR) by a +rule\&. +.RE +.PP +On error, one of the following negative values is returned: +.PP +SPI_ERROR_ARGUMENT +.RS 4 +if +\fIcommand\fR +is +NULL +or +\fIcount\fR +is less than 0 +.RE +.PP +SPI_ERROR_COPY +.RS 4 +if +\fBCOPY TO stdout\fR +or +\fBCOPY FROM stdin\fR +was attempted +.RE +.PP +SPI_ERROR_TRANSACTION +.RS 4 +if a transaction manipulation command was attempted (\fBBEGIN\fR, +\fBCOMMIT\fR, +\fBROLLBACK\fR, +\fBSAVEPOINT\fR, +\fBPREPARE TRANSACTION\fR, +\fBCOMMIT PREPARED\fR, +\fBROLLBACK PREPARED\fR, or any variant thereof) +.RE +.PP +SPI_ERROR_OPUNKNOWN +.RS 4 +if the command type is unknown (shouldn\*(Aqt happen) +.RE +.PP +SPI_ERROR_UNCONNECTED +.RS 4 +if called from an unconnected C function +.RE +.SH "NOTES" +.PP +All SPI query\-execution functions set both +\fISPI_processed\fR +and +\fISPI_tuptable\fR +(just the pointer, not the contents of the structure)\&. Save these two global variables into local C function variables if you need to access the result table of +\fBSPI_execute\fR +or another query\-execution function across later calls\&. diff --git a/doc/src/sgml/man3/SPI_execute_extended.3 b/doc/src/sgml/man3/SPI_execute_extended.3 new file mode 100644 index 0000000..e985f57 --- /dev/null +++ b/doc/src/sgml/man3/SPI_execute_extended.3 @@ -0,0 +1,144 @@ +'\" t +.\" Title: SPI_execute_extended +.\" 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 "SPI_EXECUTE_EXTENDED" "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" +SPI_execute_extended \- execute a command with out\-of\-line parameters +.SH "SYNOPSIS" +.sp +.nf +int SPI_execute_extended(const char *\fIcommand\fR, + const SPIExecuteOptions * \fIoptions\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_execute_extended\fR +executes a command that might include references to externally supplied parameters\&. The command text refers to a parameter as +$\fIn\fR, and the +\fIoptions\->params\fR +object (if supplied) provides values and type information for each such symbol\&. Various execution options can be specified in the +\fIoptions\fR +struct, too\&. +.PP +The +\fIoptions\->params\fR +object should normally mark each parameter with the +PARAM_FLAG_CONST +flag, since a one\-shot plan is always used for the query\&. +.PP +If +\fIoptions\->dest\fR +is not NULL, then result tuples are passed to that object as they are generated by the executor, instead of being accumulated in +\fISPI_tuptable\fR\&. Using a caller\-supplied +DestReceiver +object is particularly helpful for queries that might generate many tuples, since the data can be processed on\-the\-fly instead of being accumulated in memory\&. +.SH "ARGUMENTS" +.PP +const char * \fIcommand\fR +.RS 4 +command string +.RE +.PP +const SPIExecuteOptions * \fIoptions\fR +.RS 4 +struct containing optional arguments +.RE +.PP +Callers should always zero out the entire +\fIoptions\fR +struct, then fill whichever fields they want to set\&. This ensures forward compatibility of code, since any fields that are added to the struct in future will be defined to behave backwards\-compatibly if they are zero\&. The currently available +\fIoptions\fR +fields are: +.PP +ParamListInfo \fIparams\fR +.RS 4 +data structure containing query parameter types and values; NULL if none +.RE +.PP +bool \fIread_only\fR +.RS 4 +true +for read\-only execution +.RE +.PP +bool \fIallow_nonatomic\fR +.RS 4 +true +allows non\-atomic execution of CALL and DO statements +.RE +.PP +bool \fImust_return_tuples\fR +.RS 4 +if +true, raise error if the query is not of a kind that returns tuples (this does not forbid the case where it happens to return zero tuples) +.RE +.PP +uint64 \fItcount\fR +.RS 4 +maximum number of rows to return, or +0 +for no limit +.RE +.PP +DestReceiver * \fIdest\fR +.RS 4 +DestReceiver +object that will receive any tuples emitted by the query; if NULL, result tuples are accumulated into a +\fISPI_tuptable\fR +structure, as in +\fBSPI_execute\fR +.RE +.PP +ResourceOwner \fIowner\fR +.RS 4 +This field is present for consistency with +\fBSPI_execute_plan_extended\fR, but it is ignored, since the plan used by +\fBSPI_execute_extended\fR +is never saved\&. +.RE +.SH "RETURN VALUE" +.PP +The return value is the same as for +\fBSPI_execute\fR\&. +.PP +When +\fIoptions\->dest\fR +is NULL, +\fISPI_processed\fR +and +\fISPI_tuptable\fR +are set as in +\fBSPI_execute\fR\&. When +\fIoptions\->dest\fR +is not NULL, +\fISPI_processed\fR +is set to zero and +\fISPI_tuptable\fR +is set to NULL\&. If a tuple count is required, the caller\*(Aqs +DestReceiver +object must calculate it\&. diff --git a/doc/src/sgml/man3/SPI_execute_plan.3 b/doc/src/sgml/man3/SPI_execute_plan.3 new file mode 100644 index 0000000..e248c31 --- /dev/null +++ b/doc/src/sgml/man3/SPI_execute_plan.3 @@ -0,0 +1,131 @@ +'\" t +.\" Title: SPI_execute_plan +.\" 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 "SPI_EXECUTE_PLAN" "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" +SPI_execute_plan \- execute a statement prepared by \fBSPI_prepare\fR +.SH "SYNOPSIS" +.sp +.nf +int SPI_execute_plan(SPIPlanPtr \fIplan\fR, Datum * \fIvalues\fR, const char * \fInulls\fR, + bool \fIread_only\fR, long \fIcount\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_execute_plan\fR +executes a statement prepared by +\fBSPI_prepare\fR +or one of its siblings\&. +\fIread_only\fR +and +\fIcount\fR +have the same interpretation as in +\fBSPI_execute\fR\&. +.SH "ARGUMENTS" +.PP +SPIPlanPtr \fIplan\fR +.RS 4 +prepared statement (returned by +\fBSPI_prepare\fR) +.RE +.PP +Datum * \fIvalues\fR +.RS 4 +An array of actual parameter values\&. Must have same length as the statement\*(Aqs number of arguments\&. +.RE +.PP +const char * \fInulls\fR +.RS 4 +An array describing which parameters are null\&. Must have same length as the statement\*(Aqs number of arguments\&. +.sp +If +\fInulls\fR +is +NULL +then +\fBSPI_execute_plan\fR +assumes that no parameters are null\&. Otherwise, each entry of the +\fInulls\fR +array should be +\*(Aq\ \&\*(Aq +if the corresponding parameter value is non\-null, or +\*(Aqn\*(Aq +if the corresponding parameter value is null\&. (In the latter case, the actual value in the corresponding +\fIvalues\fR +entry doesn\*(Aqt matter\&.) Note that +\fInulls\fR +is not a text string, just an array: it does not need a +\*(Aq\e0\*(Aq +terminator\&. +.RE +.PP +bool \fIread_only\fR +.RS 4 +true +for read\-only execution +.RE +.PP +long \fIcount\fR +.RS 4 +maximum number of rows to return, or +0 +for no limit +.RE +.SH "RETURN VALUE" +.PP +The return value is the same as for +\fBSPI_execute\fR, with the following additional possible error (negative) results: +.PP +SPI_ERROR_ARGUMENT +.RS 4 +if +\fIplan\fR +is +NULL +or invalid, or +\fIcount\fR +is less than 0 +.RE +.PP +SPI_ERROR_PARAM +.RS 4 +if +\fIvalues\fR +is +NULL +and +\fIplan\fR +was prepared with some parameters +.RE +.PP +\fISPI_processed\fR +and +\fISPI_tuptable\fR +are set as in +\fBSPI_execute\fR +if successful\&. diff --git a/doc/src/sgml/man3/SPI_execute_plan_extended.3 b/doc/src/sgml/man3/SPI_execute_plan_extended.3 new file mode 100644 index 0000000..7eab384 --- /dev/null +++ b/doc/src/sgml/man3/SPI_execute_plan_extended.3 @@ -0,0 +1,138 @@ +'\" t +.\" Title: SPI_execute_plan_extended +.\" 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 "SPI_EXECUTE_PLAN_EXTENDED" "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" +SPI_execute_plan_extended \- execute a statement prepared by \fBSPI_prepare\fR +.SH "SYNOPSIS" +.sp +.nf +int SPI_execute_plan_extended(SPIPlanPtr \fIplan\fR, + const SPIExecuteOptions * \fIoptions\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_execute_plan_extended\fR +executes a statement prepared by +\fBSPI_prepare\fR +or one of its siblings\&. This function is equivalent to +\fBSPI_execute_plan\fR, except that information about the parameter values to be passed to the query is presented differently, and additional execution\-controlling options can be passed\&. +.PP +Query parameter values are represented by a +ParamListInfo +struct, which is convenient for passing down values that are already available in that format\&. Dynamic parameter sets can also be used, via hook functions specified in +ParamListInfo\&. +.PP +Also, instead of always accumulating the result tuples into a +\fISPI_tuptable\fR +structure, tuples can be passed to a caller\-supplied +DestReceiver +object as they are generated by the executor\&. This is particularly helpful for queries that might generate many tuples, since the data can be processed on\-the\-fly instead of being accumulated in memory\&. +.SH "ARGUMENTS" +.PP +SPIPlanPtr \fIplan\fR +.RS 4 +prepared statement (returned by +\fBSPI_prepare\fR) +.RE +.PP +const SPIExecuteOptions * \fIoptions\fR +.RS 4 +struct containing optional arguments +.RE +.PP +Callers should always zero out the entire +\fIoptions\fR +struct, then fill whichever fields they want to set\&. This ensures forward compatibility of code, since any fields that are added to the struct in future will be defined to behave backwards\-compatibly if they are zero\&. The currently available +\fIoptions\fR +fields are: +.PP +ParamListInfo \fIparams\fR +.RS 4 +data structure containing query parameter types and values; NULL if none +.RE +.PP +bool \fIread_only\fR +.RS 4 +true +for read\-only execution +.RE +.PP +bool \fIallow_nonatomic\fR +.RS 4 +true +allows non\-atomic execution of CALL and DO statements +.RE +.PP +bool \fImust_return_tuples\fR +.RS 4 +if +true, raise error if the query is not of a kind that returns tuples (this does not forbid the case where it happens to return zero tuples) +.RE +.PP +uint64 \fItcount\fR +.RS 4 +maximum number of rows to return, or +0 +for no limit +.RE +.PP +DestReceiver * \fIdest\fR +.RS 4 +DestReceiver +object that will receive any tuples emitted by the query; if NULL, result tuples are accumulated into a +\fISPI_tuptable\fR +structure, as in +\fBSPI_execute_plan\fR +.RE +.PP +ResourceOwner \fIowner\fR +.RS 4 +The resource owner that will hold a reference count on the plan while it is executed\&. If NULL, CurrentResourceOwner is used\&. Ignored for non\-saved plans, as SPI does not acquire reference counts on those\&. +.RE +.SH "RETURN VALUE" +.PP +The return value is the same as for +\fBSPI_execute_plan\fR\&. +.PP +When +\fIoptions\->dest\fR +is NULL, +\fISPI_processed\fR +and +\fISPI_tuptable\fR +are set as in +\fBSPI_execute_plan\fR\&. When +\fIoptions\->dest\fR +is not NULL, +\fISPI_processed\fR +is set to zero and +\fISPI_tuptable\fR +is set to NULL\&. If a tuple count is required, the caller\*(Aqs +DestReceiver +object must calculate it\&. diff --git a/doc/src/sgml/man3/SPI_execute_plan_with_paramlist.3 b/doc/src/sgml/man3/SPI_execute_plan_with_paramlist.3 new file mode 100644 index 0000000..a0e0f64 --- /dev/null +++ b/doc/src/sgml/man3/SPI_execute_plan_with_paramlist.3 @@ -0,0 +1,88 @@ +'\" t +.\" Title: SPI_execute_plan_with_paramlist +.\" 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 "SPI_EXECUTE_PLAN_WITH_PARAMLIST" "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" +SPI_execute_plan_with_paramlist \- execute a statement prepared by \fBSPI_prepare\fR +.SH "SYNOPSIS" +.sp +.nf +int SPI_execute_plan_with_paramlist(SPIPlanPtr \fIplan\fR, + ParamListInfo \fIparams\fR, + bool \fIread_only\fR, + long \fIcount\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_execute_plan_with_paramlist\fR +executes a statement prepared by +\fBSPI_prepare\fR\&. This function is equivalent to +\fBSPI_execute_plan\fR +except that information about the parameter values to be passed to the query is presented differently\&. The +ParamListInfo +representation can be convenient for passing down values that are already available in that format\&. It also supports use of dynamic parameter sets via hook functions specified in +ParamListInfo\&. +.PP +This function is now deprecated in favor of +\fBSPI_execute_plan_extended\fR\&. +.SH "ARGUMENTS" +.PP +SPIPlanPtr \fIplan\fR +.RS 4 +prepared statement (returned by +\fBSPI_prepare\fR) +.RE +.PP +ParamListInfo \fIparams\fR +.RS 4 +data structure containing parameter types and values; NULL if none +.RE +.PP +bool \fIread_only\fR +.RS 4 +true +for read\-only execution +.RE +.PP +long \fIcount\fR +.RS 4 +maximum number of rows to return, or +0 +for no limit +.RE +.SH "RETURN VALUE" +.PP +The return value is the same as for +\fBSPI_execute_plan\fR\&. +.PP +\fISPI_processed\fR +and +\fISPI_tuptable\fR +are set as in +\fBSPI_execute_plan\fR +if successful\&. diff --git a/doc/src/sgml/man3/SPI_execute_with_args.3 b/doc/src/sgml/man3/SPI_execute_with_args.3 new file mode 100644 index 0000000..e02aa55 --- /dev/null +++ b/doc/src/sgml/man3/SPI_execute_with_args.3 @@ -0,0 +1,133 @@ +'\" t +.\" Title: SPI_execute_with_args +.\" 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 "SPI_EXECUTE_WITH_ARGS" "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" +SPI_execute_with_args \- execute a command with out\-of\-line parameters +.SH "SYNOPSIS" +.sp +.nf +int SPI_execute_with_args(const char *\fIcommand\fR, + int \fInargs\fR, Oid *\fIargtypes\fR, + Datum *\fIvalues\fR, const char *\fInulls\fR, + bool \fIread_only\fR, long \fIcount\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_execute_with_args\fR +executes a command that might include references to externally supplied parameters\&. The command text refers to a parameter as +$\fIn\fR, and the call specifies data types and values for each such symbol\&. +\fIread_only\fR +and +\fIcount\fR +have the same interpretation as in +\fBSPI_execute\fR\&. +.PP +The main advantage of this routine compared to +\fBSPI_execute\fR +is that data values can be inserted into the command without tedious quoting/escaping, and thus with much less risk of SQL\-injection attacks\&. +.PP +Similar results can be achieved with +\fBSPI_prepare\fR +followed by +\fBSPI_execute_plan\fR; however, when using this function the query plan is always customized to the specific parameter values provided\&. For one\-time query execution, this function should be preferred\&. If the same command is to be executed with many different parameters, either method might be faster, depending on the cost of re\-planning versus the benefit of custom plans\&. +.SH "ARGUMENTS" +.PP +const char * \fIcommand\fR +.RS 4 +command string +.RE +.PP +int \fInargs\fR +.RS 4 +number of input parameters ($1, +$2, etc\&.) +.RE +.PP +Oid * \fIargtypes\fR +.RS 4 +an array of length +\fInargs\fR, containing the +OIDs of the data types of the parameters +.RE +.PP +Datum * \fIvalues\fR +.RS 4 +an array of length +\fInargs\fR, containing the actual parameter values +.RE +.PP +const char * \fInulls\fR +.RS 4 +an array of length +\fInargs\fR, describing which parameters are null +.sp +If +\fInulls\fR +is +NULL +then +\fBSPI_execute_with_args\fR +assumes that no parameters are null\&. Otherwise, each entry of the +\fInulls\fR +array should be +\*(Aq\ \&\*(Aq +if the corresponding parameter value is non\-null, or +\*(Aqn\*(Aq +if the corresponding parameter value is null\&. (In the latter case, the actual value in the corresponding +\fIvalues\fR +entry doesn\*(Aqt matter\&.) Note that +\fInulls\fR +is not a text string, just an array: it does not need a +\*(Aq\e0\*(Aq +terminator\&. +.RE +.PP +bool \fIread_only\fR +.RS 4 +true +for read\-only execution +.RE +.PP +long \fIcount\fR +.RS 4 +maximum number of rows to return, or +0 +for no limit +.RE +.SH "RETURN VALUE" +.PP +The return value is the same as for +\fBSPI_execute\fR\&. +.PP +\fISPI_processed\fR +and +\fISPI_tuptable\fR +are set as in +\fBSPI_execute\fR +if successful\&. diff --git a/doc/src/sgml/man3/SPI_finish.3 b/doc/src/sgml/man3/SPI_finish.3 new file mode 100644 index 0000000..92e1d72 --- /dev/null +++ b/doc/src/sgml/man3/SPI_finish.3 @@ -0,0 +1,52 @@ +'\" t +.\" Title: SPI_finish +.\" 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 "SPI_FINISH" "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" +SPI_finish \- disconnect a C function from the SPI manager +.SH "SYNOPSIS" +.sp +.nf +int SPI_finish(void) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_finish\fR +closes an existing connection to the SPI manager\&. You must call this function after completing the SPI operations needed during your C function\*(Aqs current invocation\&. You do not need to worry about making this happen, however, if you abort the transaction via +elog(ERROR)\&. In that case SPI will clean itself up automatically\&. +.SH "RETURN VALUE" +.PP +SPI_OK_FINISH +.RS 4 +if properly disconnected +.RE +.PP +SPI_ERROR_UNCONNECTED +.RS 4 +if called from an unconnected C function +.RE diff --git a/doc/src/sgml/man3/SPI_fname.3 b/doc/src/sgml/man3/SPI_fname.3 new file mode 100644 index 0000000..035b78e --- /dev/null +++ b/doc/src/sgml/man3/SPI_fname.3 @@ -0,0 +1,64 @@ +'\" t +.\" Title: SPI_fname +.\" 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 "SPI_FNAME" "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" +SPI_fname \- determine the column name for the specified column number +.SH "SYNOPSIS" +.sp +.nf +char * SPI_fname(TupleDesc \fIrowdesc\fR, int \fIcolnumber\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_fname\fR +returns a copy of the column name of the specified column\&. (You can use +\fBpfree\fR +to release the copy of the name when you don\*(Aqt need it anymore\&.) +.SH "ARGUMENTS" +.PP +TupleDesc \fIrowdesc\fR +.RS 4 +input row description +.RE +.PP +int \fIcolnumber\fR +.RS 4 +column number (count starts at 1) +.RE +.SH "RETURN VALUE" +.PP +The column name; +NULL +if +\fIcolnumber\fR +is out of range\&. +\fISPI_result\fR +set to +SPI_ERROR_NOATTRIBUTE +on error\&. diff --git a/doc/src/sgml/man3/SPI_fnumber.3 b/doc/src/sgml/man3/SPI_fnumber.3 new file mode 100644 index 0000000..0bf9260 --- /dev/null +++ b/doc/src/sgml/man3/SPI_fnumber.3 @@ -0,0 +1,63 @@ +'\" t +.\" Title: SPI_fnumber +.\" 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 "SPI_FNUMBER" "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" +SPI_fnumber \- determine the column number for the specified column name +.SH "SYNOPSIS" +.sp +.nf +int SPI_fnumber(TupleDesc \fIrowdesc\fR, const char * \fIcolname\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_fnumber\fR +returns the column number for the column with the specified name\&. +.PP +If +\fIcolname\fR +refers to a system column (e\&.g\&., +ctid) then the appropriate negative column number will be returned\&. The caller should be careful to test the return value for exact equality to +SPI_ERROR_NOATTRIBUTE +to detect an error; testing the result for less than or equal to 0 is not correct unless system columns should be rejected\&. +.SH "ARGUMENTS" +.PP +TupleDesc \fIrowdesc\fR +.RS 4 +input row description +.RE +.PP +const char * \fIcolname\fR +.RS 4 +column name +.RE +.SH "RETURN VALUE" +.PP +Column number (count starts at 1 for user\-defined columns), or +SPI_ERROR_NOATTRIBUTE +if the named column was not found\&. diff --git a/doc/src/sgml/man3/SPI_freeplan.3 b/doc/src/sgml/man3/SPI_freeplan.3 new file mode 100644 index 0000000..e3e12aa --- /dev/null +++ b/doc/src/sgml/man3/SPI_freeplan.3 @@ -0,0 +1,60 @@ +'\" t +.\" Title: SPI_freeplan +.\" 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 "SPI_FREEPLAN" "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" +SPI_freeplan \- free a previously saved prepared statement +.SH "SYNOPSIS" +.sp +.nf +int SPI_freeplan(SPIPlanPtr \fIplan\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_freeplan\fR +releases a prepared statement previously returned by +\fBSPI_prepare\fR +or saved by +\fBSPI_keepplan\fR +or +\fBSPI_saveplan\fR\&. +.SH "ARGUMENTS" +.PP +SPIPlanPtr \fIplan\fR +.RS 4 +pointer to statement to free +.RE +.SH "RETURN VALUE" +.PP +0 on success; +SPI_ERROR_ARGUMENT +if +\fIplan\fR +is +NULL +or invalid diff --git a/doc/src/sgml/man3/SPI_freetuple.3 b/doc/src/sgml/man3/SPI_freetuple.3 new file mode 100644 index 0000000..6db0ee5 --- /dev/null +++ b/doc/src/sgml/man3/SPI_freetuple.3 @@ -0,0 +1,49 @@ +'\" t +.\" Title: SPI_freetuple +.\" 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 "SPI_FREETUPLE" "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" +SPI_freetuple \- free a row allocated in the upper executor context +.SH "SYNOPSIS" +.sp +.nf +void SPI_freetuple(HeapTuple \fIrow\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_freetuple\fR +frees a row previously allocated in the upper executor context\&. +.PP +This function is no longer different from plain +\fBheap_freetuple\fR\&. It\*(Aqs kept just for backward compatibility of existing code\&. +.SH "ARGUMENTS" +.PP +HeapTuple \fIrow\fR +.RS 4 +row to free +.RE diff --git a/doc/src/sgml/man3/SPI_freetuptable.3 b/doc/src/sgml/man3/SPI_freetuptable.3 new file mode 100644 index 0000000..0faa366 --- /dev/null +++ b/doc/src/sgml/man3/SPI_freetuptable.3 @@ -0,0 +1,58 @@ +'\" t +.\" Title: SPI_freetuptable +.\" 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 "SPI_FREETUPTABLE" "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" +SPI_freetuptable \- free a row set created by \fBSPI_execute\fR or a similar function +.SH "SYNOPSIS" +.sp +.nf +void SPI_freetuptable(SPITupleTable * \fItuptable\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_freetuptable\fR +frees a row set created by a prior SPI command execution function, such as +\fBSPI_execute\fR\&. Therefore, this function is often called with the global variable +\fISPI_tuptable\fR +as argument\&. +.PP +This function is useful if an SPI\-using C function needs to execute multiple commands and does not want to keep the results of earlier commands around until it ends\&. Note that any unfreed row sets will be freed anyway at +\fBSPI_finish\fR\&. Also, if a subtransaction is started and then aborted within execution of an SPI\-using C function, SPI automatically frees any row sets created while the subtransaction was running\&. +.PP +Beginning in +PostgreSQL +9\&.3, +\fBSPI_freetuptable\fR +contains guard logic to protect against duplicate deletion requests for the same row set\&. In previous releases, duplicate deletions would lead to crashes\&. +.SH "ARGUMENTS" +.PP +SPITupleTable * \fItuptable\fR +.RS 4 +pointer to row set to free, or NULL to do nothing +.RE diff --git a/doc/src/sgml/man3/SPI_getargcount.3 b/doc/src/sgml/man3/SPI_getargcount.3 new file mode 100644 index 0000000..bcb91d6 --- /dev/null +++ b/doc/src/sgml/man3/SPI_getargcount.3 @@ -0,0 +1,60 @@ +'\" t +.\" Title: SPI_getargcount +.\" 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 "SPI_GETARGCOUNT" "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" +SPI_getargcount \- return the number of arguments needed by a statement prepared by \fBSPI_prepare\fR +.SH "SYNOPSIS" +.sp +.nf +int SPI_getargcount(SPIPlanPtr \fIplan\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_getargcount\fR +returns the number of arguments needed to execute a statement prepared by +\fBSPI_prepare\fR\&. +.SH "ARGUMENTS" +.PP +SPIPlanPtr \fIplan\fR +.RS 4 +prepared statement (returned by +\fBSPI_prepare\fR) +.RE +.SH "RETURN VALUE" +.PP +The count of expected arguments for the +\fIplan\fR\&. If the +\fIplan\fR +is +NULL +or invalid, +\fISPI_result\fR +is set to +SPI_ERROR_ARGUMENT +and \-1 is returned\&. diff --git a/doc/src/sgml/man3/SPI_getargtypeid.3 b/doc/src/sgml/man3/SPI_getargtypeid.3 new file mode 100644 index 0000000..65069ff --- /dev/null +++ b/doc/src/sgml/man3/SPI_getargtypeid.3 @@ -0,0 +1,70 @@ +'\" t +.\" Title: SPI_getargtypeid +.\" 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 "SPI_GETARGTYPEID" "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" +SPI_getargtypeid \- return the data type OID for an argument of a statement prepared by \fBSPI_prepare\fR +.SH "SYNOPSIS" +.sp +.nf +Oid SPI_getargtypeid(SPIPlanPtr \fIplan\fR, int \fIargIndex\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_getargtypeid\fR +returns the OID representing the type for the +\fIargIndex\fR\*(Aqth argument of a statement prepared by +\fBSPI_prepare\fR\&. First argument is at index zero\&. +.SH "ARGUMENTS" +.PP +SPIPlanPtr \fIplan\fR +.RS 4 +prepared statement (returned by +\fBSPI_prepare\fR) +.RE +.PP +int \fIargIndex\fR +.RS 4 +zero based index of the argument +.RE +.SH "RETURN VALUE" +.PP +The type OID of the argument at the given index\&. If the +\fIplan\fR +is +NULL +or invalid, or +\fIargIndex\fR +is less than 0 or not less than the number of arguments declared for the +\fIplan\fR, +\fISPI_result\fR +is set to +SPI_ERROR_ARGUMENT +and +InvalidOid +is returned\&. diff --git a/doc/src/sgml/man3/SPI_getbinval.3 b/doc/src/sgml/man3/SPI_getbinval.3 new file mode 100644 index 0000000..9d5fc88 --- /dev/null +++ b/doc/src/sgml/man3/SPI_getbinval.3 @@ -0,0 +1,75 @@ +'\" t +.\" Title: SPI_getbinval +.\" 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 "SPI_GETBINVAL" "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" +SPI_getbinval \- return the binary value of the specified column +.SH "SYNOPSIS" +.sp +.nf +Datum SPI_getbinval(HeapTuple \fIrow\fR, TupleDesc \fIrowdesc\fR, int \fIcolnumber\fR, + bool * \fIisnull\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_getbinval\fR +returns the value of the specified column in the internal form (as type +Datum)\&. +.PP +This function does not allocate new space for the datum\&. In the case of a pass\-by\-reference data type, the return value will be a pointer into the passed row\&. +.SH "ARGUMENTS" +.PP +HeapTuple \fIrow\fR +.RS 4 +input row to be examined +.RE +.PP +TupleDesc \fIrowdesc\fR +.RS 4 +input row description +.RE +.PP +int \fIcolnumber\fR +.RS 4 +column number (count starts at 1) +.RE +.PP +bool * \fIisnull\fR +.RS 4 +flag for a null value in the column +.RE +.SH "RETURN VALUE" +.PP +The binary value of the column is returned\&. The variable pointed to by +\fIisnull\fR +is set to true if the column is null, else to false\&. +.PP +\fISPI_result\fR +is set to +SPI_ERROR_NOATTRIBUTE +on error\&. diff --git a/doc/src/sgml/man3/SPI_getnspname.3 b/doc/src/sgml/man3/SPI_getnspname.3 new file mode 100644 index 0000000..24e8170 --- /dev/null +++ b/doc/src/sgml/man3/SPI_getnspname.3 @@ -0,0 +1,53 @@ +'\" t +.\" Title: SPI_getnspname +.\" 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 "SPI_GETNSPNAME" "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" +SPI_getnspname \- return the namespace of the specified relation +.SH "SYNOPSIS" +.sp +.nf +char * SPI_getnspname(Relation \fIrel\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_getnspname\fR +returns a copy of the name of the namespace that the specified +Relation +belongs to\&. This is equivalent to the relation\*(Aqs schema\&. You should +\fBpfree\fR +the return value of this function when you are finished with it\&. +.SH "ARGUMENTS" +.PP +Relation \fIrel\fR +.RS 4 +input relation +.RE +.SH "RETURN VALUE" +.PP +The name of the specified relation\*(Aqs namespace\&. diff --git a/doc/src/sgml/man3/SPI_getrelname.3 b/doc/src/sgml/man3/SPI_getrelname.3 new file mode 100644 index 0000000..ae53a5a --- /dev/null +++ b/doc/src/sgml/man3/SPI_getrelname.3 @@ -0,0 +1,51 @@ +'\" t +.\" Title: SPI_getrelname +.\" 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 "SPI_GETRELNAME" "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" +SPI_getrelname \- return the name of the specified relation +.SH "SYNOPSIS" +.sp +.nf +char * SPI_getrelname(Relation \fIrel\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_getrelname\fR +returns a copy of the name of the specified relation\&. (You can use +\fBpfree\fR +to release the copy of the name when you don\*(Aqt need it anymore\&.) +.SH "ARGUMENTS" +.PP +Relation \fIrel\fR +.RS 4 +input relation +.RE +.SH "RETURN VALUE" +.PP +The name of the specified relation\&. diff --git a/doc/src/sgml/man3/SPI_gettype.3 b/doc/src/sgml/man3/SPI_gettype.3 new file mode 100644 index 0000000..1a0f498 --- /dev/null +++ b/doc/src/sgml/man3/SPI_gettype.3 @@ -0,0 +1,62 @@ +'\" t +.\" Title: SPI_gettype +.\" 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 "SPI_GETTYPE" "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" +SPI_gettype \- return the data type name of the specified column +.SH "SYNOPSIS" +.sp +.nf +char * SPI_gettype(TupleDesc \fIrowdesc\fR, int \fIcolnumber\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_gettype\fR +returns a copy of the data type name of the specified column\&. (You can use +\fBpfree\fR +to release the copy of the name when you don\*(Aqt need it anymore\&.) +.SH "ARGUMENTS" +.PP +TupleDesc \fIrowdesc\fR +.RS 4 +input row description +.RE +.PP +int \fIcolnumber\fR +.RS 4 +column number (count starts at 1) +.RE +.SH "RETURN VALUE" +.PP +The data type name of the specified column, or +NULL +on error\&. +\fISPI_result\fR +is set to +SPI_ERROR_NOATTRIBUTE +on error\&. diff --git a/doc/src/sgml/man3/SPI_gettypeid.3 b/doc/src/sgml/man3/SPI_gettypeid.3 new file mode 100644 index 0000000..7df7b65 --- /dev/null +++ b/doc/src/sgml/man3/SPI_gettypeid.3 @@ -0,0 +1,63 @@ +'\" t +.\" Title: SPI_gettypeid +.\" 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 "SPI_GETTYPEID" "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" +SPI_gettypeid \- return the data type OID of the specified column +.SH "SYNOPSIS" +.sp +.nf +Oid SPI_gettypeid(TupleDesc \fIrowdesc\fR, int \fIcolnumber\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_gettypeid\fR +returns the +OID +of the data type of the specified column\&. +.SH "ARGUMENTS" +.PP +TupleDesc \fIrowdesc\fR +.RS 4 +input row description +.RE +.PP +int \fIcolnumber\fR +.RS 4 +column number (count starts at 1) +.RE +.SH "RETURN VALUE" +.PP +The +OID +of the data type of the specified column or +InvalidOid +on error\&. On error, +\fISPI_result\fR +is set to +SPI_ERROR_NOATTRIBUTE\&. diff --git a/doc/src/sgml/man3/SPI_getvalue.3 b/doc/src/sgml/man3/SPI_getvalue.3 new file mode 100644 index 0000000..375bc31 --- /dev/null +++ b/doc/src/sgml/man3/SPI_getvalue.3 @@ -0,0 +1,72 @@ +'\" t +.\" Title: SPI_getvalue +.\" 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 "SPI_GETVALUE" "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" +SPI_getvalue \- return the string value of the specified column +.SH "SYNOPSIS" +.sp +.nf +char * SPI_getvalue(HeapTuple \fIrow\fR, TupleDesc \fIrowdesc\fR, int \fIcolnumber\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_getvalue\fR +returns the string representation of the value of the specified column\&. +.PP +The result is returned in memory allocated using +\fBpalloc\fR\&. (You can use +\fBpfree\fR +to release the memory when you don\*(Aqt need it anymore\&.) +.SH "ARGUMENTS" +.PP +HeapTuple \fIrow\fR +.RS 4 +input row to be examined +.RE +.PP +TupleDesc \fIrowdesc\fR +.RS 4 +input row description +.RE +.PP +int \fIcolnumber\fR +.RS 4 +column number (count starts at 1) +.RE +.SH "RETURN VALUE" +.PP +Column value, or +NULL +if the column is null, +\fIcolnumber\fR +is out of range (\fISPI_result\fR +is set to +SPI_ERROR_NOATTRIBUTE), or no output function is available (\fISPI_result\fR +is set to +SPI_ERROR_NOOUTFUNC)\&. diff --git a/doc/src/sgml/man3/SPI_is_cursor_plan.3 b/doc/src/sgml/man3/SPI_is_cursor_plan.3 new file mode 100644 index 0000000..ee56992 --- /dev/null +++ b/doc/src/sgml/man3/SPI_is_cursor_plan.3 @@ -0,0 +1,82 @@ +'\" t +.\" Title: SPI_is_cursor_plan +.\" 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 "SPI_IS_CURSOR_PLAN" "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" +SPI_is_cursor_plan \- return true if a statement prepared by \fBSPI_prepare\fR can be used with \fBSPI_cursor_open\fR +.SH "SYNOPSIS" +.sp +.nf +bool SPI_is_cursor_plan(SPIPlanPtr \fIplan\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_is_cursor_plan\fR +returns +true +if a statement prepared by +\fBSPI_prepare\fR +can be passed as an argument to +\fBSPI_cursor_open\fR, or +false +if that is not the case\&. The criteria are that the +\fIplan\fR +represents one single command and that this command returns tuples to the caller; for example, +\fBSELECT\fR +is allowed unless it contains an +INTO +clause, and +\fBUPDATE\fR +is allowed only if it contains a +RETURNING +clause\&. +.SH "ARGUMENTS" +.PP +SPIPlanPtr \fIplan\fR +.RS 4 +prepared statement (returned by +\fBSPI_prepare\fR) +.RE +.SH "RETURN VALUE" +.PP +true +or +false +to indicate if the +\fIplan\fR +can produce a cursor or not, with +\fISPI_result\fR +set to zero\&. If it is not possible to determine the answer (for example, if the +\fIplan\fR +is +NULL +or invalid, or if called when not connected to SPI), then +\fISPI_result\fR +is set to a suitable error code and +false +is returned\&. diff --git a/doc/src/sgml/man3/SPI_keepplan.3 b/doc/src/sgml/man3/SPI_keepplan.3 new file mode 100644 index 0000000..37c1205 --- /dev/null +++ b/doc/src/sgml/man3/SPI_keepplan.3 @@ -0,0 +1,63 @@ +'\" t +.\" Title: SPI_keepplan +.\" 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 "SPI_KEEPPLAN" "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" +SPI_keepplan \- save a prepared statement +.SH "SYNOPSIS" +.sp +.nf +int SPI_keepplan(SPIPlanPtr \fIplan\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_keepplan\fR +saves a passed statement (prepared by +\fBSPI_prepare\fR) so that it will not be freed by +\fBSPI_finish\fR +nor by the transaction manager\&. This gives you the ability to reuse prepared statements in the subsequent invocations of your C function in the current session\&. +.SH "ARGUMENTS" +.PP +SPIPlanPtr \fIplan\fR +.RS 4 +the prepared statement to be saved +.RE +.SH "RETURN VALUE" +.PP +0 on success; +SPI_ERROR_ARGUMENT +if +\fIplan\fR +is +NULL +or invalid +.SH "NOTES" +.PP +The passed\-in statement is relocated to permanent storage by means of pointer adjustment (no data copying is required)\&. If you later wish to delete it, use +\fBSPI_freeplan\fR +on it\&. diff --git a/doc/src/sgml/man3/SPI_modifytuple.3 b/doc/src/sgml/man3/SPI_modifytuple.3 new file mode 100644 index 0000000..563205b --- /dev/null +++ b/doc/src/sgml/man3/SPI_modifytuple.3 @@ -0,0 +1,143 @@ +'\" t +.\" Title: SPI_modifytuple +.\" 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 "SPI_MODIFYTUPLE" "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" +SPI_modifytuple \- create a row by replacing selected fields of a given row +.SH "SYNOPSIS" +.sp +.nf +HeapTuple SPI_modifytuple(Relation \fIrel\fR, HeapTuple \fIrow\fR, int \fIncols\fR, + int * \fIcolnum\fR, Datum * \fIvalues\fR, const char * \fInulls\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_modifytuple\fR +creates a new row by substituting new values for selected columns, copying the original row\*(Aqs columns at other positions\&. The input row is not modified\&. The new row is returned in the upper executor context\&. +.PP +This function can only be used while connected to SPI\&. Otherwise, it returns NULL and sets +\fISPI_result\fR +to +SPI_ERROR_UNCONNECTED\&. +.SH "ARGUMENTS" +.PP +Relation \fIrel\fR +.RS 4 +Used only as the source of the row descriptor for the row\&. (Passing a relation rather than a row descriptor is a misfeature\&.) +.RE +.PP +HeapTuple \fIrow\fR +.RS 4 +row to be modified +.RE +.PP +int \fIncols\fR +.RS 4 +number of columns to be changed +.RE +.PP +int * \fIcolnum\fR +.RS 4 +an array of length +\fIncols\fR, containing the numbers of the columns that are to be changed (column numbers start at 1) +.RE +.PP +Datum * \fIvalues\fR +.RS 4 +an array of length +\fIncols\fR, containing the new values for the specified columns +.RE +.PP +const char * \fInulls\fR +.RS 4 +an array of length +\fIncols\fR, describing which new values are null +.sp +If +\fInulls\fR +is +NULL +then +\fBSPI_modifytuple\fR +assumes that no new values are null\&. Otherwise, each entry of the +\fInulls\fR +array should be +\*(Aq\ \&\*(Aq +if the corresponding new value is non\-null, or +\*(Aqn\*(Aq +if the corresponding new value is null\&. (In the latter case, the actual value in the corresponding +\fIvalues\fR +entry doesn\*(Aqt matter\&.) Note that +\fInulls\fR +is not a text string, just an array: it does not need a +\*(Aq\e0\*(Aq +terminator\&. +.RE +.SH "RETURN VALUE" +.PP +new row with modifications, allocated in the upper executor context, or +NULL +on error (see +\fISPI_result\fR +for an error indication) +.PP +On error, +\fISPI_result\fR +is set as follows: +.PP +SPI_ERROR_ARGUMENT +.RS 4 +if +\fIrel\fR +is +NULL, or if +\fIrow\fR +is +NULL, or if +\fIncols\fR +is less than or equal to 0, or if +\fIcolnum\fR +is +NULL, or if +\fIvalues\fR +is +NULL\&. +.RE +.PP +SPI_ERROR_NOATTRIBUTE +.RS 4 +if +\fIcolnum\fR +contains an invalid column number (less than or equal to 0 or greater than the number of columns in +\fIrow\fR) +.RE +.PP +SPI_ERROR_UNCONNECTED +.RS 4 +if SPI is not active +.RE diff --git a/doc/src/sgml/man3/SPI_palloc.3 b/doc/src/sgml/man3/SPI_palloc.3 new file mode 100644 index 0000000..f2ffd15 --- /dev/null +++ b/doc/src/sgml/man3/SPI_palloc.3 @@ -0,0 +1,51 @@ +'\" t +.\" Title: SPI_palloc +.\" 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 "SPI_PALLOC" "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" +SPI_palloc \- allocate memory in the upper executor context +.SH "SYNOPSIS" +.sp +.nf +void * SPI_palloc(Size \fIsize\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_palloc\fR +allocates memory in the upper executor context\&. +.PP +This function can only be used while connected to SPI\&. Otherwise, it throws an error\&. +.SH "ARGUMENTS" +.PP +Size \fIsize\fR +.RS 4 +size in bytes of storage to allocate +.RE +.SH "RETURN VALUE" +.PP +pointer to new storage space of the specified size diff --git a/doc/src/sgml/man3/SPI_pfree.3 b/doc/src/sgml/man3/SPI_pfree.3 new file mode 100644 index 0000000..21d748c --- /dev/null +++ b/doc/src/sgml/man3/SPI_pfree.3 @@ -0,0 +1,52 @@ +'\" t +.\" Title: SPI_pfree +.\" 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 "SPI_PFREE" "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" +SPI_pfree \- free memory in the upper executor context +.SH "SYNOPSIS" +.sp +.nf +void SPI_pfree(void * \fIpointer\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_pfree\fR +frees memory previously allocated using +\fBSPI_palloc\fR +or +\fBSPI_repalloc\fR\&. +.PP +This function is no longer different from plain +\fBpfree\fR\&. It\*(Aqs kept just for backward compatibility of existing code\&. +.SH "ARGUMENTS" +.PP +void * \fIpointer\fR +.RS 4 +pointer to existing storage to free +.RE diff --git a/doc/src/sgml/man3/SPI_prepare.3 b/doc/src/sgml/man3/SPI_prepare.3 new file mode 100644 index 0000000..315ec75 --- /dev/null +++ b/doc/src/sgml/man3/SPI_prepare.3 @@ -0,0 +1,134 @@ +'\" t +.\" Title: SPI_prepare +.\" 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 "SPI_PREPARE" "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" +SPI_prepare \- prepare a statement, without executing it yet +.SH "SYNOPSIS" +.sp +.nf +SPIPlanPtr SPI_prepare(const char * \fIcommand\fR, int \fInargs\fR, Oid * \fIargtypes\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_prepare\fR +creates and returns a prepared statement for the specified command, but doesn\*(Aqt execute the command\&. The prepared statement can later be executed repeatedly using +\fBSPI_execute_plan\fR\&. +.PP +When the same or a similar command is to be executed repeatedly, it is generally advantageous to perform parse analysis only once, and might furthermore be advantageous to re\-use an execution plan for the command\&. +\fBSPI_prepare\fR +converts a command string into a prepared statement that encapsulates the results of parse analysis\&. The prepared statement also provides a place for caching an execution plan if it is found that generating a custom plan for each execution is not helpful\&. +.PP +A prepared command can be generalized by writing parameters ($1, +$2, etc\&.) in place of what would be constants in a normal command\&. The actual values of the parameters are then specified when +\fBSPI_execute_plan\fR +is called\&. This allows the prepared command to be used over a wider range of situations than would be possible without parameters\&. +.PP +The statement returned by +\fBSPI_prepare\fR +can be used only in the current invocation of the C function, since +\fBSPI_finish\fR +frees memory allocated for such a statement\&. But the statement can be saved for longer using the functions +\fBSPI_keepplan\fR +or +\fBSPI_saveplan\fR\&. +.SH "ARGUMENTS" +.PP +const char * \fIcommand\fR +.RS 4 +command string +.RE +.PP +int \fInargs\fR +.RS 4 +number of input parameters ($1, +$2, etc\&.) +.RE +.PP +Oid * \fIargtypes\fR +.RS 4 +pointer to an array containing the +OIDs of the data types of the parameters +.RE +.SH "RETURN VALUE" +.PP +\fBSPI_prepare\fR +returns a non\-null pointer to an +SPIPlan, which is an opaque struct representing a prepared statement\&. On error, +NULL +will be returned, and +\fISPI_result\fR +will be set to one of the same error codes used by +\fBSPI_execute\fR, except that it is set to +SPI_ERROR_ARGUMENT +if +\fIcommand\fR +is +NULL, or if +\fInargs\fR +is less than 0, or if +\fInargs\fR +is greater than 0 and +\fIargtypes\fR +is +NULL\&. +.SH "NOTES" +.PP +If no parameters are defined, a generic plan will be created at the first use of +\fBSPI_execute_plan\fR, and used for all subsequent executions as well\&. If there are parameters, the first few uses of +\fBSPI_execute_plan\fR +will generate custom plans that are specific to the supplied parameter values\&. After enough uses of the same prepared statement, +\fBSPI_execute_plan\fR +will build a generic plan, and if that is not too much more expensive than the custom plans, it will start using the generic plan instead of re\-planning each time\&. If this default behavior is unsuitable, you can alter it by passing the +CURSOR_OPT_GENERIC_PLAN +or +CURSOR_OPT_CUSTOM_PLAN +flag to +\fBSPI_prepare_cursor\fR, to force use of generic or custom plans respectively\&. +.PP +Although the main point of a prepared statement is to avoid repeated parse analysis and planning of the statement, +PostgreSQL +will force re\-analysis and re\-planning of the statement before using it whenever database objects used in the statement have undergone definitional (DDL) changes since the previous use of the prepared statement\&. Also, if the value of +search_path +changes from one use to the next, the statement will be re\-parsed using the new +\fIsearch_path\fR\&. (This latter behavior is new as of +PostgreSQL +9\&.3\&.) See +\fBPREPARE\fR(7) +for more information about the behavior of prepared statements\&. +.PP +This function should only be called from a connected C function\&. +.PP +SPIPlanPtr +is declared as a pointer to an opaque struct type in +spi\&.h\&. It is unwise to try to access its contents directly, as that makes your code much more likely to break in future revisions of +PostgreSQL\&. +.PP +The name +SPIPlanPtr +is somewhat historical, since the data structure no longer necessarily contains an execution plan\&. diff --git a/doc/src/sgml/man3/SPI_prepare_cursor.3 b/doc/src/sgml/man3/SPI_prepare_cursor.3 new file mode 100644 index 0000000..eeb35d4 --- /dev/null +++ b/doc/src/sgml/man3/SPI_prepare_cursor.3 @@ -0,0 +1,94 @@ +'\" t +.\" Title: SPI_prepare_cursor +.\" 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 "SPI_PREPARE_CURSOR" "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" +SPI_prepare_cursor \- prepare a statement, without executing it yet +.SH "SYNOPSIS" +.sp +.nf +SPIPlanPtr SPI_prepare_cursor(const char * \fIcommand\fR, int \fInargs\fR, + Oid * \fIargtypes\fR, int \fIcursorOptions\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_prepare_cursor\fR +is identical to +\fBSPI_prepare\fR, except that it also allows specification of the planner\*(Aqs +\(lqcursor options\(rq +parameter\&. This is a bit mask having the values shown in +nodes/parsenodes\&.h +for the +options +field of +DeclareCursorStmt\&. +\fBSPI_prepare\fR +always takes the cursor options as zero\&. +.PP +This function is now deprecated in favor of +\fBSPI_prepare_extended\fR\&. +.SH "ARGUMENTS" +.PP +const char * \fIcommand\fR +.RS 4 +command string +.RE +.PP +int \fInargs\fR +.RS 4 +number of input parameters ($1, +$2, etc\&.) +.RE +.PP +Oid * \fIargtypes\fR +.RS 4 +pointer to an array containing the +OIDs of the data types of the parameters +.RE +.PP +int \fIcursorOptions\fR +.RS 4 +integer bit mask of cursor options; zero produces default behavior +.RE +.SH "RETURN VALUE" +.PP +\fBSPI_prepare_cursor\fR +has the same return conventions as +\fBSPI_prepare\fR\&. +.SH "NOTES" +.PP +Useful bits to set in +\fIcursorOptions\fR +include +CURSOR_OPT_SCROLL, +CURSOR_OPT_NO_SCROLL, +CURSOR_OPT_FAST_PLAN, +CURSOR_OPT_GENERIC_PLAN, and +CURSOR_OPT_CUSTOM_PLAN\&. Note in particular that +CURSOR_OPT_HOLD +is ignored\&. diff --git a/doc/src/sgml/man3/SPI_prepare_extended.3 b/doc/src/sgml/man3/SPI_prepare_extended.3 new file mode 100644 index 0000000..9098a25 --- /dev/null +++ b/doc/src/sgml/man3/SPI_prepare_extended.3 @@ -0,0 +1,87 @@ +'\" t +.\" Title: SPI_prepare_extended +.\" 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 "SPI_PREPARE_EXTENDED" "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" +SPI_prepare_extended \- prepare a statement, without executing it yet +.SH "SYNOPSIS" +.sp +.nf +SPIPlanPtr SPI_prepare_extended(const char * \fIcommand\fR, + const SPIPrepareOptions * \fIoptions\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_prepare_extended\fR +creates and returns a prepared statement for the specified command, but doesn\*(Aqt execute the command\&. This function is equivalent to +\fBSPI_prepare\fR, with the addition that the caller can specify options to control the parsing of external parameter references, as well as other facets of query parsing and planning\&. +.SH "ARGUMENTS" +.PP +const char * \fIcommand\fR +.RS 4 +command string +.RE +.PP +const SPIPrepareOptions * \fIoptions\fR +.RS 4 +struct containing optional arguments +.RE +.PP +Callers should always zero out the entire +\fIoptions\fR +struct, then fill whichever fields they want to set\&. This ensures forward compatibility of code, since any fields that are added to the struct in future will be defined to behave backwards\-compatibly if they are zero\&. The currently available +\fIoptions\fR +fields are: +.PP +ParserSetupHook \fIparserSetup\fR +.RS 4 +Parser hook setup function +.RE +.PP +void * \fIparserSetupArg\fR +.RS 4 +pass\-through argument for +\fIparserSetup\fR +.RE +.PP +RawParseMode \fIparseMode\fR +.RS 4 +mode for raw parsing; +RAW_PARSE_DEFAULT +(zero) produces default behavior +.RE +.PP +int \fIcursorOptions\fR +.RS 4 +integer bit mask of cursor options; zero produces default behavior +.RE +.SH "RETURN VALUE" +.PP +\fBSPI_prepare_extended\fR +has the same return conventions as +\fBSPI_prepare\fR\&. diff --git a/doc/src/sgml/man3/SPI_prepare_params.3 b/doc/src/sgml/man3/SPI_prepare_params.3 new file mode 100644 index 0000000..4500736 --- /dev/null +++ b/doc/src/sgml/man3/SPI_prepare_params.3 @@ -0,0 +1,74 @@ +'\" t +.\" Title: SPI_prepare_params +.\" 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 "SPI_PREPARE_PARAMS" "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" +SPI_prepare_params \- prepare a statement, without executing it yet +.SH "SYNOPSIS" +.sp +.nf +SPIPlanPtr SPI_prepare_params(const char * \fIcommand\fR, + ParserSetupHook \fIparserSetup\fR, + void * \fIparserSetupArg\fR, + int \fIcursorOptions\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_prepare_params\fR +creates and returns a prepared statement for the specified command, but doesn\*(Aqt execute the command\&. This function is equivalent to +\fBSPI_prepare_cursor\fR, with the addition that the caller can specify parser hook functions to control the parsing of external parameter references\&. +.PP +This function is now deprecated in favor of +\fBSPI_prepare_extended\fR\&. +.SH "ARGUMENTS" +.PP +const char * \fIcommand\fR +.RS 4 +command string +.RE +.PP +ParserSetupHook \fIparserSetup\fR +.RS 4 +Parser hook setup function +.RE +.PP +void * \fIparserSetupArg\fR +.RS 4 +pass\-through argument for +\fIparserSetup\fR +.RE +.PP +int \fIcursorOptions\fR +.RS 4 +integer bit mask of cursor options; zero produces default behavior +.RE +.SH "RETURN VALUE" +.PP +\fBSPI_prepare_params\fR +has the same return conventions as +\fBSPI_prepare\fR\&. diff --git a/doc/src/sgml/man3/SPI_register_relation.3 b/doc/src/sgml/man3/SPI_register_relation.3 new file mode 100644 index 0000000..9ff9693 --- /dev/null +++ b/doc/src/sgml/man3/SPI_register_relation.3 @@ -0,0 +1,82 @@ +'\" t +.\" Title: SPI_register_relation +.\" 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 "SPI_REGISTER_RELATION" "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" +SPI_register_relation \- make an ephemeral named relation available by name in SPI queries +.SH "SYNOPSIS" +.sp +.nf +int SPI_register_relation(EphemeralNamedRelation \fIenr\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_register_relation\fR +makes an ephemeral named relation, with associated information, available to queries planned and executed through the current SPI connection\&. +.SH "ARGUMENTS" +.PP +EphemeralNamedRelation \fIenr\fR +.RS 4 +the ephemeral named relation registry entry +.RE +.SH "RETURN VALUE" +.PP +If the execution of the command was successful then the following (nonnegative) value will be returned: +.PP +SPI_OK_REL_REGISTER +.RS 4 +if the relation has been successfully registered by name +.RE +.PP +On error, one of the following negative values is returned: +.PP +SPI_ERROR_ARGUMENT +.RS 4 +if +\fIenr\fR +is +NULL +or its +\fIname\fR +field is +NULL +.RE +.PP +SPI_ERROR_UNCONNECTED +.RS 4 +if called from an unconnected C function +.RE +.PP +SPI_ERROR_REL_DUPLICATE +.RS 4 +if the name specified in the +\fIname\fR +field of +\fIenr\fR +is already registered for this connection +.RE diff --git a/doc/src/sgml/man3/SPI_register_trigger_data.3 b/doc/src/sgml/man3/SPI_register_trigger_data.3 new file mode 100644 index 0000000..99f5b36 --- /dev/null +++ b/doc/src/sgml/man3/SPI_register_trigger_data.3 @@ -0,0 +1,81 @@ +'\" t +.\" Title: SPI_register_trigger_data +.\" 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 "SPI_REGISTER_TRIGGER_DATA" "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" +SPI_register_trigger_data \- make ephemeral trigger data available in SPI queries +.SH "SYNOPSIS" +.sp +.nf +int SPI_register_trigger_data(TriggerData *\fItdata\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_register_trigger_data\fR +makes any ephemeral relations captured by a trigger available to queries planned and executed through the current SPI connection\&. Currently, this means the transition tables captured by an +AFTER +trigger defined with a +REFERENCING OLD/NEW TABLE AS +\&.\&.\&. clause\&. This function should be called by a PL trigger handler function after connecting\&. +.SH "ARGUMENTS" +.PP +TriggerData *\fItdata\fR +.RS 4 +the +TriggerData +object passed to a trigger handler function as +fcinfo\->context +.RE +.SH "RETURN VALUE" +.PP +If the execution of the command was successful then the following (nonnegative) value will be returned: +.PP +SPI_OK_TD_REGISTER +.RS 4 +if the captured trigger data (if any) has been successfully registered +.RE +.PP +On error, one of the following negative values is returned: +.PP +SPI_ERROR_ARGUMENT +.RS 4 +if +\fItdata\fR +is +NULL +.RE +.PP +SPI_ERROR_UNCONNECTED +.RS 4 +if called from an unconnected C function +.RE +.PP +SPI_ERROR_REL_DUPLICATE +.RS 4 +if the name of any trigger data transient relation is already registered for this connection +.RE diff --git a/doc/src/sgml/man3/SPI_repalloc.3 b/doc/src/sgml/man3/SPI_repalloc.3 new file mode 100644 index 0000000..0a5558b --- /dev/null +++ b/doc/src/sgml/man3/SPI_repalloc.3 @@ -0,0 +1,58 @@ +'\" t +.\" Title: SPI_repalloc +.\" 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 "SPI_REPALLOC" "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" +SPI_repalloc \- reallocate memory in the upper executor context +.SH "SYNOPSIS" +.sp +.nf +void * SPI_repalloc(void * \fIpointer\fR, Size \fIsize\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_repalloc\fR +changes the size of a memory segment previously allocated using +\fBSPI_palloc\fR\&. +.PP +This function is no longer different from plain +\fBrepalloc\fR\&. It\*(Aqs kept just for backward compatibility of existing code\&. +.SH "ARGUMENTS" +.PP +void * \fIpointer\fR +.RS 4 +pointer to existing storage to change +.RE +.PP +Size \fIsize\fR +.RS 4 +size in bytes of storage to allocate +.RE +.SH "RETURN VALUE" +.PP +pointer to new storage space of specified size with the contents copied from the existing area diff --git a/doc/src/sgml/man3/SPI_result_code_string.3 b/doc/src/sgml/man3/SPI_result_code_string.3 new file mode 100644 index 0000000..fa76942 --- /dev/null +++ b/doc/src/sgml/man3/SPI_result_code_string.3 @@ -0,0 +1,50 @@ +'\" t +.\" Title: SPI_result_code_string +.\" 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 "SPI_RESULT_CODE_STRING" "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" +SPI_result_code_string \- return error code as string +.SH "SYNOPSIS" +.sp +.nf +const char * SPI_result_code_string(int \fIcode\fR); +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_result_code_string\fR +returns a string representation of the result code returned by various SPI functions or stored in +\fISPI_result\fR\&. +.SH "ARGUMENTS" +.PP +int \fIcode\fR +.RS 4 +result code +.RE +.SH "RETURN VALUE" +.PP +A string representation of the result code\&. diff --git a/doc/src/sgml/man3/SPI_returntuple.3 b/doc/src/sgml/man3/SPI_returntuple.3 new file mode 100644 index 0000000..7d82491 --- /dev/null +++ b/doc/src/sgml/man3/SPI_returntuple.3 @@ -0,0 +1,73 @@ +'\" t +.\" Title: SPI_returntuple +.\" 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 "SPI_RETURNTUPLE" "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" +SPI_returntuple \- prepare to return a tuple as a Datum +.SH "SYNOPSIS" +.sp +.nf +HeapTupleHeader SPI_returntuple(HeapTuple \fIrow\fR, TupleDesc \fIrowdesc\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_returntuple\fR +makes a copy of a row in the upper executor context, returning it in the form of a row type +Datum\&. The returned pointer need only be converted to +Datum +via +\fBPointerGetDatum\fR +before returning\&. +.PP +This function can only be used while connected to SPI\&. Otherwise, it returns NULL and sets +\fISPI_result\fR +to +SPI_ERROR_UNCONNECTED\&. +.PP +Note that this should be used for functions that are declared to return composite types\&. It is not used for triggers; use +\fBSPI_copytuple\fR +for returning a modified row in a trigger\&. +.SH "ARGUMENTS" +.PP +HeapTuple \fIrow\fR +.RS 4 +row to be copied +.RE +.PP +TupleDesc \fIrowdesc\fR +.RS 4 +descriptor for row (pass the same descriptor each time for most effective caching) +.RE +.SH "RETURN VALUE" +.PP +HeapTupleHeader +pointing to copied row, or +NULL +on error (see +\fISPI_result\fR +for an error indication) diff --git a/doc/src/sgml/man3/SPI_rollback.3 b/doc/src/sgml/man3/SPI_rollback.3 new file mode 100644 index 0000000..487e849 --- /dev/null +++ b/doc/src/sgml/man3/SPI_rollback.3 @@ -0,0 +1,52 @@ +'\" t +.\" Title: SPI_rollback +.\" 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 "SPI_ROLLBACK" "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" +SPI_rollback, SPI_rollback_and_chain \- abort the current transaction +.SH "SYNOPSIS" +.sp +.nf +void SPI_rollback(void) +.fi +.sp +.nf +void SPI_rollback_and_chain(void) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_rollback\fR +rolls back the current transaction\&. It is approximately equivalent to running the SQL command +\fBROLLBACK\fR\&. After the transaction is rolled back, a new transaction is automatically started using default transaction characteristics, so that the caller can continue using SPI facilities\&. +.PP +\fBSPI_rollback_and_chain\fR +is the same, but the new transaction is started with the same transaction characteristics as the just finished one, like with the SQL command +\fBROLLBACK AND CHAIN\fR\&. +.PP +These functions can only be executed if the SPI connection has been set as nonatomic in the call to +\fBSPI_connect_ext\fR\&. diff --git a/doc/src/sgml/man3/SPI_rollback_and_chain.3 b/doc/src/sgml/man3/SPI_rollback_and_chain.3 new file mode 100644 index 0000000..25edc95 --- /dev/null +++ b/doc/src/sgml/man3/SPI_rollback_and_chain.3 @@ -0,0 +1 @@ +.so man3/SPI_rollback.3 diff --git a/doc/src/sgml/man3/SPI_saveplan.3 b/doc/src/sgml/man3/SPI_saveplan.3 new file mode 100644 index 0000000..ea0df78 --- /dev/null +++ b/doc/src/sgml/man3/SPI_saveplan.3 @@ -0,0 +1,80 @@ +'\" t +.\" Title: SPI_saveplan +.\" 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 "SPI_SAVEPLAN" "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" +SPI_saveplan \- save a prepared statement +.SH "SYNOPSIS" +.sp +.nf +SPIPlanPtr SPI_saveplan(SPIPlanPtr \fIplan\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_saveplan\fR +copies a passed statement (prepared by +\fBSPI_prepare\fR) into memory that will not be freed by +\fBSPI_finish\fR +nor by the transaction manager, and returns a pointer to the copied statement\&. This gives you the ability to reuse prepared statements in the subsequent invocations of your C function in the current session\&. +.SH "ARGUMENTS" +.PP +SPIPlanPtr \fIplan\fR +.RS 4 +the prepared statement to be saved +.RE +.SH "RETURN VALUE" +.PP +Pointer to the copied statement; or +NULL +if unsuccessful\&. On error, +\fISPI_result\fR +is set thus: +.PP +SPI_ERROR_ARGUMENT +.RS 4 +if +\fIplan\fR +is +NULL +or invalid +.RE +.PP +SPI_ERROR_UNCONNECTED +.RS 4 +if called from an unconnected C function +.RE +.SH "NOTES" +.PP +The originally passed\-in statement is not freed, so you might wish to do +\fBSPI_freeplan\fR +on it to avoid leaking memory until +\fBSPI_finish\fR\&. +.PP +In most cases, +\fBSPI_keepplan\fR +is preferred to this function, since it accomplishes largely the same result without needing to physically copy the prepared statement\*(Aqs data structures\&. diff --git a/doc/src/sgml/man3/SPI_scroll_cursor_fetch.3 b/doc/src/sgml/man3/SPI_scroll_cursor_fetch.3 new file mode 100644 index 0000000..a303413 --- /dev/null +++ b/doc/src/sgml/man3/SPI_scroll_cursor_fetch.3 @@ -0,0 +1,91 @@ +'\" t +.\" Title: SPI_scroll_cursor_fetch +.\" 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 "SPI_SCROLL_CURSOR_FETCH" "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" +SPI_scroll_cursor_fetch \- fetch some rows from a cursor +.SH "SYNOPSIS" +.sp +.nf +void SPI_scroll_cursor_fetch(Portal \fIportal\fR, FetchDirection \fIdirection\fR, + long \fIcount\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_scroll_cursor_fetch\fR +fetches some rows from a cursor\&. This is equivalent to the SQL command +\fBFETCH\fR\&. +.SH "ARGUMENTS" +.PP +Portal \fIportal\fR +.RS 4 +portal containing the cursor +.RE +.PP +FetchDirection \fIdirection\fR +.RS 4 +one of +FETCH_FORWARD, +FETCH_BACKWARD, +FETCH_ABSOLUTE +or +FETCH_RELATIVE +.RE +.PP +long \fIcount\fR +.RS 4 +number of rows to fetch for +FETCH_FORWARD +or +FETCH_BACKWARD; absolute row number to fetch for +FETCH_ABSOLUTE; or relative row number to fetch for +FETCH_RELATIVE +.RE +.SH "RETURN VALUE" +.PP +\fISPI_processed\fR +and +\fISPI_tuptable\fR +are set as in +\fBSPI_execute\fR +if successful\&. +.SH "NOTES" +.PP +See the SQL +\fBFETCH\fR(7) +command for details of the interpretation of the +\fIdirection\fR +and +\fIcount\fR +parameters\&. +.PP +Direction values other than +FETCH_FORWARD +may fail if the cursor\*(Aqs plan was not created with the +CURSOR_OPT_SCROLL +option\&. diff --git a/doc/src/sgml/man3/SPI_scroll_cursor_move.3 b/doc/src/sgml/man3/SPI_scroll_cursor_move.3 new file mode 100644 index 0000000..786822e --- /dev/null +++ b/doc/src/sgml/man3/SPI_scroll_cursor_move.3 @@ -0,0 +1,92 @@ +'\" t +.\" Title: SPI_scroll_cursor_move +.\" 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 "SPI_SCROLL_CURSOR_MOVE" "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" +SPI_scroll_cursor_move \- move a cursor +.SH "SYNOPSIS" +.sp +.nf +void SPI_scroll_cursor_move(Portal \fIportal\fR, FetchDirection \fIdirection\fR, + long \fIcount\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_scroll_cursor_move\fR +skips over some number of rows in a cursor\&. This is equivalent to the SQL command +\fBMOVE\fR\&. +.SH "ARGUMENTS" +.PP +Portal \fIportal\fR +.RS 4 +portal containing the cursor +.RE +.PP +FetchDirection \fIdirection\fR +.RS 4 +one of +FETCH_FORWARD, +FETCH_BACKWARD, +FETCH_ABSOLUTE +or +FETCH_RELATIVE +.RE +.PP +long \fIcount\fR +.RS 4 +number of rows to move for +FETCH_FORWARD +or +FETCH_BACKWARD; absolute row number to move to for +FETCH_ABSOLUTE; or relative row number to move to for +FETCH_RELATIVE +.RE +.SH "RETURN VALUE" +.PP +\fISPI_processed\fR +is set as in +\fBSPI_execute\fR +if successful\&. +\fISPI_tuptable\fR +is set to +NULL, since no rows are returned by this function\&. +.SH "NOTES" +.PP +See the SQL +\fBFETCH\fR(7) +command for details of the interpretation of the +\fIdirection\fR +and +\fIcount\fR +parameters\&. +.PP +Direction values other than +FETCH_FORWARD +may fail if the cursor\*(Aqs plan was not created with the +CURSOR_OPT_SCROLL +option\&. diff --git a/doc/src/sgml/man3/SPI_start_transaction.3 b/doc/src/sgml/man3/SPI_start_transaction.3 new file mode 100644 index 0000000..c4319fd --- /dev/null +++ b/doc/src/sgml/man3/SPI_start_transaction.3 @@ -0,0 +1,45 @@ +'\" t +.\" Title: SPI_start_transaction +.\" 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 "SPI_START_TRANSACTION" "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" +SPI_start_transaction \- obsolete function +.SH "SYNOPSIS" +.sp +.nf +void SPI_start_transaction(void) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_start_transaction\fR +does nothing, and exists only for code compatibility with earlier +PostgreSQL +releases\&. It used to be required after calling +\fBSPI_commit\fR +or +\fBSPI_rollback\fR, but now those functions start a new transaction automatically\&. diff --git a/doc/src/sgml/man3/SPI_unregister_relation.3 b/doc/src/sgml/man3/SPI_unregister_relation.3 new file mode 100644 index 0000000..5ff5d20 --- /dev/null +++ b/doc/src/sgml/man3/SPI_unregister_relation.3 @@ -0,0 +1,76 @@ +'\" t +.\" Title: SPI_unregister_relation +.\" 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 "SPI_UNREGISTER_RELATION" "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" +SPI_unregister_relation \- remove an ephemeral named relation from the registry +.SH "SYNOPSIS" +.sp +.nf +int SPI_unregister_relation(const char * \fIname\fR) +.fi +.SH "DESCRIPTION" +.PP +\fBSPI_unregister_relation\fR +removes an ephemeral named relation from the registry for the current connection\&. +.SH "ARGUMENTS" +.PP +const char * \fIname\fR +.RS 4 +the relation registry entry name +.RE +.SH "RETURN VALUE" +.PP +If the execution of the command was successful then the following (nonnegative) value will be returned: +.PP +SPI_OK_REL_UNREGISTER +.RS 4 +if the tuplestore has been successfully removed from the registry +.RE +.PP +On error, one of the following negative values is returned: +.PP +SPI_ERROR_ARGUMENT +.RS 4 +if +\fIname\fR +is +NULL +.RE +.PP +SPI_ERROR_UNCONNECTED +.RS 4 +if called from an unconnected C function +.RE +.PP +SPI_ERROR_REL_NOT_FOUND +.RS 4 +if +\fIname\fR +is not found in the registry for the current connection +.RE diff --git a/doc/src/sgml/man3/dblink.3 b/doc/src/sgml/man3/dblink.3 new file mode 100644 index 0000000..fb2463d --- /dev/null +++ b/doc/src/sgml/man3/dblink.3 @@ -0,0 +1,212 @@ +'\" t +.\" Title: dblink +.\" 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" "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 \- executes a query in a remote database +.SH "SYNOPSIS" +.sp +.nf +dblink(text connname, text sql [, bool fail_on_error]) returns setof record +dblink(text connstr, text sql [, bool fail_on_error]) returns setof record +dblink(text sql [, bool fail_on_error]) returns setof record +.fi +.SH "DESCRIPTION" +.PP +\fBdblink\fR +executes a query (usually a +\fBSELECT\fR, but it can be any SQL statement that returns rows) in a remote database\&. +.PP +When two +text +arguments are given, the first one is first looked up as a persistent connection\*(Aqs name; if found, the command is executed on that connection\&. If not found, the first argument is treated as a connection info string as for +\fBdblink_connect\fR, and the indicated connection is made just for the duration of this command\&. +.SH "ARGUMENTS" +.PP +\fIconnname\fR +.RS 4 +Name of the connection to use; omit this parameter to use the unnamed connection\&. +.RE +.PP +\fIconnstr\fR +.RS 4 +A connection info string, as previously described for +\fBdblink_connect\fR\&. +.RE +.PP +\fIsql\fR +.RS 4 +The SQL query that you wish to execute in the remote database, for example +select * from foo\&. +.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 +The function returns the row(s) produced by the query\&. Since +\fBdblink\fR +can be used with any query, it is declared to return +record, rather than specifying any particular set of columns\&. This means that you must specify the expected set of columns in the calling query \(em otherwise +PostgreSQL +would not know what to expect\&. Here is an example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT * + FROM dblink(\*(Aqdbname=mydb options=\-csearch_path=\*(Aq, + \*(Aqselect proname, prosrc from pg_proc\*(Aq) + AS t1(proname name, prosrc text) + WHERE proname LIKE \*(Aqbytea%\*(Aq; +.fi +.if n \{\ +.RE +.\} +.sp +The +\(lqalias\(rq +part of the +FROM +clause must specify the column names and types that the function will return\&. (Specifying column names in an alias is actually standard SQL syntax, but specifying column types is a +PostgreSQL +extension\&.) This allows the system to understand what +* +should expand to, and what +proname +in the +WHERE +clause refers to, in advance of trying to execute the function\&. At run time, an error will be thrown if the actual query result from the remote database does not have the same number of columns shown in the +FROM +clause\&. The column names need not match, however, and +\fBdblink\fR +does not insist on exact type matches either\&. It will succeed so long as the returned data strings are valid input for the column type declared in the +FROM +clause\&. +.SH "NOTES" +.PP +A convenient way to use +\fBdblink\fR +with predetermined queries is to create a view\&. This allows the column type information to be buried in the view, instead of having to spell it out in every query\&. For example, +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE VIEW myremote_pg_proc AS + SELECT * + FROM dblink(\*(Aqdbname=postgres options=\-csearch_path=\*(Aq, + \*(Aqselect proname, prosrc from pg_proc\*(Aq) + AS t1(proname name, prosrc text); + +SELECT * FROM myremote_pg_proc WHERE proname LIKE \*(Aqbytea%\*(Aq; +.fi +.if n \{\ +.RE +.\} +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT * FROM dblink(\*(Aqdbname=postgres options=\-csearch_path=\*(Aq, + \*(Aqselect proname, prosrc from pg_proc\*(Aq) + AS t1(proname name, prosrc text) WHERE proname LIKE \*(Aqbytea%\*(Aq; + proname | prosrc +\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\- + byteacat | byteacat + byteaeq | byteaeq + bytealt | bytealt + byteale | byteale + byteagt | byteagt + byteage | byteage + byteane | byteane + byteacmp | byteacmp + bytealike | bytealike + byteanlike | byteanlike + byteain | byteain + byteaout | byteaout +(12 rows) + +SELECT dblink_connect(\*(Aqdbname=postgres options=\-csearch_path=\*(Aq); + dblink_connect +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) + +SELECT * FROM dblink(\*(Aqselect proname, prosrc from pg_proc\*(Aq) + AS t1(proname name, prosrc text) WHERE proname LIKE \*(Aqbytea%\*(Aq; + proname | prosrc +\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\- + byteacat | byteacat + byteaeq | byteaeq + bytealt | bytealt + byteale | byteale + byteagt | byteagt + byteage | byteage + byteane | byteane + byteacmp | byteacmp + bytealike | bytealike + byteanlike | byteanlike + byteain | byteain + byteaout | byteaout +(12 rows) + +SELECT dblink_connect(\*(Aqmyconn\*(Aq, \*(Aqdbname=regression options=\-csearch_path=\*(Aq); + dblink_connect +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) + +SELECT * FROM dblink(\*(Aqmyconn\*(Aq, \*(Aqselect proname, prosrc from pg_proc\*(Aq) + AS t1(proname name, prosrc text) WHERE proname LIKE \*(Aqbytea%\*(Aq; + proname | prosrc +\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\- + bytearecv | bytearecv + byteasend | byteasend + byteale | byteale + byteagt | byteagt + byteage | byteage + byteane | byteane + byteacmp | byteacmp + bytealike | bytealike + byteanlike | byteanlike + byteacat | byteacat + byteaeq | byteaeq + bytealt | bytealt + byteain | byteain + byteaout | byteaout +(14 rows) +.fi +.if n \{\ +.RE +.\} diff --git a/doc/src/sgml/man3/dblink_build_sql_delete.3 b/doc/src/sgml/man3/dblink_build_sql_delete.3 new file mode 100644 index 0000000..0c813f5 --- /dev/null +++ b/doc/src/sgml/man3/dblink_build_sql_delete.3 @@ -0,0 +1,99 @@ +'\" t +.\" Title: dblink_build_sql_delete +.\" 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_BUILD_SQL_DELETE" "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_build_sql_delete \- builds a DELETE statement using supplied values for primary key field values +.SH "SYNOPSIS" +.sp +.nf +dblink_build_sql_delete(text relname, + int2vector primary_key_attnums, + integer num_primary_key_atts, + text[] tgt_pk_att_vals_array) returns text +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_build_sql_delete\fR +can be useful in doing selective replication of a local table to a remote database\&. It builds an SQL +\fBDELETE\fR +command that will delete the row with the given primary key values\&. +.SH "ARGUMENTS" +.PP +\fIrelname\fR +.RS 4 +Name of a local relation, for example +foo +or +myschema\&.mytab\&. Include double quotes if the name is mixed\-case or contains special characters, for example +"FooBar"; without quotes, the string will be folded to lower case\&. +.RE +.PP +\fIprimary_key_attnums\fR +.RS 4 +Attribute numbers (1\-based) of the primary key fields, for example +1 2\&. +.RE +.PP +\fInum_primary_key_atts\fR +.RS 4 +The number of primary key fields\&. +.RE +.PP +\fItgt_pk_att_vals_array\fR +.RS 4 +Values of the primary key fields to be used in the resulting +\fBDELETE\fR +command\&. Each field is represented in text form\&. +.RE +.SH "RETURN VALUE" +.PP +Returns the requested SQL statement as text\&. +.SH "NOTES" +.PP +As of +PostgreSQL +9\&.0, the attribute numbers in +\fIprimary_key_attnums\fR +are interpreted as logical column numbers, corresponding to the column\*(Aqs position in +SELECT * FROM relname\&. Previous versions interpreted the numbers as physical column positions\&. There is a difference if any column(s) to the left of the indicated column have been dropped during the lifetime of the table\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT dblink_build_sql_delete(\*(Aq"MyFoo"\*(Aq, \*(Aq1 2\*(Aq, 2, \*(Aq{"1", "b"}\*(Aq); + dblink_build_sql_delete +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + DELETE FROM "MyFoo" WHERE f1=\*(Aq1\*(Aq AND f2=\*(Aqb\*(Aq +(1 row) +.fi +.if n \{\ +.RE +.\} diff --git a/doc/src/sgml/man3/dblink_build_sql_insert.3 b/doc/src/sgml/man3/dblink_build_sql_insert.3 new file mode 100644 index 0000000..c01dcf8 --- /dev/null +++ b/doc/src/sgml/man3/dblink_build_sql_insert.3 @@ -0,0 +1,105 @@ +'\" t +.\" Title: dblink_build_sql_insert +.\" 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_BUILD_SQL_INSERT" "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_build_sql_insert \- builds an INSERT statement using a local tuple, replacing the primary key field values with alternative supplied values +.SH "SYNOPSIS" +.sp +.nf +dblink_build_sql_insert(text relname, + int2vector primary_key_attnums, + integer num_primary_key_atts, + text[] src_pk_att_vals_array, + text[] tgt_pk_att_vals_array) returns text +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_build_sql_insert\fR +can be useful in doing selective replication of a local table to a remote database\&. It selects a row from the local table based on primary key, and then builds an SQL +\fBINSERT\fR +command that will duplicate that row, but with the primary key values replaced by the values in the last argument\&. (To make an exact copy of the row, just specify the same values for the last two arguments\&.) +.SH "ARGUMENTS" +.PP +\fIrelname\fR +.RS 4 +Name of a local relation, for example +foo +or +myschema\&.mytab\&. Include double quotes if the name is mixed\-case or contains special characters, for example +"FooBar"; without quotes, the string will be folded to lower case\&. +.RE +.PP +\fIprimary_key_attnums\fR +.RS 4 +Attribute numbers (1\-based) of the primary key fields, for example +1 2\&. +.RE +.PP +\fInum_primary_key_atts\fR +.RS 4 +The number of primary key fields\&. +.RE +.PP +\fIsrc_pk_att_vals_array\fR +.RS 4 +Values of the primary key fields to be used to look up the local tuple\&. Each field is represented in text form\&. An error is thrown if there is no local row with these primary key values\&. +.RE +.PP +\fItgt_pk_att_vals_array\fR +.RS 4 +Values of the primary key fields to be placed in the resulting +\fBINSERT\fR +command\&. Each field is represented in text form\&. +.RE +.SH "RETURN VALUE" +.PP +Returns the requested SQL statement as text\&. +.SH "NOTES" +.PP +As of +PostgreSQL +9\&.0, the attribute numbers in +\fIprimary_key_attnums\fR +are interpreted as logical column numbers, corresponding to the column\*(Aqs position in +SELECT * FROM relname\&. Previous versions interpreted the numbers as physical column positions\&. There is a difference if any column(s) to the left of the indicated column have been dropped during the lifetime of the table\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT dblink_build_sql_insert(\*(Aqfoo\*(Aq, \*(Aq1 2\*(Aq, 2, \*(Aq{"1", "a"}\*(Aq, \*(Aq{"1", "b\*(Aq\*(Aqa"}\*(Aq); + dblink_build_sql_insert +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + INSERT INTO foo(f1,f2,f3) VALUES(\*(Aq1\*(Aq,\*(Aqb\*(Aq\*(Aqa\*(Aq,\*(Aq1\*(Aq) +(1 row) +.fi +.if n \{\ +.RE +.\} diff --git a/doc/src/sgml/man3/dblink_build_sql_update.3 b/doc/src/sgml/man3/dblink_build_sql_update.3 new file mode 100644 index 0000000..2de7967 --- /dev/null +++ b/doc/src/sgml/man3/dblink_build_sql_update.3 @@ -0,0 +1,109 @@ +'\" t +.\" Title: dblink_build_sql_update +.\" 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_BUILD_SQL_UPDATE" "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_build_sql_update \- builds an UPDATE statement using a local tuple, replacing the primary key field values with alternative supplied values +.SH "SYNOPSIS" +.sp +.nf +dblink_build_sql_update(text relname, + int2vector primary_key_attnums, + integer num_primary_key_atts, + text[] src_pk_att_vals_array, + text[] tgt_pk_att_vals_array) returns text +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_build_sql_update\fR +can be useful in doing selective replication of a local table to a remote database\&. It selects a row from the local table based on primary key, and then builds an SQL +\fBUPDATE\fR +command that will duplicate that row, but with the primary key values replaced by the values in the last argument\&. (To make an exact copy of the row, just specify the same values for the last two arguments\&.) The +\fBUPDATE\fR +command always assigns all fields of the row \(em the main difference between this and +\fBdblink_build_sql_insert\fR +is that it\*(Aqs assumed that the target row already exists in the remote table\&. +.SH "ARGUMENTS" +.PP +\fIrelname\fR +.RS 4 +Name of a local relation, for example +foo +or +myschema\&.mytab\&. Include double quotes if the name is mixed\-case or contains special characters, for example +"FooBar"; without quotes, the string will be folded to lower case\&. +.RE +.PP +\fIprimary_key_attnums\fR +.RS 4 +Attribute numbers (1\-based) of the primary key fields, for example +1 2\&. +.RE +.PP +\fInum_primary_key_atts\fR +.RS 4 +The number of primary key fields\&. +.RE +.PP +\fIsrc_pk_att_vals_array\fR +.RS 4 +Values of the primary key fields to be used to look up the local tuple\&. Each field is represented in text form\&. An error is thrown if there is no local row with these primary key values\&. +.RE +.PP +\fItgt_pk_att_vals_array\fR +.RS 4 +Values of the primary key fields to be placed in the resulting +\fBUPDATE\fR +command\&. Each field is represented in text form\&. +.RE +.SH "RETURN VALUE" +.PP +Returns the requested SQL statement as text\&. +.SH "NOTES" +.PP +As of +PostgreSQL +9\&.0, the attribute numbers in +\fIprimary_key_attnums\fR +are interpreted as logical column numbers, corresponding to the column\*(Aqs position in +SELECT * FROM relname\&. Previous versions interpreted the numbers as physical column positions\&. There is a difference if any column(s) to the left of the indicated column have been dropped during the lifetime of the table\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT dblink_build_sql_update(\*(Aqfoo\*(Aq, \*(Aq1 2\*(Aq, 2, \*(Aq{"1", "a"}\*(Aq, \*(Aq{"1", "b"}\*(Aq); + dblink_build_sql_update +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + UPDATE foo SET f1=\*(Aq1\*(Aq,f2=\*(Aqb\*(Aq,f3=\*(Aq1\*(Aq WHERE f1=\*(Aq1\*(Aq AND f2=\*(Aqb\*(Aq +(1 row) +.fi +.if n \{\ +.RE +.\} diff --git a/doc/src/sgml/man3/dblink_cancel_query.3 b/doc/src/sgml/man3/dblink_cancel_query.3 new file mode 100644 index 0000000..2ae393c --- /dev/null +++ b/doc/src/sgml/man3/dblink_cancel_query.3 @@ -0,0 +1,63 @@ +'\" t +.\" Title: dblink_cancel_query +.\" 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_CANCEL_QUERY" "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_cancel_query \- cancels any active query on the named connection +.SH "SYNOPSIS" +.sp +.nf +dblink_cancel_query(text connname) returns text +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_cancel_query\fR +attempts to cancel any query that is in progress on the named connection\&. Note that this is not certain to succeed (since, for example, the remote query might already have finished)\&. A cancel request simply improves the odds that the query will fail soon\&. You must still complete the normal query protocol, for example by calling +\fBdblink_get_result\fR\&. +.SH "ARGUMENTS" +.PP +\fIconnname\fR +.RS 4 +Name of the connection to use\&. +.RE +.SH "RETURN VALUE" +.PP +Returns +OK +if the cancel request has been sent, or the text of an error message on failure\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT dblink_cancel_query(\*(Aqdtest1\*(Aq); +.fi +.if n \{\ +.RE +.\} diff --git a/doc/src/sgml/man3/dblink_close.3 b/doc/src/sgml/man3/dblink_close.3 new file mode 100644 index 0000000..20e1cfd --- /dev/null +++ b/doc/src/sgml/man3/dblink_close.3 @@ -0,0 +1,100 @@ +'\" t +.\" Title: dblink_close +.\" 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_CLOSE" "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_close \- closes a cursor in a remote database +.SH "SYNOPSIS" +.sp +.nf +dblink_close(text cursorname [, bool fail_on_error]) returns text +dblink_close(text connname, text cursorname [, bool fail_on_error]) returns text +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_close\fR +closes a cursor previously opened with +\fBdblink_open\fR\&. +.SH "ARGUMENTS" +.PP +\fIconnname\fR +.RS 4 +Name of the connection to use; omit this parameter to use the unnamed connection\&. +.RE +.PP +\fIcursorname\fR +.RS 4 +The name of the cursor to close\&. +.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\*(Aqs return value is set to +ERROR\&. +.RE +.SH "RETURN VALUE" +.PP +Returns status, either +OK +or +ERROR\&. +.SH "NOTES" +.PP +If +\fBdblink_open\fR +started an explicit transaction block, and this is the last remaining open cursor in this connection, +\fBdblink_close\fR +will issue the matching +\fBCOMMIT\fR\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT dblink_connect(\*(Aqdbname=postgres options=\-csearch_path=\*(Aq); + dblink_connect +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) + +SELECT dblink_open(\*(Aqfoo\*(Aq, \*(Aqselect proname, prosrc from pg_proc\*(Aq); + dblink_open +\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) + +SELECT dblink_close(\*(Aqfoo\*(Aq); + dblink_close +\-\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) +.fi +.if n \{\ +.RE +.\} diff --git a/doc/src/sgml/man3/dblink_connect.3 b/doc/src/sgml/man3/dblink_connect.3 new file mode 100644 index 0000000..9e07450 --- /dev/null +++ b/doc/src/sgml/man3/dblink_connect.3 @@ -0,0 +1,155 @@ +'\" t +.\" Title: dblink_connect +.\" 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_CONNECT" "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_connect \- opens a persistent connection to a remote database +.SH "SYNOPSIS" +.sp +.nf +dblink_connect(text connstr) returns text +dblink_connect(text connname, text connstr) returns text +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_connect()\fR +establishes a connection to a remote +PostgreSQL +database\&. The server and database to be contacted are identified through a standard +libpq +connection string\&. Optionally, a name can be assigned to the connection\&. Multiple named connections can be open at once, but only one unnamed connection is permitted at a time\&. The connection will persist until closed or until the database session is ended\&. +.PP +The connection string may also be the name of an existing foreign server\&. It is recommended to use the foreign\-data wrapper +dblink_fdw +when defining the foreign server\&. See the example below, as well as +CREATE SERVER (\fBCREATE_SERVER\fR(7)) +and +CREATE USER MAPPING (\fBCREATE_USER_MAPPING\fR(7))\&. +.SH "ARGUMENTS" +.PP +\fIconnname\fR +.RS 4 +The name to use for this connection; if omitted, an unnamed connection is opened, replacing any existing unnamed connection\&. +.RE +.PP +\fIconnstr\fR +.RS 4 +libpq\-style connection info string, for example +hostaddr=127\&.0\&.0\&.1 port=5432 dbname=mydb user=postgres password=mypasswd options=\-csearch_path=\&. For details see +Section\ \&34.1.1\&. Alternatively, the name of a foreign server\&. +.RE +.SH "RETURN VALUE" +.PP +Returns status, which is always +OK +(since any error causes the function to throw an error instead of returning)\&. +.SH "NOTES" +.PP +If untrusted users have access to a database that has not adopted a +secure schema usage pattern, begin each session by removing publicly\-writable schemas from +\fIsearch_path\fR\&. One could, for example, add +options=\-csearch_path= +to +\fIconnstr\fR\&. This consideration is not specific to +dblink; it applies to every interface for executing arbitrary SQL commands\&. +.PP +Only superusers may use +\fBdblink_connect\fR +to create non\-password\-authenticated connections\&. If non\-superusers need this capability, use +\fBdblink_connect_u\fR +instead\&. +.PP +It is unwise to choose connection names that contain equal signs, as this opens a risk of confusion with connection info strings in other +dblink +functions\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT dblink_connect(\*(Aqdbname=postgres options=\-csearch_path=\*(Aq); + dblink_connect +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) + +SELECT dblink_connect(\*(Aqmyconn\*(Aq, \*(Aqdbname=postgres options=\-csearch_path=\*(Aq); + dblink_connect +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) + +\-\- FOREIGN DATA WRAPPER functionality +\-\- Note: local connection must require password authentication for this to work properly +\-\- Otherwise, you will receive the following error from dblink_connect(): +\-\- ERROR: password is required +\-\- DETAIL: Non\-superuser cannot connect if the server does not request a password\&. +\-\- HINT: Target server\*(Aqs authentication method must be changed\&. + +CREATE SERVER fdtest FOREIGN DATA WRAPPER dblink_fdw OPTIONS (hostaddr \*(Aq127\&.0\&.0\&.1\*(Aq, dbname \*(Aqcontrib_regression\*(Aq); + +CREATE USER regress_dblink_user WITH PASSWORD \*(Aqsecret\*(Aq; +CREATE USER MAPPING FOR regress_dblink_user SERVER fdtest OPTIONS (user \*(Aqregress_dblink_user\*(Aq, password \*(Aqsecret\*(Aq); +GRANT USAGE ON FOREIGN SERVER fdtest TO regress_dblink_user; +GRANT SELECT ON TABLE foo TO regress_dblink_user; + +\eset ORIGINAL_USER :USER +\ec \- regress_dblink_user +SELECT dblink_connect(\*(Aqmyconn\*(Aq, \*(Aqfdtest\*(Aq); + dblink_connect +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) + +SELECT * FROM dblink(\*(Aqmyconn\*(Aq, \*(AqSELECT * FROM foo\*(Aq) AS t(a int, b text, c text[]); + a | b | c +\-\-\-\-+\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 0 | a | {a0,b0,c0} + 1 | b | {a1,b1,c1} + 2 | c | {a2,b2,c2} + 3 | d | {a3,b3,c3} + 4 | e | {a4,b4,c4} + 5 | f | {a5,b5,c5} + 6 | g | {a6,b6,c6} + 7 | h | {a7,b7,c7} + 8 | i | {a8,b8,c8} + 9 | j | {a9,b9,c9} + 10 | k | {a10,b10,c10} +(11 rows) + +\ec \- :ORIGINAL_USER +REVOKE USAGE ON FOREIGN SERVER fdtest FROM regress_dblink_user; +REVOKE SELECT ON TABLE foo FROM regress_dblink_user; +DROP USER MAPPING FOR regress_dblink_user SERVER fdtest; +DROP USER regress_dblink_user; +DROP SERVER fdtest; +.fi +.if n \{\ +.RE +.\} diff --git a/doc/src/sgml/man3/dblink_connect_u.3 b/doc/src/sgml/man3/dblink_connect_u.3 new file mode 100644 index 0000000..df1a9a7 --- /dev/null +++ b/doc/src/sgml/man3/dblink_connect_u.3 @@ -0,0 +1,62 @@ +'\" t +.\" Title: dblink_connect_u +.\" 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_CONNECT_U" "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_connect_u \- opens a persistent connection to a remote database, insecurely +.SH "SYNOPSIS" +.sp +.nf +dblink_connect_u(text connstr) returns text +dblink_connect_u(text connname, text connstr) returns text +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_connect_u()\fR +is identical to +\fBdblink_connect()\fR, except that it will allow non\-superusers to connect using any authentication method\&. +.PP +If the remote server selects an authentication method that does not involve a password, then impersonation and subsequent escalation of privileges can occur, because the session will appear to have originated from the user as which the local +PostgreSQL +server runs\&. Also, even if the remote server does demand a password, it is possible for the password to be supplied from the server environment, such as a +~/\&.pgpass +file belonging to the server\*(Aqs user\&. This opens not only a risk of impersonation, but the possibility of exposing a password to an untrustworthy remote server\&. Therefore, +\fBdblink_connect_u()\fR +is initially installed with all privileges revoked from +PUBLIC, making it un\-callable except by superusers\&. In some situations it may be appropriate to grant +EXECUTE +permission for +\fBdblink_connect_u()\fR +to specific users who are considered trustworthy, but this should be done with care\&. It is also recommended that any +~/\&.pgpass +file belonging to the server\*(Aqs user +\fInot\fR +contain any records specifying a wildcard host name\&. +.PP +For further details see +\fBdblink_connect()\fR\&. diff --git a/doc/src/sgml/man3/dblink_disconnect.3 b/doc/src/sgml/man3/dblink_disconnect.3 new file mode 100644 index 0000000..55a77c6 --- /dev/null +++ b/doc/src/sgml/man3/dblink_disconnect.3 @@ -0,0 +1,74 @@ +'\" t +.\" Title: dblink_disconnect +.\" 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_DISCONNECT" "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_disconnect \- closes a persistent connection to a remote database +.SH "SYNOPSIS" +.sp +.nf +dblink_disconnect() returns text +dblink_disconnect(text connname) returns text +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_disconnect()\fR +closes a connection previously opened by +\fBdblink_connect()\fR\&. The form with no arguments closes an unnamed connection\&. +.SH "ARGUMENTS" +.PP +\fIconnname\fR +.RS 4 +The name of a named connection to be closed\&. +.RE +.SH "RETURN VALUE" +.PP +Returns status, which is always +OK +(since any error causes the function to throw an error instead of returning)\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT dblink_disconnect(); + dblink_disconnect +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) + +SELECT dblink_disconnect(\*(Aqmyconn\*(Aq); + dblink_disconnect +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) +.fi +.if n \{\ +.RE +.\} diff --git a/doc/src/sgml/man3/dblink_error_message.3 b/doc/src/sgml/man3/dblink_error_message.3 new file mode 100644 index 0000000..cefdcd2 --- /dev/null +++ b/doc/src/sgml/man3/dblink_error_message.3 @@ -0,0 +1,71 @@ +'\" t +.\" Title: dblink_error_message +.\" 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_ERROR_MESSAGE" "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_error_message \- gets last error message on the named connection +.SH "SYNOPSIS" +.sp +.nf +dblink_error_message(text connname) returns text +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_error_message\fR +fetches the most recent remote error message for a given connection\&. +.SH "ARGUMENTS" +.PP +\fIconnname\fR +.RS 4 +Name of the connection to use\&. +.RE +.SH "RETURN VALUE" +.PP +Returns last error message, or +OK +if there has been no error in this connection\&. +.SH "NOTES" +.PP +When asynchronous queries are initiated by +\fBdblink_send_query\fR, the error message associated with the connection might not get updated until the server\*(Aqs response message is consumed\&. This typically means that +\fBdblink_is_busy\fR +or +\fBdblink_get_result\fR +should be called prior to +\fBdblink_error_message\fR, so that any error generated by the asynchronous query will be visible\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT dblink_error_message(\*(Aqdtest1\*(Aq); +.fi +.if n \{\ +.RE +.\} diff --git a/doc/src/sgml/man3/dblink_exec.3 b/doc/src/sgml/man3/dblink_exec.3 new file mode 100644 index 0000000..4af3189 --- /dev/null +++ b/doc/src/sgml/man3/dblink_exec.3 @@ -0,0 +1,117 @@ +'\" t +.\" Title: dblink_exec +.\" 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_EXEC" "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_exec \- executes a command in a remote database +.SH "SYNOPSIS" +.sp +.nf +dblink_exec(text connname, text sql [, bool fail_on_error]) returns text +dblink_exec(text connstr, text sql [, bool fail_on_error]) returns text +dblink_exec(text sql [, bool fail_on_error]) returns text +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_exec\fR +executes a command (that is, any SQL statement that doesn\*(Aqt return rows) in a remote database\&. +.PP +When two +text +arguments are given, the first one is first looked up as a persistent connection\*(Aqs name; if found, the command is executed on that connection\&. If not found, the first argument is treated as a connection info string as for +\fBdblink_connect\fR, and the indicated connection is made just for the duration of this command\&. +.SH "ARGUMENTS" +.PP +\fIconnname\fR +.RS 4 +Name of the connection to use; omit this parameter to use the unnamed connection\&. +.RE +.PP +\fIconnstr\fR +.RS 4 +A connection info string, as previously described for +\fBdblink_connect\fR\&. +.RE +.PP +\fIsql\fR +.RS 4 +The SQL command that you wish to execute in the remote database, for example +insert into foo values(0, \*(Aqa\*(Aq, \*(Aq{"a0","b0","c0"}\*(Aq)\&. +.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\*(Aqs return value is set to +ERROR\&. +.RE +.SH "RETURN VALUE" +.PP +Returns status, either the command\*(Aqs status string or +ERROR\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT dblink_connect(\*(Aqdbname=dblink_test_standby\*(Aq); + dblink_connect +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) + +SELECT dblink_exec(\*(Aqinsert into foo values(21, \*(Aq\*(Aqz\*(Aq\*(Aq, \*(Aq\*(Aq{"a0","b0","c0"}\*(Aq\*(Aq);\*(Aq); + dblink_exec +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + INSERT 943366 1 +(1 row) + +SELECT dblink_connect(\*(Aqmyconn\*(Aq, \*(Aqdbname=regression\*(Aq); + dblink_connect +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) + +SELECT dblink_exec(\*(Aqmyconn\*(Aq, \*(Aqinsert into foo values(21, \*(Aq\*(Aqz\*(Aq\*(Aq, \*(Aq\*(Aq{"a0","b0","c0"}\*(Aq\*(Aq);\*(Aq); + dblink_exec +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + INSERT 6432584 1 +(1 row) + +SELECT dblink_exec(\*(Aqmyconn\*(Aq, \*(Aqinsert into pg_class values (\*(Aq\*(Aqfoo\*(Aq\*(Aq)\*(Aq,false); +NOTICE: sql error +DETAIL: ERROR: null value in column "relnamespace" violates not\-null constraint + + dblink_exec +\-\-\-\-\-\-\-\-\-\-\-\-\- + ERROR +(1 row) +.fi +.if n \{\ +.RE +.\} diff --git a/doc/src/sgml/man3/dblink_fetch.3 b/doc/src/sgml/man3/dblink_fetch.3 new file mode 100644 index 0000000..d126722 --- /dev/null +++ b/doc/src/sgml/man3/dblink_fetch.3 @@ -0,0 +1,129 @@ +'\" t +.\" Title: dblink_fetch +.\" 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_FETCH" "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_fetch \- returns rows from an open cursor in a remote database +.SH "SYNOPSIS" +.sp +.nf +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 +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_fetch\fR +fetches rows from a cursor previously established by +\fBdblink_open\fR\&. +.SH "ARGUMENTS" +.PP +\fIconnname\fR +.RS 4 +Name of the connection to use; omit this parameter to use the unnamed connection\&. +.RE +.PP +\fIcursorname\fR +.RS 4 +The name of the cursor to fetch from\&. +.RE +.PP +\fIhowmany\fR +.RS 4 +The maximum number of rows to retrieve\&. The next +\fIhowmany\fR +rows are fetched, starting at the current cursor position, moving forward\&. Once the cursor has reached its end, no more rows are produced\&. +.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 +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 +\fBdblink\fR\&. +.SH "NOTES" +.PP +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 +\fBFETCH\fR +has been done\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT dblink_connect(\*(Aqdbname=postgres options=\-csearch_path=\*(Aq); + dblink_connect +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) + +SELECT dblink_open(\*(Aqfoo\*(Aq, \*(Aqselect proname, prosrc from pg_proc where proname like \*(Aq\*(Aqbytea%\*(Aq\*(Aq\*(Aq); + dblink_open +\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) + +SELECT * FROM dblink_fetch(\*(Aqfoo\*(Aq, 5) AS (funcname name, source text); + funcname | source +\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\- + byteacat | byteacat + byteacmp | byteacmp + byteaeq | byteaeq + byteage | byteage + byteagt | byteagt +(5 rows) + +SELECT * FROM dblink_fetch(\*(Aqfoo\*(Aq, 5) AS (funcname name, source text); + funcname | source +\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\- + byteain | byteain + byteale | byteale + bytealike | bytealike + bytealt | bytealt + byteane | byteane +(5 rows) + +SELECT * FROM dblink_fetch(\*(Aqfoo\*(Aq, 5) AS (funcname name, source text); + funcname | source +\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\- + byteanlike | byteanlike + byteaout | byteaout +(2 rows) + +SELECT * FROM dblink_fetch(\*(Aqfoo\*(Aq, 5) AS (funcname name, source text); + funcname | source +\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\- +(0 rows) +.fi +.if n \{\ +.RE +.\} diff --git a/doc/src/sgml/man3/dblink_get_connections.3 b/doc/src/sgml/man3/dblink_get_connections.3 new file mode 100644 index 0000000..d671ec8 --- /dev/null +++ b/doc/src/sgml/man3/dblink_get_connections.3 @@ -0,0 +1,56 @@ +'\" t +.\" Title: dblink_get_connections +.\" 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_CONNECTIONS" "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_connections \- returns the names of all open named dblink connections +.SH "SYNOPSIS" +.sp +.nf +dblink_get_connections() returns text[] +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_get_connections\fR +returns an array of the names of all open named +dblink +connections\&. +.SH "RETURN VALUE" +.PP +Returns a text array of connection names, or NULL if none\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT dblink_get_connections(); +.fi +.if n \{\ +.RE +.\} diff --git a/doc/src/sgml/man3/dblink_get_notify.3 b/doc/src/sgml/man3/dblink_get_notify.3 new file mode 100644 index 0000000..1195b90 --- /dev/null +++ b/doc/src/sgml/man3/dblink_get_notify.3 @@ -0,0 +1,86 @@ +'\" t +.\" Title: dblink_get_notify +.\" 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_NOTIFY" "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_notify \- retrieve async notifications on a connection +.SH "SYNOPSIS" +.sp +.nf +dblink_get_notify() returns setof (notify_name text, be_pid int, extra text) +dblink_get_notify(text connname) returns setof (notify_name text, be_pid int, extra text) +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_get_notify\fR +retrieves notifications on either the unnamed connection, or on a named connection if specified\&. To receive notifications via dblink, +\fBLISTEN\fR +must first be issued, using +\fBdblink_exec\fR\&. For details see +\fBLISTEN\fR(7) +and +\fBNOTIFY\fR(7)\&. +.SH "ARGUMENTS" +.PP +\fIconnname\fR +.RS 4 +The name of a named connection to get notifications on\&. +.RE +.SH "RETURN VALUE" +.PP +Returns +setof (notify_name text, be_pid int, extra text), or an empty set if none\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT dblink_exec(\*(AqLISTEN virtual\*(Aq); + dblink_exec +\-\-\-\-\-\-\-\-\-\-\-\-\- + LISTEN +(1 row) + +SELECT * FROM dblink_get_notify(); + notify_name | be_pid | extra +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\- +(0 rows) + +NOTIFY virtual; +NOTIFY + +SELECT * FROM dblink_get_notify(); + notify_name | be_pid | extra +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\- + virtual | 1229 | +(1 row) +.fi +.if n \{\ +.RE +.\} diff --git a/doc/src/sgml/man3/dblink_get_pkey.3 b/doc/src/sgml/man3/dblink_get_pkey.3 new file mode 100644 index 0000000..7906a73 --- /dev/null +++ b/doc/src/sgml/man3/dblink_get_pkey.3 @@ -0,0 +1,93 @@ +'\" t +.\" Title: dblink_get_pkey +.\" 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_PKEY" "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_pkey \- returns the positions and field names of a relation\*(Aqs primary key fields +.SH "SYNOPSIS" +.sp +.nf +dblink_get_pkey(text relname) returns setof dblink_pkey_results +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_get_pkey\fR +provides information about the primary key of a relation in the local database\&. This is sometimes useful in generating queries to be sent to remote databases\&. +.SH "ARGUMENTS" +.PP +\fIrelname\fR +.RS 4 +Name of a local relation, for example +foo +or +myschema\&.mytab\&. Include double quotes if the name is mixed\-case or contains special characters, for example +"FooBar"; without quotes, the string will be folded to lower case\&. +.RE +.SH "RETURN VALUE" +.PP +Returns one row for each primary key field, or no rows if the relation has no primary key\&. The result row type is defined as +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TYPE dblink_pkey_results AS (position int, colname text); +.fi +.if n \{\ +.RE +.\} +.sp +The +position +column simply runs from 1 to +\fIN\fR; it is the number of the field within the primary key, not the number within the table\*(Aqs columns\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE foobar ( + f1 int, + f2 int, + f3 int, + PRIMARY KEY (f1, f2, f3) +); +CREATE TABLE + +SELECT * FROM dblink_get_pkey(\*(Aqfoobar\*(Aq); + position | colname +\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\- + 1 | f1 + 2 | f2 + 3 | f3 +(3 rows) +.fi +.if n \{\ +.RE +.\} 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 +.\} diff --git a/doc/src/sgml/man3/dblink_is_busy.3 b/doc/src/sgml/man3/dblink_is_busy.3 new file mode 100644 index 0000000..86bc3d9 --- /dev/null +++ b/doc/src/sgml/man3/dblink_is_busy.3 @@ -0,0 +1,62 @@ +'\" t +.\" Title: dblink_is_busy +.\" 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_IS_BUSY" "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_is_busy \- checks if connection is busy with an async query +.SH "SYNOPSIS" +.sp +.nf +dblink_is_busy(text connname) returns int +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_is_busy\fR +tests whether an async query is in progress\&. +.SH "ARGUMENTS" +.PP +\fIconnname\fR +.RS 4 +Name of the connection to check\&. +.RE +.SH "RETURN VALUE" +.PP +Returns 1 if connection is busy, 0 if it is not busy\&. If this function returns 0, it is guaranteed that +\fBdblink_get_result\fR +will not block\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT dblink_is_busy(\*(Aqdtest1\*(Aq); +.fi +.if n \{\ +.RE +.\} diff --git a/doc/src/sgml/man3/dblink_open.3 b/doc/src/sgml/man3/dblink_open.3 new file mode 100644 index 0000000..8efb63f --- /dev/null +++ b/doc/src/sgml/man3/dblink_open.3 @@ -0,0 +1,113 @@ +'\" t +.\" Title: dblink_open +.\" 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_OPEN" "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_open \- opens a cursor in a remote database +.SH "SYNOPSIS" +.sp +.nf +dblink_open(text cursorname, text sql [, bool fail_on_error]) returns text +dblink_open(text connname, text cursorname, text sql [, bool fail_on_error]) returns text +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_open()\fR +opens a cursor in a remote database\&. The cursor can subsequently be manipulated with +\fBdblink_fetch()\fR +and +\fBdblink_close()\fR\&. +.SH "ARGUMENTS" +.PP +\fIconnname\fR +.RS 4 +Name of the connection to use; omit this parameter to use the unnamed connection\&. +.RE +.PP +\fIcursorname\fR +.RS 4 +The name to assign to this cursor\&. +.RE +.PP +\fIsql\fR +.RS 4 +The +\fBSELECT\fR +statement that you wish to execute in the remote database, for example +select * from pg_class\&. +.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\*(Aqs return value is set to +ERROR\&. +.RE +.SH "RETURN VALUE" +.PP +Returns status, either +OK +or +ERROR\&. +.SH "NOTES" +.PP +Since a cursor can only persist within a transaction, +\fBdblink_open\fR +starts an explicit transaction block (\fBBEGIN\fR) on the remote side, if the remote side was not already within a transaction\&. This transaction will be closed again when the matching +\fBdblink_close\fR +is executed\&. Note that if you use +\fBdblink_exec\fR +to change data between +\fBdblink_open\fR +and +\fBdblink_close\fR, and then an error occurs or you use +\fBdblink_disconnect\fR +before +\fBdblink_close\fR, your change +\fIwill be lost\fR +because the transaction will be aborted\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT dblink_connect(\*(Aqdbname=postgres options=\-csearch_path=\*(Aq); + dblink_connect +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) + +SELECT dblink_open(\*(Aqfoo\*(Aq, \*(Aqselect proname, prosrc from pg_proc\*(Aq); + dblink_open +\-\-\-\-\-\-\-\-\-\-\-\-\- + OK +(1 row) +.fi +.if n \{\ +.RE +.\} diff --git a/doc/src/sgml/man3/dblink_send_query.3 b/doc/src/sgml/man3/dblink_send_query.3 new file mode 100644 index 0000000..c8d7e59 --- /dev/null +++ b/doc/src/sgml/man3/dblink_send_query.3 @@ -0,0 +1,71 @@ +'\" t +.\" Title: dblink_send_query +.\" 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_SEND_QUERY" "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_send_query \- sends an async query to a remote database +.SH "SYNOPSIS" +.sp +.nf +dblink_send_query(text connname, text sql) returns int +.fi +.SH "DESCRIPTION" +.PP +\fBdblink_send_query\fR +sends a query to be executed asynchronously, that is, without immediately waiting for the result\&. There must not be an async query already in progress on the connection\&. +.PP +After successfully dispatching an async query, completion status can be checked with +\fBdblink_is_busy\fR, and the results are ultimately collected with +\fBdblink_get_result\fR\&. It is also possible to attempt to cancel an active async query using +\fBdblink_cancel_query\fR\&. +.SH "ARGUMENTS" +.PP +\fIconnname\fR +.RS 4 +Name of the connection to use\&. +.RE +.PP +\fIsql\fR +.RS 4 +The SQL statement that you wish to execute in the remote database, for example +select * from pg_class\&. +.RE +.SH "RETURN VALUE" +.PP +Returns 1 if the query was successfully dispatched, 0 otherwise\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT dblink_send_query(\*(Aqdtest1\*(Aq, \*(AqSELECT * FROM foo WHERE f1 < 3\*(Aq); +.fi +.if n \{\ +.RE +.\} |