Table of Contents
Stored procedures and functions are routines that are created with CREATE PROCEDURE and CREATE FUNCTION statements. A procedure is invoked using a CALL statement, and can only pass back values using output variables. Functions may return a scalar value and can be called from inside a statement just like any other function (that is, by invoking the function's name). Stored routines may call other stored routines. A routine is either a procedure or a function.
At present, MySQL only preserves context for the default database. That is, if you say USE dbname within a procedure, the original default database is restored upon routine exit. A routine inherits the default database from the caller, so generally routines should either issue a USE dbname statement, or specify all tables with an explicit database reference, e.g. dbname.tablename.
MySQL supports the very useful extension that allows the use of regular SELECT statements (that is, without using cursors or local variables) inside a stored procedure. The result set of such a query is simply sent directly to the client. Multiple SELECT statements generate multiple result sets, so the client must use a MySQL client library that supports multiple result sets. This means the client must use a client library from a version of MySQL at least as recent as 4.1.
This following section describes the syntax used to create, alter, drop, and query stored procedures and functions.
CREATE PROCEDURE sp_name ([parameter[,...]]) [characteristic ...] routine_body CREATE FUNCTION sp_name ([parameter[,...]]) [RETURNS type] [characteristic ...] routine_body parameter: [ IN | OUT | INOUT ] param_name type type: Any valid MySQL data type characteristic: LANGUAGE SQL | [NOT] DETERMINISTIC | SQL SECURITY {DEFINER | INVOKER} | COMMENT string routine_body: Valid SQL procedure statement(s)
The RETURNS clause may be specified for a only FUNCTION. It is used to indicate the return type of the function, and the function body must contain a RETURN value statement.
The parameter list enclosed within parentheses must always be present. If there are no parameters, an empty parameter list of () should be used. Each parameter is an IN parameter by default. To specify otherwise for a parameter, use the keyword OUT or INOUT before the parameter name. Specifying IN, OUT, or INOUT is only valid for a PROCEDURE.
The CREATE FUNCTION statement is used in earlier versions of MySQL to support UDFs (User Defined Functions). See Adding functions. UDFs continue to be supported, even with the existence of stored functions. A UDF can be regarded as an external stored function. However, do note that stored functions share their namespace with UDFs.
A framework for external stored procedures will be introduced in the near future. This will allow you to write stored procedures in languages other than SQL. Most likely, one of the first languages to be supported will be PHP, as the core PHP engine is small, thread-safe, and can easily be embedded. As the framework will be public, it is expected that many other languages will also be supported.
A function is considered ``deterministic'' if it always returns the same result for the same input parameters, and ``not deterministic'' otherwise. Currently, the DETERMINISTIC characteristic is accepted, but not yet used by the optimizer.
The SQL SECURITY characteristic can be used to specify whether the routine should be executed using the permissions of the user who creates the routine, or the user who invokes it. The default value is DEFINER. This feature is new in SQL:2003.
MySQL does not yet use the GRANT EXECUTE privilege. So for now, if a procedure p1() mentions table t1, the caller must have privileges on table t1 in order to call procedure p1() successfully.
MySQL stores the sql_mode settings in effect at the time a routine is created, and will always execute routines with these settings in force.
The COMMENT clause is a MySQL extension, and may be used to describe the stored procedure. This information is displayed by the SHOW CREATE PROCEDURE and SHOW CREATE FUNCTION statements.
MySQL allows routines to contain DDL statements (such as CREATE and DROP) and SQL transaction statements (such as COMMIT). This is not required by the standard and is therefore implementation-specific.
NOTE: Currently, stored FUNCTIONs may not contain references to tables. Please note that this includes some SET statements, but excludes some SELECT statements. This limitation will be lifted as soon as possible.
The following is an example of a simple stored procedure that uses an OUT parameter. The example uses the mysql client delimiter command to change the statement delimiter prior to defining the procedure. This allows the ; delimiter used in the procedure body to be passed through to the server rather than being interpreted by mysql itself.
mysql> delimiter | mysql> CREATE PROCEDURE simpleproc (OUT param1 INT) -> BEGIN -> SELECT COUNT(*) INTO param1 FROM t; -> END -> | Query OK, 0 rows affected (0.00 sec) mysql> CALL simpleproc(@a)| Query OK, 0 rows affected (0.00 sec) mysql> SELECT @a| +------+ | @a | +------+ | 3 | +------+ 1 row in set (0.00 sec)
The following is an example of a function that takes a parameter, performs an operation using an SQL function, and returns the result:
mysql> delimiter | mysql> CREATE FUNCTION hello (s CHAR(20)) RETURNS CHAR(50) -> RETURN CONCAT('Hello, ',s,'!'); -> | Query OK, 0 rows affected (0.00 sec) mysql> SELECT hello('world')| +----------------+ | hello('world') | +----------------+ | Hello, world! | +----------------+ 1 row in set (0.00 sec)
ALTER {PROCEDURE | FUNCTION} sp_name [characteristic ...] characteristic: NAME newname | SQL SECURITY {DEFINER | INVOKER} | COMMENT string
This command can be used to rename a stored procedure or function, and to change its characteristics. More than one change may be specified in an ALTER PROCEDURE or ALTER FUNCTION statement.
DROP {PROCEDURE | FUNCTION} [IF EXISTS] sp_name
This command is used to delete a stored procedure or function. That is, the specified routine is removed from the server.
The IF EXISTS clause is a MySQL extension. It prevents an error from occurring if the procedure or function does not exist. A warning is produced that can be viewed with SHOW WARNINGS.