NAME

lonsql - LON TCP-MySQL-Server Daemon for handling database requests.


SYNOPSIS

This script should be run as user=www. Note that a lonsql.pid file contains the pid of the parent process.


OVERVIEW

The SQL database in LON-CAPA is used for catalog searches against resource metadata only. The authoritative version of the resource metadata is an XML-file on the normal file system (same file name as resource plus ``.meta''). The SQL-database is a cache of these files, and can be reconstructed from the XML files at any time.

The current database is implemented assuming a non-adjustable architecture involving these data fields (specific to each version of a resource).

Purpose within LON-CAPA

LON-CAPA is meant to distribute A LOT of educational content to A LOT of people. It is ineffective to directly rely on contents within the ext2 filesystem to be speedily scanned for on-the-fly searches of content descriptions. (Simply put, it takes a cumbersome amount of time to open, read, analyze, and close thousands of files.)

The solution is to index various data fields that are descriptive of the educational resources on a LON-CAPA server machine in a database. Descriptive data fields are referred to as ``metadata''. The question then arises as to how this metadata is handled in terms of the rest of the LON-CAPA network without burdening client and daemon processes.

The obvious solution, using lonc to send a query to a lond process, doesn't work so well in general as you can see in the following example:

    lonc= loncapa client process    A-lonc= a lonc process on Server A
    lond= loncapa daemon process
                 database command
    A-lonc  --------TCP/IP----------------> B-lond

The problem emerges that A-lonc and B-lond are kept waiting for the MySQL server to ``do its stuff'', or in other words, perform the conceivably sophisticated, data-intensive, time-sucking database transaction. By tying up a lonc and lond process, this significantly cripples the capabilities of LON-CAPA servers.

The solution is to offload the work onto another process, and use lonc and lond just for requests and notifications of completed processing:

                database command
  A-lonc  ---------TCP/IP-----------------> B-lond =====> B-lonsql
         <---------------------------------/                |
           "ok, I'll get back to you..."                    |
                                                            |
                                                            /
  A-lond  <-------------------------------  B-lonc   <======
           "Guess what? I have the result!"

Of course, depending on success or failure, the messages may vary, but the principle remains the same where a separate pool of children processes (lonsql's) handle the MySQL database manipulations.

Thus, lonc and lond spend effectively no time waiting on results from the database.


Internals

Global Variables
dbh
Variables required for forking
$MAX_CLIENTS_PER_CHILD
The number of clients each child should process.

%children
The keys to %children are the current child process IDs

$children
The current number of children

Main body of code.
Read data from loncapa_apache.conf and loncapa.conf.
Ensure we can access the database.
Determine if there are other instances of lonsql running.
Read the hosts file.
Create a socket for lonsql.
Fork once and dissociate from parent.
Write PID to disk.
Prefork children and maintain the population of children.
&make_new_child
Inputs: None

Returns: None

&do_sql_query
Runs an sql metadata table query.

Inputs: $query, $custom, $customshow

Returns: A string containing escaped results.

&logthis
Inputs: $message, the message to log

Returns: nothing

Writes $message to the logfile.

&subreply
Sends a command to a server. Called only by &reply.

Inputs: $cmd,$server

Returns: The results of the message or 'con_lost' on error.

&reply
Sends a command to a server.

Inputs: $cmd,$server

Returns: The results of the message or 'con_lost' on error.

&escape
Escape special characters in a string.

Inputs: string to escape

Returns: The input string with special characters escaped.

&unescape
Unescape special characters in a string.

Inputs: string to unescape

Returns: The input string with special characters unescaped.

&ishome
Determine if the current machine is the home server for a user. The determination is made by checking the filesystem for the users information.

Inputs: $author

Returns: 0 - this is not the authors home server, 1 - this is.

&propath
Inputs: user name, user domain

Returns: The full path to the users directory.

&courselog
Inputs: $path, $command

Returns: unescaped string of values.

&userlog
Inputs: $path, $command

Returns: unescaped string of values.

Functions required for forking
REAPER
REAPER takes care of dead children.

HUNTSMAN
Signal handler for SIGINT.

HUPSMAN
Signal handler for SIGHUP

DISCONNECT
Disconnects from database.