Introduction to MySQL cursor
To handle a result set inside a
stored procedure, you use a cursor. A cursor allows you to
iterate a set of rows returned by a query and process each row accordingly.
MySQL cursor is read only, non-scrollable and asensitive.
- Read only: you cannot update data in the underlying table through the cursor.
- Non-scrollable: you can only fetch rows in the order determined by the SELECT statement. You cannot fetch rows in the reversed order. In addition, you cannot skip rows or jump to a specific row in the result set.
- Asensitive: there are two kinds of cursors:
asensitive cursor and insensitive cursor. An asensitive cursor points
to the actual data, whereas an insensitive cursor uses a temporary copy
of the data. An asensitive cursor performs faster than an insensitive
cursor because it does not have to make a temporary copy of data.
However, any change that made to the data from other connections will
affect the data that is being used by an asensitive cursor, therefore it
is safer if you don’t update the data that is being used by an
asensitive cursor. MySQL cursor is asensitive.
You can use MySQL cursors in
stored procedures, stored functions and
triggers.
Working with MySQL cursor
First, you have to declare a cursor by using the
DECLARE statement:
|
|
DECLARE cursor_name CURSOR FOR SELECT_statement;
|
The cursor declaration must be after any
variable declaration.
If you declare a cursor before variables declaration, MySQL will issue
an error. A cursor must always be associated with a
SELECT statement.
Next, you open the cursor by using the
OPEN statement. The
OPEN statement initializes the result set for the cursor therefore you must call the
OPEN statement before fetching rows from the result set.
Then, you use the
FETCH statement to retrieve the next row pointed by the cursor and move the cursor to the next row in the result set.
|
|
FETCH cursor_name INTO variables list;
|
After that, you can check to see if there is any row available before fetching it.
Finally, you call the
CLOSE statement to deactivate the cursor and release the memory associated with it as follows:
When the cursor is no longer used, you should close it.
When working with MySQL cursor, you must also declare a
NOT FOUND handler to handle the situation when the cursor could not find any row. Because each time you call the
FETCH
statement, the cursor attempts to read the next row in the result set.
When the cursor reaches the end of the result set, it will not be able
to get the data, and a condition is raised. The handler is used to
handle this condition.
To declare a
NOT FOUND handler, you use the following syntax:
|
|
DECLARE CONTINUE HANDLER FOR NOT FOUND SET finished = 1;
|
Where
finished is
a variable to indicate that the cursor has reached the end of the
result set. Notice that the handler declaration must appear after
variable and cursor declaration inside the stored procedures.
The following diagram illustrates how MySQL cursor works.
MySQL Cursor Example
We are going to develop a stored procedure that builds an
email list of all employees in the
employees table in the
MySQL sample database.
First, we declare some variables, a cursor for looping over the emails of employees, and a
NOT FOUND handler:
|
|
DECLARE finished INTEGER DEFAULT 0;
DECLARE email varchar(255) DEFAULT "";
-- declare cursor for employee email
DEClARE email_cursor CURSOR FOR
SELECT email FROM employees;
-- declare NOT FOUND handler
DECLARE CONTINUE HANDLER
FOR NOT FOUND SET finished = 1;
|
Next, we open the
email_cursor by using the
OPEN statement:
Then, we iterate
the email list, and concatenate all emails where each email is separated by a semicolon(;):
|
|
get_email: LOOP
FETCH email_cursor INTO v_email;
IF v_finished = 1 THEN
LEAVE get_email;
END IF;
-- build email list
SET email_list = CONCAT(v_email,";",email_list);
END LOOP get_email;
|
After that, inside the loop we used the
v_finished variable to check if there is any email in the list to terminate the loop.
Finally, we close the cursor using the
CLOSE statement:
The
build_email_list stored procedure is as follows:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
|
DELIMITER $$
CREATE PROCEDURE build_email_list (INOUT email_list varchar(4000))
BEGIN
DECLARE v_finished INTEGER DEFAULT 0;
DECLARE v_email varchar(100) DEFAULT "";
-- declare cursor for employee email
DEClARE email_cursor CURSOR FOR
SELECT email FROM employees;
-- declare NOT FOUND handler
DECLARE CONTINUE HANDLER
FOR NOT FOUND SET v_finished = 1;
OPEN email_cursor;
get_email: LOOP
FETCH email_cursor INTO v_email;
IF v_finished = 1 THEN
LEAVE get_email;
END IF;
-- build email list
SET email_list = CONCAT(v_email,";",email_list);
END LOOP get_email;
CLOSE email_cursor;
END$$
DELIMITER ;
|
You can test the
build_email_list stored procedure using the following script:
|
|
SET @email_list = "";
CALL build_email_list(@email_list);
SELECT @email_list;
|
In this tutorial, we have shown you how to use MySQL cursor to iterate a result set and process each row accordingly.
