Important Information

InstantDB databases should only ever be accessed by a single Java Virtual Machine™ (JVM) at any one time. Attempting to access an InstantDB database simultaneously from multiple virtual machines can corrupt the database without warning.

In order to have multiple applications access InstantDB at the same time, simply follow the instructions for setting up InstantDB as an RmiJDBC™ server. Applications wishing to use the database then connect to this via the RmiJDBC™ driver, rather than InstantDB's native JDBC™ driver. The fact that the applications are all on the same machine doesn't matter - it all looks the same from the server's point of view. With this arrangement, you can have as many clients as you wish, while the database remains under the control of a single Java Virtual Machine™.

The only exception to this rule is in the case of readonly databases. Databases opened in readonly mode can be safely accessed by multiple simultaneous JVMs.

InstantDB holds a lot of data in memory. Some of this only gets written to disk as part of a clean shutdown. This is necessary for performance reasons. (Note however that actual table data always gets written to disk at the end of a transaction. Only caches and indexing information are held in memory.)

If JVM 1 opens a database and then JVM 2 opens the same one, JVM 2 will see that there is data missing. It will assume that the database has not been cleanly shut down and will try to repair the database. When JVM 1 shuts down it will corrupt the database without realising it. This is illustrated in the diagram below.

 

 

This means for example that you cannot access the database from a separate monitoring program while your main application has the database open.

Using the RmiJdbc driver means that only the RMI server's JVM actually has the database open. All of the client applications: your main application(s) and any monitoring programs, access the database indirectly via the RMI server.

InstantDB will close a database automatically when there are no surviving database connections. You should always try to close all connections before the JVM which has access to the database exits.

Sometimes however this is not possible, particularly when the database is being accessed via the RmiJdbc driver. In order to force the database to shut down you can issue the SQL command:

This will do a clean shutdown by locking all the tables in the database (thus ensuring that all existing transactions complete) and then closing the database files.

If it is not possible to perform a shutdown, say because a particular transaction is deadlocked, then the

option can be used. This forces all database files to close without first locking the underlying tables.

If InstantDB opens a database and finds that data is missing it cannot tell whether this is simply due to another JVM using the database or whether it has failed to shut down cleanly and needs to be recovered. By default InstantDB asks whether it should perform recovery or not.

InstantDB's behaviour can be altered using the database property: recoveryPolicy. Setting this value to 1 (one) causes InstantDB to perform automatic recovery when it finds a corrupt database. This is a useful policy when the database is being used as a server and automated failover recovery is required.

Setting recoveryPolicy to 2 (two) makes InstantDB issue a prompt on standard in whenever it encounters a potentially corrupt database. This is useful during development when interactive monitoring of the database is useful but might accidentally lead to corruption.

Setting recoveryPolicy to 0 (zero) makes InstantDB refuse to open the database if data appears to be missing.