diff options
Diffstat (limited to 'doc/src/sgml/ref/drop_procedure.sgml')
| -rw-r--r-- | doc/src/sgml/ref/drop_procedure.sgml | 231 |
1 files changed, 231 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/drop_procedure.sgml b/doc/src/sgml/ref/drop_procedure.sgml new file mode 100644 index 0000000..84e6b09 --- /dev/null +++ b/doc/src/sgml/ref/drop_procedure.sgml @@ -0,0 +1,231 @@ +<!-- +doc/src/sgml/ref/drop_procedure.sgml +PostgreSQL documentation +--> + +<refentry id="sql-dropprocedure"> + <indexterm zone="sql-dropprocedure"> + <primary>DROP PROCEDURE</primary> + </indexterm> + + <refmeta> + <refentrytitle>DROP PROCEDURE</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>DROP PROCEDURE</refname> + <refpurpose>remove a procedure</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +DROP PROCEDURE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] [, ...] + [ CASCADE | RESTRICT ] +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>DROP PROCEDURE</command> removes the definition of one or more + existing procedures. To execute this command the user must be the + owner of the procedure(s). The argument types to the + procedure(s) usually must be specified, since several different procedures + can exist with the same name and different argument lists. + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><literal>IF EXISTS</literal></term> + <listitem> + <para> + Do not throw an error if the procedure does not exist. A notice is issued + in this case. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">name</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of an existing procedure. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">argmode</replaceable></term> + + <listitem> + <para> + The mode of an argument: <literal>IN</literal>, <literal>OUT</literal>, + <literal>INOUT</literal>, or <literal>VARIADIC</literal>. If omitted, + the default is <literal>IN</literal> (but see below). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">argname</replaceable></term> + + <listitem> + <para> + The name of an argument. + Note that <command>DROP PROCEDURE</command> does not actually pay + any attention to argument names, since only the argument data + types are used to determine the procedure's identity. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">argtype</replaceable></term> + + <listitem> + <para> + The data type(s) of the procedure's arguments (optionally + schema-qualified), if any. + See below for details. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the procedure, + and in turn all objects that depend on those objects + (see <xref linkend="ddl-depend"/>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the procedure if any objects depend on it. This + is the default. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id="sql-dropprocedure-notes"> + <title>Notes</title> + + <para> + If there is only one procedure of the given name, the argument list + can be omitted. Omit the parentheses too in this case. + </para> + + <para> + In <productname>PostgreSQL</productname>, it's sufficient to list the + input (including <literal>INOUT</literal>) arguments, + because no two routines of the same name are allowed to share the same + input-argument list. Moreover, the <command>DROP</command> command + will not actually check that you wrote the types + of <literal>OUT</literal> arguments correctly; so any arguments that + are explicitly marked <literal>OUT</literal> are just noise. But + writing them is recommendable for consistency with the + corresponding <command>CREATE</command> command. + </para> + + <para> + For compatibility with the SQL standard, it is also allowed to write + all the argument data types (including those of <literal>OUT</literal> + arguments) without + any <replaceable class="parameter">argmode</replaceable> markers. + When this is done, the types of the procedure's <literal>OUT</literal> + argument(s) <emphasis>will</emphasis> be verified against the command. + This provision creates an ambiguity, in that when the argument list + contains no <replaceable class="parameter">argmode</replaceable> + markers, it's unclear which rule is intended. + The <command>DROP</command> command will attempt the lookup both ways, + and will throw an error if two different procedures are found. + To avoid the risk of such ambiguity, it's recommendable to + write <literal>IN</literal> markers explicitly rather than letting them + be defaulted, thus forcing the + traditional <productname>PostgreSQL</productname> interpretation to be + used. + </para> + + <para> + The lookup rules just explained are also used by other commands that + act on existing procedures, such as <command>ALTER PROCEDURE</command> + and <command>COMMENT ON PROCEDURE</command>. + </para> + </refsect1> + + <refsect1 id="sql-dropprocedure-examples"> + <title>Examples</title> + + <para> + If there is only one procedure <literal>do_db_maintenance</literal>, + this command is sufficient to drop it: +<programlisting> +DROP PROCEDURE do_db_maintenance; +</programlisting> + </para> + + <para> + Given this procedure definition: +<programlisting> +CREATE PROCEDURE do_db_maintenance(IN target_schema text, OUT results text) ... +</programlisting> + any one of these commands would work to drop it: +<programlisting> +DROP PROCEDURE do_db_maintenance(IN target_schema text, OUT results text); +DROP PROCEDURE do_db_maintenance(IN text, OUT text); +DROP PROCEDURE do_db_maintenance(IN text); +DROP PROCEDURE do_db_maintenance(text); +DROP PROCEDURE do_db_maintenance(text, text); -- potentially ambiguous +</programlisting> + However, the last example would be ambiguous if there is also, say, +<programlisting> +CREATE PROCEDURE do_db_maintenance(IN target_schema text, IN options text) ... +</programlisting></para> + </refsect1> + + <refsect1 id="sql-dropprocedure-compatibility"> + <title>Compatibility</title> + + <para> + This command conforms to the SQL standard, with + these <productname>PostgreSQL</productname> extensions: + <itemizedlist> + <listitem> + <para>The standard only allows one procedure to be dropped per command.</para> + </listitem> + <listitem> + <para>The <literal>IF EXISTS</literal> option is an extension.</para> + </listitem> + <listitem> + <para>The ability to specify argument modes and names is an + extension, and the lookup rules differ when modes are given.</para> + </listitem> + </itemizedlist></para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-createprocedure"/></member> + <member><xref linkend="sql-alterprocedure"/></member> + <member><xref linkend="sql-dropfunction"/></member> + <member><xref linkend="sql-droproutine"/></member> + </simplelist> + </refsect1> + +</refentry> |