Compiling PL/SQL Code for Native Execution

Compiling PL/SQL Code for Native Execution

You can speed up PL/SQL procedures by compiling them into native code residing in shared libraries. The procedures are translated into C code, then compiled with your usual C compiler and linked into the Oracle process.

You can use this technique with both the supplied Oracle packages, and procedures you write yourself. Procedures compiled this way work in all server environments, such as the shared server configuration (formerly known as multi-threaded server) and Oracle Real Application Clusters.

Before You Begin

If you are a first-time user of native PL/SQL compilation, try it first with a test database, before proceeding to a production environment.

Always back up your database before configuring the database for PL/SQL native compilation. If you find that the performance benefit is outweighed by extra compilation time, it might be faster to restore from a backup than to recompile everything in interpreted mode.

Some of the setup steps require DBA authority. You must change the values of some initialization parameters, and create a new directory on the database server, preferably near the data files for the instance. The database server also needs a C compiler; on a cluster, the compiler is needed on each node. Even if you can test out these steps yourself on a development machine, you will generally need to consult with a DBA and enlist their help to use native compilation on a production server.

Contact your system administrator to ensure that you have the required C compiler on your operating system, and find the path for its location. Use a text editor such as vi to open the file $ORACLE_HOME/plsql/spnc_commands, and make sure the command templates are correct. Generally, you should not need to make any changes here, just confirm that the setup is correct.

Determining Whether to Use PL/SQL Native Compilation

PL/SQL native compilation provides the greatest performance gains for computation-intensive procedural operations. Examples of such operations are data warehouse applications, and applications with extensive server-side transformations of data for display. In such cases, expect speed increases of up to 30%.

Because this technique cannot do much to speed up SQL statements called from PL/SQL, it is most effective for compute-intensive PL/SQL procedures that do not spend most of their time executing SQL. You can test to see how much performance gain you can get by enabling PL/SQL native compilation.

It takes longer to compile program units with native compilation than to use the default interpreted mode. You might turn off native compilation during the busiest parts of the development cycle, where code is being frequently recompiled.

When you have decided that you will have significant performance gains in database operations using PL/SQL native compilation, Oracle Corporation recommends that you compile the whole database using the NATIVE setting. Compiling all the PL/SQL code in the database means you see the speedup in your own code, and in calls to all the built-in PL/SQL packages.

How PL/SQL Native Compilation Works

If you do not use native compilation, each PL/SQL program unit is compiled into an intermediate form, machine-readable code (m-code). The m-code is stored in the database dictionary and interpreted at run time.

11-22 PL/SQL User's Guide and Reference

Compiling PL/SQL Code for Native Execution

With PL/SQL native compilation, the PL/SQL statements are turned into C code that bypasses all the runtime interpretation, giving faster runtime performance.

PL/SQL uses the command file $ORACLE_HOME/plsql/spnc_commands, and the supported operating system C compiler and linker, to compile and link the resulting C code into shared libraries. The shared libraries are stored inside the data dictionary, so that they can be backed up automatically and are protected from being deleted. These shared library files are copied to the filesystem and are loaded and run when the PL/SQL subprogram is invoked. If the files are deleted from the filesystem while the database is shut down, or if you change the directory that holds the libraries, they are extracted again automatically.

Although PL/SQL program units that just call SQL statements might see little or no speedup, natively compiled PL/SQL is always at least as fast as the corresponding interpreted code. The compiled code makes the same library calls as the interpreted code would, so its behavior is exactly the same.

Format of the spnc_commands File

The spnc_commands file, in the $ORACLE_HOME/plsql directory, contains the templates for the commands to compile and link each program. Some special names such as %(src) are predefined, and are replaced by the corresponding filename. The variable $(ORACLE_HOME) is replaced by the location of the Oracle home directory. You can include comment lines, starting with a # character. The file contains comments that explain all the special notation.

The spnc_commands file contains a predefined path for the C compiler, depending on the particular operating system. (One specific compiler is supported on each operating system.) In most cases, you should not need to change this path, but you might if you the system administrator has installed it in another location.

System-Level Initialization Parameters for PL/SQL Native Compilation

The following table lists the initialization parameters you must set before using PL/SQL native compilation. They can be set only at the system level, not by an ALTER SESSION command. You cannot use variables such as ORACLE_HOME in the values; use the full path instead.

Note: The examples in this section for setting system parameters for PL/SQL native compilation assume a system using a server parameter file (SPFILE).

If you use a text initialization parameter file (PFILE, or initsid.ora), ensure that you change parameters in your initialization parameter file, as indicated in the following table.

PLSQL_NATIVE_LIBRARY_DIR The full path and directory name used to store the shared libraries that contain natively compiled PL/SQL code.

