begriffs open source - ai-pg/blob - full-docs/txt/sql-createprocedure.txt

   1
   2 CREATE PROCEDURE
   3
   4    CREATE PROCEDURE — define a new procedure
   5
   6 Synopsis
   7
   8 CREATE [ OR REPLACE ] PROCEDURE
   9     name ( [ [ argmode ] [ argname ] argtype [ { DEFAULT | = } default_expr ] [,
  10  ...] ] )
  11   { LANGUAGE lang_name
  12     | TRANSFORM { FOR TYPE type_name } [, ... ]
  13     | [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER
  14     | SET configuration_parameter { TO value | = value | FROM CURRENT }
  15     | AS 'definition'
  16     | AS 'obj_file', 'link_symbol'
  17     | sql_body
  18   } ...
  19
  20 Description
  21
  22    CREATE PROCEDURE defines a new procedure. CREATE OR REPLACE PROCEDURE
  23    will either create a new procedure, or replace an existing definition.
  24    To be able to define a procedure, the user must have the USAGE
  25    privilege on the language.
  26
  27    If a schema name is included, then the procedure is created in the
  28    specified schema. Otherwise it is created in the current schema. The
  29    name of the new procedure must not match any existing procedure or
  30    function with the same input argument types in the same schema.
  31    However, procedures and functions of different argument types can share
  32    a name (this is called overloading).
  33
  34    To replace the current definition of an existing procedure, use CREATE
  35    OR REPLACE PROCEDURE. It is not possible to change the name or argument
  36    types of a procedure this way (if you tried, you would actually be
  37    creating a new, distinct procedure).
  38
  39    When CREATE OR REPLACE PROCEDURE is used to replace an existing
  40    procedure, the ownership and permissions of the procedure do not
  41    change. All other procedure properties are assigned the values
  42    specified or implied in the command. You must own the procedure to
  43    replace it (this includes being a member of the owning role).
  44
  45    The user that creates the procedure becomes the owner of the procedure.
  46
  47    To be able to create a procedure, you must have USAGE privilege on the
  48    argument types.
  49
  50    Refer to Section 36.4 for further information on writing procedures.
  51
  52 Parameters
  53
  54    name
  55           The name (optionally schema-qualified) of the procedure to
  56           create.
  57
  58    argmode
  59           The mode of an argument: IN, OUT, INOUT, or VARIADIC. If
  60           omitted, the default is IN.
  61
  62    argname
  63           The name of an argument.
  64
  65    argtype
  66           The data type(s) of the procedure's arguments (optionally
  67           schema-qualified), if any. The argument types can be base,
  68           composite, or domain types, or can reference the type of a table
  69           column.
  70
  71           Depending on the implementation language it might also be
  72           allowed to specify “pseudo-types” such as cstring. Pseudo-types
  73           indicate that the actual argument type is either incompletely
  74           specified, or outside the set of ordinary SQL data types.
  75
  76           The type of a column is referenced by writing
  77           table_name.column_name%TYPE. Using this feature can sometimes
  78           help make a procedure independent of changes to the definition
  79           of a table.
  80
  81    default_expr
  82           An expression to be used as default value if the parameter is
  83           not specified. The expression has to be coercible to the
  84           argument type of the parameter. All input parameters following a
  85           parameter with a default value must have default values as well.
  86
  87    lang_name
  88           The name of the language that the procedure is implemented in.
  89           It can be sql, c, internal, or the name of a user-defined
  90           procedural language, e.g., plpgsql. The default is sql if
  91           sql_body is specified. Enclosing the name in single quotes is
  92           deprecated and requires matching case.
  93
  94    TRANSFORM { FOR TYPE type_name } [, ... ] }
  95           Lists which transforms a call to the procedure should apply.
  96           Transforms convert between SQL types and language-specific data
  97           types; see CREATE TRANSFORM. Procedural language implementations
  98           usually have hardcoded knowledge of the built-in types, so those
  99           don't need to be listed here. If a procedural language
 100           implementation does not know how to handle a type and no
 101           transform is supplied, it will fall back to a default behavior
 102           for converting data types, but this depends on the
 103           implementation.
 104
 105    [EXTERNAL] SECURITY INVOKER
 106           [EXTERNAL] SECURITY DEFINER
 107           SECURITY INVOKER indicates that the procedure is to be executed
 108           with the privileges of the user that calls it. That is the
 109           default. SECURITY DEFINER specifies that the procedure is to be
 110           executed with the privileges of the user that owns it.
 111
 112           The key word EXTERNAL is allowed for SQL conformance, but it is
 113           optional since, unlike in SQL, this feature applies to all
 114           procedures not only external ones.
 115
 116           A SECURITY DEFINER procedure cannot execute transaction control
 117           statements (for example, COMMIT and ROLLBACK, depending on the
 118           language).
 119
 120    configuration_parameter
 121           value
 122           The SET clause causes the specified configuration parameter to
 123           be set to the specified value when the procedure is entered, and
 124           then restored to its prior value when the procedure exits. SET
 125           FROM CURRENT saves the value of the parameter that is current
 126           when CREATE PROCEDURE is executed as the value to be applied
 127           when the procedure is entered.
 128
 129           If a SET clause is attached to a procedure, then the effects of
 130           a SET LOCAL command executed inside the procedure for the same
 131           variable are restricted to the procedure: the configuration
 132           parameter's prior value is still restored at procedure exit.
 133           However, an ordinary SET command (without LOCAL) overrides the
 134           SET clause, much as it would do for a previous SET LOCAL
 135           command: the effects of such a command will persist after
 136           procedure exit, unless the current transaction is rolled back.
 137
 138           If a SET clause is attached to a procedure, then that procedure
 139           cannot execute transaction control statements (for example,
 140           COMMIT and ROLLBACK, depending on the language).
 141
 142           See SET and Chapter 19 for more information about allowed
 143           parameter names and values.
 144
 145    definition
 146           A string constant defining the procedure; the meaning depends on
 147           the language. It can be an internal procedure name, the path to
 148           an object file, an SQL command, or text in a procedural
 149           language.
 150
 151           It is often helpful to use dollar quoting (see Section 4.1.2.4)
 152           to write the procedure definition string, rather than the normal
 153           single quote syntax. Without dollar quoting, any single quotes
 154           or backslashes in the procedure definition must be escaped by
 155           doubling them.
 156
 157    obj_file, link_symbol
 158           This form of the AS clause is used for dynamically loadable C
 159           language procedures when the procedure name in the C language
 160           source code is not the same as the name of the SQL procedure.
 161           The string obj_file is the name of the shared library file
 162           containing the compiled C procedure, and is interpreted as for
 163           the LOAD command. The string link_symbol is the procedure's link
 164           symbol, that is, the name of the procedure in the C language
 165           source code. If the link symbol is omitted, it is assumed to be
 166           the same as the name of the SQL procedure being defined.
 167
 168           When repeated CREATE PROCEDURE calls refer to the same object
 169           file, the file is only loaded once per session. To unload and
 170           reload the file (perhaps during development), start a new
 171           session.
 172
 173    sql_body
 174           The body of a LANGUAGE SQL procedure. This should be a block
 175
 176 BEGIN ATOMIC
 177   statement;
 178   statement;
 179   ...
 180   statement;
 181 END
 182
 183           This is similar to writing the text of the procedure body as a
 184           string constant (see definition above), but there are some
 185           differences: This form only works for LANGUAGE SQL, the string
 186           constant form works for all languages. This form is parsed at
 187           procedure definition time, the string constant form is parsed at
 188           execution time; therefore this form cannot support polymorphic
 189           argument types and other constructs that are not resolvable at
 190           procedure definition time. This form tracks dependencies between
 191           the procedure and objects used in the procedure body, so DROP
 192           ... CASCADE will work correctly, whereas the form using string
 193           literals may leave dangling procedures. Finally, this form is
 194           more compatible with the SQL standard and other SQL
 195           implementations.
 196
 197 Notes
 198
 199    See CREATE FUNCTION for more details on function creation that also
 200    apply to procedures.
 201
 202    Use CALL to execute a procedure.
 203
 204 Examples
 205
 206 CREATE PROCEDURE insert_data(a integer, b integer)
 207 LANGUAGE SQL
 208 AS $$
 209 INSERT INTO tbl VALUES (a);
 210 INSERT INTO tbl VALUES (b);
 211 $$;
 212
 213    or
 214 CREATE PROCEDURE insert_data(a integer, b integer)
 215 LANGUAGE SQL
 216 BEGIN ATOMIC
 217   INSERT INTO tbl VALUES (a);
 218   INSERT INTO tbl VALUES (b);
 219 END;
 220
 221    and call like this:
 222 CALL insert_data(1, 2);
 223
 224 Compatibility
 225
 226    A CREATE PROCEDURE command is defined in the SQL standard. The
 227    PostgreSQL implementation can be used in a compatible way but has many
 228    extensions. For details see also CREATE FUNCTION.
 229
 230 See Also
 231
 232    ALTER PROCEDURE, DROP PROCEDURE, CALL, CREATE FUNCTION