Here's a collection of comments, tips, and notes that we're not sure where else to put right now. The features and syntax described here are currently supported, and the general functionality will likely be supported in the future, but they should be considered non-normative--we may change these features or syntax in future releases.
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.)
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 Connection
s. (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();
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
.
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.)
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.
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.
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.
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.