CREATE FUNCTION

描述

CREATE FUNCTION定义一个新函数。 CREATE OR REPLACE FUNCTION将创建一个 新函数或者替换一个现有的函数。要定义一个函数，用户必须具有该语言上的 USAGE特权。

如果包括了一个模式名，那么该函数会被创建在指定的模式中。否则，它会被 创建在当前模式中。新函数的名称不能匹配同一个模式中具有相同输入参数类型 的任何现有函数。不过，不同参数类型的函数能够共享一个名字（这被称作 重载）。

要替换一个现有函数的当前定义，可以使用 CREATE OR REPLACE FUNCTION。但不能用这种 方式更改函数的名称或者参数类型（如果尝试这样做，实际上就会创建一个新的 不同的函数）。还有， CREATE OR REPLACE FUNCTION将不会让你更改 一个现有函数的返回类型。要这样做，你必须先删除再重建该函数（在使用 OUT参数时，这意味着除了删除函数之外无法更改任何 OUT参数的类型）。

当CREATE OR REPLACE FUNCTION被用来替换一个现有的函数， 该函数的拥有权和权限不会改变。所有其他的函数属性会按照该命令中所指定的或者 隐含的来赋值。必须拥有（包括成为拥有角色的成员）该函数才能替换它。

如果你删除并且重建一个函数，新函数将和旧的不一样，你将必须删掉引用旧函数的 现有规则、视图、触发器等。使用 CREATE OR REPLACE FUNCTION更改一个函数定义 不会破坏引用该函数的对象。还有，ALTER FUNCTION可以被用 来更改一个现有函数的大部分辅助属性。

创建该函数的用户将成为该函数的拥有者。

要创建一个函数，你必须拥有参数类型和返回类型上的USAGE 特权。

参数

编写函数的进一步信息可以参考Section 35.3。

重载

PostgreSQL允许函数 重载，也就是说同一个名称可以被用于多个不同的 函数，只要它们具有可区分的输入参数类型。不过，所有函数的 C 名称必须 不同，因此你必须给被重载的 C 函数指定不同的 C 名称（例如，把参数类型 作为 C 名称的一部分）。

如果两个函数具有相同的名称和输入参数类型，它们被认为 相同（不考虑任何OUT参数）。因此这些声明会冲突：

CREATE FUNCTION foo(int) ...
CREATE FUNCTION foo(int, out text) ...

具有不同参数类型列表的函数在创建时将不会被认为是冲突的，但是如果默认值 被提供，在使用时它们有可能会冲突。例如，考虑

CREATE FUNCTION foo(int) ...
CREATE FUNCTION foo(int, int default 42) ...

调用foo(10)将会失败，因为在要决定应该调用哪个函数时会有歧义。

注解

允许把完整的SQL类型语法用于声明一个函数的参数和 返回值。不过，CREATE FUNCTION会抛弃带圆括号的类型 修饰符（例如类型numeric的精度域）。例如 CREATE FUNCTION foo (varchar(10)) ... 和 CREATE FUNCTION foo (varchar) ...完全一样。

在用CREATE OR REPLACE FUNCTION替换一个现有函数时，对于更改参数名是有限制的。不能更改 已经分配给任何输入参数的名称（不过可以给之前没有名称的参数增加名称）。 如果有多于一个输出参数，不能更改输出参数的名称，因为可能会改变描述 函数结果的匿名组合类型的列名。这些限制是为了确保函数被替换时，已有的 对该函数的调用不会停止工作。

如果一个被声明为STRICT的函数带有一个VARIADIC 参数，会严格检查该可变数组作为一个整体是否为非空。如果 该数组有空值元素，该函数仍将被调用。

示例

这里是一些小例子，它们可以帮你了解函数创建。更多信息和例子可见 Section 35.3。

CREATE FUNCTION add(integer, integer) RETURNS integer
    AS 'select $1 + $2;'
    LANGUAGE SQL
    IMMUTABLE
    RETURNS NULL ON NULL INPUT;

