27.2.2. CREATE FUNCTION/DROP FUNCTION 语法
CREATE [AGGREGATE] FUNCTION function_name RETURNS {STRING|INTEGER|REAL}
SONAME shared_library_name
DROP FUNCTION function_name
一个自定义函数 (UDF)就是用一个象ABS() 或 CONCAT()这样的固有(内建)函数一样作用的新函数去扩展MySQL。
function_name 是 用在SQL声明中以备调用的函数名字。RETURNS 子句说明函数返回值的类型。 shared_library_name 是共享目标文件的基本名,共享目标文件含有实现函数的代码。该文件必须位于一个能被你系统的动态连接者搜索的目录里。
你必须有mysql 数据库的INSERT 权限才能创建一个函数,你必须有mysql 数据库的DELETE权限才能撤销一个函数。这是因为CREATE FUNCTION 往记录函数名字,类型和共享名的mysql.func系统表里添加了一行,而DROP FUNCTION则是从表中删掉这一行。如果你没有这个系统表,你应该运行mysql_fix_privilege_tables脚本来创建一个。请参阅2.10.2节,“升级授权表”。
一个有效的函数是一个用CREATE FUNCTION加载且没有用DROP FUNCTION移除的函数。每次服务器启动的时候会重新加载所有有效函数,除非你使用--skip-grant-tables参数启动mysqld。在这种情况下, 将跳过UDF的初始化,UDF不可用。
要了解编写自定义函数的说明,请参阅27.2.3节,“添加新的自定义函数”。要使得UDF机制能够起作用,必须使用C或者C++编写函数,你的系统必须支持动态加载,而且你必须是动态编译的mysqld(非静态)。
一个AGGREGATE函数就像一个MySQL固有的集合(总和)函数一样起作用,比如,SUM或COUNT()函数。要使得AGGREGATE 起作用,你的mysql.func表必须包括一个type列。如果你的mysql.func表没有这一 列,你应该运行mysql_fix_privilege_tables脚本来创建此 列。
要使得UDF机制能够起作用,必须使用C或者C++编写函数,你的系统必须支持动态加载。MySQL 源码分发版包括一个sql/udf_example.cc 文件,此文件定义了5个新函数。可以参考这个文件,看UDF是如何调用常规工作。
为了能使用UDF,你需要动态链接mysqld。不要配置MySQL使用--with-mysqld-ldflags=-all-static参数。如果你想使用一个需要从mysqld 访问符号的UDF(例如在使用default_charset_info的sql/udf_example.cc文件中的metaphone函数),你必须使用-rdynamic参数来链接程序(参阅man dlopen)。如果你计划使用UDF, 一个经验法则就是,用with-mysqld-ldflags=-rdynamic设定MySQL,除非你有很好的理由不去这么做。
如果你使用的是预编译分发版的MySQL, 请使用MySQL-Max,其中含有一个动态链接了的服务器,它可以支持动态加载。
对于每个你想要使用在SQL声明中的函数,你应该定义相应的C (或 C++)函数。在下面的讨论中,xxx用来表示范例函数的名字,为了区分使用SQL还是C/C++,xxx()(上标)表示SQL函数调用,xxx()(下标)表示C/C++函数调用。
你为xxx()编写来实现接口的C/C++ 函数如下:
当SQL声明调用XXX()时,MySQL调用初始化函数xxx_init(),让它执行必要的设置,比如,检查 参量或分配内存。如果xxx_init() 返回一个错误,SQL声明会退出并给出错误信息,而主函数和去初始化函数并没有被调用。 否则,主函数xxx() 对每一行都被调用一次。所有行都处理完之后,调用去初始化函数xxx_deinit() 执行必要的清除。
对于象SUM()一样工作的集合函数,你也必须提供如下的函数:
MySQL 按下列操作来处理集合UDF:
-
调用 xxx_init() 让集合函数分配它需要用来存储结果的内存。
-
按照GROUP BY表达式来排序表。
-
为每个新组中的第一行调用xxx_clear()函数。
-
为属于同组的每一个新行调用xxx_add()函数。
-
当组改变时或每组的最后一行被处理完之后,调用xxx()来获取集合结果。
-
重复,以上3-步直到所有行被处理完。
-
调用xxx_deinit() 函数去释放UDF分配的内存。.
所有函数必须时线程安全的,这不仅对主函数,对初始化和去初始化函数也一样,也包括集合函数要求的附加函数。这个要求的一个结果就是,你不能分配任何变化的全局或静态变量。如果你需要内存,你可以在xxx_init()函数分配内存,然后在xxx_deinit()函数释放掉。
下面介绍创建简单UDF时需要定义的不同函数。27.2.3节,“添加新的自定义函数”中介绍了MySQL调用这些函数的顺序。
如本节所示,应该说明主函数xxx()。注意返回值和参数会有所不同,这取决于你说明的SQL函数xxx()在CREATE FUNCTION声明中返回的是STRING,INTEGER类型还是REAL类型示:
对于STRING 型函数:
char *xxx(UDF_INIT *initid, UDF_ARGS *args,
char *result, unsigned long *length,
char *is_null, char *error);
对于INTEGER型函数:
long long xxx(UDF_INIT *initid, UDF_ARGS *args,
char *is_null, char *error);
对于REAL型函数:
double xxx(UDF_INIT *initid, UDF_ARGS *args,
char *is_null, char *error);
初始化和去初始化函数如下说明:
my_bool xxx_init(UDF_INIT *initid, UDF_ARGS *args, char *message);
void xxx_deinit(UDF_INIT *initid);
initid 参数被传递给所有的三个函数。它指向一个UDF_INIT 结构,这个结构被用来在函数之间交换信息。UDF_INIT 结构项跟随着。初始化函数应该给任何它想要改变的项赋值。(要使用项的默认值,就让它不被改变)
-
my_bool maybe_null
如果xxx() 能返回NULL,xxx_init()应maybe_null 为 1 。如果任一参量被说明了 maybe_null值,其 默认值是1 。
-
unsigned int decimals
小数位数。默认值是传到主函数的参量里小数的最大位数。(例如,如果函数传递 1.34, 1.345, 和1.3, 那么默认值为,因为1.345 有3位小数。
-
unsigned int max_length
结果的最大长度。max_length 的默认值因函数的结果类型而异。对字符串函数,默认值是最长参量的长度。对整型函数,默认是21位。对实型函数,默认是13再加上initid->decimals指示的小数位数。(对数字函数,长度包含正负号或者小数点符)。
如果想返回团值,你可以把max_length 设为从65KB到16MB。这个内存不会被分配,但是如果有临时数据需要存储,这个设置了的值被用来决定使用哪种 列的类型。
-
char *ptr
函数可以用作本身目的的指针。比如,函数可以用initid->ptr 来在分配了的内存内部通讯。 xxx_init() 应该分配内存,并指派给这个指针:
initid->ptr = allocated_memory;
在 xxx() 和 xxx_deinit()中,借用 initid->ptr 来使用或分配内存。