You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by ch...@apache.org on 2010/04/22 17:02:05 UTC
svn commit: r936885 - in /db/derby/docs/trunk/src: adminguide/ devguide/
ref/ tools/ tuning/
Author: chaase3
Date: Thu Apr 22 15:02:04 2010
New Revision: 936885
URL: http://svn.apache.org/viewvc?rev=936885&view=rev
Log:
DERBY-4525: Document the in-memory storage back end
Added 1 topic each to Developer's Guide, Reference Manual, and Tuning guide; modified 11 topics in Dev Guide, 4 in Ref, 2 in Tools, 1 in Tuning, 1 in Admin Guide
Patch: DERBY-4525-3.diff
Added:
db/derby/docs/trunk/src/devguide/cdevdvlpinmemdb.dita (with props)
db/derby/docs/trunk/src/ref/rrefattribdrop.dita (with props)
db/derby/docs/trunk/src/tuning/ctunperfinmemdb.dita (with props)
Modified:
db/derby/docs/trunk/src/adminguide/cadminappsclient.dita
db/derby/docs/trunk/src/devguide/cdevdvlp17453.dita
db/derby/docs/trunk/src/devguide/cdevdvlp18166.dita
db/derby/docs/trunk/src/devguide/cdevdvlp19297.dita
db/derby/docs/trunk/src/devguide/cdevdvlp19700.dita
db/derby/docs/trunk/src/devguide/cdevdvlp27610.dita
db/derby/docs/trunk/src/devguide/cdevdvlp40350.dita
db/derby/docs/trunk/src/devguide/cdevdvlp40724.dita
db/derby/docs/trunk/src/devguide/cdevdvlp42173.dita
db/derby/docs/trunk/src/devguide/cdevdvlp846369.dita
db/derby/docs/trunk/src/devguide/cdevdvlp96597.dita
db/derby/docs/trunk/src/devguide/derbydev.ditamap
db/derby/docs/trunk/src/devguide/rdevdvlp22102.dita
db/derby/docs/trunk/src/ref/refderby.ditamap
db/derby/docs/trunk/src/ref/rrefattrib16471.dita
db/derby/docs/trunk/src/ref/rrefattrib17246.dita
db/derby/docs/trunk/src/ref/rrefattrib24612.dita
db/derby/docs/trunk/src/ref/rrefattrib26867.dita
db/derby/docs/trunk/src/tools/rtoolsijcomref22318.dita
db/derby/docs/trunk/src/tools/rtoolsijcomref27997.dita
db/derby/docs/trunk/src/tuning/ctunperf25864.dita
db/derby/docs/trunk/src/tuning/tuningderby.ditamap
Modified: db/derby/docs/trunk/src/adminguide/cadminappsclient.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/cadminappsclient.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/adminguide/cadminappsclient.dita (original)
+++ db/derby/docs/trunk/src/adminguide/cadminappsclient.dita Thu Apr 22 15:02:04 2010
@@ -32,7 +32,12 @@ addition, you must specify a user name a
</codeblock>where the <codeph><URL attribute></codeph> is either a <ph
conref="../conrefs.dita#prod/productshortname"></ph> embedded or network
client attribute.</p>
-
+<p>To access an in-memory database using the Network Server, the syntax is:</p>
+<codeblock>jdbc:derby://<<i>server</i>>[:<<i>port</i>>]/memory:
+<<i>databaseName</i>>[;<URL attribute>=<value> [;...]]
+</codeblock>
+<p>For more information, see "Using in-memory databases" in the
+<ph conref="../conrefs.dita#pub/citdevelop"></ph>.</p>
<p>
For both driver and DataSource access, the database name (including path),
user, password and other attribute values must consist of single-byte
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp17453.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp17453.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp17453.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp17453.dita Thu Apr 22 15:02:04 2010
@@ -50,11 +50,14 @@ URL, see <xref href="rdevdvlp22102.dita#
<codeblock>jdbc:derby:[subsubprotocol:][<i>databaseName</i>][;<i>attribute</i>=<i>value</i>]*</codeblock>
<p><i>Subsubprotocol</i>, which is not typically specified, determines
how <ph conref="../conrefs.dita#prod/productshortname"></ph> looks for a database:
-in a directory, in a class path, or in a jar file. <i>Subsubprotocol</i> is one of
+in a directory, in memory, in a class path, or in a jar file. <i>Subsubprotocol</i> is one of
the following:</p>
<ul>
<li><i>directory</i>: The default. Specify this explicitly only to distinguish
a database that might be ambiguous with one on the class path.</li>
+<li><i>memory</i>: Databases exist only in main memory and are not written to
+disk. An in-memory database may be useful when there is no need to persist the
+database -- for example, in some testing situations.</li>
<li><i>classpath</i>: Databases are treated as read-only databases, and all <i>databaseNames</i> must
begin with at least a slash, because you specify them "relative" to the classpath
directory. See <xref href="cdevdvlp91854.dita#cdevdvlp91854"></xref> for details.</li>
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp18166.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp18166.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp18166.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp18166.dita Thu Apr 22 15:02:04 2010
@@ -21,6 +21,7 @@ limitations under the License.
<concept id="cdevdvlp18166" xml:lang="en-us">
<title>Storage and recovery</title>
<shortdesc>A <ph conref="../conrefs.dita#prod/productshortname"></ph> database
+(unless it is an in-memory database)
provides persistent storage and recovery. <ph conref="../conrefs.dita#prod/productshortname"></ph> ensures
that all committed transactions are durable, even if the system fails, through
the use of a database transaction log.</shortdesc>
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp19297.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp19297.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp19297.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp19297.dita Thu Apr 22 15:02:04 2010
@@ -39,9 +39,7 @@ your databases there is the recommended
<li>Once you connect to a database, it is part of the current system and thus
inherits all system-wide properties.</li>
<li>Only one instance of <ph conref="../conrefs.dita#prod/productshortname"></ph> can
-run in a JVM at a single time, and only one instance of <ph conref="../conrefs.dita#prod/productshortname"></ph> should
-boot a database at one time. Keeping databases in the system directory makes
-it less likely that you would use more than one instance of <ph conref="../conrefs.dita#prod/productshortname"></ph>.</li>
+run in a JVM at a single time.</li>
<li>The error log is located inside the system directory.</li>
</ul></p>
</conbody>
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp19700.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp19700.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp19700.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp19700.dita Thu Apr 22 15:02:04 2010
@@ -23,5 +23,9 @@ limitations under the License.
<shortdesc>You can also access databases from the classpath or from a jar
file (in the classpath or not) as read-only databases.</shortdesc>
<prolog></prolog>
-<conbody></conbody>
+<conbody>
+<p>You can create in-memory databases for use in testing and development and for
+processing temporary or reproducible data. See
+<xref href="cdevdvlpinmemdb.dita#cdevdvlpinmemdb"></xref> for details.</p>
+</conbody>
</concept>
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp27610.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp27610.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp27610.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp27610.dita Thu Apr 22 15:02:04 2010
@@ -61,5 +61,6 @@ href="cdevdvlp25889.dita#cdevdvlp25889">
has the same name as the database (see <xref href="cdevdvlp21955.dita#cdevdvlp21955"></xref>).</p>
<p>In addition, if you connect to a database outside the current system, it
automatically becomes part of the current system.</p>
+<note>In-memory databases do not appear in the system directory.</note>
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp40350.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp40350.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp40350.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp40350.dita Thu Apr 22 15:02:04 2010
@@ -21,7 +21,7 @@ limitations under the License.
<concept id="cdevdvlp40350" xml:lang="en-us">
<title>Conventions for specifying the database path</title>
<shortdesc>When accessing databases from the file system (instead of from
-classpath or a jar file), any path that is not absolute is interpreted as
+memory, the classpath, or a jar file), any path that is not absolute is interpreted as
relative to the system directory.</shortdesc>
<prolog><metadata>
<keywords><indexterm>Databases<indexterm>convention for specifying connection
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp40724.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp40724.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp40724.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp40724.dita Thu Apr 22 15:02:04 2010
@@ -34,6 +34,11 @@ in Derby</indexterm><indexterm>tables<in
<indexterm>rows<indexterm>table size limitations</indexterm></indexterm></keywords>
</metadata></prolog>
<conbody>
+<note>An in-memory database does not use the file system, but the size limits
+listed in the table
+<xref href="cdevdvlp40724.dita#cdevdvlp40724/cdevdvlp85623"></xref> still
+apply. For some limits, the maximum value is determined by the available main
+memory instead of the available disk space and file system limitations.</note>
<p>A database directory contains the following, as shown in the following
figure.</p>
<ul>
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp42173.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp42173.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp42173.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp42173.dita Thu Apr 22 15:02:04 2010
@@ -29,7 +29,9 @@ URL.</shortdesc>
<indexterm>Databases<indexterm>backing up</indexterm></indexterm></keywords>
</metadata></prolog>
<conbody>
-<p>There is no drop database command. To drop a database, delete the database
+<p>If you use an in-memory database, you can use a connection URL attribute
+to drop it. For a file system database, however, there is no drop attribute. To
+drop a database on the file system, delete the database
directory with operating system commands. The database must not be booted
when you remove a database. You can get a list of booted databases with <i>getPropertyInfo</i>.</p>
<p>To back up a database, you can use the online backup utility. For information
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp846369.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp846369.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp846369.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp846369.dita Thu Apr 22 15:02:04 2010
@@ -20,7 +20,7 @@ limitations under the License.
-->
<concept id="cdevdvlp846369" xml:lang="en-us">
<title>Connecting to databases within the system</title>
-<shortdesc>The standard way to access databases is in the file system by specifying
+<shortdesc>The standard way to access databases in the file system is by specifying
the path to the database, either absolute or relative to the system directory.
In a client/server environment, this path is always on the <i>server</i> machine.</shortdesc>
<prolog><metadata>
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp96597.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp96597.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp96597.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp96597.dita Thu Apr 22 15:02:04 2010
@@ -19,21 +19,30 @@ See the License for the specific languag
limitations under the License.
-->
<concept id="cdevdvlp96597" xml:lang="en-us">
-<title>One Derby instance for each Java Virtual Machine</title>
+<title>One Derby instance for each Java Virtual Machine (JVM)</title>
<shortdesc>You could potentially have two instances of a <ph conref="../conrefs.dita#prod/productshortname"></ph> system
-(JVM) running on the same machine at the same time. Each instance must run
-in a different JVM. Two separate instances of <ph conref="../conrefs.dita#prod/productshortname"></ph> must
-not access the same database.</shortdesc>
+running on the same machine at the same time. Each instance must run
+in a different Java Virtual Machine (JVM).</shortdesc>
<prolog><metadata>
<keywords><indexterm>Multiple JVMs accessing<indexterm>prohibition of</indexterm></indexterm>
<indexterm> single system<indexterm>prohibition of</indexterm></indexterm>
</keywords>
</metadata></prolog>
<conbody>
-<p>For example, in an embedded environment, an application that accesses <ph
-conref="../conrefs.dita#prod/productshortname"></ph> databases starts up the
-local JDBC driver, which starts up an instance of <ph conref="../conrefs.dita#prod/productshortname"></ph>.
-If you start another application, such as ij, and connect to the same database,
-severe database corruption can result. See <xref href="cdevdvlp20458.dita#cdevdvlp20458"></xref>.</p>
+<p>If you use the embedded driver, two
+separate instances of <ph conref="../conrefs.dita#prod/productshortname"></ph>
+cannot access the same database. If
+a <ph conref="../conrefs.dita#prod/productshortname"></ph> instance attempts
+to access a running database, an error message appears, and a stack trace
+appears in the <i>derby.log</i> file. If you want more than one
+<ph conref="../conrefs.dita#prod/productshortname"></ph> instance to be able
+to access the same database, you can use the Network Server.</p>
+<p>If a <ph conref="../conrefs.dita#prod/productshortname"></ph> instance
+uses the in-memory database capability for its database connection, the database
+exists only within the JVM of that
+<ph conref="../conrefs.dita#prod/productshortname"></ph> instance. Another
+<ph conref="../conrefs.dita#prod/productshortname"></ph> instance could refer to
+the same database name, but it would not be referring to the same actual
+database, and no error would result.</p>
</conbody>
</concept>
Added: db/derby/docs/trunk/src/devguide/cdevdvlpinmemdb.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlpinmemdb.dita?rev=936885&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlpinmemdb.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevdvlpinmemdb.dita Thu Apr 22 15:02:04 2010
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<concept id="cdevdvlpinmemdb" xml:lang="en-us">
+<title>Using in-memory databases</title>
+<shortdesc>For testing and developing applications, or for processing transient
+or reproducible data, you can use
+<ph conref="../conrefs.dita#prod/productshortname"></ph>'s in-memory database
+facility.</shortdesc>
+<prolog><metadata><keywords>
+<indexterm>in-memory databases</indexterm>
+<indexterm>databases<indexterm>in-memory</indexterm></indexterm>
+</keywords></metadata></prolog>
+<conbody>
+<p>An in-memory database resides completely in main memory, not in the file
+system. It is useful for testing and developing applications, when you may want
+to create and discard databases that will never be used again. It is also
+useful when you need to process only temporary or reproducible data.</p>
+<p>If you have the required memory available, you may also benefit from faster
+processing (no disk I/O) and from the simplicity of not having to explicitly
+delete databases you have finished with.</p>
+<section><title>Creating an in-memory database</title>
+<p>To create an in-memory database, specify <codeph>memory</codeph> as the JDBC
+subsubprotocol. For example, to create an in-memory database named
+<codeph>myDB</codeph> using the embedded driver, use the following connection
+URL:</p>
+<codeblock>jdbc:derby:memory:myDB;create=true</codeblock>
+<p>For the network client driver, use the following connection URL. Because
+the client driver does not understand the <codeph>memory</codeph>
+subsubprotocol, you must include it in the database name:</p>
+<codeblock>jdbc:derby://<i>myhost</i>:1527/memory:myDB;create=true</codeblock>
+<p>Be careful to specify a colon (<codeph>:</codeph>) after
+<codeph>memory</codeph>.</p>
+</section>
+<section><title>Using in-memory databases</title>
+<p>When you use an in-memory database, you need to make sure to configure the
+heap and the <ph conref="../conrefs.dita#prod/productshortname"></ph> page
+cache size. See "Configure
+<ph conref="../conrefs.dita#prod/productshortname"></ph> to use an in-memory
+database" in <ph conref="../conrefs.dita#pub/cittuning"></ph> for details.</p>
+<p>For examples of how to use an in-memory database, see some of the
+<codeph>ij</codeph> command examples in the
+<ph conref="../conrefs.dita#pub/citutilities"></ph> (<codeph>execute</codeph>
+and <codeph>async</codeph>, for example).</p>
+</section>
+<section><title>Removing an in-memory database</title>
+<p>To remove an in-memory database, use the connection URL attribute <i>drop</i>
+as follows:</p>
+<codeblock>jdbc:derby:memory:myDB;drop=true</codeblock>
+<codeblock>jdbc:derby://<i>myhost</i>:1527/memory:myDB;drop=true</codeblock>
+<p>You can shut down an in-memory database using the <i>shutdown=true</i>
+attribute before you drop the database, but this is optional. Dropping the
+database also performs the shutdown.</p>
+<p>When you drop the database,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> issues what appears to
+be an error but is actually an indication of success. You need to catch error
+08006, as described in "The WwdEmbedded program" in
+<ph conref="../conrefs.dita#pub/citgetstart"></ph>.</p>
+<p>
+If user
+<xref href="cdevcsecure36127.dita#cdevcsecure36127">authentication</xref>
+and
+<xref href="cdevcsecure36595.dita#cdevcsecure36595">SQL authorization</xref>
+are both enabled, only the
+<xref href="cdevcsecureDbOwner.dita#cdevcsecureDbOwner">database owner</xref>
+can drop the database.
+</p>
+<p>An in-memory database is automatically removed if any of the following
+happens:</p>
+<ul>
+<li>The Java Virtual Machine (JVM) is shut down normally (for example, if you
+exit the <codeph>ij</codeph> tool)</li>
+<li>The JVM crashes</li>
+<li>The machine you are running on crashes or shuts down</li>
+</ul>
+</section>
+<section><title>Persisting an in-memory database</title>
+<p>If you create an in-memory database and then decided that you want to keep it
+after all, you can use one of the backup system procedures
+(SYSCS_UTIL.SYSCS_BACKUP_DATABASE, for example) to persist it. You can then boot
+it as an in-memory database at a later time, or use it as a normal file system
+database. See "Backing up and restoring databases" in
+<ph conref="../conrefs.dita#pub/citadmin"></ph> for information on using the
+backup procedures.</p>
+</section>
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/devguide/cdevdvlpinmemdb.dita
------------------------------------------------------------------------------
svn:eol-style = native
Modified: db/derby/docs/trunk/src/devguide/derbydev.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/derbydev.ditamap?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/derbydev.ditamap (original)
+++ db/derby/docs/trunk/src/devguide/derbydev.ditamap Thu Apr 22 15:02:04 2010
@@ -1587,7 +1587,7 @@ system"></topicref>
<topicref href="cdevadvjdbc32436.dita" navtitle="Using Derby with IDEs"></topicref>
</relcell>
<relcell>
-<topicref href="cdevdvlp96597.dita" navtitle="One Derby instance for each Java Virtual Machine">
+<topicref href="cdevdvlp96597.dita" navtitle="One Derby instance for each Java Virtual Machine (JVM)">
</topicref>
<topicref href="cdevdvlp40653.dita" navtitle="Derby JDBC driver">
</topicref>
@@ -1738,7 +1738,7 @@ system"></topicref>
<topicref href="cdevdvlp17453.dita" navtitle="Derby JDBC database connection URL">
</topicref>
<topicref href="cdevdvlp27610.dita" navtitle="Derby system">
-<topicref href="cdevdvlp96597.dita" navtitle="One Derby instance for each Java Virtual Machine">
+<topicref href="cdevdvlp96597.dita" navtitle="One Derby instance for each Java Virtual Machine (JVM)">
</topicref>
<topicref href="cdevdvlp27715.dita" navtitle="Booting databases"></topicref>
<topicref href="tdevdvlp20349.dita" navtitle="Shutting down the system"></topicref>
@@ -1800,6 +1800,7 @@ system"></topicref>
</topicref>
</topicref>
</topicref>
+<topicref href="cdevdvlpinmemdb.dita" navtitle="Using in-memory databases"></topicref>
<topicref collection-type="family" href="cdevsetprop34818.dita" navtitle="Working with Derby properties">
<topicref collection-type="family" href="cdevsetprop11108.dita" navtitle="Properties overview">
<topicref href="cdevsetprop824451.dita" navtitle="Scope of properties"></topicref>
Modified: db/derby/docs/trunk/src/devguide/rdevdvlp22102.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevdvlp22102.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevdvlp22102.dita (original)
+++ db/derby/docs/trunk/src/devguide/rdevdvlp22102.dita Thu Apr 22 15:02:04 2010
@@ -56,6 +56,9 @@ it does not exist.</p></li>
</p></li>
<li><i>jdbc:derby:/myDB</i> <p>Access <i>myDB</i> (which is directly in
a directory in the classpath) as a read-only database.</p></li>
+<li><i>jdbc:derby:memory:myDB</i> <p>Access the in-memory database named
+<i>myDB</i>. The syntax for a client connection URL is different; see
+<xref href="cdevdvlpinmemdb.dita#cdevdvlpinmemdb"></xref> for details.</p></li>
<li><i>jdbc:derby:classpath:/myDB</i> <p>Access <i>myDB</i> (which is directly
in a directory in the classpath) as a read-only database. The reason for using
the subsubprotocol is that it might have the same path as a database in the
Modified: db/derby/docs/trunk/src/ref/refderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/refderby.ditamap?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/refderby.ditamap (original)
+++ db/derby/docs/trunk/src/ref/refderby.ditamap Thu Apr 22 15:02:04 2010
@@ -633,6 +633,8 @@ URL syntax"></topicref>
</topicref>
<topicref href="rrefattrib15290.dita" navtitle="dataEncryption=true attribute">
</topicref>
+<topicref href="rrefattribdrop.dita" navtitle="drop=true attribute">
+</topicref>
<topicref href="rrefattribencryptkey.dita" navtitle="encryptionKey=key attribute">
</topicref>
<topicref href="rrefattrib88843.dita" navtitle="encryptionProvider=providerName attribute">
Modified: db/derby/docs/trunk/src/ref/rrefattrib16471.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattrib16471.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefattrib16471.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefattrib16471.dita Thu Apr 22 15:02:04 2010
@@ -54,10 +54,15 @@ writing all data and transaction informa
to be performed at the next connection.</p> <p>Used to shut down the entire
system only when it is embedded in an application. <note>Any request to
the <i>DriverManager</i> with a <i>shutdown=true</i> attribute raises an exception.</note></p> </section>
-<example> <codeblock><b><ph>-- shuts down entire system</ph>
+<example><title>Examples</title>
+<codeblock><b><ph>-- shut down entire system</ph>
jdbc:derby:;shutdown=true
-<ph>-- shuts down salesDB (authentication not enabled)</ph>
-jdbc:derby:salesDB;shutdown=true</b></codeblock> </example>
+<ph>-- shut down salesDB (authentication not enabled)</ph>
+jdbc:derby:salesDB;shutdown=true
+<ph>-- shut down an in-memory database using the embedded driver</ph>
+jdbc:derby:memory:myInMemDB;shutdown=true
+<ph>-- shut down an in-memory database using the Network Server</ph>
+jdbc:derby://localhost:1527/memory:myInMemDB;shutdown=true</b></codeblock> </example>
</refbody>
</reference>
Modified: db/derby/docs/trunk/src/ref/rrefattrib17246.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattrib17246.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefattrib17246.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefattrib17246.dita Thu Apr 22 15:02:04 2010
@@ -22,22 +22,28 @@ limitations under the License.
<title>databaseName=nameofDatabase attribute</title>
<prolog><metadata>
<keywords><indexterm>databaseName=nameOfDatabase database connection URL
-attribute</indexterm></keywords>
-</metadata></prolog>
+attribute</indexterm>
+<indexterm>Connecting to a database (using databaseName attribute)</indexterm>
+</keywords></metadata></prolog>
<refbody>
<section><title>Function</title> <p>Specifies a database name for a connection;
-it can be used instead of specifying the database name in after the subprotocol<i>.</i></p> <p><indexterm>Connecting
-to a database (using databaseName attribute)</indexterm>For example, these
+it can be used instead of specifying the database name after the subprotocol.</p> <p>For example, these
URL (and Properties object) combinations are equivalent: <ul>
<li><i>jdbc:derby:toursDB</i></li>
<li><i>jdbc:derby:;databaseName=toursDB</i></li>
<li><i>jdbc:derby:</i>(with a property <i>databaseName</i> and its value set
to <i>toursDB</i> in the <i>Properties</i> object passed into a connection
request)</li>
-</ul></p> <p>If the database name is specified both in the URL (as a subname)
+</ul></p>
+<p>If you use a subsubprotocol to specify the database (for example,
+<i>memory</i> for an in-memory database), include the subsubprotocol
+as part of the <i>databaseName</i> attribute specification. For example:</p>
+<codeblock><b>jdbc:derby:;databaseName=memory:myDB</b></codeblock>
+<p>If the database name is specified both in the URL (as a subname)
and as an attribute, the database name set as the subname has priority. For
-example, the following database connection URL connects to <i>toursDB</i>:</p> <codeblock><b>jdbc:derby:toursDB;databaseName=flightsDB</b></codeblock
-> <p>Allowing the database name to be set as an attribute allows the <i>getPropertyInfo</i> method
+example, the following database connection URL connects to <i>toursDB</i>:</p>
+<codeblock><b>jdbc:derby:toursDB;databaseName=flightsDB</b></codeblock>
+<p>Allowing the database name to be set as an attribute allows the <i>getPropertyInfo</i> method
to return a list of choices for the database name based on the set of databases
known to <ph conref="../conrefs.dita#prod/productshortname"></ph>. For more
information, see <i><xref href="rrefjdbc34954.dita#rrefjdbc34954"></xref>.</i></p> </section>
Modified: db/derby/docs/trunk/src/ref/rrefattrib24612.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattrib24612.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefattrib24612.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefattrib24612.dita Thu Apr 22 15:02:04 2010
@@ -25,8 +25,9 @@ a JDBC feature.</shortdesc>
<refbody>
<section><p>The attributes are specific to <ph conref="../conrefs.dita#prod/productshortname"></ph>.</p></section>
<section><p>You typically set attributes in a semicolon-separated list following
-the protocol and subprotocol. For information on how you set attributes, see <xref
-href="rrefjdbc10889.dita#rrefjdbc10889"></xref>. This chapter provides reference
+the protocol and subprotocol (and, in some cases, the subsubprotocol). For
+information on how you set attributes, see <xref
+href="rrefjdbc10889.dita#rrefjdbc10889"></xref>. This section provides reference
information only.</p></section>
<section> <note>Attributes are not parsed for correctness. If you pass in
an incorrect attribute or corresponding value, it is simply ignored.</note></section>
Modified: db/derby/docs/trunk/src/ref/rrefattrib26867.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattrib26867.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefattrib26867.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefattrib26867.dita Thu Apr 22 15:02:04 2010
@@ -47,6 +47,7 @@ before the next attempt to create the da
<ph conref="../conrefs.dita#pub/citdevelop"></ph>),
only the database owner can
<xref href="rrefattrib16471.dita#rrefattrib16471">shut down</xref>
+ or <xref href="rrefattribdrop.dita#rrefattribdrop">drop</xref>
the database,
<xref href="rrefattrib15290.dita#rrefattrib15290">encrypt</xref> it,
reencrypt it with a new
@@ -60,15 +61,28 @@ before the next attempt to create the da
</p>
</section>
<section><title>Combining with other attributes</title> <p>You
-must specify a <i>databaseName</i> (after the subprotocol in the database
+must specify a <i>databaseName</i> (after the subprotocol or subsubprotocol in
+the database
connection URL) or a <i><xref href="rrefattrib17246.dita#rrefattrib17246">databaseName=nameofDatabase</xref></i> attribute
with this attribute.</p> <p>You can combine this attribute with other attributes.
To specify a territory when creating a database, use the <i><xref href="rrefattrib56769.dita#rrefattrib56769">territory=ll_CC</xref></i> attribute.
- <note>If you specify <i>create=true</i> and the database already exists,
-an <i>SQLWarning</i> is raised.</note></p> </section>
-<example> <codeblock><b>jdbc:derby:sampleDB;create=true
-
-jdbc:derby:;databaseName=newDB;create=true;</b></codeblock> </example>
+</p> </section>
+<example><title>Examples</title>
+<p>Creating a file system database:</p>
+<codeblock><b><ph>-- create a file system database</ph>
+jdbc:derby:sampleDB;create=true
+<ph>-- create a file system database using the databaseName attribute</ph>
+jdbc:derby:;databaseName=newDB;create=true
+<ph>-- create an in-memory database using the embedded driver</ph>
+jdbc:derby:memory:myInMemDB;create=true
+<ph>-- create an in-memory database using the databaseName attribute</ph>
+jdbc:derby:;databaseName=memory:myInMemDB;create=true
+<ph>-- create an in-memory database using the Network Server</ph>
+jdbc:derby://localhost:1527/memory:myInMemDB;create=true</b></codeblock>
+<p>See "Using in-memory databases" in the
+<ph conref="../conrefs.dita#pub/citdevelop"/> for information on creating
+in-memory databases.</p>
+</example>
</refbody>
</reference>
Added: db/derby/docs/trunk/src/ref/rrefattribdrop.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattribdrop.dita?rev=936885&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefattribdrop.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefattribdrop.dita Thu Apr 22 15:02:04 2010
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<reference id="rrefattribdrop" xml:lang="en-us">
+<title>drop=true attribute</title>
+<prolog><metadata>
+<keywords><indexterm>drop=true database connection URL attribute</indexterm>
+<indexterm>in-memory databases<indexterm>removing</indexterm></indexterm>
+<indexterm>databases<indexterm>removing in-memory</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section><title>Function</title>
+<p>Removes the in-memory database specified within the database connection URL.
+Generates the <i>SQLException</i> 08006 if successful. If the database does not
+exist, generates an error reporting that the database could not be found.</p>
+<p>For a database for which authentication and SQL authorization are both
+enabled, only the
+<xref href="rrefattrib26867.dita#rrefattrib26867">database owner</xref>
+can drop that database.
+</p>
+<p>It is not necessary to shut down the database before dropping it.</p>
+<p>If you specify this attribute with a database that is not an in-memory
+database, <ph conref="../conrefs.dita#prod/productshortname"></ph> generates the
+<i>SQLException</i> XBM0I.</p>
+</section>
+<section><title>Combining with other attributes</title>
+<p>This attribute, like
+<i><xref href="rrefattrib16471.dita#rrefattrib16471">shutdown=true</xref></i>,
+cannot be combined with other attributes.</p>
+</section>
+<example><title>Examples</title>
+<codeblock><b><ph>-- drop an in-memory database using the embedded driver</ph>
+jdbc:derby:memory:myInMemDB;drop=true
+<ph>-- drop an in-memory database using the Network Server</ph>
+jdbc:derby://localhost:1527/memory:myInMemDB;drop=true</b></codeblock>
+</example>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/ref/rrefattribdrop.dita
------------------------------------------------------------------------------
svn:eol-style = native
Modified: db/derby/docs/trunk/src/tools/rtoolsijcomref22318.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/rtoolsijcomref22318.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tools/rtoolsijcomref22318.dita (original)
+++ db/derby/docs/trunk/src/tools/rtoolsijcomref22318.dita Thu Apr 22 15:02:04 2010
@@ -43,7 +43,7 @@ becomes the current one and ij displays
to be entered. If you have more than one open connection, the name of the
connection appears in the prompt.</p><p>All further commands are processed
against the new, current connection.</p> </section>
-<example><title>Example</title><codeblock>ij> <b>connect 'jdbc:derby:menuDB;create=true';</b>
+<example><title>Examples</title><codeblock>ij> <b>connect 'jdbc:derby:menuDB;create=true';</b>
ij> -- we create a new table in menuDB:
<b>CREATE TABLE menu(course CHAR(10), item CHAR(20), price INTEGER);</b>
ij> <b>protocol 'jdbc:derby:';</b>
@@ -55,6 +55,11 @@ NEWDB* - jdbc:derby:anotherDB
SAMPLE1 - jdbc:derby:newDB
ij>
ij> <b>connect 'jdbc:derby:sample' user 'sa' password 'cloud3x9';</b>
-ij></codeblock> </example>
+ij></codeblock>
+<codeblock>ij> <b>protocol 'jdbc:derby:';</b>
+ij> <b>connect 'memory:sample;create=true';</b></codeblock>
+<codeblock>ij> <b>protocol 'jdbc:derby:memory:';</b>
+ij> <b>connect 'sample;create=true';</b></codeblock>
+</example>
</refbody>
</reference>
Modified: db/derby/docs/trunk/src/tools/rtoolsijcomref27997.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/rtoolsijcomref27997.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tools/rtoolsijcomref27997.dita (original)
+++ db/derby/docs/trunk/src/tools/rtoolsijcomref27997.dita Thu Apr 22 15:02:04 2010
@@ -34,12 +34,17 @@ and the protocol specific to <ph conref=
see the <cite><ph conref="../conrefs.dita#pub/citdevelop"></ph></cite>. Only <ph conref="../conrefs.dita#prod/productshortname"></ph> protocols are supported.
Those protocols are listed in <xref href="rtoolsijpropref35032.dita#rtoolsijpropref35032"/>.</p>
<p>Providing a protocol allows you to use a shortened database connection URL for connections.
-You can provide only the database name instead of the full protocol. In addition,
+You can provide only the database name (and a subsubprotocol name if needed)
+instead of the full protocol. In addition,
you do not need to use the <xref href="rtoolsijcomref39042.dita#rtoolsijcomref39042">Driver</xref> command
or specify a driver at start-up, since the driver is loaded automatically.</p>
<p>If you name the protocol, you can refer to the protocol name in the <xref href="rtoolsijcomref22318.dita#rtoolsijcomref22318">Connect</xref> command.</p>
</section>
-<example><title>Example</title>
+<example><title>Examples</title>
<codeblock>ij> <b>protocol 'jdbc:derby:';</b>
ij> <b>connect 'sample';</b></codeblock>
+<codeblock>ij> <b>protocol 'jdbc:derby:';</b>
+ij> <b>connect 'memory:sample;create=true';</b></codeblock>
+<codeblock>ij> <b>protocol 'jdbc:derby:memory:';</b>
+ij> <b>connect 'sample;create=true';</b></codeblock>
</example></refbody></reference>
Modified: db/derby/docs/trunk/src/tuning/ctunperf25864.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunperf25864.dita?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunperf25864.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunperf25864.dita Thu Apr 22 15:02:04 2010
@@ -43,8 +43,11 @@ startup time can be improved by reducing
directory. </li>
<li><i><xref href="ctunperf16800.dita#ctunperf16800">Avoid inserts in autocommit mode if possible</xref></i>. Speed
up insert performance.</li>
-<li><i><xref href="ctunperftablefunctions.dita#ctunperftablefunctions">Customize the optimizer methods for table functions</xref></i>. Force
+<li><i><xref href="ctunperftablefunctions.dita#ctunperftablefunctions">Improve the performance of table functions</xref></i>. Force
more efficient join orders for queries which use table functions.</li>
+<li><i><xref href="ctunperfinmemdb.dita#ctunperfinmemdb"></xref></i>. Tune the
+Java heap and <ph conref="../conrefs.dita#prod/productshortname"></ph> page
+cache size when using an in-memory database.</li>
</ul>
<p>These tips might solve your particular performance problem. Be sure to
visit the Support section of <ph conref="../conrefs.dita#prod/productshortname"></ph>'s Web site for up-to-date performance
Added: db/derby/docs/trunk/src/tuning/ctunperfinmemdb.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunperfinmemdb.dita?rev=936885&view=auto
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunperfinmemdb.dita (added)
+++ db/derby/docs/trunk/src/tuning/ctunperfinmemdb.dita Thu Apr 22 15:02:04 2010
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<concept id="ctunperfinmemdb" xml:lang="en-us">
+<title>Configure <ph conref="../conrefs.dita#prod/productshortname"></ph> to
+use an in-memory database</title>
+<prolog><metadata><keywords>
+<indexterm>in-memory databases<indexterm>configuring</indexterm></indexterm>
+<indexterm>databases<indexterm>in-memory</indexterm></indexterm>
+</keywords></metadata></prolog>
+<conbody>
+<p>If you use
+<ph conref="../conrefs.dita#prod/productshortname"></ph>'s in-memory database
+facility, it is important to configure the following:</p>
+<ul>
+<li><i>The size of the Java heap.</i> The memory requirements for an in-memory
+database should be similar to the memory requirements for using the file system,
+plus the size of the user data.</li>
+<li><i>The <ph conref="../conrefs.dita#prod/productshortname"></ph> page cache
+size.</i> For good performance, use no less than the default size of 1000 pages.
+The data must pass through the page cache, even though the user data is already
+stored in main memory. A larger page cache may improve performance at the
+expense of increased memory usage. See
+<xref href="ctunperf54492.dita#ctunperf54492"></xref> for more information.</li>
+</ul>
+<p>If you want to prevent
+<ph conref="../conrefs.dita#prod/productshortname"></ph> from writing anything
+to the <i>derby.log</i> file, use one of the <i>derby.stream.error</i>
+properties (for instance, <i>derby.stream.error.field</i>).</p>
+<p>For more information, see "Using in-memory databases" in the
+<ph conref="../conrefs.dita#pub/citdevelop"></ph>.</p>
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/tuning/ctunperfinmemdb.dita
------------------------------------------------------------------------------
svn:eol-style = native
Modified: db/derby/docs/trunk/src/tuning/tuningderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/tuningderby.ditamap?rev=936885&r1=936884&r2=936885&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/tuningderby.ditamap (original)
+++ db/derby/docs/trunk/src/tuning/tuningderby.ditamap Thu Apr 22 15:02:04 2010
@@ -62,7 +62,9 @@ toc="no"></topicref>
</topicref>
<topicref href="ctunperf16800.dita" navtitle="Avoid inserts in autocommit mode if possible">
</topicref>
-<topicref href="ctunperftablefunctions.dita" navtitle="Customize the optimizer methods for table functions">
+<topicref href="ctunperftablefunctions.dita" navtitle="Improve the performance of table functions">
+</topicref>
+<topicref href="ctunperfinmemdb.dita" navtitle="Configure Derby to use an in-memory database">
</topicref>
</topicref>
<topicref collection-type="family" href="ctunperf31086.dita" navtitle="More tips">