Oracle DML Error Logging
August 23, 2006
Not all errors in Oracle are fatal, and that statement applies to data manipulation language statements as well. Even though an error in and of itself may be fatal, when handled properly it becomes benign. The question is this: how do you make an otherwise fatal error benign or harmless? There are at least three ways, two of which you are probably quite familiar with, and a lesser known, but very versatile third method.
The Tried and True Ways
Two methods of capturing DML errors and being able to deal with them in a suitable manner are SQL*Loader and PL/SQL exception handling. If your situation involves uploading data or writing blocks of exception handling code (and only checking for a few errors), then by and large, these manners are suitable. SQL*Loader can provide a wealth of information about a bad record via the log, bad, and discard files, but its usefulness across all DML operations is limited.
PL/SQL exception handling can also capture errors and provide information for feedback, but coding all of the potential places where an integrity error can occur, in addition to keeping track of an exception blocks scope, can grow to be quite tedious. Besides, are you sure you accounted for all of the possible errors? The PL/SQL approach also means having to wrap blocks in an inappropriate manner and repeating the error handling from block to block. The PL/SQL approach also incurs the cost of context switching because of having to switch between SQL and PL/SQL. There has to be a better way, and in this case, there does exist a better way, namely, that of what is referred to as DML error logging.
DML Error Logging Basics
Managing Tables, Chapter 15 of the Administrators Guide, explains what takes place during DML error logging.
To use DML error logging, you add a statement clause that specifies the name of an error logging table into which the database records errors encountered during DML operations. When you add this error logging clause to the
The scenario just shown mentions INSERT, but DML error logging applies to UPDATE and DELETE as well. The basic steps (summarized from the documentation) are to:
1. Optionally create an error logging table. You can create the table manually or use the DBMS_ERRLOG package to automatically create it for you.
2. Execute a DML statement and include an error logging clause. This clause:
3. Note: If the statement exceeds the reject limit and rolls back, the error logging table retains the log entries recorded so far.
4. Query the error logging table and take corrective action for the rows that generated errors.
If you do create an error logging table, you must include all of the mandatory error logging columns (although they can be created in any order). You may optionally create additional columns, which reference the DML table. An important point to keep in mind is that datatypes of the additional columns must be able to capture or handle the datatype of the DML column. For example, dont make a number column in the error table when the DML table is trying to use VARCHAR2. Do, however, make the error table column datatype VARCHAR2 when dealing with a number in the DML table. Oracle will handle the casting for you (if it can). VARCHAR2(4000) is pretty much the default datatype you should use for typical DML column datatypes.
The mandatory columns in an (again, optional) error table are:
You have two options with respect to creating an error table. The first is to let Oracle do the work for you, and that requires using the DBMS_ERRLOG package. This built-in will not only create the mandatory columns just mentioned, but will also map the target DML tables columns. The second and decidedly more difficult way is to manually create the logging table via a data definition language (DDL) CREATE TABLE statement. Under the manual method, you are responsible for ensuring the mandatory parts are in place and for mapping any additional columns.
The only real advantage to manually creating an error logging table is that you can name it whatever you want and add (or not) only some of the DML tables columns. Otherwise, the table is named ERR$_<first 25 characters of the DML tables name>.
The DBMS_ERRLOG Package
This package, described in Chapter 38 of Oracle® Database PL/SQL Packages and Types Reference, 10g Release 2 (10.2) employs a security model. For the most part, you can create an error logging table for any table (or view) you own. Some of the packages input parameters can be null, and the only mandatory input parameter is the name of the DML (or target) table. There is only one procedure in this package, and that is the CREATE_ERROR_LOG procedure. To help prevent a datatype mismatch between the DML and error logging table, you may want to consider using the skip_unsupported input parameter (BOOLEAN, default is false, meaning an unsupported column type will cause the procedure to terminate).
Lets look at an example/use case for DML error logging. To keep things simple, we will use the EMP table in Scotts schema. The steps below show how easy it is to create the error logging table. Note how all of the columns in EMP have been mapped to VARCHAR2(4000)s in ERR$_EMP.
SQL> set serveroutput on SQL> exec DBMS_ERRLOG.CREATE_ERROR_LOG ('EMP'); PL/SQL procedure successfully completed. SQL> desc err$_emp; Name Null? Type ----------------------------------------------------------- -------- ---------------- ORA_ERR_NUMBER$ NUMBER ORA_ERR_MESG$ VARCHAR2(2000) ORA_ERR_ROWID$ ROWID ORA_ERR_OPTYP$ VARCHAR2(2) ORA_ERR_TAG$ VARCHAR2(2000) EMPNO VARCHAR2(4000) ENAME VARCHAR2(4000) JOB VARCHAR2(4000) MGR VARCHAR2(4000) HIREDATE VARCHAR2(4000) SAL VARCHAR2(4000) COMM VARCHAR2(4000) DEPTNO VARCHAR2(4000)
Now that the error logging table is created, lets attempt a DML statement which we know will have an error. Try to duplicate the employee named MILLER.
SQL> INSERT INTO emp values (7934,'MILLER','CLERK',7782,'23-JAN-82',3900,null,20) 2 LOG ERRORS INTO err$_emp ('insert example') REJECT LIMIT 25; 0 rows created.
We failed to insert into EMP, but what is in ERR$_EMP?
As another example, what if the ENAMEs were constrained to be not null? Issue "alter table emp modify (ename not null);" to achieve the desired effect, and then attempt an insert as shown below (with and without the error logging clause).
You have to admit this is much easier than using nested PL/SQL blocks where scope has to be considered to keep an operation running.
The utility or usefulness of DML error logging is considerable if your application processes large amounts of records. Instead of (potentially) bombing out after running for hours, you can craft a means of allowing good records to be processed and then come back to problem records at a later time. This approach to programming does not imply you should minimize why an error occurred. Capturing badly formatted data is a clear case of utility, but handling incorrect referential data must be considered as to why or how DML failed.