External Database Drivers

The external driver sends messages to the external database proxy daemon instead of calling database client libraries directly. This database proxy daemon can be a local or remote process. The reason for this seemingly unnecessary indirection is that some database client libraries are undesirable partners in the AOLserver process space. For example, they may make assumptions regarding per-process resources such as signals, or they may not be thread-safe. Also, platforms without support for a particular database client library can still interface with a database via a remote database proxy daemon.

A database proxy daemon is created for each connection in an AOLserver database pool. Like connections within a pool configured for an internal driver, the connections associated with proxy daemons are efficiently managed by the AOLserver on an ad hoc basis. Thus, database proxy daemon processes are created and shut down by the AOLserver as demand for concurrent database handles varies over time.

This distributed approach is not intended to replace the existing practice of linking database client libraries into the server via a driver. It merely provides an alternative interface mechanism--augmenting the choices available to developers who are extending the AOLserver database interface capabilities. It is likely, however, that this distributed approach, i.e. a separate process per database connection, will improve overall database throughput, even with the additional communication overhead. We expect this performance improvement because vendor-supplied database client libraries, running within a multi-threaded server, must limit concurrency via resource locks.

Configuration

Configuration for an external database driver consists of setting parameters for the external driver and creating a database pool that uses that driver. An external driver is configured to spawn and communicate with a database-specific proxy daemon. Database proxy daemons are provided for Sybase.

The following example describes the steps involved in configuring an external driver to interface with the Sybase proxy daemon.

Configure an External Database Driver

1. Edit your AOLserver configuration file, usually named nsd.tcl.

2. Add a configuration file section called ns/db/drivers:

       ns_section "ns/db/drivers"
   

3. List the Sybase database driver. For example:

       ns_section "ns/db/drivers"
       ns_param extsyb nssybpd.so
   

4. Configure the Sybase driver. For example:

       ns_section "ns/db/driver/extsyb"
       ns_param LocalDaemon nssybpd
       ns_param Param SYBASE-env-variable
   

   The Param parameter should be set to the value of the SYBASE environment variable. For a description of the all the parameters, see page 73.

5. Add a configuration file section to list your database pools. For example:

       ns_section "ns/db/pools"
       ns_param mypool "This pool will use Sybase"
   

6. Add a configuration file section to define the database pool you have named. Seepage 75 for a complete list of database pool parameters. For example:

       ns_section "ns/db/pool/mypool"
       ns_param Driver extsyb
   

7. Choose which server or servers is to have access to the database pools you have defined. For each server, add a configuration file section to define which database pools it can access. For example:

       ns_section "ns/server/Server1/db"
       ns_params Pools *
   

   The "*" designation means that this server can access any of the defined database pools. See page 58 for a complete list of parameters for this section.

Remote Database Proxy Daemons

The previous example showed configuration of a local proxy daemon. One of the advantages of the external driver interface is that you are free to run database proxy daemons on any other host, perhaps one on which database vendor client libraries are more readily available or more reliable.

The following example shows how to configure an interface to a proxy daemon on a remote machine.

Configure a Remote External Database Driver

1. Edit your AOLserver configuration file as described in the previous section, "External Database Drivers" section.

2. In the ns/db/drivers/extsyb configuration section, delete the definition for the LocalDaemon parameter.

3. Add definitions for the RemoteHost and RemotePort parameters. For example:

       ns_section "ns/db/driver/extsyb"
       ns_param RemoteHost host-name
       ns_param RemotePort port-number
       ns_param Param SYBASE-env-variable
   

4. Run nssybpd, or configure inetd as shown in the next step instead. For example:

       nssybpd 8199
   

5. As an alternative to running nssybpd as shown in the previous step, you can configure inetd on the target remote machine as follows.
   1. Add the following line to /etc/inet/services:

       nssybpd			8199/tcp	
   

   1. Add the following line to /etc/inet/inetd.conf:

       nssybpd stream tcp nowait sa 
       /serverhome/bin/nssybpd nssybpd
   
   (Type the above all on one line.)
   
   
   

   1. Send a SIGHUP signal to your inetd process.

Tcl Interface

In addition to the built-in, database-driver independent ns_db Tcl functions, the ns_ext function is available for special functions that relate to the external driver mechanism. In general, you will not need to use ns_ext for most database operations. The ns_ext functions are used primarily by the ns_db functions, but ns_ext is provided in the event that you need to call it directly (see page 105 of the AOLserver Tcl Developer's Guide).