In accordance with optimal flexible architecture (OFA) rules, Oracle Corporation recommends that you create the shared library directory as a subdirectory where the data files are located.

For security reasons, only the users oracle and root should have write privileges for this directory.

Tuning PL/SQL Applications for Performance 11-23

Compiling PL/SQL Code for Native Execution

Session-Level Initialization Parameter for PL/SQL Native Compilation

The parameter PLSQL_CODE_TYPE determines whether PL/SQL code is natively compiled or interpreted. The default setting is INTERPRETED. To enable PL/SQL native compilation, set the value of PLSQL_CODE_TYPE to NATIVE.

If you compile the whole database as NATIVE, Oracle Corporation recommends that you set PLSQL_CODE_TYPE at the system level.

Use the following syntax to set this parameter:

alter session set plsql_code_type='NATIVE'; alter session set plsql_code_type='INTERPRETED'; alter system set plsql_code_type='NATIVE'; alter system set plsql_code_type='INTERPRETED';

See Also: Oracle Database Reference for complete details about the initialization parameters and data dictionary views.

Setting Up and Using PL/SQL Native Compilation

To speed up one or more subprograms through native compilation:

1.Set up the PLSQL_NATIVE_LIBRARY_DIR initialization parameter, and optionally the PLSQL_NATIVE_LIBRARY_SUBDIR_COUNT initialization parameter, as described above.

2.Use the ALTER SYSTEM or ALTER SESSION command, or update your initialization file, to set the parameter PLSQL_CODE_TYPE to the value NATIVE.

3.Compile one or more subprograms, using one of these methods:

■ Use CREATE OR REPLACE to create or recompile the subprogram.

■Use the ALTER PROCEDURE, ALTER FUNCTION, or ALTER PACKAGE command with the COMPILE option to recompile the subprogram or the entire package. (You can also use the clause PLSQL_CODE_TYPE = NATIVE with the ALTER statements to affect specific subprograms without changing the initialization parameter for the whole session.)

■Drop the subprogram and create it again.

■Run one of the SQL*Plus scripts that creates a set of Oracle-supplied packages.

■Create a database using a preconfigured initialization file with PLSQL_CODE_TYPE=NATIVE. During database creation, the UTLIRP script is run to compile all the Oracle-supplied packages.

4.To be sure that the process worked, you can query the data dictionary to see that a procedure is compiled for native execution. To check whether an existing procedure is compiled for native execution or not, you can query the data dictionary views USER_PLSQL_OBJECT_SETTINGS,

11-24 PL/SQL User's Guide and Reference

Compiling PL/SQL Code for Native Execution

DBA_PLSQL_OBJECT_SETTINGS, and ALL_PLSQL_OBJECT_SETTINGS. For example, to check the status of the procedure MY_PROC, you could enter:

CREATE OR REPLACE PROCEDURE my_proc AS BEGIN NULL; END;

/

SELECT plsql_code_type FROM user_plsql_object_settings WHERE name = 'MY_PROC'; DROP PROCEDURE my_proc;

The CODE_TYPE column has a value of NATIVE for procedures that are compiled for native execution, and INTERPRETED otherwise.

After the procedures are compiled and turned into shared libraries, they are automatically linked into the Oracle process. You do not need to restart the database, or move the shared libraries to a different location. You can call back and forth between stored procedures, whether they are all interpreted, all compiled for native execution, or a mixture of both.

Dependencies, Invalidation and Revalidation

This recompilation happens automatically invalidated, such as when a table that it depends on is re-created.

If an object on which a natively compiled PL/SQL subprogram depends changes, the subprogram is invalidated. The next time the same subprogram is called, the database recompiles the subprogram automatically. Because the PLSQL_CODE_TYPE setting is stored inside the library unit for each subprogram, the automatic recompilation uses this stored setting for code type.

The stored settings are only used when recompiling as part of revalidation. If a PL/SQL subprogram is explicitly compiled through the SQL commands "create or replace" or "alter...compile", the current session setting is used.

The generated shared libraries are stored in the database, in the SYSTEM tablespace. The first time a natively compiled procedure is executed, the corresponding shared library is copied from the database to the directory specified by the initialization parameter PLSQL_NATIVE_LIBRARY_DIR.

Setting Up Databases for PL/SQL Native Compilation

Use the procedures in this section to set up an entire database for PL/SQL native compilation. The performance benefits apply to all the built-in PL/SQL packages, which are used for many database operations.

Creating a New Database for PL/SQL Native Compilation

If you use Database Configuration Assistant, use it to set the initialization parameters required for PL/SQL native compilation, as described in the preceding section, "System-Level Initialization Parameters for PL/SQL Native Compilation".

To find the supported C compiler on your operating system. refer to the table "Precompilers and Tools Restrictions and Requirements" in the installation guide for your operating system. Determine from your system administrator where it is located on your system. You will need to check that this path is correct in the spnc_commands file.

