[Db-derby Wiki] Update of "InMemoryBackEndPrimer" by KristianWaagan

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Db-derby Wiki" for change notification.

The following page has been changed by KristianWaagan:
http://wiki.apache.org/db-derby/InMemoryBackEndPrimer

New page:
This page describes the '''experimental''' in-memory storage factory for Derby. 
When used, Derby will store the database only in main memory. All the data will be lost on any of the following events:
  * the Java VM crashes / exists
  * the Java VM is shut down normally
  * the machine crashes or shuts down (i.e. power failure, OS hang, reboot)

The in-memory storage back end '''must''' only be used for temporary or reproducible data.

== How to use ==
To instruct Derby to use the in-memory storage factory, specify ''memory'' as the JDBC sub-sub-protocol: ''jdbc:derby:memory:myDb;create=true''

== How to delete an in-memory database ==
A proper mechanism to delete an in-memory database has not yet been added.
The user is left with two choices:
  * restart the Java VM
  * use the static method ''VF!MemoryStorageFactory.purgeDatabase(String)''.

The latter mechanism isn't part of Derby's published API (it is not documented), and will most likely be removed in the next version of Derby. '''Use it at your own risk'''.
[[BR]]
See also under the heading ''Future features''.

== Configuration and tuning ==
The most important aspect to configure, is the size of the Java heap. When using the in-memory storage back end, the memory requirement should be similar to the memory requirements of using the disk-based storage back end plus the size of the user data. The general overhead will be increased somewhat.
[[BR]]

Sizing the Derby page cache still impacts the performance when using the in-memory storage back end. The default value of ''1000'' pages should give acceptable performance for most basic applications, but it is not recommended that a smaller number of pages is specified. The data has to pass through the page cache even though the user data is already stored in main memory. A larger page cache may increase the performance at the cost of increased memory usage.

== Known limitations and bugs ==
Know problems and issues will be listed in the table below.

|| Issue || Jira || Description ||

== User feedback ==
Users testing out the feature are welcome to provide feedback to the Derby developer list, on the [https://issues.apache.org/jira/browse/DERBY-646 DERBY-646] Jira issue or on this page.
[[BR]]
Feedback, positive or negative, is appreciated!

== Future features ==
A basic list of possible future features. Feel free to comment on the existing ones, or add a new feature you would like to see.
  
==== Automatic database persistence on JVM shutdown ====
No description yet.

==== JMX monitoring and/or management ====
 * List databases stored in-memory
 * Obtain size of databases stored in main memory
 * Obtain size of a single database stored in main memory
 * Delete database from main memory

== Risky features ==
'''The text below describes some risky actions you can do with the in-memory back end. You, and your data, are on your own on this one.'''
[[BR]]

It is possible to create an in-memory database, work with it, and then take a backup before the Java VM is shut down. This will result in the database being persisted to disk, and it can be restored into main memory using the in-memory back end and one of the ''createFrom'' and ''restoreFrom'' JDBC connection URL attributes.
[[BR]]
If you do this and it fails, we'd like to hear about it, but we won't feel sorry for you :)

'''Always consider your data as transient / volatile when using the in-memory storage back end.'''

== Jira references ==
[https://issues.apache.org/jira/browse/DERBY-646 DERBY-646]