Frequently Asked Questions
(please read before reporting a bug)
- Is there
an InstantDB mailing list that I can use to ask questions?
Yes. To subscribe go to the Mailing
- What is Java? How do I set my CLASSPATH?
Where can I get the JDK...?
If you're just starting out programming in Java then you can do no
better than to read Peter van der Linden's excellent Java FAQ. This
is available from many web sites and news groups. Try here
for an up to date copy.
- Where are the API definitions? The examples
are too complicated.
InstantDB uses Sun's JDBC API. This is described in your Java documentation,
at sun's website
and in numerous books and articles. You need to learn this API before
you will be able to write programs that use InstantDB.
- InstantDB seems to allow the same PRIMARY
KEY value to be used multiple times. Shouldn't this be illegal?
Strictly speaking, yes, it should be illegal. However, not all databases
enforce this. In order to be able to exchange data with such systems
InstantDB relaxes this restriction on primary keys. You can enforce
the restriction if you really want to using the UNIQUE PRIMARY KEY construct.
- Every time I start my program I see the message:
"Database not shut down cleanly or in use by another program.
Set recoveryPolicy=1 for automatic recovery.
Should InstantDB attempt recovery now? (y/n)". This means that InstantDB
has detected that there is information missing from the database files
on disk. This can be for one of two reasons. Either the database was
not shutdown cleanly or it is currently being accessed by another
program. If you are sure that no other programs are currently accessing
your database then you should type y and allow recovery to proceed.
No information will actually have been lost, but InstantDB will perform
various cross checks and will rebuild indexes on affected tables.
If another program is accessing the database then you must
not allow the program showing the recovery message to proceed. See
for full details.
- How do I set the base and step values for
By default, all AUTO-INCREMENT int columns start at 1,000, and all AUTO-INCREMENT
long columns start at 10,000,000,000. All values increment by 1. You
can alter the base value using the SET INCREMENT_BASE... command. It
is not currently possible to alter the increment step.
- String searches that worked OK before now
seem to fail
InstantDB uses hashes to create indexes. The String hashing algorithm
changed between JDK 1.1 and JDK 1.2. Indexes built by one JDK are therefore
not understood by the other. You will be affected by this problem if
all of the following conditions hold.
- You have char or varchar columns of width
greater than 15 characters.
- The columns are part of an index.
You built the database under 1.1 or 1.2
and then tried to run InstantDB using the other JDK.
From InstantDB 2.3 onwards, InstantDB calculates its own string hashes.
If you think you are affected by this problem then DROP all affected indexes
(including primary keys where applicable) and recreate the indexes using
String indexes created prior to InstantDB 2.3 under JDK 1.2 will not be
understood by InstantDB 2.3 or later. To overcome this, set alStringHashing=1
in the database prpoerties file. This forces InstantDB to use the JDK's
Object.hashCode() function instead of its own String hashing.
- I can open my database from the properties
directory but not from another directory.
You are probably using a URL like jdbc:idb:mydb.prp. Change instead
to a fully qualified pathname for the properties file - something like
- What platforms and OS' is InstantDB known
to run on?
InstantDB has been known to run successfully under: NT4, '95, Linux,
Solaris, AIX, OS2, MacOS, SVR4, EPOC32.
- What is the largest size of an InstantDB
The largest InstantDB table tested so far was just over one million
rows. Each row had about 20 columns.
There is no limit to the size of InstantDB tables. However each index
entry consumes, on average, about 15 bytes. So indexes on very large
tables should only be used where sufficient physical memory has been
allocated to the Java Virtual Machine.
- If start up appears slow.
The most likely explanation for this is that all connections were not
properly closed from the previous database session. When a table gets
modified, InstantDB marks that table as dirty. When the last database
connection is closed, all dirty tables are closed cleanly and left in
a consistent state.
If the database is shut down abrubtly, say using ^C or an unhandled
exception, then when it is next opened it enters a recovery mode. This
involves full table scans of all dirty tables and the rebuilding from
scratch of all modified indexes. This can take a substantial amount
of time. The database must be shut down cleanly in order to save the
- Index files are suspiciously very small.
Again, this is due to an uncontrolled shutdown of the database. Indexes
are held entirely in memory and are not written to disk until the last
database connection is closed.
- I seem to get FileNotFound Exceptions with
This is actually a file access permissions problem. Make sure that all
of the database files have world read/write privilege.
- Inserts seem to slow down as the table size
If a single connection is adding records to a table with no indexes
then InstantDB's insert performance is virtually constant over a very
wide range of table sizes.
However, if the table contains one or more indexes (even a PRIMARY KEY),
then the time take to navigate the indexes will gradually increase.
For bulk data imports, we recommend creating indexes after all of the
data has been added.
If there are additional connections performing queries against a table
while INSERTs are being performed, then the time taken to perform the
queries will also grow as indexes grow and full table scans take longer.
These connections will therefore lock out insert statements for longer
as the table size increases. They will also leave the random access
file pointer for the underlying file in a sub-optimal position.
- The database occasionally just seems to
Almost certainly due to a connection holding a table lock. By default,
all InstantDB transactions are serializable. This means that, even for
a query, all tables involved in a SQL statement are locked exclusively
(all InstantDB locks are exclusive).
A query retains its table locks until the results set has been completely
read, or until a new query is executed. Simply by not reading the last
row of a results set, a connection can lock all of the tables involved.
The description of JDBC transaction handling is given in the java.sql.Connection
documentation. Unfortunately it is spread out throughout the entire
html page, and you really have to read it from top to bottom to understand
what's going on. Once you've done that, read Transactions
to understand how InstantDB implements transaction processing.
- Applications work but Applets seem to fail.
Java imposes security restrictions on Applets. They are not allowed
to read or write to disk and can only form network links to the location
they were downloaded from. This prevents rogue Applets, downloaded from
untrusted sources, from damaging your system.
InstantDB makes extensive use of disk files and so an arbitrary Applet
will not be able to access an InstantDB database. However, it is possible
to get around this. The security restrictions imposed on Applets are
enforced by a browser's security manager. If the security manager can
be persuaded to trust the Applet then it will allow disk access to take
place. Both Internet Explorer and Netscape allow you to digitally sign
an Applet using a trusted key. Unfortunately, they do this in different
ways, so it isn't possible to have the same Applet trusted by both major
Netscape also provide proprietary extensions which allow Applets to
talk directly to their security manager and remove the security restrictions.
For an example of this see the JDBCAppl