2.2 Getting Started

The first step in using elephant is to open a store controller. A store controller is an object that coordinates lisp program access to the chosen data store.

To obtain a store controller, you call open-store with a store specification. A store specification is a list containing a backend specifier (:BDB or :CLSQL) and a backend-specific reference.

For :BDB, the second element is a string or pathname that references a local directory for the database files. This directory must be created prior to calling open-store.

     (open-store '(:BDB ``/users/me/db/my-db/''))

For :CLSQL the second argument is another list consisting of a specific SQL database and the name of a database file or connection record to the SQL server. Examples are:

     (open-store '(:CLSQL (:SQLITE "/users/me/db/sqlite.db")))
     (open-store '(:CLSQL (:POSTGRESQL "localhost.localdomain"
                                       "mydb" "myuser" ""))))

We use Berkeley DB as our example backend. To open a BDB store-controller we can do the following:

     (asdf:operate 'asdf:load-op :elephant)
     (use-package :elephant)
     (setf *test-db-spec*
           '(:BDB "/home/me/db/testdb/"))
     (open-store *test-db-spec*)

We do not need to store the reference to the store just now as it is automatically assigned to the variable, *store-controller*. For a deeper discussion of store controller management see the User Guide.

When you're done with your session, release the store-controller's resources by calling close-store.

Also there is a convenience macro with-open-store that will open and close the store, but opening the store is an expensive operation so it is generally better to leave the store open until your application no longer needs it.