Storing sessions in a database is a good solution. Backups are easier; persistence and pruning orphaned sessions are simpler. Security is available through the database server’s security. We will use MySQL, since it is the best supported in newLISP.

Setting up the database

First, we need a table in which to store session data. Using a MySQL TIMESTAMP column will provide us with an automatically updating time stamp on the last modification of the session, which we will use below to find old sessions to remove.

CREATE TABLE sessions (
	sid VARCHAR(255) PRIMARY KEY,
	DATA TEXT NOT NULL,
	ts TIMESTAMP
)

Designing the storage module

Several functions need to be defined to handle storing data. First, we must ensure that the MySQL module is loaded and initialized. We will do this in a separate module that we will call DBSessions.

(context 'DBSessions)
 
(unless (sym "MYSQL" 'MySQL nil) ; do not reinitialize if already loaded
  (module "mysql5.lsp") ; with newlisp 10.1, this will change to "mysql.lsp"
  (MySQL:init)
  (MySQL:connect "127.0.0.1" "user" "secret" "somedb"))
 
(context 'MAIN)

Next, we define a function to create or resume a session from the database. Sessions are stored in memory as contexts, making our job easier. Our function will query MySQL to see if the session id exists, and either create a new session and insert it or retrieve an existing session and load it. The function Web:session-id gives us the current session id from the session cookie or creates a new one and sends the client a cookie to store it. Web:session-context returns a symbol pointed to the context storing the current session.

(define (open-session)
  (when (MySQL:query (format "SELECT data FROM sessions WHERE sid = '%s'" (MySQL:escape (Web:session-id))))
    (let ((data (MySQL:fetch-row)))
      (if data
        ;; Evaluate the serialized context into the current session context
        (eval-string (first data) (Web:session-context))
        ;; Create a new session and save it
        (MySQL:query (format "INSERT INTO sessions (sid, data) VALUES ('%s', '%s')"
          (MySQL:escape (Web:session-id))
          (MySQL:escape (source (Web:session-context)))))))))

Next, we need a function to write any changes to the session to storage. Since the session is stored as a context, this is quite simple.

(define (close-session)
  (MySQL:query (format "UPDATE sessions SET data = '%s' WHERE sid = '%s'"
    (MySQL:escape (source (Web:session-context)))
    (MySQL:escape (Web:session-id)))))

We also need a function to delete entire sessions when necessary. This is also simple.

(define (delete-session)
  (MySQL:query (format "DELETE FROM sessions WHERE sid = '%s'"
    (MySQL:escape (Web:session-id)))))

Finally, a function to cull old sessions from the database. For this, we use the variable Web:SESSION_MAX_AGE to determine which sessions have expired.

(define (clean-sessions)
  (MySQL:query (format "DELETE FROM sessions WHERE NOW() >= DATE_ADD(ts, INTERVAL %d SECOND)"
    Web:SESSION_MAX_AGE)))

Registering the handler in Web

Last, the handler functions need to be registered in the Web module.

(Web:define-session-handlers
  open-session close-session delete-session clean-sessions)

Putting it all together

(unless (sym "MYSQL" 'MySQL nil) ; do not reinitialize if already loaded
  (module "mysql5.lsp") ; with newlisp 10.1, this will change to "mysql.lsp"
  (MySQL:init)
  (MySQL:connect "127.0.0.1" "user" "secret" "somedb"))
 
(context 'DBSessions)
 
(define (open-session)
  (when (MySQL:query (format "SELECT data FROM sessions WHERE sid = '%s'" (MySQL:escape (Web:session-id))))
    (let ((data (MySQL:fetch-row)))
      (if data
        ;; Evaluate the serialized context into the current session context
        (eval-string (first data) (Web:session-context))
        ;; Create a new session and save it
        (MySQL:query (format "INSERT INTO sessions (sid, data) VALUES ('%s', '%s')"
          (MySQL:escape (Web:session-id))
          (MySQL:escape (source (Web:session-context)))))))))
 
(define (close-session)
  (MySQL:query (format "UPDATE sessions SET data = '%s' WHERE sid = '%s'"
    (MySQL:escape (source (Web:session-context)))
    (MySQL:escape (Web:session-id)))))
 
(define (delete-session)
  (MySQL:query (format "DELETE FROM sessions WHERE sid = '%s'"
    (MySQL:escape (Web:session-id)))))
 
(define (clean-sessions)
  (MySQL:query (format "DELETE FROM sessions WHERE NOW() >= DATE_ADD(ts, INTERVAL %d SECOND)"
    Web:SESSION_MAX_AGE)))
 
(Web:define-session-handlers
  open-session close-session delete-session clean-sessions)
 
(context 'MAIN)

Submit article

The Mysql module differs from the distribution standard module in several important ways. Most obviously, it uses FOOP wrappers for MySQL types. It also requires clients to free results instances; in the standard module, only the base MYSQL instance itself must be freed (using MySQL:close-db).

The significance of this is that it is much simpler to create multiple connections (without having to duplicate the entire context at compile time). Result sets are completely independent of each other, and several may be maintained in any state at once. This also means that a spawned process may be given its own Mysql instance to use without having to worry about other processes’ instances interfering. Using the standard module, the entire context would need to be cloned at compile time and given a static symbol reference (e.g., (new 'MySQL 'db)) in order to run multiple instances or connections to a server.

Moreover, because this module uses unpack and MySQL C API accessor functions, there is no need for the client to calculate member offsets in MySQL compound types. So long as newLisp was compiled for the same target as the libmysqlclient library (both are 32 bit or both are 64 bit), everything should work out of the box. Additionally, MySQL errors are now checked in the connect and query functions and re-thrown as interpreter errors. Instead of checking for nil returns and a using MySQL:error to get the error message, standard error  handling with the catch function may be used.

Several convenience functions and macros have been defined in the mysql context for common operations, including connecting to the database and iterating over results without having to worry about catching errors and managing memory. SQL statements may be passed as strings or a list containing a format string and its parameters, which will type-checked and automatically be escaped as needed.

(mysql:on-connect '("localhost" "user" "secret" "my_database")
  (lambda (db err)
    (if err
      (println "Error! " err)
      (mysql:row-iter db "SELECT * FROM some_table" true
        (lambda (row)
          (println row))))))

This module has been tested with MySQL version 5 and 5.1 and newLisp version 10.0.1. It requires newLisp 10.0 or later. You can download it from the Artful Code newLisp module repository.

Submit article

The basics

The basics of the MySQL full-text search functions are well-documented in the MySQL online documentation. For those lacking patience, here is a quick rundown.

Full-text searching is somewhat akin to a LIKE condition, but is much faster, requiring a FULLTEXT index to be created for the table columns targeted in the search. To search the title and description columns of a table, entries, the following statement would create the proper index:

ALTER TABLE entries ADD FULLTEXT(title, description)

To search these columns for the text, “python threading,” the MATCH...AGAINST functions are used:

SELECT id, MATCH(title, description) AGAINST ('python threading') AS score
FROM entries
ORDER BY score DESC

Notice that we keep the result of the match. The value returned is a float representing the relevance of the match. The higher the number, the more relevant the match.

There are several caveats to the full-text search. In particular, any words that are common between many entries are treated as noise and their relevance in any search is diminished. This means that were every article in entries to be about threading in Python, searching for “python threading” may not return extremely relevant results. Refer to the MySQL docs for more information.

The hard part

If the content to be searched is not conveniently located in one table, things get more complex. In this case, a method must be devised to create an intermediary table to contain the search target.

This might be accomplished with a cron script that aggregates the information nightly or using stored procedures to keep the target table updated.

Refining results

A common case is to weight the search to favor more recent results. Assuming that each entry has a DATETIME field named timestamp, this is easily accomplished by using the entry’s age to modify the score.

For an even reduction to the score based on the article’s age, divide the score by the age, which is determined with DATEDIFF(NOW(), timestamp).

(MATCH(title, description) AGAINST ('python threading'))/GREATEST(1, DATEDIFF(NOW(), timestamp))

Since DATEDIFF returns the difference in days, an entry written today could cause division by zero.
GREATEST means that entries written today and yesterday have equal weight, but prevents results from omitting today’s articles.

A quick test of this will show that results become wildly incorrect after a few days as the text match score begins to diminish further with age. This effect can be reduced by taking the LOG of the age, making the divisor increase less and less the greater the age.

LOG(GREATEST(1, DATEDIFF(NOW(), timestamp)))

The use of LOG causes a steep drop initially, smothing over time. For a less dramatic effect, substituting the square root causes a similar drop in the weight of the entry’s age over time, but diminishing less starkly over time and without the initial steep drop.

SQRT(GREATEST(1, DATEDIFF(NOW(), timestamp)))

The complete SQL statement is now:

SELECT id,
  (MATCH(title, description) AGAINST ('python threading'))/SQRT(GREATEST(1, DATEDIFF(NOW(), timestamp)))
  AS score
FROM entries
ORDER BY score DESC

Submit article

Updating paths

The file paths in the MySQL module only include the most common libmysqlclient paths. Update the files list to contain /usr/lib64 as well:

(set 'files '(
    "/usr/lib64/libmysqlclient.so" ; 64 bit Linux, UNIX
    "/usr/lib/libmysqlclient.so" ; Linux, UNIX
    "/usr/local/mysql/lib/libmysqlclient.dylib" ; MacOS X
))

If you are not sure where you libmysqlclient library is, you can find it with this command (assuming it is somewhere in /usr):

find /usr -name "libmysqlclient.so"

Updating alignments

The offsets for most structure fields are set at the beginning of mysql5.lsp. They need to be updated:

(constant 'NUM_ROWS_OFFSET (if big-endian 4 0))
(constant 'NUM_FIELDS_OFFSET 96)
(constant 'ERROR_OFFSET 141)
(constant 'INSERT_ID_OFFSET (if big-endian 836 832))
(constant 'AFFECTED_ROWS_OFFSET (if big-endian 828 824))

This is not necessarily the same on all systems. In the newLISP source tree is a folder named util. Compile sql.c and execute it to get the proper offsets. Note that the numbers generated are only one of the two used in this; you need to first determine the endianness of your system. The module itself uses this newLISP form:

(= (pack ">ld" 1) (pack "ld" 1))

If that returns true, update the first number and offset the other number by -4. Otherwise, update the second number and offset the first by 4 (except for NUM_FIELDS_OFFSET and ERROR_OFFSET).

The offsets for the MYSQL_FIELD structure fields are hard-coded in the functions fetch-row and keep-type.

In keep-type, update the line:

(set 'data (get-int (int (+ type_ptr (* 19 4)))))

…to:

(set 'data (get-int (int (+ type_ptr (+ (* 9 8) (* 10 4))))))

That reflects that there are 9 8-byte fields (all char* or ulong) and 10 4-byte fields (all uint) in the MYSQL_FIELD struct. That will keep the coerced types returned from queries straight.

Next, in fetch-row, the pointer to the field structure is found using:

(set 'field_addr (get-int (int (+ rdata (* field 4)))))

Change the 4 to 8:

(set 'field_addr (get-int (int (+ rdata (* field 8)))))

…or you will only get half the fields’ values :).

Data types

On the newLISP forum, Lutz pointed out that in fetch-row, the call to get-int must be changed to get-long for the 64-bit library. After a quick look at the types returned in the MySQL C api docs, I also updated num-rows, affected-rows and inserted-id.

Test it out

Load the updated module in the newLISP shell and run:

(test-mysql)

Submit article

Much of the module uses the small convenience classes to “serialize” SQL expressions. Most of the module’s classes have :serialize methods that render the encapsulated data as a string. For example, the Field class:

(let ((f (Field "table" "fieldname")))
    (:serialize f))
=> "table.fieldname"

…or the Condition class:

(let ((c (Condition ">" "salary" 65000)))
    (:serialize c))
=> "salary > '65000'"

Note that values are enclosed in single quotes for ANSI compliance. The most interesting function in the module, however, is sql:expr, which uses the match-based primitives in the functional module to generate various types of expressions:

(sql:expr "employees" "first_name")
=> "employees.first_name"
 
(sql:expr "LIKE" "first_name" "Stev%")
=> "first_name LIKE 'Stev%'"
 
(sql:expr "OR" (sql:expr "LIKE" "first_name" "Stev%")
               (sql:expr "LIKE" "last_name" "John%"))
=> "((first_name LIKE 'Stev%') OR (last_name LIKE 'John%'))"
 
(sql:expr 6)
=>"6"
 
(sql:expr 'myapp:employees)
=> "employees"
 
(sql:expr "CONV" "AF" 16 10)
=> "CONV('AF',16,10)"
 
(sql:expr "LIKE" (sql:expr "employees" "first_name") "Stev%")
=> "employees.first_name LIKE 'Stev%'"

Additional functions directly express select, update, insert, and delete statements or handle data type conversions (such as parsing SQL datetimes).

Functional

Another addition to Artful Code’s module list is the functional module. This library provides some basic conditionals that make use of match to process data. These macros express program logic by associating blocks of code with the structure of data.

Here is an example using match-case. match-case accepts a single expression and a series of forms that describe what to do based on its structure. Each case form consists of a match expression, a list of variables to be locally bound to the result of the match, and an individual form to evaluate in a local scope with the matched variables bound:

(let ((x '(1 2 3 4 5)))
    (match-case x
        ((? ? ?) (a b c)
         (println "a b and c do not get bound here, because they do not match x"))
        ((? ? ? *) (a b c d)
         (println "a = 1, b = 2, c = 3, and d = '(4 5)"))))

Here, the second block would match because (? ? ? *) matches against (1 2 3 4 5) and creates the binding association, ((a 1) (b 2) (c 3) (d (4 5))).

Also included in the module is match-cond, which is more powerful than match-case. match-cond works like cond, except that instead of a user-defined conditional, the first form in each case is a list of pattern, symbol-list, and target. See the documentation for more details.

Edit (2009-02-16): the functional module in mentioned in this post has been replaced with the matching module.

Submit article

New features in this version of the module:

• Fixed fetch-all to use a local variable to prevent alteration of future result sets
• num-fields: returns the number of columns in the result set
• result-fields: returns a list of columns’ field-names for the current result set
• fetch-table: maps the column field names to the row data
  *add-path: adds a path to an internal list of paths that init will search for the mysql client library
• Added several default paths:
  • /usr/lib/libmysqlclient.so
  • /usr/local/mysql/lib/libmysqlclient.dylib
  • C:mysqllibmysqlclient.dll

Caveats:

• Broke documentation module by using lisp-style function documentation (inline docs and comments) and deleting Lutz’s documentation for my own fiendish reasons (I can see more code while I’m working on the source). If I get around to making my changes more professional, I will restore the documentation for the module.
• fetch-table is perhaps not quite as optimized as it could be; as it is, it takes nearly twice the time to create the results list as a normal fetch-all operation

I will also make this available on its own page on the site. Now, without further ado:

(context 'MySQL)
 
; following constant offsets into 'C' data structures are different on each
; major MySQL version compile and run util/sql.c from the distribution to
; obtain these numbers
 
; check endianess of the host CPU
(set 'big-endian (= (pack ">ld" 1) (pack "ld" 1)))
 
(constant 'NUM_ROWS_OFFSET (if big-endian 4 0))
(constant 'NUM_FIELDS_OFFSET 60)
(constant 'ERROR_OFFSET 85)
(constant 'INSERT_ID_OFFSET (if big-endian 708 704))
(constant 'AFFECTED_ROWS_OFFSET (if big-endian 700 696))
 
(define (init)
  (set 'MYSQL (mysql_init 0))
  (if (= MYSQL 0) (set 'MYSQL nil))
  (not (= MYSQL nil)))
 
(define (connect host user passw database)
  (not(= (mysql_real_connect MYSQL host user passw database 0 0 0) 0)))
 
(define (MySQL:query sql)
  (if MYSQL_RES (mysql_free_result MYSQL_RES))
  (set 'result  (= (mysql_query MYSQL sql) 0))
  (set 'MYSQL_RES (mysql_store_result MYSQL))
  (if (= MYSQL_RES 0) (set 'MYSQL_RES nil))
  (if (and result (find "insert into" sql 1)) (set 'result (inserted-id)))
  result)
 
(define (num-rows)
  (if MYSQL_RES (get-int (int (+ MYSQL_RES NUM_ROWS_OFFSET)))))
 
(define (num-fields)
  (if MYSQL_RES (get-int (int (+ MYSQL_RES NUM_FIELDS_OFFSET)))))
 
(define (keep-type res_ptr field_addr column_num, data)
  (set 'type_ptr (mysql_fetch_field_direct res_ptr (int column_num)))
  ; The field type is the 20th field of the MySQL_FIELD structure
  ; since fields 1-19 are all 4 byte fields we get the enum value
  ; like so
  (set 'data (get-int (int (+ type_ptr (* 19 4)))))
  ; Consult 'enum_field_types' in mysql_com.h for values
  (if (= data 1) ;; boolean
        (get-string field_addr)
      (= data 3) ;; integer
        (int (get-string field_addr))
      (= data 12) ;; datetime
        (apply date-value (map int (parse (get-string field_addr) "[-: ]" 0)))
      (= data 4) ;; float
        (float (get-string field_addr))
      ; else (will handle TEXT type 252)
      (get-string field_addr)
  )
)
 
(define (fetch-row)
  (if MYSQL_RES
    (set 'rdata (mysql_fetch_row MYSQL_RES))
    (set 'rdata 0))
  (if (!= rdata 0)
    (begin
      (set 'row '())
      (dotimes (field (num-fields))
            (set 'field_addr (get-int (int (+ rdata (* field 4)))))
            (if (= field_addr 0)
              (push nil row -1) ;; what to do when the field contains NULL
              (push (keep-type MYSQL_RES field_addr field) row -1)))
    row)))
 
(define (fetch-all)
  (dotimes (x (num-rows)) (push (fetch-row) all))
  (reverse all))
 
(define (databases)
  (query "show databases;")
  (fetch-all))
 
(define (tables)
  (query "show tables;")
  (fetch-all))
 
(define (fields table)
  (query (append "show fields from " table ";"))
  (fetch-all))
 
(define (data-seek offset)
  (if MYSQL_RES
    (if big-endian
        (mysql_data_seek MYSQL_RES  0 (int offset))
        (mysql_data_seek MYSQL_RES (int offset) 0)))
  true
)
 
(define (error)
  (if MYSQL (get-string (+ MYSQL ERROR_OFFSET))))
 
(define (affected-rows)
  (if MYSQL
    (get-int (int (+ MYSQL AFFECTED_ROWS_OFFSET)))))
 
(define (inserted-id)
  (if MYSQL (get-int (int (+ MYSQL INSERT_ID_OFFSET)))))
 
(define (escape value , safe-value)
  (set 'safe-value (dup " " (+ 1 (length value))))
  (MySQL:mysql_real_escape_string MySQL:MYSQL safe-value value (length value))
  safe-value)
 
(define (close-db)
  (if MYSQL_RES (mysql_free_result MYSQL_RES))
  (if MYSQL (mysql_close MYSQL))
  (set 'MYSQL nil)
  (set 'MYSQL_RES nil)
  true)
 
;;; My additions
 
(set 'lib-paths '("/usr/lib/libmysqlclient.so" ; linux
                  "/usr/local/mysql/lib/libmysqlclient.dylib" ; osx
                  "C:\\mysql\\lib\\mysqlclient.dll")) ; win32
 
(define (add-path str-path)
  "Pushes new path on to lib-paths, our list of paths to search for the
  mysql client library."
  (push str-path lib-paths))
 
(define (init)
  "Attempts to initialize the module."
  ;; New init actions
  (dolist (lib lib-paths) (if (file? lib) (set 'libmysqlclient lib)))
  (import libmysqlclient "mysql_init")
  (import libmysqlclient "mysql_real_connect")
  (import libmysqlclient "mysql_get_host_info")
  (import libmysqlclient "mysql_real_escape_string")
  (import libmysqlclient "mysql_query")
  (import libmysqlclient "mysql_real_query")
  (import libmysqlclient "mysql_store_result")
  (import libmysqlclient "mysql_free_result")
  (import libmysqlclient "mysql_data_seek")
  (import libmysqlclient "mysql_fetch_row")
  (import libmysqlclient "mysql_close")
  (import libmysqlclient "mysql_fetch_field_direct")
  (import libmysqlclient "mysql_insert_id")
  (import libmysqlclient "mysql_num_fields")
  (import libmysqlclient "mysql_fetch_field")
  ;; Perform previous definition's actions
  (set 'MYSQL (mysql_init 0))
  (if (= MYSQL 0) (set 'MYSQL nil))
  (not (= MYSQL nil)))
 
(define (fetch-all , all)
  "Redefined fetch-all that is not affected by previous results, nor does it
  affect future results."
  (dotimes (x (num-rows)) (push (fetch-row) all))
  (reverse all))
 
(define (num-fields)
  "Evaluates the total number of fields for the current result."
  (mysql_num_fields MYSQL_RES))
 
(define (result-fields)
  "Generates a list of strings reflecting the names of the fields in the
  current result."
  (let ((fields '()))
       (dotimes (i (num-fields))
         (push (get-string (get-int (mysql_fetch_field MYSQL_RES)))
               fields -1)) fields))
 
(define (fetch-table)
  "Creates a table associating field names with field values for the current
  result.  This will not work if the result has already been pulled another
  way."
  (letn ((rows (fetch-all)) (fields (result-fields))
         (pair (lambda (row) (map list fields row))))
        (map pair rows)))
 
(context 'MAIN)

Submit article

Before that can be done, however, a note for those who do not know C. Functions in C have a declared type, as do all of their arguments. When reading the docs for a particular library, you will want to know description conventions for C routines. Let’s use the example of mysql_init() to begin with.

MYSQL *mysql_init(MYSQL *mysql)

The first part, MYSQL *mysql_init, defines the function’s return type and name. MYSQL is a type created by the library that stores a struct. This is actually completely irrelevant at this point, because of the asterisk. The asterisk means that the function is actually allocating a pointer. Although we can pass an already existing MYSQL object pointer (that’s the second part), generally we will just use this function to create the internal struct needed to run the program. We will need to store the pointer that is returned.

The second part, MYSQL *mysql, states this- namely, that a pointer (named mysql, and we know it’s a pointer because it’s labelled with an asterisk- *mysql) will be returned. We store it because this will be passed to most of the other routines in the library.

Technically, we do not really need to define the routine in Lisp. The function, foreign-funcall, allows us to call the foreign function directly.

(foreign-funcall "mysql_init" :pointer (null-pointer) :pointer)

In this, we apply mysql_init to a null pointer (an empty pointer argument), created using the CFFI function (null-pointer). The last symbol states we will get a pointer back.

In order to wrap this as a pretty Lisp function, we do:

(defcfun ("mysql_init" libmysql-init) :pointer
  (mysql :pointer))

This points the Lisp symbol libmysql-init to “mysql_init” in the C library. The next argument, :pointer, states that this returns a pointer. Next, we can have an &rest list of (parameter-name :type), to define the parameters to pass to the function, in this case, (mysql :pointer). Available types are listed in the CFFI documentation.

However, we don’t want to have to run (null-pointer) every time we use this function. We also need to store the return value for future use. So let’s wrap it in another function to make it more expressive:

(defun mysql-init ()
  (setq *mysql* (libmysql-init (null-pointer)))
  (or *mysql* (setq *mysql* nil)))

Now, we can simply run (mysql-init) and we will have the symbol *mysql* pointing to the returned pointer or nil in the event of a failure.

If we do have a failure, we can use the following definitions to get at the error text:

(defcfun ("mysql_error" libmysql-error) :string
    (mysql :pointer))
 
(defun mysql-error ()
    (libmysql-error *mysql*))

Of course, we will want to add error handling and some other niceties, but having these declared makes writing and testing those completed functions that much easier.

Submit article

My database of choice (and the one available to me on my host) is MySQL. Unfortunately, this is the piece of CLSQL that I can’t seem to get running on OSX. In every dialect I’ve tried (sbcl, cmucl, clisp, openmcl, ad infinitum), CFFI/UFFI cannot find the libmysqlclient library- even when it has been pushed onto the library search path… but that is a rant for a different blog (or Usenet).

CFFI is generally available via ASDF and plays well with GNU CLISP. It has a fairly simple, intuitive syntax for making C routines available to lisp (as a side note, I have not encountered anything as easy as newLisp’s C library importer, although this is made easier in that newLisp is implemented in C).

Using CFFI, we can fairly easily create mappings for the most important MySQL C api functions. This entry will walk through the process of importing the library; future entries will go one to defining a few of the most basic routines for our lisp image.

Let’s begin by defining our mysql wrapper package.

(defpackage :mysql-api
  (:use :common-lisp :cffi))
(in-package :mysql-api)

To load the library itself, we use the function, define-foreign-library, in the CFFI package. The first argument to define-foreign-library is the symbol we wish to point to the library. Next, we create list similar in syntax to cond, where we define the names of our libraries based on, for example, the host OS. Since I happen to know that CFFI does find the library path even when explicitly specified, we can conveniently specify a list of full paths to try for each OS. The full list of platform symbols available here.

(define-foreign-library libmysqlclient
  (:darwin (:or "/usr/local/mysql/lib/libmysqlclient.dylib"
                "/sw/lib/libmysqlclient.dylib"
                "/usr/local/lib/libmysqlclient.dylib"))
  (t (:default "libmysqlclient")))

The last line is a catch-all, and will format the filename based on the OS (i.e., libmysqlclient.so for unix, .dll for Windows). Although I know my library is located in /usr/local/mysql/lib, I have included various other commonly used paths for MySQL libraries in OSX.

Then, to load the library:

(use-foreign-library libmysqlclient)

This will return a pointer to a foreign address (for the C-challenged, a pointer is a variable to points to a value’s address in memory; it is used to access a value by reference, rather than by value) or, in the event that it did not work, it will throw up an error. Generally, the error will be caused by CFFI not being able to find the library. If this is the case, verify that your account has access to the file and that the file is included in one of the paths above.

Next, we will begin defining our C routines in lisp.

Submit article