faq.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<!--
Copyright 2004-2009 H2 Group. Multiple-Licensed under the H2 License, Version 1.0,
and under the Eclipse Public License, Version 1.0
(http://h2database.com/html/license.html).
Initial Developer: H2 Group
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head><meta http-equiv="Content-Type" content="text/html;charset=utf-8" /><title>
Frequently Asked Questions
</title><link rel="stylesheet" type="text/css" href="stylesheet.css" />
<!-- [search] { -->
<script type="text/javascript" src="navigation.js"></script>
</head><body onload="frameMe();">
<table class="content"><tr class="content"><td class="content"><div class="contentDiv">
<!-- } -->

<h1>Frequently Asked Questions</h1>

<a href="#known_bugs">
    Are there Known Bugs? When is the Next Release?</a><br />
<a href="#open_source">
    Is this Database Engine Open Source?</a><br />
<a href="#query_slow">
    My Query is Slow</a><br />
<a href="#create_database">
    How to Create a New Database?</a><br />
<a href="#connect">
    How to Connect to a Database?</a><br />
<a href="#database_files">
    Where are the Database Files Stored?</a><br />
<a href="#size_limit">
    What is the Size Limit (Maximum Size) of a Database?</a><br />
<a href="#reliable">
    Is it Reliable?</a><br />
<a href="#slow_open">
    Why is Opening my Database Slow?</a><br />
<a href="#column_names_incorrect">
    Column Names are Incorrect?</a><br />
<a href="#gcj">
    Is the GCJ Version Stable? Faster?</a><br />
<a href="#translate">
    How to Translate this Project?</a><br />

<h3 id="known_bugs">Are there Known Bugs? When is the Next Release?</h3>
<p>
Usually, bugs get fixes as they are found. There is a release every few weeks.
Here is the list of known and confirmed issues:
</p>
<ul><li>Tomcat and Glassfish 3 set most static fields (final or non-final) to <code>null</code> when
    unloading a web application. This can cause a <code>NullPointerException</code> in H2 versions
    1.1.107 and older, and may still not work in newer versions. Please report it if you
    run into this issue. In Tomcat >= 6.0 this behavior can be disabled by setting the
    system property <code>org.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false</code>,
    however Tomcat may then run out of memory. A known workaround is to
    put the <code>h2*.jar</code> file in a shared <code>lib</code> directory
    (<code>common/lib</code>).
</li><li>Some problems have been found with right outer join. Internally, it is converted
    to left outer join, which does not always produce the same results as other databases
    when used in combination with other joins.
</li><li>When using Install4j before 4.1.4 on Linux and enabling <code>pack200</code>,
    the <code>h2*.jar</code> becomes corrupted by the install process, causing application failure.
    A workaround is to add an empty file <code>h2*.jar.nopack</code>
    next to the <code>h2*.jar</code> file.
    This problem is solved in Install4j 4.1.4.
</li></ul>

<h3 id="open_source">Is this Database Engine Open Source?</h3>
<p>
Yes. It is free to use and distribute, and the source code is included.
See also under license.
</p>

<h3 id="query_slow">My Query is Slow</h3>
<p>
Slow <code>SELECT</code> (or <code>DELETE, UPDATE, MERGE</code>)
statement can have multiple reasons. Follow this checklist:
</p>
<ul>
<li>Run <code>ANALYZE</code> (see documentation for details).
</li><li>Run the query with <code>EXPLAIN</code> and check if indexes are used
    (see documentation for details).
</li><li>If required, create additional indexes and try again using
    <code>ANALYZE</code> and <code>EXPLAIN</code>.
</li><li>If it doesn't help please report the problem.
</li>
</ul>

<h3 id="create_database">How to Create a New Database?</h3>
<p>
By default, a new database is automatically created if it does not yet exist.
See <a href="tutorial.html#creating_new_databases">Creating New Databases</a>.
</p>

<h3 id="connect">How to Connect to a Database?</h3>
<p>
The database driver is <code>org.h2.Driver</code>,
and the database URL starts with <code>jdbc:h2:</code>.
To connect to a database using JDBC, use the following code:
</p>
<pre>
Class.forName("org.h2.Driver");
Connection conn = DriverManager.getConnection("jdbc:h2:~/test", "sa", "");
</pre>

<h3 id="database_files">Where are the Database Files Stored?</h3>
<p>
When using database URLs like <code>jdbc:h2:~/test</code>,
the database is stored in the user directory.
For Windows, this is usually <code>C:\Documents and Settings\&lt;userName&gt;</code>.
If the base directory is not set (as in <code>jdbc:h2:test</code>),
the database files are stored in the directory where the application is started
(the current working directory). When using the H2 Console application from the start menu,
this is <code>&lt;Installation Directory&gt;/bin</code>.
The base directory can be set in the database URL. A fixed or relative path can be used. When using the URL
<code>jdbc:h2:file:data/sample</code>, the database is stored in the directory
<code>data</code> (relative to the current working directory).
The directory is created automatically if it does not yet exist. It is also possible to use the
fully qualified directory name (and for Windows, drive name).
Example: <code>jdbc:h2:file:C:/data/test</code>
</p>

<h3 id="size_limit">What is the Size Limit (Maximum Size) of a Database?</h3>
<p>
See <a href="advanced.html#limits_limitations">Limits and Limitations</a>.
</p>

<h3 id="reliable">Is it Reliable?</h3>
<p>
That is not easy to say. It is still a quite new product. A lot of tests have been written,
and the code coverage of these tests is very high. Randomized stress tests
are run regularly. But there are probably still
bugs that have not yet been found (as with most software). Some features are known
to be dangerous, they are only supported for situations where performance is more important
than reliability. Those dangerous features are:
</p>
<ul>
<li>Disabling the transaction log mechanism using <code>SET LOG 0</code>.
</li><li>Using the transaction isolation level <code>READ_UNCOMMITTED</code>
    (<code>LOCK_MODE 0</code>) while at the same time using multiple
    connections.
</li><li>Disabling database file protection using <code>FILE_LOCK=NO</code>
    in the database URL.
</li><li>Disabling referential integrity using <code>SET REFERENTIAL_INTEGRITY FALSE</code>.
</li></ul>
<p>
In addition to that, running out of memory should be avoided.
In older versions, OutOfMemory errors while using the database could corrupt a databases.
</p>
<p>
Areas that are not fully tested:
</p>
<ul>
<li>Platforms other than Windows XP, Linux, Mac OS X, or JVMs other than Sun 1.5 or 1.6
</li><li>The features <code>AUTO_SERVER</code> and
    <code>AUTO_RECONNECT</code>
</li><li>The MVCC (multi version concurrency) mode
</li><li>Cluster mode, 2-phase commit, savepoints
</li><li>24/7 operation
</li><li>Some operations on databases larger than 500 MB may be slower than expected
</li><li>The optimizer may not always select the best plan
</li><li>Fulltext search
</li><li>Operations on LOBs over 2 GB
</li></ul>
<p>
Areas considered experimental are:
</p>
<ul>
<li>The PostgreSQL server
</li><li>Multi-threading within the engine using <code>SET MULTI_THREADED=1</code>
</li><li>Compatibility modes for other databases (only some features are implemented)
</li><li>The soft reference cache (CACHE_TYPE=SOFT_LRU). It might not improve performance,
    and out of memory issues have been reported.
</li></ul>
<p>
Some users have reported that after a power failure, the database can sometimes not be
opened because the index file is corrupt. In that case, the index file can be deleted
(it is automatically re-created). To avoid this, append
<code>;LOG=2</code> to the database URL.
See also: <a href="grammar.html#set_log" class="notranslate">SET LOG</a>. This problem will be solved
using the new 'page store' mechanism (currently beta).
</p>

<h3 id="column_names_incorrect">Column Names are Incorrect?</h3>
<p>
For the query <code>SELECT ID AS X FROM TEST</code> the method
<code>ResultSetMetaData.getColumnName()</code> returns <code>ID</code>, I expect it to
return <code>X</code>. What's wrong?
</p>
<p>
This is not a bug. According the the JDBC specification, the method
<code>ResultSetMetaData.getColumnName()</code> should return the name of the column
and not the alias name. If you need the alias name, use
<a href="http://java.sun.com/javase/6/docs/api/java/sql/ResultSetMetaData.html#getColumnLabel(int)"><code>ResultSetMetaData.getColumnLabel()</code></a>.
Other database don't work like this (they don't follow the JDBC specification).
If you need compatibility with those databases, use the <a href="features.html#compatibility">Compatibility Mode</a>,
or set the system property <a href="../javadoc/org/h2/constant/SysProperties.html#h2.aliasColumnName"><code>h2.aliasColumnName</code></a>.
</p>

