For building scalable and high-performance Web based applications, ASP.NET provides a feature called data caching. Data caching enables programmatic storing of frequently accessed data objects in memory. This feature can be extended to vastly improve performance for ASP.NET applications that query data stored in an Oracle database. This article describes a strategy for caching Oracle database data in ASP.NET Web applications deployed using a Web Farm environment. This technique enables caching of frequently accessed Oracle database data in memory rather than making frequent database calls to retrieve the data. This helps to avoid unnecessary roundtrips to the Oracle database server. Further the article proposes an implementation for maintaining the cached data so it is always in sync with the corresponding data in the Oracle database.

Data Caching in ASP.NET

Data Caching in ASP.NET is facilitated via the Cache class and the CacheDependency class in the System.Web.Caching namespace. The Cache class provides methods for inserting data and retrieving data from the cache. The CacheDependency class enables dependencies to be specified for the data items placed in the cache. An expiration policy for an item can be specified when we add it to the cache using the Insert method or Add method. We can define the life span for an item in the cache by using the absoluteExpiration parameter in the Insert method. This parameter allows one to specify the exact datetime that the corresponding data item will expire. One can also use the slidingExpiration parameter, specifying the elapsed time before the item will expire based on the time it was accessed. Once the item expires, it is removed from the cache. Attempts to access it will return a null value unless the item is added to the Cache again.

Specifying Dependencies for Cache

ASP.NET allows us to define the dependency of a cached item based on an external file, a directory, or another cached item. These are described as file dependencies and key dependencies. If a dependency changes, the cached item gets automatically invalidated and removed from the cache. We can use this approach to delete items from the cache when the corresponding data source changes. For example, if we write an application that retrieves data from an XML file and displays it in a grid, we can store the data from the file in the Cache and specify a Cache dependency on the XML file. When the XML file is updated, the data item gets removed from the cache. When this event occurs, the application reads the XML file again, and the latest copy of the data item is inserted into the cache again. Further, callback event handlers can be specified as a listener for getting notified when the cache item gets deleted from the cache. This eliminates the need to continuously poll the cache to determine whether the data item has been invalidated.

ASP.NET Cache Dependency on Oracle Database

Let us consider a scenario where data is stored in the Oracle database and accessed by an ASP.NET application using ADO.NET. Furthermore, let us assume that the data in the database table(s) is generally static but accessed frequently by the Web application. In a nutshell, there are very few DML operations on the table but lots of Selects on the data. Such a scenario is ideal for data caching. But unfortunately, ASP.NET does not allow a dependency to be specified whereby a cache item is dependent on data stored in a database table. Furthermore, in real world Web based systems, the Web server and the Oracle database server could be potentially running on different machines, making this cache invalidation process more challenging. Also most Web-based applications are deployed using Web farms with instances of the same application running on multiple Web servers for load balancing. This scenario makes the database caching problem slightly more complex.

For exploring the solution to the above problem, let's put together a sample Web application to illustrate how it can be implemented. For our example, we use ASP.NET application implemented in VB .Net communicating with the Oracle 9i database using Oracle Data Provider for .NET (ODP).

In this example, consider a table named Employee in the Oracle database. We define a trigger for insert, update and delete operations on the Employee table. This trigger calls a PL/SQL function that serves as a wrapper for a Java stored procedure. This Java stored procedure in turn will be responsible for updating the Cache dependency file.

ASP.NET Tier Implementation Using VB.NET

On the ASP.NET tier, we have a listener class containing a callback method to handle the notification when the cache item gets invalidated.

The callback method RemovedCallback is registered by using a delegate function. The callback method onRemove declaration must have the same signature as the CacheItemRemovedCallback delegate declaration.

    Dim onRemove As CacheItemRemovedCallback = Nothing

       onRemove = New CacheItemRemovedCallback(AddressOf RemovedCallback)

The definition for the listener event handler method RemovedCallback responsible for handling the notification from the database trigger is illustrated below. When the cache item gets invalidated, data is retrieved from the database by using the database method call getRecordFromdatabase(). The parameter "key" refers to the index location for the item removed from the cache. The parameter "value" refers to the data object removed from the cache. The parameter "CacheItemRemovedReason" specifies the reason causing the data item to be removed from the cache.

PublicSub RemovedCallback(ByVal key AsString, ByVal value AsObject,

                                                 ByVal reason As CacheItemRemovedReason)

        Dim Source As DataView

        Source = getRecordFromdatabase()

        Cache.Insert("employeeTable ", Source, New

              System.Web.Caching.CacheDependency("d:\download\tblemployee.txt"),

              Cache.NoAbsoluteExpiration, Cache.NoSlidingExpiration,

              CacheItemPriority.Normal, onRemove)

EndSub

The method getRecordFromdatabase() is responsible for querying the database table Employee and it returns a DataView object reference. It makes use of a stored procedure called getEmployee to abstract the SQL for retrieving the data from the Employee table. The method expects a parameter called p_empid representing the primary key for the Employee table.

