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 2013/11/06 23:27:23 UTC
svn commit: r1539484 - in /db/derby/docs/trunk/src/adminguide:
cadminhubbkup01.dita cadminrollforward.dita tadminlog800206.dita
Author: chaase3
Date: Wed Nov 6 22:27:23 2013
New Revision: 1539484
URL: http://svn.apache.org/r1539484
Log:
DERBY-6399 clarify backup section in Derby Server and Administration Guide regarding connecting to the backed up db
Modified 3 Admin Guide topics.
Patch: DERBY-6399-3.diff
Modified:
db/derby/docs/trunk/src/adminguide/cadminhubbkup01.dita
db/derby/docs/trunk/src/adminguide/cadminrollforward.dita
db/derby/docs/trunk/src/adminguide/tadminlog800206.dita
Modified: db/derby/docs/trunk/src/adminguide/cadminhubbkup01.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/cadminhubbkup01.dita?rev=1539484&r1=1539483&r2=1539484&view=diff
==============================================================================
--- db/derby/docs/trunk/src/adminguide/cadminhubbkup01.dita (original)
+++ db/derby/docs/trunk/src/adminguide/cadminhubbkup01.dita Wed Nov 6 22:27:23 2013
@@ -35,7 +35,8 @@ system procedure</indexterm></keywords>
<li>SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE</li>
<li>SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE_NOWAIT </li>
</ul>
-<p>Use the SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE
+<p>Use the SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE or
+SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE_NOWAIT
procedure if you want to make it possible to perform a roll-forward recovery of
a damaged database. See
<xref href="cadminrollforward.dita#cadminrollforward"></xref> for details.</p>
@@ -44,7 +45,7 @@ in progress with unlogged operations to
backup; instead, they return an error immediately.</p>
<p>See the <ph conref="../conrefs.dita#pub/citref"></ph> for details about these
system procedures.</p>
-<p>The SYSCS_UTIL.SYSCS_BACKUP_DATABASE procedure takes a string argument
+<p>All four of these system procedures take a string argument
that represents the location in which to back up the database. Typically,
you provide the full path to the backup directory. (Relative paths are interpreted
as relative to the current directory, not to the derby.system.home directory.)</p>
@@ -52,7 +53,8 @@ as relative to the current directory, no
a database that is currently open, use the following statement (forward slashes
are used as path separators in SQL commands):</p>
<codeblock><b>CALL SYSCS_UTIL.SYSCS_BACKUP_DATABASE('c:/mybackups/2012-04-01')</b></codeblock>
-<p>The SYSCS_UTIL.SYSCS_BACKUP_DATABASE procedure puts the database
+<p>The SYSCS_UTIL.SYSCS_BACKUP_DATABASE or
+SYSCS_UTIL.SYSCS_BACKUP_DATABASE_NOWAIT procedure puts the database
into a state in which it can be safely copied. The procedure then copies the
entire original database directory (including data files, online transaction log
files, and jar files) to the specified backup directory. Files that are not
@@ -60,6 +62,16 @@ within the original database directory (
are <i>not</i> copied. With the exception of a few cases mentioned in
<xref href="cadminhubbkup01.dita#cadminhubbkup01/hubbkupunlogged"></xref>,
the procedure does not block concurrent transactions at any time.</p>
+<p>A backup made with the
+SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE or
+SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE_NOWAIT procedure is
+not a full copy of the database, but depends on the log files created in the
+database since the backup. An attempt to access the backup directly will
+invalidate the backup. The result could include a corrupted database, missing
+data, errors during a subsequent attempt at restoring the database, or database
+corruption errors encountered only once the restored database is being used. The
+only supported way to access this kind of backup is to restore the database as
+documented in <xref href="cadminrollforward.dita#cadminrollforward"></xref>.</p>
<p>The following example shows how to back up a database to a directory with
a name that reflects the current date:</p>
<codeblock>public static void backUpDatabase(Connection conn)throws SQLException
Modified: db/derby/docs/trunk/src/adminguide/cadminrollforward.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/cadminrollforward.dita?rev=1539484&r1=1539483&r2=1539484&view=diff
==============================================================================
--- db/derby/docs/trunk/src/adminguide/cadminrollforward.dita (original)
+++ db/derby/docs/trunk/src/adminguide/cadminrollforward.dita Wed Nov 6 22:27:23 2013
@@ -76,7 +76,7 @@ for log archival mode:</p>
location where the backup should be stored and specify whether or not the
database should keep online archived logs for the backup. Existing online
archived log files that were created before this backup will be deleted if
-the input parameter value for the <i>deleteOnlineArchivedLogFiles</i> parameter
+the input parameter value for the <i>DELETE_ARCHIVED_LOG_FILES</i> parameter
is non-zero. The log files are deleted only after a successful backup. <note>Make
sure to store the backup database in a safe place when you choose the log
file removal option.</note></p>
@@ -95,7 +95,7 @@ are complete, use the SYSCS_UTIL.SYSCS_B
procedure. This procedure issues an error immediately at the start of the
backup if there are any transactions in progress with unlogged operations,
instead of waiting for those transactions to complete.</p>
-<p><b>Disabling log archival mode:</b></p>
+<p><b>Disabling log archival mode</b></p>
<p>After you enable log archival mode, the database will always have the log
archival mode enabled even if it is subsequently booted or backed up. The
only way to disable the log archive mode is to run the following procedure:</p>
@@ -103,34 +103,65 @@ only way to disable the log archive mode
<p>This system procedure disables the log archive mode and deletes any existing
online archived log files if the input parameter <i>DELETE_ARCHIVED_LOG_FILES</i> is
non-zero.</p>
-<p><b>Performing roll-forward recovery:</b></p>
-<p>By using the full backup copy, archived logs, and active logs, you can
-restore a database to its most recent state by performing roll-forward recovery.
-You perform a roll-forward recovery by specifying the connection URL attribute <i>rollForwardRecoveryFrom=path</i> at
-boot time. This brings the database to its most recent state by using full
-backup copy, archived logs, and active logs. All the log files should be in
-the database log path directory.</p>
-<p>For more information, see "rollForwardRecoveryFrom=path attribute"
-in the <ph conref="../conrefs.dita#pub/citref"></ph>.</p>
-
-<p><b>Backing up a database:</b></p>
-<p>In the following example, a database named wombat is backed up to the d:/backup
-directory with log archive mode enabled:<codeblock>connect 'jdbc:derby:wombat;create=true';
-
-create table t1(a int not null primary key);
+<p><b>Performing roll-forward recovery</b></p>
+<p>If you have a backup made by using
+SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE or
+SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE_NOWAIT, you can
+restore it to its most recent state by using the full backup copy, archived
+logs, and active logs. You perform a roll-forward recovery by specifying the
+connection URL attribute <i>rollForwardRecoveryFrom=path</i> at boot time. All
+the log files should be in the database log path directory.</p>
+<p>The steps involved are as follows. They do not show the commands to start
+<codeph>ij</codeph>.</p>
+<ol>
+<li><b>Back up the database with log archive mode enabled.</b>
+<p>For example, you could back up a database named <codeph>wombat</codeph>
+to the <codeph>/backup</codeph> directory as follows. After many operations,
+the database crashes.</p>
+<codeblock>ij> <b>connect 'jdbc:derby:wombat;create=true';</b>
+ij> <b>create table t1(a int not null primary key);</b>
+0 rows inserted/updated/deleted
------------------DML/DDL Operations
-CALL SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE
-('d:/backup', 0);
-insert into t1 values(19);
-create table t2(a int);
+ij> <b>CALL SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE
+('/backup', 0);</b>
+0 rows inserted/updated/deleted
+ij> <b>insert into t1 values(19);</b>
+1 row inserted/updated/deleted
+ij> <b>create table t2(a int);</b>
+0 rows inserted/updated/deleted
-----------------DML/DDL Operations
------------------Database Crashed (Media Corruption on data disks)</codeblock></p>
-<p><b>Restoring a database using roll-forward recovery:</b></p>
-<p>In the following example, the database is restored using roll-forward recovery
-after a media failure:<codeblock>connect 'jdbc:derby:wombat;rollForwardRecoveryFrom=d:/backup/wombat';
-select * from t1;
----------------DML/DDL Operations</codeblock></p>
+-----------------Database Crashed (Media Corruption on data disks)</codeblock>
+</li>
+<li><b>Prepare the database for restoration.</b>
+<p>Before you restore the database, shut down the original database and rename
+the original database directory. For example, after shutdown, you could issue
+the following commands in a Linux shell:</p>
+<codeblock><b>mv /databases/wombat /databases/brokenwombat
+cd /databases</b></codeblock>
+</li>
+<li><b>Restore the database using roll-forward recovery.</b>
+<p>Since you moved the database, you need to specify the
+<i>logDevice=logDirectoryPath</i> attribute in addition to the
+<i>rollForwardRecoveryFrom=path</i> attribute when you restore the database
+using roll-forward recovery. Use commands like the following (the connection URL
+must be all on one line):</p>
+<codeblock>ij> <b>connect 'jdbc:derby:wombat;rollForwardRecoveryFrom=/backup/wombat;
+logDevice=/databases/brokenwombat';</b>
+ij> <b>select * from t1;</b>
+A
+-----------
+19
+
+1 row selected
+---------------DML/DDL Operations</codeblock>
<p>After a database is restored from full backup, transactions from the online
-archived logs and active logs are replayed.</p>
+archived logs and active logs are replayed. This brings the database to its most
+recent state. All the log files should be in the directory specified by the
+<i>logDevice=logDirectoryPath</i> attribute.</p>
+</li>
+</ol>
+<p>For more information, see "rollForwardRecoveryFrom=path attribute" and
+"logDevice=logDirectoryPath attribute" in the
+<ph conref="../conrefs.dita#pub/citref"></ph>.</p>
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/adminguide/tadminlog800206.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/tadminlog800206.dita?rev=1539484&r1=1539483&r2=1539484&view=diff
==============================================================================
--- db/derby/docs/trunk/src/adminguide/tadminlog800206.dita (original)
+++ db/derby/docs/trunk/src/adminguide/tadminlog800206.dita Wed Nov 6 22:27:23 2013
@@ -21,24 +21,29 @@ limitations under the License.
<task id="tadminlog800206" xml:lang="en-us">
<title>Using the logDevice=logDirectoryPath attribute</title>
<shortdesc>To specify a non-default location for the log directory, set
-the <codeph>logDevice=<i>logDirectoryPath</i></codeph> attribute on the database connection URL when
-you create the database.</shortdesc>
+the <codeph>logDevice=<i>logDirectoryPath</i></codeph> attribute on the database connection
+URL.</shortdesc>
<prolog><metadata>
<keywords><indexterm>logDevice</indexterm><indexterm>service.properties file<indexterm>setting
logDevice in</indexterm></indexterm></keywords>
</metadata></prolog>
<taskbody>
-<context> <p>This attribute is meaningful only when you are creating
-a database. You can specify <codeph>logDevice=<i>logDirectoryPath</i></codeph> as either an absolute
-path or as a path that is relative to the directory where the JVM is executed.</p> <p>Setting <codeph>logDevice=<i>logDirectoryPath</i></codeph> on
-the database connection URL adds an entry to the <i>service.properties</i> file.
+<context> <p>This attribute is meaningful when you are creating a database or
+when you are restoring a database using roll-forward recovery. You can specify
+<codeph>logDevice=<i>logDirectoryPath</i></codeph> as either an absolute path or
+as a path that is relative to the directory where the JVM is executed.</p>
+<p>Setting <codeph>logDevice=<i>logDirectoryPath</i></codeph> on
+the database connection URL when you create the database adds an entry to the
+<i>service.properties</i> file.
If you ever move the log manually, you will need to alter the entry in <i>service.properties</i>.
If you move the log back to the default location, remove the <i>logDevice</i> entry
from the <i>service.properties</i> file.</p> </context>
<example><p>To check the log location for an existing database, you can retrieve
the <codeph>logDevice=<i>logDirectoryPath</i></codeph> attribute as a database property by using the
following statement:</p><codeblock>VALUES SYSCS_UTIL.SYSCS_GET_DATABASE_PROPERTY('logDevice')</codeblock>
-<p>For more information, see "logDevice=logDirectoryPath attribute" in the
+<p>For more information, see
+<xref href="cadminrollforward.dita#cadminrollforward"></xref> in this manual and
+"logDevice=logDirectoryPath attribute" in the
<ph conref="../conrefs.dita#pub/citref"></ph>.</p>
</example>
</taskbody>