Axion: Tidbits

Database name overrides location

When you first connect to an Axion database, you indicate whether the database is transient (in-memory) or persistent, and if persistent, where the data files live. Internally, Axion will store a case-insensitive reference to the named database, and this database will persist until the VM exits or the database is SHUTDOWN.

Note that once the database is created (and until the database is SHUTDOWN), all connect strings that reference a database with that name will point to the same database. This means, for example, if you initially connect to a database using:

jdbc:axiondb:FOO:/data/foodb

Then all of the following connect strings will also connect to the database whose files live at /data/foodb:

jdbc:axiondb:FOO:/data/bardb
jdbc:axiondb:FOO
jdbc:axiondb:foo:/bardb
jdbc:axiondb:foo
jdbc:axiondb:FoO

That is, after the initial connection to the database, only the case-insensitive name is important. All references to databases with the same name will point to the same database. (The Axion team believes this to be a feature, for reasons we'll see below.)

SHUTDOWN

When Axion is running in-process, note that the VM is hosting both the client and server side of the database. The server-side of the database persists beyond the lifespan of specific client-side Connections. (I.e., if you close a Connection and then reopen it, the database isn't recreated, it still exists.) To close the server-side of the database, you need to issue a SHUTDOWN command. E.g.,

Connection conn = DriverManager.getConnection("jdbc:axiondb:foo:/data/foo");
Statement stmt = conn.createStatement();
stmt.execute("shutdown");
stmt.close();
conn.close();

CHECKPOINT

Axion isn't fully durable just yet. Some of the database state doesn't persist to disk immediately. To force Axion to synchronize its in-memory state with the persistent, on-disk state, you can issue a CHECKPOINT command. E.g.:

Connection conn = DriverManager.getConnection("jdbc:axiondb:foo:/data/foo");
Statement stmt = conn.createStatement();
stmt.execute("checkpoint");
stmt.close();
conn.close();

CHECKPOINT is implicitly invoked whenever you close a Connection or when the database is SHUTDOWN.

Read-Only Mode

You can force Axion into a read-only mode by setting the property readonly to true in your axiondb.properties file. This will cause any CREATE, INSERT, UPDATE, DELETE, etc. command to throw a SQLException.

Read-only mode can be used when an Axion database is stored on read-only media, but it isn't strictly necessary. Axion will not attempt to open a file for writing until a data-modifying command is executed. (I.e., if you only issue SELECT commands, Axion will only open files for reading anyway.)

REMOUNT and CHECKFILESTATE

Sometimes an Axion database is stored on removeable media like a CD or DVD. It is possible for the user or operating system to remove or move this media or these mount points while the database is running. Two extensions have been added to Axion to help deal with these situations.

The CHECKFILESTATE command will confirm that the database's data files are accessible. On success, CHECKFILESTATE will return a ResultSet containing at least one row. On failure, CHECKFILESTATE will return an empty ResultSet. For example:

Connection conn = DriverManager.getConnection("jdbc:axiondb:foo:/data/foo");
Statement stmt = conn.createStatement();
ResultSet rset = stmt.executeQuery("checkfilestate");
if(rset.next()) {
  // database files are still readable
} else {
  // database files seem to have been moved or removed
}
rset.close();
stmt.close();
conn.close();

The REMOUNT command will point the database to a new location on the file system (for example, to the new mount-point for a CD containing the database files). The syntax is REMOUNT new-location. For example:

Connection conn = DriverManager.getConnection("jdbc:axiondb:foo:/data/foo");
Statement stmt = conn.createStatement();
ResultSet rset = stmt.execute("remount /data/bar");
stmt.close();
conn.close();

Note that the new-location argument may be a bind variable.

Note that as described in Database name overrides location, both jdbc:axiondb:foo:/data/foo and jdbc:axiondb:foo:/data/bar (and for that matter, jdbc:axiondb:foo) will point to the same database, both before and after the remount.

Extending Axion with new Data Types

To add a new data type to Axion, simply create a class that implements DataType and register it with Axion in the axiondb.properties file.

See the org.axiondb.types package for examples.

Extending Axion with new Functions

To add a new function to Axion, simply create a class that implements AggregateFunction or ScalarFunction and register it with Axion in the axiondb.properties file.

See the org.axiondb.functions package for examples.

Defragmenting (Compacting) an Axion Database

The current default implementation of a disk-based Axion database does not recycle the "slots" that a row is saved into. This means that the disk files grow, not only for INSERT statements, but also for UPDATEs. Similarly, DELETEs do not reduce the size of these files either.

It is possible to "defragment" or "compact" such a database via the Defrag tool. It is used like this:

java -cp axiondb.jar;commons-collections.jar;commons-logging.jar \
         org.axiondb.tools.Defrag [dbpath]

The behavior of this application is unspecified if the database is open in any other process while this application is running.

Note that a database that is only used via INSERT and SELECT statements is already minimally sized, there is no value in defragmenting it.