begriffs open source - ai-pg/blob - full-docs/man7/CREATE_PROCEDURE.7

   1 '\" t
   2 .\"     Title: CREATE PROCEDURE
   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 "CREATE PROCEDURE" "7" "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 CREATE_PROCEDURE \- define a new procedure
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 CREATE [ OR REPLACE ] PROCEDURE
  36     \fIname\fR ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ { DEFAULT | = } \fIdefault_expr\fR ] [, \&.\&.\&.] ] )
  37   { LANGUAGE \fIlang_name\fR
  38     | TRANSFORM { FOR TYPE \fItype_name\fR } [, \&.\&.\&. ]
  39     | [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER
  40     | SET \fIconfiguration_parameter\fR { TO \fIvalue\fR | = \fIvalue\fR | FROM CURRENT }
  41     | AS \*(Aq\fIdefinition\fR\*(Aq
  42     | AS \*(Aq\fIobj_file\fR\*(Aq, \*(Aq\fIlink_symbol\fR\*(Aq
  43     | \fIsql_body\fR
  44   } \&.\&.\&.
  45 .fi
  46 .SH "DESCRIPTION"
  47 .PP
  48 \fBCREATE PROCEDURE\fR
  49 defines a new procedure\&.
  50 \fBCREATE OR REPLACE PROCEDURE\fR
  51 will either create a new procedure, or replace an existing definition\&. To be able to define a procedure, the user must have the
  52 USAGE
  53 privilege on the language\&.
  54 .PP
  55 If a schema name is included, then the procedure is created in the specified schema\&. Otherwise it is created in the current schema\&. The name of the new procedure must not match any existing procedure or function with the same input argument types in the same schema\&. However, procedures and functions of different argument types can share a name (this is called
  56 overloading)\&.
  57 .PP
  58 To replace the current definition of an existing procedure, use
  59 \fBCREATE OR REPLACE PROCEDURE\fR\&. It is not possible to change the name or argument types of a procedure this way (if you tried, you would actually be creating a new, distinct procedure)\&.
  60 .PP
  61 When
  62 \fBCREATE OR REPLACE PROCEDURE\fR
  63 is used to replace an existing procedure, the ownership and permissions of the procedure do not change\&. All other procedure properties are assigned the values specified or implied in the command\&. You must own the procedure to replace it (this includes being a member of the owning role)\&.
  64 .PP
  65 The user that creates the procedure becomes the owner of the procedure\&.
  66 .PP
  67 To be able to create a procedure, you must have
  68 USAGE
  69 privilege on the argument types\&.
  70 .PP
  71 Refer to
  72 Section\ \&36.4
  73 for further information on writing procedures\&.
  74 .SH "PARAMETERS"
  75 .PP
  76 \fIname\fR
  77 .RS 4
  78 The name (optionally schema\-qualified) of the procedure to create\&.
  79 .RE
  80 .PP
  81 \fIargmode\fR
  82 .RS 4
  83 The mode of an argument:
  84 IN,
  85 OUT,
  86 INOUT, or
  87 VARIADIC\&. If omitted, the default is
  88 IN\&.
  89 .RE
  90 .PP
  91 \fIargname\fR
  92 .RS 4
  93 The name of an argument\&.
  94 .RE
  95 .PP
  96 \fIargtype\fR
  97 .RS 4
  98 The data type(s) of the procedure\*(Aqs arguments (optionally schema\-qualified), if any\&. The argument types can be base, composite, or domain types, or can reference the type of a table column\&.
  99 .sp
 100 Depending on the implementation language it might also be allowed to specify
 101 \(lqpseudo\-types\(rq
 102 such as
 103 cstring\&. Pseudo\-types indicate that the actual argument type is either incompletely specified, or outside the set of ordinary SQL data types\&.
 104 .sp
 105 The type of a column is referenced by writing
 106 \fItable_name\fR\&.\fIcolumn_name\fR%TYPE\&. Using this feature can sometimes help make a procedure independent of changes to the definition of a table\&.
 107 .RE
 108 .PP
 109 \fIdefault_expr\fR
 110 .RS 4
 111 An expression to be used as default value if the parameter is not specified\&. The expression has to be coercible to the argument type of the parameter\&. All input parameters following a parameter with a default value must have default values as well\&.
 112 .RE
 113 .PP
 114 \fIlang_name\fR
 115 .RS 4
 116 The name of the language that the procedure is implemented in\&. It can be
 117 sql,
 118 c,
 119 internal, or the name of a user\-defined procedural language, e\&.g\&.,
 120 plpgsql\&. The default is
 121 sql
 122 if
 123 \fIsql_body\fR
 124 is specified\&. Enclosing the name in single quotes is deprecated and requires matching case\&.
 125 .RE
 126 .PP
 127 TRANSFORM { FOR TYPE \fItype_name\fR } [, \&.\&.\&. ] }
 128 .RS 4
 129 Lists which transforms a call to the procedure should apply\&. Transforms convert between SQL types and language\-specific data types; see
 130 CREATE TRANSFORM (\fBCREATE_TRANSFORM\fR(7))\&. Procedural language implementations usually have hardcoded knowledge of the built\-in types, so those don\*(Aqt need to be listed here\&. If a procedural language implementation does not know how to handle a type and no transform is supplied, it will fall back to a default behavior for converting data types, but this depends on the implementation\&.
 131 .RE
 132 .PP
 133 [EXTERNAL] SECURITY INVOKER
 134 .br
 135 [EXTERNAL] SECURITY DEFINER
 136 .RS 4
 137 SECURITY INVOKER
 138 indicates that the procedure is to be executed with the privileges of the user that calls it\&. That is the default\&.
 139 SECURITY DEFINER
 140 specifies that the procedure is to be executed with the privileges of the user that owns it\&.
 141 .sp
 142 The key word
 143 EXTERNAL
 144 is allowed for SQL conformance, but it is optional since, unlike in SQL, this feature applies to all procedures not only external ones\&.
 145 .sp
 146 A
 147 SECURITY DEFINER
 148 procedure cannot execute transaction control statements (for example,
 149 \fBCOMMIT\fR
 150 and
 151 \fBROLLBACK\fR, depending on the language)\&.
 152 .RE
 153 .PP
 154 \fIconfiguration_parameter\fR
 155 .br
 156 \fIvalue\fR
 157 .RS 4
 158 The
 159 SET
 160 clause causes the specified configuration parameter to be set to the specified value when the procedure is entered, and then restored to its prior value when the procedure exits\&.
 161 SET FROM CURRENT
 162 saves the value of the parameter that is current when
 163 \fBCREATE PROCEDURE\fR
 164 is executed as the value to be applied when the procedure is entered\&.
 165 .sp
 166 If a
 167 SET
 168 clause is attached to a procedure, then the effects of a
 169 \fBSET LOCAL\fR
 170 command executed inside the procedure for the same variable are restricted to the procedure: the configuration parameter\*(Aqs prior value is still restored at procedure exit\&. However, an ordinary
 171 \fBSET\fR
 172 command (without
 173 LOCAL) overrides the
 174 SET
 175 clause, much as it would do for a previous
 176 \fBSET LOCAL\fR
 177 command: the effects of such a command will persist after procedure exit, unless the current transaction is rolled back\&.
 178 .sp
 179 If a
 180 SET
 181 clause is attached to a procedure, then that procedure cannot execute transaction control statements (for example,
 182 \fBCOMMIT\fR
 183 and
 184 \fBROLLBACK\fR, depending on the language)\&.
 185 .sp
 186 See
 187 \fBSET\fR(7)
 188 and
 189 Chapter\ \&19
 190 for more information about allowed parameter names and values\&.
 191 .RE
 192 .PP
 193 \fIdefinition\fR
 194 .RS 4
 195 A string constant defining the procedure; the meaning depends on the language\&. It can be an internal procedure name, the path to an object file, an SQL command, or text in a procedural language\&.
 196 .sp
 197 It is often helpful to use dollar quoting (see
 198 Section\ \&4.1.2.4) to write the procedure definition string, rather than the normal single quote syntax\&. Without dollar quoting, any single quotes or backslashes in the procedure definition must be escaped by doubling them\&.
 199 .RE
 200 .PP
 201 \fIobj_file\fR, \fIlink_symbol\fR
 202 .RS 4
 203 This form of the
 204 AS
 205 clause is used for dynamically loadable C language procedures when the procedure name in the C language source code is not the same as the name of the SQL procedure\&. The string
 206 \fIobj_file\fR
 207 is the name of the shared library file containing the compiled C procedure, and is interpreted as for the
 208 \fBLOAD\fR
 209 command\&. The string
 210 \fIlink_symbol\fR
 211 is the procedure\*(Aqs link symbol, that is, the name of the procedure in the C language source code\&. If the link symbol is omitted, it is assumed to be the same as the name of the SQL procedure being defined\&.
 212 .sp
 213 When repeated
 214 \fBCREATE PROCEDURE\fR
 215 calls refer to the same object file, the file is only loaded once per session\&. To unload and reload the file (perhaps during development), start a new session\&.
 216 .RE
 217 .PP
 218 \fIsql_body\fR
 219 .RS 4
 220 The body of a
 221 LANGUAGE SQL
 222 procedure\&. This should be a block
 223 .sp
 224 .if n \{\
 225 .RS 4
 226 .\}
 227 .nf
 228 BEGIN ATOMIC
 229   \fIstatement\fR;
 230   \fIstatement\fR;
 231   \&.\&.\&.
 232   \fIstatement\fR;
 233 END
 234 .fi
 235 .if n \{\
 236 .RE
 237 .\}
 238 .sp
 239 This is similar to writing the text of the procedure body as a string constant (see
 240 \fIdefinition\fR
 241 above), but there are some differences: This form only works for
 242 LANGUAGE SQL, the string constant form works for all languages\&. This form is parsed at procedure definition time, the string constant form is parsed at execution time; therefore this form cannot support polymorphic argument types and other constructs that are not resolvable at procedure definition time\&. This form tracks dependencies between the procedure and objects used in the procedure body, so
 243 DROP \&.\&.\&. CASCADE
 244 will work correctly, whereas the form using string literals may leave dangling procedures\&. Finally, this form is more compatible with the SQL standard and other SQL implementations\&.
 245 .RE
 246 .SH "NOTES"
 247 .PP
 248 See
 249 CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7))
 250 for more details on function creation that also apply to procedures\&.
 251 .PP
 252 Use
 253 \fBCALL\fR(7)
 254 to execute a procedure\&.
 255 .SH "EXAMPLES"
 256 .PP
 257 .if n \{\
 258 .RS 4
 259 .\}
 260 .nf
 261 CREATE PROCEDURE insert_data(a integer, b integer)
 262 LANGUAGE SQL
 263 AS $$
 264 INSERT INTO tbl VALUES (a);
 265 INSERT INTO tbl VALUES (b);
 266 $$;
 267 .fi
 268 .if n \{\
 269 .RE
 270 .\}
 271 .sp
 272 or
 273 .sp
 274 .if n \{\
 275 .RS 4
 276 .\}
 277 .nf
 278 CREATE PROCEDURE insert_data(a integer, b integer)
 279 LANGUAGE SQL
 280 BEGIN ATOMIC
 281   INSERT INTO tbl VALUES (a);
 282   INSERT INTO tbl VALUES (b);
 283 END;
 284 .fi
 285 .if n \{\
 286 .RE
 287 .\}
 288 .sp
 289 and call like this:
 290 .sp
 291 .if n \{\
 292 .RS 4
 293 .\}
 294 .nf
 295 CALL insert_data(1, 2);
 296 .fi
 297 .if n \{\
 298 .RE
 299 .\}
 300 .SH "COMPATIBILITY"
 301 .PP
 302 A
 303 \fBCREATE PROCEDURE\fR
 304 command is defined in the SQL standard\&. The
 305 PostgreSQL
 306 implementation can be used in a compatible way but has many extensions\&. For details see also
 307 CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7))\&.
 308 .SH "SEE ALSO"
 309 ALTER PROCEDURE (\fBALTER_PROCEDURE\fR(7)), DROP PROCEDURE (\fBDROP_PROCEDURE\fR(7)), \fBCALL\fR(7), CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7))