PublicFunction getRecordFromdatabase (ByVal p_empid As Int32) As DataView

            Dim con As OracleConnection = Nothing

            Dim cmd As OracleCommand = Nothing

            Dim ds As DataSet = Nothing

            Try

                con = getDatabaseConnection(

                              "UserId=scott;Password=tiger;Data Source=testingdb;")

                cmd = New OracleCommand("Administrator.getEmployee", con)

                cmd.CommandType = CommandType.StoredProcedure

                cmd.Parameters.Add(New OracleParameter("employeeId",

                        OracleDbType.Int64)).Value = p_empid

                Dim param AsNew OracleParameter("RC1", OracleDbType.RefCursor)

                cmd.Parameters.Add(param).Direction = ParameterDirection.Output

                Dim myCommand AsNew OracleDataAdapter(cmd)

                ds = New DataSet

                myCommand.Fill(ds)

                Dim table As DataTable = ds.Tables(0)

                Dim index As Int32 = table.Rows.Count

                Return ds.Tables(0).DefaultView

            Catch ex As Exception

                ThrowNew Exception("Exception in Database Tier Method

                                getRecordFromdatabase () " + ex.Message, ex)

            Finally

                Try

                    cmd.Dispose()

                Catch ex As Exception

                Finally

                    cmd = Nothing

                EndTry

                Try

                    con.Close()

                Catch ex As Exception

                Finally

                    con = Nothing

                EndTry

            EndTry

        EndFunction

The function getDatabaseConnection accepts a connectionstring as an argument and returns an OracleConnection object reference.

PublicFunction getDatabaseConnection(ByVal strconnection as string) As

                    OracleConnection

            Dim con As Oracle.DataAccess.Client.OracleConnection = Nothing

            Try

                con = New Oracle.DataAccess.Client.OracleConnection

                con.ConnectionString = strconnection

                con.Open()

                Return con

            Catch ex As Exception

                    ThrowNew Exception("Exception in Database Tier Method

                                   getOracleConnection() " + ex.Message, ex)

            EndTry

 EndFunction

Oracle Database Tier Implementation

The Trigger body defined for DML events on the Employee Table is shown below. This trigger simply invokes a PL/SQL wrapper function for updating an operating system file called tblemployee.txt. Copies of this file are updated on two different machines called machine1 and machine2 that are running different instances of the same Web application to enable load balancing. Here administrator refers to the owner of the schema objects in the Oracle database.

begin

   administrator.plfile('machine1\\download\\ tblemployee.txt');

   administrator.plfile('machine2\\download\\ tblemployee.txt');

end;

For updating the cache dependency file, we will need to write a C function or a Java stored procedure. In our example, we chose a Java stored procedure since Oracle database server has a built-in JVM, making it easy to write Java stored procedures. Adequate memory must be allocated for the Java Pool in the System global area (SGA) of the Oracle instance. The static method updateFile accepts an absolute pathname as a parameter and creates the cache dependency file in the appropriate directory. If the file already exists, it is deleted and created again.

import java.io.*;

public class UpdFile {

  public static void updateFile(String filename) {

    try {

    File f = new File(filename);

    f.delete();

     f.createNewFile();

   }

   catch (IOException e)

   {

            // log exception

    }

  }

};

The pl/sql wrapper implementation is shown below. The wrapper function accepts the filename as a parameter and invokes the method updateFile in the Java stored procedure.

(p_filename  IN  VARCHAR2)

AS LANGUAGE JAVA

NAME 'UpdFile.updateFile (java.lang.String)';

Database Caching in a Web Farm Deployment

As illustrated in the example we have discussed, Web Servers machine1 and machine2 constitute the Web farm to provide load balancing for our Web application. Each machine runs an instance of the same Web application. In this scenario, each instance of the Web application can have its own copy of the cached data stored in its Cache object. When the employee table changes, the corresponding database trigger updates the file tblemployee.txt on both of these machines. Each instance of the Web application specifies a cache dependency on the local file tblemployee.txt, and the cache for both the instances in the Web Farm gets updated correctly, enabling the data cache on both the instances to remain in sync with the database table Employee.

Conclusion

Data Caching can be an effective technique for optimizing ASP.NET applications using the Oracle database. Although ASP.NET does not allow database dependency to be specified for the cache, Oracle triggers in conjunction with Java stored procedures can be used to extend the power of the ASP.NET cache to enable Oracle database caching. This technique can also be applied to Web Farm deployments.

Narayan Veeramani

In this recipe, I discuss all the code necessary to use Ajax to go from a simple Web page to a JavaScript function to an XMLHttpRequest to a PHP script and, finally, to an Oracle database. Along with the code, I do talk about the individual pieces with respect to the whole picture: what each chunk does and why it's important. By reading this HowTo, you will acquire not only some sample code but also, hopefully, a broader understanding of the whole Ajax concept.

Background

The example I'll be working with will be a registration form (or a minimal part of it, anyway). The theory is that I must confirm unique email addresses in the users table so that people cannot register multiple times using the same address. This is normally part of the validation process that comes after the user submits the form to the handling PHP script. But why should the user have to wait until then for this piece of validation? Instead, as soon as the user enters their email address and goes to the next form field, the email address will be immediately validated. But to do so, I still need to query the database, which is where Ajax comes in.

The simplified table structure for this example could be created with the following SQL statement (without the presence of the other tables, I've done away with identifying keys and such).

CREATE TABLE users (
	email VARCHAR2(60)
)

Obviously you could expand on this in many ways. For now, though, the important thing is that the sample code assumes you have established such a table and can connect to it from a PHP script. Some records must be in this table for the example to fully function, so you should populate it like so:

INSERT INTO users (email) VALUES ('this@that.com')
INSERT INTO users (email) VALUES ('me@school.edu')
INSERT INTO users (email) VALUES ('fake@address.net')

After you've created and populated the table, you can begin coding. As I mentioned, there are two scripts involved. To develop and test everything, you will:

1. Create the PHP script that queries the Oracle database.
2. Manually test the PHP script to see how it works.
3. Write the JavaScript code that interacts with the PHP script.
4. Make the HTML form that ties into the JavaScript.
5. Test the entire process.

Step 1: Programming the Database Query

The entire PHP script is called ajax.php. (See sample code zip.) The purpose of this script is to run a query in Oracle and print a message based upon the results of the query. This is all very basic Oracle, SQL, and PHP, but I'll run through it to clarify what's happening.

The script expects to receive an email address in the URL, which is available in the variable $_GET['email']. Then the script connects to the Oracle database. The query itself counts how many records in the users table have that email address:

SELECT COUNT(*) AS NUM_ROWS FROM users WHERE email='{$_GET['email']}'

This should return either 0 or 1 (or nothing at all). The query is executed in Oracle and the results are bound to the PHP $rows variable. Now $rows represents how many records in the database have that email address. With respect to Ajax, the important part of the script is shown below.

if ($rows > 0) {
	echo 'Email address has already been registered!';
} else {
	echo 'Email address is available!';
}

One of those two messages will be printed, based upon the value of $rows. That's all there is to this page! Absolutely no HTML is needed as this script won't be used like a standard Web page.

If you want to improve this script, you can confirm that the email address matches a regular expression pattern for email addresses. If so, execute the query like normal; if not, echo a statement saying that it's not a valid email address. At the very least, you'd likely want to prevent SQL injection attacks. (I.e., avoid using the $_GET variable in your query without some assurances of its validity.)

Step 2: Testing the PHP Script

Because this entire Ajax process involves several technologies—HTML, JavaScript, PHP, SQL, and Oracle—you'll be best off testing each piece as you go. If you don't, you can easily get lost trying to find where a problem exists. Testing this PHP script should be fairly easy:

1. Make sure you've created the table in Oracle and populated it.
2. Edit ajax.php so that it uses valid connection parameters for your Oracle installation.
3. Save the script as ajax.php.
4. Place it in the proper directory for your Web server.
5. Go to http://yoururl/ajax.php?email=X in your Web browser.

In place of X, use one of the email addresses that's already in the database (e.g., http://yoururl/ajax.php?email=this@that.com). You should see the "Email address has already been registered!" message. Then use an email address that has not been stored. You should see the "Email address is available!" text. Once you have that working, you can move on to the actual Ajax aspect of this example.

Step 3: Programming the JavaScript

This section of the process is probably the most difficult unless you've done tons of JavaScript already. In any case, the JavaScript code is the heart of the Ajax process, as it performs and handles the request from the PHP page. I'll go through this code in detail.

The JavaScript code will define three functions. The first creates a request object variable:

function createRequestObject() {
	var ro;
	if (navigator.appName == "Microsoft Internet Explorer") {
		ro = new ActiveXObject("Microsoft.XMLHTTP");
	} else {
		ro = new XMLHttpRequest();
	}
	return ro;
}

You should be able to use this code for any Ajax application without modification. If the Web browser being used is Microsoft Internet Explorer, then the ro variable is initialized as an ActiveXObject of type Microsoft.XMLHTTP. For all other browsers, ro is a straightforward XMLHttpRequest type of object. That's really nothing else to it. The ro variable is now an object with all the necessary functionality to perform an asynchronous request. After creating the request object variable, this function then returns it.

This function is immediately called by the JavaScript code when the page is first loaded:

var http = createRequestObject();

Now http represents the object and is globally available in the other functions.

Next up is the function that calls the PHP script:

function sendRequest(email) {
	http.open('get', 'ajax.php?email=' + encodeURIComponent(email));
	http.onreadystatechange = handleResponse;
	http.send(null);
}

This function takes one argument, which is the email address to be verified. Then it opens a connection to the PHP script. As the first argument in the open() method indicates, the request will be of type get, as opposed to post. The email address is appended to the URL, resulting in a page request like ajax.php?email=this@that.com. As you already know, this is how the PHP script is properly called. The encodeURIComponent() function just encodes the submitted value to make it URL-safe. The third line within the function tells the object what JavaScript function to call after the request has been made. The final line actually makes the request.

To recap, the first function, createRequestObject(), makes the object variable that's needed. The second function, sendRequest(), makes the actual request of the PHP script. Now we need a function that handles that request:

function handleResponse() {
	if (http.readyState == 4) {
		document.getElementById('email_label').innerHTML = http.responseText;
	}
}

The previous function told the request object to call this function after the request has been made. This function first checks that the request was successfully made. If so, then http.readyState will be equal to 4. It could also be equal to 0 through 3 (you can search online for their actual meanings, if you care), but being equal to 4 means the request worked. The results of the request will be stored in the http.responseText attribute, the results being either of the two messages echoed by the PHP script. To be clear, if the request worked, then http.responseText will either be "Email address has already been registered!" or "Email address is available!".

At this point, the JavaScript knows what the result of the PHP script was. All you need to do is get the JavaScript to notify the user of that result. An easy option would be to use an alert() box:

alert(http.responseText);

If you put this within the conditional, you'll see the result when you test the whole application. (In fact, alert() is a great debugging tool to confirm what's going on in your JavaScript code.) However, I find these alerts to be annoying as an end user and would rather print the message next to the form's email input. To do so, I refer to the DOM (Document Object Model). Specifically, I assign the http.responseText to an element in my page called email_label. You'll see this in Step 4.

Whew! Hopefully you followed all that. To repeat, this is the most important and most complex part of this sequence. The JavaScript uses three functions to do three things: define a browser-specific request object; make a request to the PHP script; and, do something with the results of the request. If you're confused by any of this, or when it comes time to make a more complex Ajax application, you'll likely want to do a little research on JavaScript and DOM.

Step 4: Making a JavaScript-functional HTML Form

As I wrote previously, the premise behind this example is a registration form that takes, at the least, an email address. The minimal form would be:

<form action="somepage.php" method="post">
Email Address: <input name="email" type="text" size="30" maxlength="60" /><br />
First Name: <input name="first_name" type="text" size="20" maxlength="20" /><br />
(Rest of the form...)
</form>

That's it! Well, not quite. You'd want more inputs (a "submit" button, and so on). But for the purposes of this example, that's all you need. To avoid confusion, note that the action and method attributes here have nothing to do with the ajax.php script (which doesn't handle this form's submission).

Two more things are required, though. First, this form must somehow call the JavaScript code that makes the request. You could use several tricks to do that: make a clickable link, wait for the submit button to be clicked, and so on. I've decided that once the user has entered an email address and has gone on to the next form element, the JavaScript should be called. This requires the onchange() method, which I'll add to the email input:

Email Address: <input name="email" type="text" size="30" maxlength="60"

onchange="sendRequest(this.form.email.value)" />

As soon as the user changes the value in this input, including entering anything for the first time, and then tabs or clicks to another input, the JavaScript sendRequest() function will be called. It is fed one argument, the value of the email form input. If you look back at the JavaScript code, you can see how the value typed here gets sent to that function, which in turn is sent to the PHP script.

The second thing the HTML form needs is a place where JavaScript can "write" the received message so that it's visible to the user. As the handleResponse() function dictates, that message will be assigned to the innerHTML of an element called email_label. For this I add a span with that ID after the email address input:

<span id="email_label"></span>

That's it for tying the HTML form to the JavaScript. (See Listing 1 in the sample code zip for the final code.) Now it's time to see how it works!

Step 5: Testing the Ajax Process

Having completed the HTML and JavaScript, you should save that as ajax.html (or anything, really), then place it in the same directory as the PHP script. Load the form by running it in your Web browser, through a URL, not by opening it from the file system (i.e, go to http://yoururl/ajax.html). Type an unused email address in the proper input, then tab or click on the next input. Repeat using a stored email address.

The two screenshots below show the results you should see. Absolute magic!

Conclusion

In this article you've seen how you can easily implement an Ajax process using PHP and Oracle. By doing so, server side validation is being accomplished within the client (although you should still keep server side validation as well, in case JavaScript is disabled). This particular example, in my opinion, demonstrates a nice feature for an end user, saving them from having to:

• Submit the form
• See that the email address has already been registered
• Return to the form
• Repeat

Also, I think this example and the concept in general is kind of cool. And on the Web, that's not an insignificant factor.

Of course, there's tons more you can do with Ajax, PHP, and Oracle. The example in this article sent only one piece of data to the PHP script and retrieved just a string. You can send much more back and forth. If you have a significant amount of data to be returned to the calling page, you can have PHP return it in XML format, then use JavaScript to parse and display it. If you search online, you'll find many different examples.

Larry Ullman

In this article, I'll explain the basic yet essential processes involved in building a .NET application that uses an Oracle database, including:

• How to add project references to support Oracle class libraries in your .NET project
• How to create Oracle Database connection strings
• How to work with Connection, Command, and DataReader objects

You will have the opportunity to apply what you have learned in three practice labs, ranging in difficulty from the relatively simple to the more complex. The article's screenshots are taken from Visual Studio 2008, but the experience is very similar in Visual Studio 2005.

For information and labs about how to secure your application, see my article "Securing a .NET Application on the Oracle Database". (Also, see the OTN .NET Developer Center for technical articles covering a range of Oracle.NET application lifecycle issues.)

Note that the free Oracle Developer Tools for Visual Studio, available for download from OTN, provides a Visual Studio add-in that makes the development of .NET apps on Oracle much easier and more intuitive. That subject is beyond our scope here, however.

.NET Data Provider

In addition to basic Oracle client connectivity software, .NET applications require the use of what is known as a managed data provider (where "managed" refers to code managed by the .NET framework). The data provider is the layer between the .NET application code and the Oracle client connectivity software. In almost every case, the best performance is achieved by using a provider optimized for a specific database platform instead of the generic .NET OLE DB data provider.

Oracle, Microsoft, and third-party vendors all offer .NET data providers optimized for Oracle. Oracle and Microsoft make their Oracle data providers available for free. (Microsoft's provider for the .NET Framework 2.0 is included in the framework, but it still requires Oracle client software installation.) In this article, we will use of the Oracle Data Provider for .NET (ODP.NET), which is included with the Oracle Database or as a separate download.

ODP.NET provides standard ADO.NET data access, while exposing Oracle database-specific features, such as XML DB, data access performance optimizations, and Real Application Clusters connection pooling.

When ODP.NET and Oracle client software are installed, application development using Visual Studio can begin. It's a good idea to confirm client connectivity before starting development. If you can connect to Oracle using Oracle client software such as SQL*Plus on the same machine as Visual Studio, then you know that your Oracle client-side software is properly installed and configured.

If you are new to Oracle, see the section "Installing .NET Products" in the Oracle Database 2 Day Developer's Guide for background information regarding installing and configuring ODP.NET specifically, or to the Oracle Database Documentation Library for general information about Oracle Database.

Creating a Project in Visual Studio 2005 or 2008

Let's create an ODP.NET application that retrieves data from an Oracle database. Later, we'll see how to perform error handling with ODP.NET and handle an additional data retrieval scenario.

After starting Visual Studio, the first task is to create a project. You can either select File | New | Project as shown below or click the New Project button located directly under File.

A New Project dialog box appears. On the left side of the dialog box under Project Types, select the programming language of your choice. In our example, "Visual Basic" was chosen. On the right side under Visual Studio installed templates, choose a project template. To keep things simple, a "Windows Forms Application" is selected.

You'll want to specify meaningful names for the project name (we used OraWinApp) and the solution name (we used OraWinApp). A solution contains one or more projects. When a solution contains only one project, many people use the same name for both.

Adding a Reference

Because our project must connect to an Oracle database, it is necessary to add a reference to the ODP.NET DLL containing the data provider of our choice. Within the Solution Explorer, select the project name, right click and select Add Reference. Alternatively, you can go to the menu bar and select Project and then select Add Reference.

The Add Reference dialog box appears.

ODP.NET is found under the Oracle.DataAccess component name. Select Oracle.DataAccess from the list, then click OK to make the ODP.NET data provider known to your project.

Visual Basic/C# Statements

After adding references, it is standard practice to add Visual Basic Imports statements or C# using statements. Technically, these statements are not required but they do allow you to refer to database objects without using lengthy, fully qualified names.

By convention, these statements appear at or near the top of a code file, before the namespace or class declaration.

Imports Oracle.DataAccess.Client ' Visual Basic ODP.NET Oracle managed provider

using Oracle.DataAccess.Client; // C# ODP.NET Oracle managed provider

If you added the reference, Intellisense will help you complete the addition of an Imports or using statement as shown in Figure 5.

Connection Strings and Objects

An Oracle connection string is inseparable from Oracle names resolution. Suppose you had a database alias of OraDb defined in a tnsnames.ora file as follows:

OraDb=
  (DESCRIPTION=
    (ADDRESS_LIST=
      (ADDRESS=(PROTOCOL=TCP)(HOST=ORASRVR)(PORT=1521))
    )
    (CONNECT_DATA=
      (SERVER=DEDICATED)
      (SERVICE_NAME=ORCL)
    )
  )

The OraDb alias defines the database address connection information for the client. To use the OraDb alias defined in the tnsnames.ora file shown above, you would use the following syntax:

Dim oradb As String = "Data Source=OraDb;User Id=scott;Password=tiger;" ' Visual Basic

string oradb = "Data Source=OraDb;User Id=scott;Password=tiger;"; // C#

You can modify the connection string to obviate the need for the tnsnames.ora file, however. Simply replace the name of the alias with how it would be defined in a tnsnames.ora file.

' Visual Basic
Dim oradb As String = "Data Source=(DESCRIPTION=" _
           + "(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=ORASRVR)(PORT=1521)))" _
           + "(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=ORCL)));" _
           + "User Id=scott;Password=tiger;"

// C#
string oradb = "Data Source=(DESCRIPTION="
             + "(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=ORASRVR)(PORT=1521)))"
             + "(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=ORCL)));"
             + "User Id=scott;Password=tiger;";

As you can see above, the username and password are embedded in the connection string in clear text. This is the simplest approach to creating a connection string. However, the clear text approach is undesirable from a security perspective. In particular, you must understand that compiled .NET application code is only marginally more secure than the clear text source code files. It is very easy to decompile .NET DLL and EXE files and view the original clear text contents. (Encryption is in fact the appropriate solution, but that subject would be a quite lengthy digression from our discussion here.)

Next, you must instantiate a connection object from the connection class. The connection string must be associated with the connection object.

Dim conn As New OracleConnection(oradb) ' Visual Basic

OracleConnection conn = new OracleConnection(oradb); // C#

Notice that the connection string is associated with the connection object by being passed through the object's constructor, which is overloaded. The constructor's other overload allows the following alternative syntax:

Dim conn As New OracleConnection() ' Visual Basic
conn.ConnectionString = oradb

OracleConnection conn = new OracleConnection(); // C#
conn.ConnectionString = oradb;

After associating a connection string with a connection object, use the Open method to make the actual connection.

conn.Open() ' Visual Basic

conn.Open(); // C#

We'll cover error handling later.

Command Object

The Command object is used to specify the SQL command text that is executed, either a SQL string or a stored procedure. Similar to the Connection object, it must be instantiated from its class and it has an overloaded constructor. In this sample, ODP.NET will perform a SQL query to return the department name (DNAME) from the departments table (DEPT) where the department number (DEPTNO) is 10.

Dim sql As String = "select dname from dept where deptno = 10" ' Visual Basic
Dim cmd As New OracleCommand(sql, conn)
cmd.CommandType = CommandType.Text

string sql = "select dname from dept where deptno = 10"; // C#
OracleCommand cmd = new OracleCommand(sql, conn);
cmd.CommandType = CommandType.Text;

Using different overloads, the syntax can be structured slightly differently. The Command object has methods for executing the command text, which will be seen in the next section. Different methods are appropriate for different types of SQL commands.

Retrieving a Scalar Value

Retrieving data from the database can be accomplished by instantiating an OracleDataReader object and using the ExecuteReader method, which returns an OracleDataReader object. Returned data is accessible by passing either the column name or zero-based column ordinal to the OracleDataReader.

Dim dr As OracleDataReader = cmd.ExecuteReader() ' Visual Basic
dr.Read()

Label1.Text = dr.Item("dname") ' retrieve by column name
Label1.Text = dr.Item(0) ' retrieve the first column in the select list
Label1.Text = dr.GetString(0) ' return a .NET data type
Label1.Text = dr.GetOracleString(0) ' return an Oracle data type

There are typed accessors for returning .NET native data types and others for returning native Oracle data types, all of which are available in C#, Visual Basic, or any other .NET language. Zero-based ordinals are passed to the accessors to specify which column to return.

OracleDataReader dr = cmd.ExecuteReader(); // C#
dr.Read();

label1.Text = dr["dname"].ToString(); // C# retrieve by column name
label1.Text = dr.GetString(0).ToString();  // return a .NET data type
label1.Text = dr.GetOracleString(0).ToString();  // return an Oracle data type

In this simplified example, the returned value of DNAME is a string and is used to set the value of the label control's text property, which is also a string. But if DEPTNO, which is not a string, had been retrieved instead, there would be a data type mismatch. The .NET runtime attempts to implicitly convert from one data type to another when the source and destination data types don't match. Sometimes the data types are incompatible and the implicit conversion fails, throwing an exception. But even when it works, it's still better to use explicit data type conversions instead of implicit data type conversion.

An explicit cast to integer is shown below:

Label1.Text = CStr(dr.Item("deptno")) ' Visual Basic integer to string cast

C# is not as forgiving as Visual Basic on implicit conversions. You'll find yourself doing explicit conversions: 

label1.Text = dr.GetInt16("deptno").ToString(); // C#

You can explicitly cast scalar values as well as arrays.

Close and Dispose

Either the connection object's Close or the Dispose method should be called to close the connection to the database. The Dispose method calls the Close method.

conn.Close()   ' Visual Basic
conn.Dispose() ' Visual Basic

conn.Close();   // C#
conn.Dispose(); // C#

You don't have to explicitly call Close or Dispose if you use VB's Using keyword or C#'s using keyword.

using (OracleConnection conn = new OracleConnection(oradb)) // C#
{
    conn.Open();

    OracleCommand cmd = new OracleCommand();
    cmd.Connection = conn;
    cmd.CommandText = "select dname from dept where deptno = 10";
    cmd.CommandType = CommandType.Text;

    OracleDataReader dr = cmd.ExecuteReader();
    dr.Read();

    label1.Text = dr.GetString(0);
}

In addition, OracleCommand includes a Dispose method; OracleDataReader includes a Close and Dispose method. Closing and disposing .NET objects free up system resources, ensuring more efficient application performance, which is especially important under high load conditions. You can experiment with some of the concepts we've learned here in Lab 1 (Retrieving Data from the Database) and Lab 2 (Adding Interactivity).

Error Handling

When an error occurs, .NET applications should gracefully handle the error and inform the user with a meaningful message. Try-Catch-Finally structured error handling is a part of .NET languages; here is a relatively minimalist example of using the Try-Catch-Finally syntax:

' Visual Basic
Try
    conn.Open()

    Dim cmd As New OracleCommand
    cmd.Connection = conn
    cmd.CommandText = "select dname from dept where deptno = " + TextBox1.Text
    cmd.CommandType = CommandType.Text

    If dr.Read() Then
        Label1.Text = dr.Item("dname") ' or use dr.Item(0)
    End If
Catch ex As Exception ' catches any error
    MessageBox.Show(ex.Message.ToString())
Finally
    ' In a real application, put cleanup code here.
End Try

// C#
try
{
    conn.Open();

    OracleCommand cmd = new OracleCommand();
    cmd.Connection = conn;
    cmd.CommandText = "select dname from dept where deptno = " + textBox1.Text;
    cmd.CommandType = CommandType.Text;

    if (dr.Read()) // C#
    {
        label1.Text = dr["dname"].ToString();
                   // or use dr.GetOracleString(0).ToString()
    }
}
catch (Exception ex) // catches any error
{
    MessageBox.Show(ex.Message.ToString());
}
finally
{
    // In a real application, put cleanup code here.
}

Although this approach will gracefully capture any errors in attempting to get data from the database, it is not user friendly. For example, look at the following message displayed when the database is unavailable:

An ORA-12545 is quite meaningful for an Oracle DBA or developer, but not for an end user. A better solution is to add an additional Catch statement to trap for the most common database errors and provide user-friendly messages.

Catch ex As OracleException ' catches only Oracle errors
    Select Case ex.Number
        Case 1
            MessageBox.Show("Error attempting to insert duplicate data.")
        Case 12545
            MessageBox.Show("The database is unavailable.")
        Case Else
            MessageBox.Show("Database error: " + ex.Message.ToString())
    End Select
Catch ex As Exception ' catches any error
    MessageBox.Show(ex.Message.ToString())

catch (OracleException ex) // catches only Oracle errors
{
    switch (ex.Number)
    {
        case 1:
            MessageBox.Show("Error attempting to insert duplicate data.");
            break;
        case 12545:
            MessageBox.Show("The database is unavailable.");
            break;
        default:
            MessageBox.Show("Database error: " + ex.Message.ToString());
            break;
    }
}
catch (Exception ex) // catches any error not previously caught
{
    MessageBox.Show(ex.Message.ToString());
}

Notice the two Catch statements in the code sample above. If there aren't any Oracle errors to catch, the first statement branch is skipped, leaving any other non-Oracle error to be caught by the second statement. Catch statements must be ordered in the code from most specific to most general. After implementing the user-friendly exception handling code, the ORA-12545 error message appears as follows:

The Finally code block is always executed regardless of whether or not an error occurred. It is where cleanup code belongs. If you don't use Using or using, you should dispose your connection and other objects in the Finally code block.

Retrieving Multiple Values Using a DataReader

So far our examples have only showed how to retrieve a single value. An OracleDataReader can retrieve values for multiple columns and multiple rows. First consider a multiple column, single row query:

select deptno, dname, loc from dept where deptno = 10

To obtain the values of the columns, either zero-based ordinals or column names can be used. Ordinals are relative to the order in the query. Thus, the LOC column's value can be retrieved in Visual Basic by using either dr.Item(2) or dr.Item("loc").

Here is a code snippet that concatenates the DNAME and LOC columns from the previous query:

Label1.Text = "The " + dr.Item("dname") + " department is in " + dr.Item("loc") ' VB

label1.Text = "The " + dr["dname"].ToString() + " department is in " +
              dr["loc"].ToString();  // C#

Now consider a query that returns multiple rows:

select deptno, dname, loc from dept

To process multiple rows returned from an OracleDataReader, some type of looping construct is needed. Furthermore, a control that can display multiple rows is desirable. An OracleDataReader is a forward-only, read-only cursor, so it can't be bound to an updateable or fully scrollable control such as a Windows Forms DataGrid control. An OracleDataReader is compatible with a ListBox control, as the following code snippet illustrates:

While dr.Read() ' Visual Basic
   ListBox1.Items.Add("The " + dr.Item("dname") + " department is in " + dr.Item("loc"))
End While

while (dr.Read()) // C#
{
    listBox1.Items.Add("The " + dr["dname"].ToString() + " department is in " +
                       dr["loc"].ToString());
}

Lab 3 (Retrieve Multiple Columns and Rows with an OracleDataReader) highlights some of these concepts.

Building and Running on x64

When running Visual Studio 2008 on an x64 operating system, the Active solution platform defaults to Any CPU. Change that to x86 before building your project.

Conclusion

This article has introduced you to the process of accessing Oracle databases using .NET programming languages. You should now have the capability to connect to the database and retrieve multiple columns and rows.

John Paul Cook

Oracle Streams Advanced Queuing provides database-integrated message queuing functionality. Because Oracle Streams Advanced Queuing is implemented in database tables, queue data enjoys the Oracle Database benefits of high availability, scalability, and reliability.

Oracle Data Provider for .NET (ODP.NET), Oracle’s ADO.NET-compliant data provider, includes Oracle Streams Advanced Queuing classes to expose the messaging capabilities of Oracle Streams Advanced Queuing. Oracle Developer Tools for Visual Studio, a plug-in for Microsoft Visual Studio 2008 and Visual Studio 2005, includes administration tools that assist with tasks such as creating and modifying queues and queue tables.

This article guides you through creating a set of .NET applications that make up a stock ticker system that demonstrates many Oracle Streams Advanced Queuing features. You will first create a queue in Oracle Database that holds stock ticker symbols and the corresponding stock prices. Every time a stock price changes, it will be loaded onto this queue by the StockQueueLoader application that you create next. You will also create the StockTickerListener application that receives notifications whenever a new stock price arrives in the queue and then retrieves the stock information and displays it on a ticker screen. StockTickerListener can receive notifications for all stocks that are loaded in the queue, but the queue can also be configured with rules specifying that StockTickerListener receives notifications only when specific stocks and, optionally, price ranges for specific stocks are loaded in the queue. To make it easy for a user to dynamically modify these rules, you will also run a helper application called StockQueueSubscriberAdmin.

Setup

To follow along with the steps in this article, you will need the following:

• SYSDBA privileges for Oracle Database Release 9.2 or later, which may be required to grant some of the Oracle Streams Advanced Queuing privileges
• Microsoft Visual Studio 2008 or Visual Studio 2005
• Oracle Developer Tools for Visual Studio and Oracle Data Provider for .NET Release 11.1.7.10 or later

Before you build the sample applications, you will create connections to Oracle Database from Visual Studio and grant the appropriate privileges to enable the use of queuing.

To connect to Oracle Database from Visual Studio, create a new connection in Data Connections, the top-level node of Server Explorer. (If Server Explorer is not yet visible, select View -> Server Explorer from the main menu.)

Right-click Data Connections, and select Add Connection. In the dialog box that appears, confirm that Oracle Database (Oracle ODP.NET) appears in the Data source field. If you do not see Oracle Database (Oracle ODP.NET), click the Change button and select Oracle Data Provider for .NET from the list of providers. Select the database you want to connect to from the Datasource name list. Click Use a specific user name and password. In the User name field, enter SYS. In the Password field, enter the password for SYS, and ensure that Role is set to SYSDBA. Click Test connection to verify that you can connect, and click OK to complete the connection setup.

To create and modify queues and queue tables and to enqueue and dequeue from them, you need the EXECUTE privilege on the DBMS_AQ and DBMS_AQADM PL/SQL packages. (If you wanted to modify queues you did not create, you would also require privileges on the AQ_ADMINISTRATOR_ROLE role.) You will grant the required privileges, using the Grant/Revoke Privilege dialog box in Visual Studio.

Right-click the SYS connection node, and choose Privileges from the context menu. In the Grant/Revoke Privileges dialog box that appears, set Object Type to Package. Leave Schema set to SYS. Click the first radio button, labeled Grant/Revoke privileges to a user/role on one or more database object(s). Hold down the Ctrl key, and in the Object Names list, highlight both DBMS_AQ and DBMS_AQADM. From the User/Role list, select User and choose HR or some other username. In the list of privileges, in the Grant column, check the check box next to the EXECUTE privilege. Click OK to accept the changes, and close the dialog box.

Now connect to Oracle Database as HR (or whichever user you just granted the Oracle Streams Advanced Queuing package privileges). In Server Explorer, right-click Data Connections and select Add Connection. Follow the same steps to connect as HR that you used to connect as SYS, except to set Role to Default.

Creating the STOCK User-Defined Type

Oracle Database queues typically hold objects of a single type (unless they are defined as ANYTYPE queues) and can be an XMLType, a user-defined type (UDT), or a RAW type. For more information on Oracle Streams Advanced Queuing queue types, including the benefits and limitations of each, see the Oracle Streams Advanced Queuing User’s Guide.

The queue for this article will be made up of a user-defined type called STOCK, whose definition will include a stock symbol name as well as the price of the stock. (For a deep dive into Oracle user-defined types with Visual Studio and .NET, see “It Takes All Types” in the May/June 2008 issue of Oracle Magazine).

To create the user-defined type, in Server Explorer, under the HR data connection, right-click the User Defined Types node and choose New Object Type from the menu. This will launch Object Designer. In the Type name field, enter STOCK. Click the Add button to add an attribute, and in the Attribute Properties Name field, enter SYMBOL. From the Type list, choose VARCHAR2. Click the Add button again to add another attribute. In the Name field for this new attribute, enter PRICE and choose NUMBER from the Type list. Click OK to create the type. The type will now be visible in Server Explorer under the User Defined Types node and will also be available in datatype lists in various Oracle designers, such as Queue Designer.

Creating the Queue and the Queue Table

Next, create a queue named STOCK_Q and its queue table, STOCK_QTAB. Under the HR data connection node in Server Explorer, expand the Advanced Queues node, which will expose the Queues and Queue Tables collection nodes (see Figure 1). Right-click the Queues node, and select New Queue from the menu. This will launch Queue Designer (see Figure 2).

Figure 1: Server Explorer Advanced Queues and User-Defined Types nodes (left); Queues node context menu (right)

Figure 2: Queue Designer

In the Queue name field, enter STOCK_Q. From the Queue type list, choose Normal Queue. For Payload Type, click the Complex radio button, and then from the list next to it, choose the STOCK user-defined type.

Click the Queue Table tab in the lower half of the designer. In the Queue Table area, click the New radio button and enter STOCK_QTAB as the name of the queue table. Leave the rest of the default settings as they are. (The most important settings are the Multi-Consumer and Secure check boxes, which must be checked, because multiple stock ticker applications can be run at the same time and all of them will need access to the contents of the queue.)

Still in the Queue Designer, click the Subscribers tab. Click the grid in the lower half of the designer, which will cause SUBSCRIBER1 to be entered for Consumer Name. Leave the Rule field blank. Click a new line in the grid to create another subscriber entry. Change the name of this one from SUBSCRIBER2 to DEFAULT. Leave the rule for this subscriber entry blank.

Click Save to create the queue and the queue table. The STOCK_Q queue and the STOCK_QTAB queue table will now be visible in Server Explorer (see Figure 1). The designer automatically starts the queue after creating it.

Note that an exception queue named AQ$_STOCK_QTAB_E has been automatically created for you and that the exceptions will be stored in the STOCK_QTAB queue table. Oracle Streams Advanced Queuing exceptions are generated in a variety of circumstances, such as when a message expires before it is dequeued. For more information on Oracle Streams Advanced Queuing exceptions, see Oracle Streams Advanced Queuing User’s Guide.

Building the StockQueueLoader Application

With the queue and the queue table created, you will now build the StockQueueLoader application that generates fictional stock price fluctuations in a fantasy stock market consisting of 10 ticker symbols and loads these stock prices (using a STOCK user-defined type) into the STOCK_Q queue you just created. (In a real-world scenario, actual stock price updates could be obtained via Web services and then inserted into an Oracle queue.)

(Note that all of the applications created and used in this article—StockQueueLoader, StockTickerListener, and QueueSubscriberAdmin—are available prebuilt in the article’s application download.)

To begin construction of the queue loader application (StockQueueLoader), choose File -> New -> Project from the main menu. In the dialog box that appears, under Project type Visual C#, choose Windows, and then on the right side of the dialog box, choose the Console Application template. In the Name field, enter StockQueueLoader.

In the newly opened project, go to Solution Explorer; right-click the ConsoleApplication project; and from the menu, choose Add Reference. On the .NET tab in the Add Reference dialog box, scroll down until you see the Oracle.DataAccess assembly. You may see multiple versions, but select version 2.111.7.10—the version in which Oracle Streams Advanced Queuing support was first introduced—or later.

Next, download the sample applications at otn.oracle.com/oramag/oracle/09-nov/o69odt.zip, unzip the file, and copy the contents of the AQ_ORAMAG\CodeListings\aqloader.txt file on top of the default template code. (Excerpts of the new code appear in Listing 1.) Notice that the key ODP.NET classes being used are OracleAQQueue and OracleAQMessage. Furthermore, note that the payload for the OracleAQMessage class is another .NET class called STOCK. STOCK is the .NET custom class for the STOCK Oracle user-defined type. (Custom classes enable .NET code to pass user-defined type values to and from Oracle Database.)

Code Listing 1: StockQueueLoader application code excerpt

OracleAQQueue queue = new OracleAQQueue("HR.STOCK_Q", con);
queue.MessageType = OracleAQMessageType.Udt;
queue.EnqueueOptions.Visibility = OracleAQVisibilityMode.Immediate;
OracleAQMessage enqMsg = new OracleAQMessage();

Console.WriteLine("Connected to Oracle.... Will start enqueuing in 10 seconds");
System.Threading.Thread.Sleep(10000);

string[] symbols = new string[10] { "ORCL", "MSFT", "INTC", "CSCO", "ADBE", "GOOG", "AAPL", "AMZN", "EBAY", "JAVA" };

double[] prices = new double[10] { 19.5, 19, 18.25, 15, 24, 383.25, 121, 79.75, 15, 9 };

Random rand = new Random();
while (true)
{
    for (int i = 0; i < 10; i++)
    {
        //...code to randomly increase or decrease prices[i] goes here
        }

        //We don't want multiple copies of the same stock on the queue
        //at the same time, so the message will expire after 5 seconds
        enqMsg.Expiration = 5;

        enqMsg.SenderId = new OracleAQAgent("QUEUELOADER");
        enqMsg.Payload = new STOCK(symbols[i], (decimal)prices[i]);
        queue.Enqueue(enqMsg);

Now generate the STOCK custom class from the STOCK user-defined type, by using a wizard. To start the wizard, in Server Explorer, under the HR data connection, expand the User-Defined Types node (see Figure 1). Find and right-click the STOCK node. From the menu, choose Generate Custom Class. In the wizard, click Next to move past the splash screen. In the next screen, uncheck the Inherit from Project check box, directly above the Namespace field. Then change Namespace to Stock, click Next until you get to the final screen, and click the Finish button. This will generate a Stock.cs file and place it in your project.

Now add the following constructor to the Stock class, below the automatically generated constructors:

public STOCK(string sym, decimal pr)
{
   SYMBOL = sym;
   PRICE = pr;
}

Finally, build the application, by selecting Build from the Visual Studio main menu and then selecting Rebuild Solution. Run the application, by choosing Debug from the main menu, and then select Run Without Debugging.

As you see messages appear in the console indicating that stock prices are being loaded into the queue, you can inspect the STOCK_QTAB table in Oracle Database to see these values being added there. In Server Explorer, under the HR data connection, expand the Tables node and double-click the STOCK_QTAB node to open the data window. If you right-click the data window and choose Refresh from the context menu, you can watch this queue table grow and notice that after five seconds, each entry in this table is replaced with an advanced queuing exception. Because the StockQueueLoader .NET code sets an expiration of five seconds for each item loaded into the queue, these exceptions indicate that the item was not dequeued before this expiration.

Building the StockTickerListener Application

Consumer applications have several options for finding out if there is something in a queue they are interested in. They can poll a queue by inspecting it from time to time to see if there is a message they need; they can listen to the queue with a dedicated thread; or they can register a callback, a subroutine that gets called and is passed a notification when a message that meets certain criteria is put into the queue.

There are various ways a consumer application can choose whether a message is of interest. Messages can be addressed to specific recipients or recipient groups. Messages can also be assigned correlations, which are ad hoc identifiers assigned by the producing applications. Messages also have priorities for filtering. Finally, messages can be inspected via rules, which are essentially WHERE clauses added to SELECT statements that query against the queue.

A consumer application can specify an interest in certain messages in a queue by becoming a subscriber. Each subscriber can define a named rule. You will now build an application—StockTickerListener—that receives callbacks whenever stock prices appear in the queue that match a subscriber rule. These stock prices will be output to a window much like a stock ticker.

To build the StockTickerListener application, in a new instance of Visual Studio, first create a new console application, including an Oracle.DataAccess reference (in the same way you did in the previous section). Now add the Stock.cs custom class file (from the StockQueueLoader application) to your new project, by right-clicking the new project name in Solution Explorer, choosing Add an Existing Item, and then browsing to the file. Visual Studio will then make a local copy of that file in your project, saving you the trouble of re-creating it.

Code Listing 2: StockTickerListener application code excerpt

OracleAQQueue queue = new OracleAQQueue("HR.STOCK_Q", con);
queue.MessageType = OracleAQMessageType.Udt;
queue.NotificationConsumers = new string[1] { "SUBSCRIBER1" };

queue.MessageAvailable +=
  new OracleAQMessageAvailableEventHandler(QueueCallback.MsgReceived);
.....

static void MsgReceived(object src, OracleAQMessageAvailableEventArgs arg)
{
    try
    {
        Console.WriteLine("Notification Received...");
        byte[] notifiedMsgId = arg.MessageId[0];

        OracleConnection con = new OracleConnection(constr);
        con.Open();

        // Prepare to dequeue message by its MessageID
        OracleAQQueue queue = new OracleAQQueue("HR.STOCK_Q", con);
        queue.MessageType = OracleAQMessageType.Udt;
        queue.UdtTypeName = "HR.STOCK";
        queue.DequeueOptions.MessageId = notifiedMsgId;
        queue.DequeueOptions.ConsumerName = "SUBSCRIBER1"; 

        queue.DequeueOptions.DequeueMode = OracleAQDequeueMode.Browse;

        //Dequeue
        OracleAQMessage deqMsg = queue.Dequeue();
        STOCK st = (deqMsg.Payload as STOCK);

        Console.WriteLine(st.SYMBOL + ": " + st.PRICE);

From the sample applications you downloaded earlier, copy the contents of the AQ_ORAMAG\CodeListings\stocktickerlistener.txt file on top of the console template code. (Excerpts of this code appear in Listing 2.) The main part of the code contains two key methods. The first is

queue.NotificationConsumers

which is set to SUBSCRIBER1. This indicates that callbacks should be received only when the SUBSCRIBER1 subscription rules are satisfied. The second key method is

queue.MessageAvailable += new
OracleAQMessageAvailableEventHandler
(QueueCallback.MsgReceived);

This registers the MsgReceived method as a callback.

In the code for the MsgReceived callback, note that the advanced queuing AQ MessageID is included as part of the arguments that are passed to the method. This ID is set to

queue.DequeueOptions.MessageId

to specify the message you want. Finally,

queue.DequeueOptions.DequeueMode = OracleAQDequeueMode.Browse

indicates that the message should not be removed from the queue after viewing, because other client applications may need to view that stock.

Build this application, by selecting Build from the Visual Studio main menu and then selecting Rebuild Solution. Run the application, by choosing Debug from the main menu, and then select Run Without Debugging.

Now go back to the earlier instance of Visual Studio, rerun the StockQueueLoader application, and place both console application windows side by side. You should see the StockTickerListener application display every stock price that is loaded by the StockQueueLoader application (see Figure 3). This is because SUBSCRIBER1’s rule is currently set to null. Because these rules are essentially WHERE clauses in a query over the queue contents, a null rule means that every item on the queue will be included. Keep both applications running while you move on to the next section.

Figure 3: StockQueueLoader (top) and StockTickerListener (bottom)

Modifying a SUBSCRIBER Rule at Runtime

Earlier, you saw a subscriber rule in the Queue Designer in Visual Studio. This rule selects specific STOCK user-defined type stock symbols and enables users to specify a range of stock prices in which they are interested. Now you will run a helper application that makes it easier to change this rule at runtime while the stock ticker application is running.

The download provided with this article includes a Windows Forms application called StockQueueSubscriberAdmin.This application presents a user interface (see Figure 4) that includes a list of stock symbols; an optional field for providing a stock price; and a list of conditions that enables the user to set up a subscriber rule for receiving stock prices that are less than, greater than, or equal to the provided value.

Figure 4: StockQueueSubscriberAdmin user interface

Run the StockQueueSubscriberAdmin application. Select the ORCL symbol from the stock list, and click Add to Rule. In the text box, you will see

tab.user_data.SYMBOL=''ORCL''

This rule will cause your stock ticker to receive notifications only when ORCL stock values are placed in the queue. Next, select the JAVA symbol from the list and enter 3 in the Price field. Choose > (greater than) from the Condition list. Click Add to Rule. Now the text box contains

tab.user_data.SYMBOL=''ORCL'' OR
(tab.user_data.SYMBOL=''JAVA'' AND
tab.user_data.PRICE>3)

This rule will cause your stock ticker to receive notifications when all ORCL stock prices as well as any JAVA prices above $3 are loaded into the queue.

Finally, click Alter Subscription!. This will execute the DBMS_AQADM.ALTER_SUBSCRIBER procedure and pass the rule you have created. (The code that calls this procedure is shown in Listing 3.) To see the new rule, in Server Explorer right-click the STOCK_Q node, choose Design Queue, and then click the Subscribers tab.

Code Listing 3: StockQueueSubscriber

private void button2_Click_1(object sender, EventArgs e)
{
//Executes DBMS_AQADM.ALTER_SUBSCRIBER to modify the SUBSCRIBER1 subscription
string conString = "User Id=hr;Password=hr;Data Source=;";
OracleConnection con = new OracleConnection();
con.ConnectionString = conString;
con.Open();

OracleCommand cmd = con.CreateCommand();

string cmdtxt = "DECLARE " +
    "SUBSCRIBER SYS.AQ$_AGENT; " +
    "BEGIN " +
    @"SUBSCRIBER := SYS.AQ$_AGENT('""SUBSCRIBER1""', NULL, 0); " +
    "DBMS_AQADM.ALTER_SUBSCRIBER(" +
    @"queue_name => '""STOCK_Q""'," +
    "subscriber => SUBSCRIBER," +
    "rule => '" + textBox2.Text +"'," +
    "transformation => ''" +
    "); " +
    "END;";

OracleCommandBuilder oc = new OracleCommandBuilder();
cmd.CommandText = cmdtxt;

//Execute batched statement
cmd.ExecuteNonQuery();
}

If both of the earlier applications are still running, you should notice that your stock ticker application is now displaying only ORCL and JAVA ticker symbols. Each time the rule is modified, your running stock ticker will immediately reflect the change.

Now go back to the Queue Subscription GUI application, click Clear Rule, and click Alter Subscription!. This will set the rule to null. Watch as the stock ticker immediately resumes displaying all the stock symbols that are loaded into the queue.

Summary

This article showed you how you can leverage Oracle Streams Advanced Queuing database-integrated messaging from .NET applications. You loaded a queue from one application, subscribed to that queue from another application, and received callback notifications based on subscription rules you modified by using the DBMS_AQADM package.

Christian Shay

This article is for developers working with Ruby on Rails applications on an Oracle database, with special attention to those having a live application that needs to be optimized. You will learn which options tweak the parameters that handle the connection to the database for the Oracle adapter to boost the application performance, as well as get a useful plugin to track down the query execution plans for live applications. You'll build a simple set of models and look at various typical queries on them, exploring how you can improve their efficiency.

Setup

The prerequisite to follow this article is having Ruby on Rails installed and configured properly to connect with an Oracle database. "The Ruby on Rails with Oracle FAQ" by Casimir Saternos explains the process in detail. (It's quite easy.)

All the examples for this article have been written and tested on a Windows XP machine running Instant Rails 1.5 preview 1 connecting to Oracle Database 10g Express Edition (XE) installed on Debian Linux.

For the remainder of this article I will make examples based on a Rails "version" of the HR schema that has been modified to directly comply with the common Rail conventions (as opposed to using the standard HR schema from a Rails application, explained in Saternos' "HR Schema On Rails"). This choice has been dictated by the wish to show the behavior of a standard Rails application on an Oracle database without being distracted by the specifics of handling a separate schema to map the HR schema into the Rails conventions. (Which is indeed a very clever way to handle legacy schemas!)

In the sample code file you will find the complete migrations for the schema and a (yml format) dump of the data which can be used to load them using the Active Record fixtures plugin, which is also included. (The db/db_loading.rb file does the data import and can be executed using script/runner).

The six tables are populated by the very same data that the regular HR schema holds, while they have some columns modified. (E.g., all of them now use the common Rails convention of having one id column as their primary key.)

The models also define some relations among them; you can see the full code for the models in the sample code file:

class Country < ActiveRecord::Base
    belongs_to :region
    has_many  :locations
end

class Department < ActiveRecord::Base
    belongs_to :manager, :class_name => "Employee", :foreign_key => "manager_id"
    belongs_to :location
    has_many :employees
end

class Employee < ActiveRecord::Base
    belongs_to :department
    belongs_to :manager, :class_name => "Employee", :foreign_key => "manager_id"
    belongs_to :job
    belongs_to :department
    has_many :managed_employees, :class_name => "Employee", :foreign_key => "manager_id"
end

class Job < ActiveRecord::Base
  has_many :employees
end

class Location < ActiveRecord::Base
  belongs_to :country
  has_many :department
end

class Region < ActiveRecord::Base
	 has_many :country
end

All our tests will be done simply by connection with the Rails console and interactively querying the database through the model methods as we would do from within our controllers:

C:\Progetti\ArticoliROR\Oracle\project> ruby script\console
Loading development environment.
>>

Part 1: Of configuration, Cursors, and Rows

Basic Configuration

So, you have already configured all the required prerequisites for running Rails on an Oracle database, and bootstrapping your Rails application is just a matter of opening a prompt window (terminal, xterm, or whatever) and typing:

rails myapp

This will reward you with a skeleton application that is ready to hold your code (models, views, controller and tests). You will need to customize the config/database.yml file telling the framework basic information for each one of the databases that Rails uses.

Each entry is identified with a key that tells the system if the specific information is to be used while developing the application, while running the tests or when running the application in production mode. You could even define other database connections beyond the standard three and use them from your Rails application, but this subject goes beyond the scope of this article.

Having separate database settings means that you may modify the values in the development or testing database and conduct your tests and measures without touching the production database.

Here is an example of the basic configuration:

development:
  adapter: oracle
  host: DEBIAN
  username: rails
  password: rails

The adapter parameter specify that we are connecting with an Oracle database and selects the OracleAdapter (see: activerecord/lib/active_record/connection_adapters/oracle_adapter.rb ). Older Rails releases used the 'oci' value to identify the oracle adapter, and this value can still be used.

With the host parameter you specify the database to which you want to connect. If you have configured TNS entry for your database:

DEBIAN =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = 10.211.55.7)(PORT = 1521))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = XE)
    )
  )

you may use its name for the host parameter; otherwise, you can use the Easy Connect naming convention to address the Oracle instance (host: //10.211.55.7:1521/XE).

The username and password are the credentials you want to use for your application. All the objects (tables, sequences) needed by the application should be accessible from this user and anything built thorough the database migrations will be built into this user's schema (at least this is the default behavior).

Models and SQL Queries

Now we will look at some of the queries that are generated by ActiveRecord, and this is made simple by the fact that while in development mode Rails writes all the queries it is performing to the log file. In this manner you can familiarize yourself with the behavior of the framework and gain greater confidence in what the tool will do.

I find that having a deeper understanding of how the framework code is going to translate your high level requests into actual SQL is a required step when working with powerful frameworks that make complex interactions with the data. You will gain a better understanding of the Rails idioms that should be used and how to write more efficient code.

One of the most common ways to get the model data is looking up an object by its id:

emp = Employee.find(202)

will get you the employee record with id = 202. Looking at the development.log we will see the queries that are getting executed:

Employee Columns (0.120000)
 select column_name as name, data_type as sql_type, data_default, nullable,
  decode(data_type, 'NUMBER', data_precision,
  'FLOAT', data_precision,
  'VARCHAR2', data_length,
 null) as limit,
 decode(data_type, 'NUMBER', data_scale, null) as scale
 from all_tab_columns
 where owner = 'RAILS'
 and table_name = 'EMPLOYEES'
 order by column_id

Employee Load (0.070000)  SELECT * FROM employees WHERE (employees.id = 202)

The first query is executed once the first time a model class is loaded to pull the columns from the employee table allowing the system to dynamically generate the required methods for the model based on the database structure. (This is one of those features that make Rails development really quick!) Be warned that while doing your activity and running the server in development mode you will see this query repeated many times as the models get reloaded on each browser request. This makes the server slower but allows you to get the updates to the database structures without restarting the server.

The second query gets the data from the employees table for the employee whose id is 202.

Other examples of the models may be the following (all presented with the actual query executed on the database):

Given an employee, get its department manager.

mgr = emp.department.manager

SELECT * FROM departments WHERE (departments.id = 20)
SELECT * FROM employees WHERE (employees.id = 201)

Given an employee, get all the colleagues at the same department.

emps = emp.department.employees

SELECT * FROM employees WHERE (employees.department_id = 20) 

mgr.managed_employees

SELECT * FROM employees WHERE (employees.manager_id = 201) 

You may use the include option to pull down in a single query from the server also objects which have some relation with our entity:

emp = Employee.find(202, :include=>[:department,:manager])
emp.department
emp.manager

SELECT employees.id AS t0_r0, employees.commission AS t0_r1, employees.job_id AS t0_r2,
employees.manager_id AS t0_r3,employees.salary AS t0_r4, employees.hire_date AS t0_r5,
employees.phone_number AS t0_r6, employees.department_id AS t0_r7,
employees.first_name AS t0_r8, employees.last_name AS t0_r9, employees.email AS t0_r10,
departments.id AS t1_r0, departments.name AS t1_r1, departments.manager_id AS t1_r2,
departments.location_id AS t1_r3, managers_employees.id AS t2_r0,
managers_employees.commission AS t2_r1, managers_employees.job_id AS t2_r2,
managers_employees.manager_id AS t2_r3, managers_employees.salary AS t2_r4,
managers_employees.hire_date AS t2_r5, managers_employees.phone_number AS t2_r6,
managers_employees.department_id AS t2_r7, managers_employees.first_name AS t2_r8,
managers_employees.last_name AS t2_r9,
managers_employees.email AS t2_r10 FROM employees LEFT OUTER JOIN departments
  ON departments.id = employees.department_id LEFT OUTER JOIN employees managers_employees
  ON managers_employees.id = employees.manager_id WHERE (employees.id = 202)

This is really handy and efficient when working with objects behaving as containers for sets of other items as it avoids going to the database with a query for each and every row you want to manipulate.

Here's another example:

job = Job.find(id,:include=>:employees)
job.employees

SELECT jobs.id AS t0_r0, jobs.job_title AS t0_r1, jobs.min_salary AS t0_r2,
jobs.max_salary AS t0_r3, employees.id AS t1_r0, employees.commission AS t1_r1,
employees.job_id AS t1_r2, employees.manager_id AS t1_r3, employees.salary AS t1_r4,
employees.hire_date AS t1_r5, employees.phone_number AS t1_r6,
employees.department_id AS t1_r7, employees.first_name AS t1_r8,
employees.last_name AS t1_r9, employees.email AS t1_r10 FROM jobs LEFT OUTER JOIN employees
  ON employees.job_id = jobs.id WHERE (jobs.id = 7)

One of the points of this article is to show you the new configuration parameters introduced with the release 1.2 of Rails that may help in tuning the database-related performance of your application, but before going deeper into it let me explain how currently Rails builds the actual SQL used.

Bind Variables and Cursor Sharing

ActiveRecord uses its (dynamically built) knowledge of the models and database to create queries on the fly. It even builds many methods of the models themselves in this way allowing the developer to write things like:

Employee.find_by_first_name_and_last_name('Steven','King')

but it does so by building the SQL query as a string and doing parameter interpolation before sending the query to the adapter for execution (without using bind variables). SQL injection and security problems are attacked at the adapter level by quoting the values on SQL interpolation but the performance hit remains, and it also impacts the scalability of any Rails application running on Oracle. To understand how this impacts performance and scalability, let me explain what happens when a query is executed.

When a query is first executed Oracle performs a hard parse step which verifies that it is syntactically correct and that all the objects (tables, columns, …) being accessed really exist. If the checks pass, a new entry is created in the library cache with the parse results that may be reused for subsequent executions. The key to the library cache is the SQL text for the query itself, therefore two queries that have any literal difference are considered different for the purposes of parsing.

When a new query is executed, a hash lookup into the library cache is done to see if the query had been already parsed. If the query is found then the cached parse result is used and the hard parse step is avoided, moreover no new entries are added to the library cache. A way to minimize hard parses is to always use bind parameters.

Within the context of a pre-1.2 Rails application, without any specific database tuning this means that each time a different query is executed (even if it differs just for the parameter values), the statement is hard parsed by the database engine and a new query entry is inserted in the library cache.

You can verify what happens by looking at the v$sql view where the sql_text column holds the actual SQL used for the queries: each row in v$sql corresponds to an entry in the library cache. We may use the following query to get all the queries generated by our application (limiting ourselves to the queries that hit one of the 6 tables):

select sql_text from v$sql
where (    lower(sql_text) like '%employee%'
        or lower(sql_text) like '%countries%'
        or lower(sql_text) like '%departments%'
        or lower(sql_text) like '%jobs%'
        or lower(sql_text) like '%locations%'
        or lower(sql_text) like '%regions%'
      )
and   not lower(sql_text) like '%v$sql%'
order by sql_text
If we do the following:
(1..200).each do |id|
	Employee.find(id) rescue nil
end

which tries to get each Employee with id between 1 and 200. You'd end up with the following in v$sql:

SQL_TEXT
--------------------------------------------------------------------------------
SELECT * FROM employees WHERE (employees.id = 1)
SELECT * FROM employees WHERE (employees.id = 10)
SELECT * FROM employees WHERE (employees.id = 100)
SELECT * FROM employees WHERE (employees.id = 101)
...

This is not an advisable behavior from an application expected to scale, especially for the common patterns of use where you may expect many queries using the primary key (e.g. accessing to the user table for login purposes or for configuration data).

Work is under way to provide Rails with proper handling of bind variables, or at least to let ActiveRecord adapters themselves do the binding of parameters within the query. In the meantime the best option is to use the ability to handle query rewriting built into the database.

A specific configuration offered by Oracle comes to the rescue here. The CURSOR_SHARING database parameter changes the way the database behaves doing hard and soft parses in presence of queries that are not using bind parameters. The parameter can be set to exact, similar, or force (and the latter can be set databasewide or on a specific session).

• exact is the default value where the database behaves as outlined above.
• force tells the database to rewrite all the queries substituting the literals in the SQL text with bind parameters (e.g. :"SYS_B_0") resulting in one parsed entry for each query.
• similar rewrites the query but also looks at the effect of such rewrite and generates different entries in library cache for queries that would end up using different execution plans—that is, if substituting the literal with a bind parameter would end up in a different plan being executed then the replacement is not done.

Before Rails 1.2, to change the cursor sharing setting you'd need to change it for the entire database instance or patch the ActiveRecord adapter. From the last major release an adapter configuration parameter has been added to do just that.

The cursor_sharing setting can be used in database.yml to choose the preferred value without messing with the global database parameters (thus being better citizens in an heterogeneous environment where other applications may require different settings).

development:
  adapter: oracle
  host: DEBIAN
  username: rails
  password: rails
  cursor_sharing: similar

Its value is used straight in an alter session statement upon establishing a connection (in OracleConnectionFactory.new_connection):

conn.exec "alter session set cursor_sharing = #{cursor_sharing}" rescue nil

Moreover the default value has been chosen to be similar, which means that without needing to add cursor_sharing to the parameters you get a reasonable behavior: the queries are changed according to the plan that would be used depending on the values.

If you redo the query above you'll see this in v$sql:

SELECT * FROM employees WHERE (employees.id = :"SYS_B_0")
just one library cache entry for any Employee.find(id) call.

To see the impact of similar vs. force, update the table to have some skewed data:

Employee.find(:all).each do |emp|
	emp.salary = 3000 unless emp.id == 100
	emp.save
end

You updated all the records to have a salary of 3,000 except for the one whose id equals 100. Now you can add an index to the employee table from within the Rails project by generating a migration:

C:\Progetti\ArticoliROR\Oracle\project>ruby script/generate migration AddIndexes
      exists  db/migrate
      create  db/migrate/007_add_indexes.rb

In the generated file you should have

class AddIndexes < ActiveRecord::Migration
  def self.up
    add_index :employees, :salary, :name=>:idx_emp_salary
   end

  def self.down
    remove_index :employees, :name=>:idx_emp_salary
  end
end
then we do a rake db:migrate from the command line. Now if we do:
Employee.find(:all, :conditions=>["salary = ?", 24000])
Employee.find(:all, :conditions=>["salary = ?", 3000])

You'll find two parsed entries in v$sql:

SELECT * FROM employees WHERE (salary = :"SYS_B_0")
SELECT * FROM employees WHERE (salary = :"SYS_B_0")

This is because the two queries generated would use two different plans depending on the salary value. (In the first case the index would be used while in the second case a full table scan would result being the best plan.) Using force cursor sharing would tell the database to use to the same parsed entry for both queries which is not what we want in this case, even if it meant having only one cache entry.

Having a configuration available for this from Rails, let's tune its value on a per-application case, depending also on which kind of data you have and on which patterns of use you are seeing for your application.

A second parameter added to Rails 1.2, which may help in tuning the application, is the prefetch_rows configuration. This allows setting the OCI_ATTR_PREFETCH_ROWS connection parameter, which specifies the amount of rows to be pre-fetched from the database on each round trip. It can give a great performance boost in all cases where you want to fetch many rows.

Typical patterns are iterations over a set of entities like in:

Employee.find(:all, :conditions=>"salary < 5000")

In these cases rows pre-fetching means fewer hits to the database, while the cost is more memory used by the adapter—which is not a problem anyway if you want to process all the rows returned by the query.

The default value is set to 100 which has been identified by the Oracle adapter contributors to be ideal in a range of test cases, but more than for cursor_sharing the prefetch value needs to be tweaked by benchmarking with the real data-sets and queries used in the application. For custom tuning this parameter is set in database.yml as usual:

development:
  adapter: oracle
  host: DEBIAN
  username: rails
  password: rails
  prefetch_rows: 100
  

Part 2: Execution plans and Indexes

What Rails Cannot Do

While Rails goes great lengths toward reducing the burden of development through a clever use of conventions and design pattern implementation, there are situations where it cannot have the required knowledge to make the decisions for the developer. Thus, the Rails developer should not forget that he or she is building a database-backed application, nor which database he or she is developing for.

While most of the coding is doable in a fairly database independent way a good understanding of how a database works is required if you want to get the best performance out of your applications.

Knowing how your database works is useful while developing the data model and while building the queries, but it is much more important when deciding which indexes you need on your tables. This is something that the framework cannot do and does not even attempt to do, as it would depend on:

• the specific database that is used (as it might have or not have some capability when it comes to creating and using indexes)
• the data that is present in the tables (as they influence the query execution plan and which indexes are used)
• the specific application (as the actual queries used may access the data in unpredictable ways based on usage patterns)

Moreover these factors influence each other and any optimization will depend on all of them collectively. In his blog post "Indexing for DB Performance", Jamis Buck gives some tips on the kind of indexes that might be needed:

• foreign keys (has_one, belongs_to, has_many, … relations)
• non-index fields that are frequently queried upon (e.g. login names)
• columns where you sort of do calculations frequently
• sets of columns that are used as conditions together

Each index adds some overhead as it needs to be updated on data insert and update, so you should not add indexes for every column (or combination of them). Rather you should make informed choices starting with some reasonable set of indexes, modifying them as the application evolves over time, taking into account the actual data and usage patterns.

Explain Plan. In an Oracle context, this means using the explain plan command to understand how queries are executed. It gives the developer a way to optimize the query itself and to eventually add indexes.

You should always try to optimize the query first and only afterward go on to add the indexes.

Rails makes it rather easy to use custom queries instead of a regular one with the handy find_by_sql method of ActiveRecord. Note however that in the find_by_sql call you could simply pass the text of the SQL query, but you should really confirm that you use the parameter substitution form, passing an array with the query and the list of parameters. This way you can use the parameter quoting that is in the database adapter and you make sure that you will use real bind variables in future when ActiveRecord supports them without the need to modify your code.

Query_Analyzer Plugin. While looking for bottlenecks in your application it is important that you get to know which queries are executed. The Rails log files can be really useful here, as the application while running in development mode logs all the actual queries. They might be collected and examined one by one to find the queries and generate the execution plans. This can become tedious work. The query_analyzer plugin helps relieve the burden by dumping the explain plan output in the log file. You can get an Oracle compatible release here; it was originally developed by Bob Silva for MySQL. To install it just unzip the archive contents in the vendor/plugins directory on your Rails project.

To allow the plugin to work in Oracle the database user will need to be given enough privileges on the data dictionary tables that are queried on loading the model. The following statement will do it:

GRANT SELECT ANY DICTIONARY TO < database user >;

The plugin monkey patches the database adapter to add the explain plan for each query that is executed by the adapter while running at a logging level below INFO. The plan is formatted and printed at the debug level to the default logger. This default behavior makes sure that the plan is not executed while running on the production environment.

Two parameters are available to modify the default behavior; both can be modified within the environment setup files: The plan_table_name parameter can be used to specify the name of the plan table and its default is the standard PLAN_TABLE; the plan_details parameter can be used to specify which details should be printed by the explain plan statement. Possible values are:

• BASIC: displays minimum information
• TYPICAL: displays most relevant information (default value)
• SERIAL: like TYPICAL but without parallel information
• ALL: displays all information

If you execute a common query:

Employee.find(101)

it will dump the following data to the development.log file:

Employee Load (0.000000)  explain plan for SELECT * FROM employees WHERE (employees.id = 101)
Analyzing Employee Load
  plan_table_output
   -------------------------------------------------------------------------------------------
   Plan hash value: 1171009080                                                                

   -------------------------------------------------------------------------------------------
   | Id  | Operation                   | Name        | Rows  | Bytes | Cost (%CPU)| Time     |
   -------------------------------------------------------------------------------------------
   |   0 | SELECT STATEMENT            |             |     1 |   719 |     2   (0)| 00:00:01 |
   |   1 |  TABLE ACCESS BY INDEX ROWID| EMPLOYEES   |     1 |   719 |     2   (0)| 00:00:01 |
   |*  2 |   INDEX UNIQUE SCAN         | SYS_C004026 |     1 |       |     1   (0)| 00:00:01 |
   -------------------------------------------------------------------------------------------

   Predicate Information (identified by operation id):
   ---------------------------------------------------                                        

      2 - access("EMPLOYEES"."ID"=101)

Note that the query uses a unique index related to the primary key for the table; in this case, nothing needs to be done.

Leaving the plugin active (setting a debug level of informations) allows you to collect the plan table outputs for all queries while running the application.

The plan table outputs a lot of information on the queries. You can quickly spot the tables that may need a new index by searching for 'TABLE ACCESS FULL' in the log file.

Employee Load (0.010000)  explain plan for SELECT * FROM employees WHERE (first_name = 'Stephen')
Analyzing Employee Load
  plan_table_output
   -------------------------------------------------------------------------------
   Plan hash value: 1445457117                                                    

   -------------------------------------------------------------------------------
   | Id  | Operation         | Name      | Rows  | Bytes | Cost (%CPU)| Time     |
   -------------------------------------------------------------------------------
   |   0 | SELECT STATEMENT  |           |     1 |   719 |     3   (0)| 00:00:01 |
   |*  1 |  TABLE ACCESS FULL| EMPLOYEES |     1 |   719 |     3   (0)| 00:00:01 |
   -------------------------------------------------------------------------------

   Predicate Information (identified by operation id):
   ---------------------------------------------------                            

      1 - filter("FIRST_NAME"='Stephen')                                          

   Note
   -----
      - dynamic sampling used for this statement

This is the result of querying all the employees that have first name 'Stephen': Employee.find(:all, :conditions=>["first_name = ?", "Stephen"]).

Note that this query needs to scan the full EMPLOYEES table to get just one row when using a filter on the first_name column. If this kind of query is seen many times through the application, you should consider adding an index. The predicate information for the more costly operations gives you a good hint at what indexes may benefit the query execution—in this case, obviously an index on the first_name column.

Rails Migrations. You can also use Rails Migrations to manage indexes. (See the API docs for more information on what Migrations are and how to use them to manage a database schema.) To add an index use:

add_index table_name, column_names, options = {}

this adds an index on "table_name" for "column_names" where the latter can be a single column or a list of columns:

add_index :departments, :manager_id
add_index :locations, [:city, :postal_code]

Within the options parameter you can specify if the index is to be created as unique:

add_index :locations, [:city, :postal_code, :street_address], :unique => true

or with a given name. (This is useful on Oracle since the default is to use a combination of table name and first column name, which can be too long.)

add_index :locations, [:city, :postal_code], :name => :idx_city_zip

To remove an index just use the remove_index method:

remove_index table_name, options = {}
we can pass as options the column name(s) or the index name:
  remove_index :departments, :manager_id
  remove_index :departments, :column => :manager_id
  remove_index :locations, :column => [:city, :postal_code, :street_address]
  remove_index :locations, :name => :idx_city_zip

If you need to use more complex or database-specific SQL, use the execute command from the up or down methods to which you pass the SQL string to execute:

execute "CREATE INDEX idx_emp_first_name ON employees (first_name)"

In the example above:

C:\Progetti\ArticoliROR\Oracle\project>ruby script/generate migration AddFirstNameIndex
      exists  db/migrate
      create  db/migrate/008_add_first_name_index.rb

This is the migration file:

class AddFirstNameIndex < ActiveRecord::Migration
  def self.up
    add_index :employees, :first_name, :name=>:idx_emp_first_name
   end

  def self.down
    remove_index :employees, :name=>:idx_emp_first_names
  end
end

Run the migration using rake db:migrate.

C:\Progetti\ArticoliROR\Oracle\project>rake db:migrate
(in C:/Progetti/ArticoliROR/Oracle/project)
== AddFirstNameIndex: migrating ===============================================
-- add_index(:employees, :first_name, {:name=>:idx_emp_first_name})
   -> 0.0100s
== AddFirstNameIndex: migrated (0.0100s) ======================================

Executing the query again shows that the index is now used:

Employee Load (0.010000)  explain plan for SELECT * FROM employees WHERE (first_name = 'Stephen')
Analyzing Employee Load
  plan_table_output
   --------------------------------------------------------------------------------------------------
   Plan hash value: 2736374945                                                                       

   --------------------------------------------------------------------------------------------------
   | Id  | Operation                   | Name               | Rows  | Bytes | Cost (%CPU)| Time     |
   --------------------------------------------------------------------------------------------------
   |   0 | SELECT STATEMENT            |                    |     1 |   719 |     2   (0)| 00:00:01 |
   |   1 |  TABLE ACCESS BY INDEX ROWID| EMPLOYEES          |     1 |   719 |     2   (0)| 00:00:01 |
   |*  2 |   INDEX RANGE SCAN          | IDX_EMP_FIRST_NAME |     1 |       |     1   (0)| 00:00:01 |
   --------------------------------------------------------------------------------------------------

   Predicate Information (identified by operation id):
   ---------------------------------------------------                                               

      2 - access("FIRST_NAME"='Stephen')                                                             

   Note
   -----
      - dynamic sampling used for this statement

As you have seen it is really easy to use the plugin to poke at the execution plans used by a running application and you may even leave it installed on the production server and disable/enable it when needed by changing the logging level.

Conclusion

In this article you dug a bit into how connections to an Oracle database are configured in a Rails application, and you have seen how the framework has been updated in the 1.2 release to have better performances thorough the use of the cursor_sharing and prefetch_rows parameters (while waiting for a real bind variable implementation).

You have also examined the Rails migration commands that are relevant to tuning the database (specially creating/removing indexes).

Finally, as you've learned, a good understanding of both how Rails builds the SQL from the code and how the database executes them is needed to get the best performance. The provided plugins should help here.