Chapter 40. PL/pgSQL - SQL Procedural Language

Table of Contents
40.1. Overview
40.1.1. Advantages of Using PL/pgSQL
40.1.2. Developing in PL/pgSQL
40.2. Handling of Quotations Marks
40.3. Structure of PL/pgSQL
40.4. Declarations
40.4.1. Aliases for Function Parameters
40.4.2. Copying Types
40.4.3. Row Types
40.4.4. Record Types
40.4.5. RENAME
40.5. Expressions
40.6. Basic Statements
40.6.1. Assignment
40.6.2. SELECT INTO
40.6.3. Executing an Expression or Query With No Result
40.6.4. Executing Dynamic Commands
40.6.5. Obtaining the Result Status
40.7. Control Structures
40.7.1. Returning From a Function
40.7.2. Conditionals
40.7.3. Simple Loops
40.7.4. Looping Through Query Results
40.8. Cursors
40.8.1. Declaring Cursor Variables
40.8.2. Opening Cursors
40.8.3. Using Cursors
40.9. Errors and Messages
40.10. Trigger Procedures
40.11. Porting from Oracle PL/SQL
40.11.1. Porting Examples
40.11.2. Other Things to Watch For
40.11.3. Appendix

PL/pgSQL is a loadable procedural language for the PostgreSQL database system. The design goals of PL/pgSQL were to create a loadable procedural language that

40.1. Overview

The PL/pgSQL call handler parses the function's source text and produces an internal binary instruction tree the first time the function is called (within each session). The instruction tree fully translates the PL/pgSQL statement structure, but individual SQL expressions and SQL commands used in the function are not translated immediately.

As each expression and SQL command is first used in the function, the PL/pgSQL interpreter creates a prepared execution plan (using the SPI manager's SPI_prepare and SPI_saveplan functions). Subsequent visits to that expression or command reuse the prepared plan. Thus, a function with conditional code that contains many statements for which execution plans might be required will only prepare and save those plans that are really used during the lifetime of the database connection. This can substantially reduce the total amount of time required to parse, and generate execution plans for the statements in a PL/pgSQL function. A disadvantage is that errors in a specific expression or command may not be detected until that part of the function is reached in execution.

Once PL/pgSQL has made an execution plan for a particular command in a function, it will reuse that plan for the life of the database connection. This is usually a win for performance, but it can cause some problems if you dynamically alter your database schema. For example:

CREATE FUNCTION populate() RETURNS integer AS '
DECLARE
    -- declarations
BEGIN
    PERFORM my_function();
END;
' LANGUAGE plpgsql;

If you execute the above function, it will reference the OID for my_function() in the execution plan produced for the PERFORM statement. Later, if you drop and recreate my_function(), then populate() will not be able to find my_function() anymore. You would then have to recreate populate(), or at least start a new database session so that it will be compiled afresh. Another way to avoid this problem is to use CREATE OR REPLACE FUNCTION when updating the definition of my_function (when a function is "replaced", its OID is not changed).

Because PL/pgSQL saves execution plans in this way, SQL commands that appear directly in a PL/pgSQL function must refer to the same tables and columns on every execution; that is, you cannot use a parameter as the name of a table or column in an SQL command. To get around this restriction, you can construct dynamic commands using the PL/pgSQL EXECUTE statement --- at the price of constructing a new execution plan on every execution.

Note: The PL/pgSQL EXECUTE statement is not related to the EXECUTE statement supported by the PostgreSQL server. The server's EXECUTE statement cannot be used within PL/pgSQL functions (and is not needed).

Except for input/output conversion and calculation functions for user-defined types, anything that can be defined in C language functions can also be done with PL/pgSQL. For example, it is possible to create complex conditional computation functions and later use them to define operators or use them in index expressions.

40.1.1. Advantages of Using PL/pgSQL

SQL is the language PostgreSQL (and most other relational databases) use as query language. It's portable and easy to learn. But every SQL statement must be executed individually by the database server.

That means that your client application must send each query to the database server, wait for it to process it, receive the results, do some computation, then send other queries to the server. All this incurs interprocess communication and may also incur network overhead if your client is on a different machine than the database server.

With PL/pgSQL you can group a block of computation and a series of queries inside the database server, thus having the power of a procedural language and the ease of use of SQL, but saving lots of time because you don't have the whole client/server communication overhead. This can make for a considerable performance increase.

Also, with PL/pgSQL you can use all the data types, operators and functions of SQL.

40.1.2. Developing in PL/pgSQL

One good way to develop in PL/pgSQL is to simply use the text editor of your choice to create your functions, and in another window, use psql to load those functions. If you are doing it this way, it is a good idea to write the function using CREATE OR REPLACE FUNCTION. That way you can reload the file to update the function definition. For example:

CREATE OR REPLACE FUNCTION testfunc(integer) RETURNS integer AS '
	  ....
end;
' LANGUAGE plpgsql;

While running psql, you can load or reload such a function definition file with

\i filename.sql

and then immediately issue SQL commands to test the function.

Another good way to develop in PL/pgSQL is using a GUI database access tool that facilitates development in a procedural language. One example of such as a tool is PgAccess, although others exist. These tools often provide convenient features such as escaping single quotes and making it easier to recreate and debug functions.