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

   1 '\" t
   2 .\"     Title: SPI_execute
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "SPI_EXECUTE" "3" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 SPI_execute \- execute a command
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 int SPI_execute(const char * \fIcommand\fR, bool \fIread_only\fR, long \fIcount\fR)
  36 .fi
  37 .SH "DESCRIPTION"
  38 .PP
  39 \fBSPI_execute\fR
  40 executes the specified SQL command for
  41 \fIcount\fR
  42 rows\&. If
  43 \fIread_only\fR
  44 is
  45 true, the command must be read\-only, and execution overhead is somewhat reduced\&.
  46 .PP
  47 This function can only be called from a connected C function\&.
  48 .PP
  49 If
  50 \fIcount\fR
  51 is zero then the command is executed for all rows that it applies to\&. If
  52 \fIcount\fR
  53 is greater than zero, then no more than
  54 \fIcount\fR
  55 rows will be retrieved; execution stops when the count is reached, much like adding a
  56 LIMIT
  57 clause to the query\&. For example,
  58 .sp
  59 .if n \{\
  60 .RS 4
  61 .\}
  62 .nf
  63 SPI_execute("SELECT * FROM foo", true, 5);
  64 .fi
  65 .if n \{\
  66 .RE
  67 .\}
  68 .sp
  69 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,
  70 .sp
  71 .if n \{\
  72 .RS 4
  73 .\}
  74 .nf
  75 SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5);
  76 .fi
  77 .if n \{\
  78 .RE
  79 .\}
  80 .sp
  81 inserts all rows from
  82 bar, ignoring the
  83 \fIcount\fR
  84 parameter\&. However, with
  85 .sp
  86 .if n \{\
  87 .RS 4
  88 .\}
  89 .nf
  90 SPI_execute("INSERT INTO foo SELECT * FROM bar RETURNING *", false, 5);
  91 .fi
  92 .if n \{\
  93 .RE
  94 .\}
  95 .sp
  96 at most 5 rows would be inserted, since execution would stop after the fifth
  97 RETURNING
  98 result row is retrieved\&.
  99 .PP
 100 You can pass multiple commands in one string;
 101 \fBSPI_execute\fR
 102 returns the result for the command executed last\&. The
 103 \fIcount\fR
 104 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\&.
 105 .PP
 106 When
 107 \fIread_only\fR
 108 is
 109 false,
 110 \fBSPI_execute\fR
 111 increments the command counter and computes a new
 112 snapshot
 113 before executing each command in the string\&. The snapshot does not actually change if the current transaction isolation level is
 114 SERIALIZABLE
 115 or
 116 REPEATABLE READ, but in
 117 READ COMMITTED
 118 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\&.
 119 .PP
 120 When
 121 \fIread_only\fR
 122 is
 123 true,
 124 \fBSPI_execute\fR
 125 does not update either the snapshot or the command counter, and it allows only plain
 126 \fBSELECT\fR
 127 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
 128 stable
 129 functions to be built: since successive executions will all use the same snapshot, there will be no change in the results\&.
 130 .PP
 131 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\&.
 132 .PP
 133 The actual number of rows for which the (last) command was executed is returned in the global variable
 134 \fISPI_processed\fR\&. If the return value of the function is
 135 SPI_OK_SELECT,
 136 SPI_OK_INSERT_RETURNING,
 137 SPI_OK_DELETE_RETURNING,
 138 SPI_OK_UPDATE_RETURNING, or
 139 SPI_OK_MERGE_RETURNING, then you can use the global pointer
 140 SPITupleTable *SPI_tuptable
 141 to access the result rows\&. Some utility commands (such as
 142 \fBEXPLAIN\fR) also return row sets, and
 143 SPI_tuptable
 144 will contain the result in these cases too\&. Some utility commands (\fBCOPY\fR,
 145 \fBCREATE TABLE AS\fR) don\*(Aqt return a row set, so
 146 SPI_tuptable
 147 is NULL, but they still return the number of rows processed in
 148 \fISPI_processed\fR\&.
 149 .PP
 150 The structure
 151 SPITupleTable
 152 is defined thus:
 153 .sp
 154 .if n \{\
 155 .RS 4
 156 .\}
 157 .nf
 158 typedef struct SPITupleTable
 159 {
 160     /* Public members */
 161     TupleDesc   tupdesc;        /* tuple descriptor */
 162     HeapTuple  *vals;           /* array of tuples */
 163     uint64      numvals;        /* number of valid tuples */
 164
 165     /* Private members, not intended for external callers */
 166     uint64      alloced;        /* allocated length of vals array */
 167     MemoryContext tuptabcxt;    /* memory context of result table */
 168     slist_node  next;           /* link for internal bookkeeping */
 169     SubTransactionId subid;     /* subxact in which tuptable was created */
 170 } SPITupleTable;
 171 .fi
 172 .if n \{\
 173 .RE
 174 .\}
 175 .sp
 176 The fields
 177 tupdesc,
 178 vals, and
 179 numvals
 180 can be used by SPI callers; the remaining fields are internal\&.
 181 vals
 182 is an array of pointers to rows\&. The number of rows is given by
 183 numvals
 184 (for somewhat historical reasons, this count is also returned in
 185 \fISPI_processed\fR)\&.
 186 tupdesc
 187 is a row descriptor which you can pass to SPI functions dealing with rows\&.
 188 .PP
 189 \fBSPI_finish\fR
 190 frees all
 191 SPITupleTables allocated during the current C function\&. You can free a particular result table earlier, if you are done with it, by calling
 192 \fBSPI_freetuptable\fR\&.
 193 .SH "ARGUMENTS"
 194 .PP
 195 const char * \fIcommand\fR
 196 .RS 4
 197 string containing command to execute
 198 .RE
 199 .PP
 200 bool \fIread_only\fR
 201 .RS 4
 202 true
 203 for read\-only execution
 204 .RE
 205 .PP
 206 long \fIcount\fR
 207 .RS 4
 208 maximum number of rows to return, or
 209 0
 210 for no limit
 211 .RE
 212 .SH "RETURN VALUE"
 213 .PP
 214 If the execution of the command was successful then one of the following (nonnegative) values will be returned:
 215 .PP
 216 SPI_OK_SELECT
 217 .RS 4
 218 if a
 219 \fBSELECT\fR
 220 (but not
 221 \fBSELECT INTO\fR) was executed
 222 .RE
 223 .PP
 224 SPI_OK_SELINTO
 225 .RS 4
 226 if a
 227 \fBSELECT INTO\fR
 228 was executed
 229 .RE
 230 .PP
 231 SPI_OK_INSERT
 232 .RS 4
 233 if an
 234 \fBINSERT\fR
 235 was executed
 236 .RE
 237 .PP
 238 SPI_OK_DELETE
 239 .RS 4
 240 if a
 241 \fBDELETE\fR
 242 was executed
 243 .RE
 244 .PP
 245 SPI_OK_UPDATE
 246 .RS 4
 247 if an
 248 \fBUPDATE\fR
 249 was executed
 250 .RE
 251 .PP
 252 SPI_OK_MERGE
 253 .RS 4
 254 if a
 255 \fBMERGE\fR
 256 was executed
 257 .RE
 258 .PP
 259 SPI_OK_INSERT_RETURNING
 260 .RS 4
 261 if an
 262 \fBINSERT RETURNING\fR
 263 was executed
 264 .RE
 265 .PP
 266 SPI_OK_DELETE_RETURNING
 267 .RS 4
 268 if a
 269 \fBDELETE RETURNING\fR
 270 was executed
 271 .RE
 272 .PP
 273 SPI_OK_UPDATE_RETURNING
 274 .RS 4
 275 if an
 276 \fBUPDATE RETURNING\fR
 277 was executed
 278 .RE
 279 .PP
 280 SPI_OK_MERGE_RETURNING
 281 .RS 4
 282 if a
 283 \fBMERGE RETURNING\fR
 284 was executed
 285 .RE
 286 .PP
 287 SPI_OK_UTILITY
 288 .RS 4
 289 if a utility command (e\&.g\&.,
 290 \fBCREATE TABLE\fR) was executed
 291 .RE
 292 .PP
 293 SPI_OK_REWRITTEN
 294 .RS 4
 295 if the command was rewritten into another kind of command (e\&.g\&.,
 296 \fBUPDATE\fR
 297 became an
 298 \fBINSERT\fR) by a
 299 rule\&.
 300 .RE
 301 .PP
 302 On error, one of the following negative values is returned:
 303 .PP
 304 SPI_ERROR_ARGUMENT
 305 .RS 4
 306 if
 307 \fIcommand\fR
 308 is
 309 NULL
 310 or
 311 \fIcount\fR
 312 is less than 0
 313 .RE
 314 .PP
 315 SPI_ERROR_COPY
 316 .RS 4
 317 if
 318 \fBCOPY TO stdout\fR
 319 or
 320 \fBCOPY FROM stdin\fR
 321 was attempted
 322 .RE
 323 .PP
 324 SPI_ERROR_TRANSACTION
 325 .RS 4
 326 if a transaction manipulation command was attempted (\fBBEGIN\fR,
 327 \fBCOMMIT\fR,
 328 \fBROLLBACK\fR,
 329 \fBSAVEPOINT\fR,
 330 \fBPREPARE TRANSACTION\fR,
 331 \fBCOMMIT PREPARED\fR,
 332 \fBROLLBACK PREPARED\fR, or any variant thereof)
 333 .RE
 334 .PP
 335 SPI_ERROR_OPUNKNOWN
 336 .RS 4
 337 if the command type is unknown (shouldn\*(Aqt happen)
 338 .RE
 339 .PP
 340 SPI_ERROR_UNCONNECTED
 341 .RS 4
 342 if called from an unconnected C function
 343 .RE
 344 .SH "NOTES"
 345 .PP
 346 All SPI query\-execution functions set both
 347 \fISPI_processed\fR
 348 and
 349 \fISPI_tuptable\fR
 350 (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
 351 \fBSPI_execute\fR
 352 or another query\-execution function across later calls\&.