Determine if you have so many PL/SQL program units that you need to set the initialization parameter PLSQL_NATIVE_DIR_SUBDIR_COUNT, and create PL/SQL native library subdirectories if necessary. By default, PL/SQL program units are kept in one directory. If the number of program units exceeds 15,000, the operating system begins to impose performance limits. To work around this problem, Oracle

Tuning PL/SQL Applications for Performance 11-25

Compiling PL/SQL Code for Native Execution

Corporation recommends that you spread the PL/SQL program units among subdirectories.

If you have set up a test database, use this SQL query to determine how many PL/SQL program units you are using:

select count (*) from DBA_PLSQL_OBJECTS;

If the count returned by this query is greater than 15,000, complete the procedure described in the section "Setting Up PL/SQL Native Library Subdirectories".

Modifying an Existing Database for PL/SQL Native Compilation

To natively compile an existing database, complete the following procedure:

1.Contact your system administrator to ensure that you have the required C compiler on your operating system, and find the path for its location. Use a text editor such as vi to open the file spnc_commands, and make sure the command templates are correct.

2.As the oracle user, create the PL/SQL native library directory for each Oracle database.

Note: You must set up PL/SQL libraries for each Oracle database. Shared libraries (.so and .dll files) are logically connected to the database. They cannot be shared between databases. If you set up PL/SQL libraries to be shared, the databases will be corrupted.

Create a directory in a secure place, in accordance with OFA rules, to prevent .so and .dll files from unauthorized access.

In addition, ensure that the compiler executables used for PL/SQL native compilation are writable only by a properly secured user.

The original copies of the shared libraries are stored inside the database, so they are backed up automatically with the database.

3.Using SQL, set the initialization parameter PLSQL_NATIVE_LIBRARY_DIR to the full path to the PL/SQL native library.

For example, if the path to the PL/SQL native library directory is

/oracle/oradata/mydb/natlib, enter the following:

alter system set plsql_native_library_dir='/oracle/oradata/mydb/natlib'

4.Determine if you need to set the initialization parameter

PLSQL_NATIVE_DIR_SUBDIR_COUNT, and create PL/SQL native library subdirectories if necessary.

By default, PL/SQL program units are kept in one directory. However, if the number of program units exceeds 15000, then the operating system begins to impose performance limits. To work around this problem, Oracle Corporation recommends that you spread the PL/SQL program units in subdirectories.

If you have an existing database that you will migrate to the new installation, or if you have set up a test database, use the following SQL query to determine how many PL/SQL program units you are using:

select count (*) from DBA_PLSQL_OBJECTS;

11-26 PL/SQL User's Guide and Reference

Compiling PL/SQL Code for Native Execution

If the count returned by this query is greater than 15,000, complete the procedure described in the following section, "Setting Up PL/SQL Native Library Subdirectories".

5.Set the remaining required initialization parameters as listed in the table in the preceding section "System-Level Initialization Parameters for PL/SQL Native Compilation".

6.Create the following stored procedure to confirm that PL/SQL native compilation is enabled:

CREATE OR REPLACE PROCEDURE Hello AS BEGIN

dbms_output.put_line ( 'This output is from a natively compiled procedure.'

);

END Hello;

/

7.Run the stored procedure:

CALL Hello();

If the program does not return the expected output, contact Oracle Support for assistance. (Remember to SET SERVEROUTPUT ON in SQL*Plus before running the procedure.)

8.Recompile all the PL/SQL subprograms in the database. The script $ORACLE_HOME/admin/utlirp.sql is typically used here.

Setting Up PL/SQL Native Library Subdirectories

If you need to set up PL/SQL native library subdirectories, use the following procedure:

1.Create subdirectories sequentially in the form of d0, d1, d2, d3...dx, where x is the total number of directories. Oracle Corporation recommends that you use a script for this task. For example, you might run a PL/SQL block like the following, save its output to a file, then run that file as a shell script:

BEGIN

FOR j IN 0..999 LOOP

dbms_output.put_line ( 'mkdir d' || TO_CHAR(j) ); END LOOP;

END;

/

2.Set the initialization parameter PLSQL_NATIVE_DIR_COUNT to the number of subdirectories you have created. For example, if you created 1000 subdirectories, enter the following SQL statement in SQL*Plus:

alter system set plsql_native_library_subdir_count=1000;

Example 11–8 Compiling a PL/SQL Procedure for Native Execution

alter session set plsql_code_type='NATIVE'; CREATE OR REPLACE PROCEDURE hello_native AS

BEGIN

dbms_output.put_line('Hello world.'); dbms_output.put_line('Today is ' || TO_CHAR(SYSDATE) || '.');

Tuning PL/SQL Applications for Performance 11-27