<h3 id="slow_open">Why is Opening my Database Slow?</h3>
<p>
If it takes a long time to open a database, in most cases it was not closed the last time.
This is specially a problem for larger databases.
To close a database, close all connections to it before the application ends, or execute
the command <code>SHUTDOWN</code>.
The database is also closed when the virtual machine exits normally
by using a shutdown hook. However killing a Java process or calling <code>Runtime.halt</code> will prevent this.
The reason why opening is slow in this situations is that indexes are re-created.
If you  can not guarantee the database is closed, consider using
<a href="grammar.html#set_log" class="notranslate">SET LOG 2</a>.
</p>
<p>
To find out what the problem is, open the database in embedded mode using the H2 Console.
This will print progress information. If you have many lines with 'Creating index' it is an indication that the
database was not closed the last time.
</p>
<p>
Other possible reasons are: the database is very big (many GB), or contains linked tables
that are slow to open.
</p>

<h3 id="gcj">Is the GCJ Version Stable? Faster?</h3>
<p>
The GCJ version is not as stable as the Java version.
When running the regression test with the GCJ version, sometimes the application just stops
at what seems to be a random point without error message.
Currently, the GCJ version is also slower than when using the Sun VM.
However, the startup of the GCJ version is faster than when using a VM.
</p>

<h3 id="translate">How to Translate this Project?</h3>
<p>
For more information, see
<a href="build.html#translating">Build/Translating</a>.
</p>

<!-- [close] { --></div></td></tr></table><!-- } --><!-- analytics --></body></html>