在PL/pgSQL中，使用一个参数名称增加一个整数：

CREATE OR REPLACE FUNCTION increment(i integer) RETURNS integer AS $$
        BEGIN
                RETURN i + 1;
        END;
$$ LANGUAGE plpgsql;

返回一个包含多个输出参数的记录：

CREATE FUNCTION dup(in int, out f1 int, out f2 text)
    AS $$ SELECT $1, CAST($1 AS text) || ' is text' $$
    LANGUAGE SQL;

SELECT * FROM dup(42);

你可以用更复杂的方式（用一个显式命名的组合类型）来做同样的事情：

CREATE TYPE dup_result AS (f1 int, f2 text);

CREATE FUNCTION dup(int) RETURNS dup_result
    AS $$ SELECT $1, CAST($1 AS text) || ' is text' $$
    LANGUAGE SQL;

SELECT * FROM dup(42);

另一种返回多列的方法是使用一个TABLE函数：

CREATE FUNCTION dup(int) RETURNS TABLE(f1 int, f2 text)
    AS $$ SELECT $1, CAST($1 AS text) || ' is text' $$
    LANGUAGE SQL;

SELECT * FROM dup(42);

不过，TABLE函数与之前的例子不同，因为它实际返回了一个 记录集合而不只是一个记录。

安全地编写 SECURITY DEFINER函数

因为一个SECURITY DEFINER函数会被以创建它的用户 的特权来执行，需要小心地确保该函数不会被误用。为了安全， search_path应该被设置为排除任何不可信用户 可写的模式。这可以阻止恶意用户创建对象来掩饰该函数所用到的对象。 在这方面特别重要的是临时表模式，默认情况下它会第一个被搜索并且通常 对任何用户都是可写的。可以通过强制最后搜索临时模式来得到一种安全的 布局。要这样做，把 pg_temp 写成search_path中的最后一项。这个函数展示了安全的用法：

CREATE FUNCTION check_password(uname TEXT, pass TEXT)
RETURNS BOOLEAN AS $$
DECLARE passed BOOLEAN;
BEGIN
        SELECT  (pwd = $2) INTO passed
        FROM    pwds
        WHERE   username = $1;

        RETURN passed;
END;
$$  LANGUAGE plpgsql
    SECURITY DEFINER
    -- 设置一个安全的 search_path：受信的模式，然后是 'pg_temp'。
    SET search_path = admin, pg_temp;

在PostgreSQL 版本 8.3 之前， SET选项不可用，因而较老的函数可能包含相当复杂的逻辑 来保存、设置以及恢复search_path。对于这种目的， SET选项更容易。

另一点要记住的是默认情况下，会为新创建的函数给PUBLIC 授予执行特权（详见GRANT）。你常常会希望把 安全定义器函数的使用限制在某些用户中。要这样做，你必须收回默认的 PUBLIC特权，然后选择性地授予执行特权。为了避免出现新 函数能被所有人访问的时间窗口，应在一个事务中创建它并且设置特权。例如：

BEGIN;
CREATE FUNCTION check_password(uname TEXT, pass TEXT) ... SECURITY DEFINER;
REVOKE ALL ON FUNCTION check_password(uname TEXT, pass TEXT) FROM PUBLIC;
GRANT EXECUTE ON FUNCTION check_password(uname TEXT, pass TEXT) TO admins;
COMMIT;

兼容性

CREATE FUNCTION命令被定义在 SQL:1999 及 其后的版本中。PostgreSQL的版本类似但 不完全兼容。属性是不可移植的，不同的可用语言也是不能移植的。

对于和一些其他数据库系统的兼容性， argmode可以被写在 argname之前或者之后。 但只有第一种方式是兼容标准的。

对于参数默认值，SQL 标准只指定带有DEFAULT关键词 的语法。带有=的语法被用在 T-SQL 和 Firebird 中。

另见