Library Version 12.1.6.0
Backing up and Restoring Berkeley DB Java Edition
Applications
12/7/2015
Getting Started with JE
Page 152
Cleaning the Log Files
Because JE uses no-overwrite log files, the logs must be compacted or cleaned so as to
conserve disk space.
JE uses the cleaner background thread to perform this task. When it runs, the cleaner thread
picks the log file with the smallest number of active records and scans each log record in it. If
the record is no longer active in the database tree, the cleaner does nothing. If the record is
still active in the tree, then the cleaner copies the record forward to a newer log file.
Once a log file is no longer needed (that is, it no longer contains active records), then the
cleaner thread deletes the log file for you. Or, optionally, the cleaner thread can simply
rename the discarded log file with a del suffix.
JE uses a minimum log utilization property to determine how much cleaning to perform.
The log files contain both obsolete and utilized records. Obsolete records are records
that are no longer in use, either because they have been modified or because they
have been deleted. Utilized records are those records that are currently in use. The
je.cleaner.minUtilization property identifies the minimum percentage of log space that
must be used by utilized records. If this minimum percentage is not met, then log files are
cleaned until the minimum percentage is met.
For information on managing the cleaner thread, see The Cleaner Thread (page 159).
The BTree
JE databases are internally organized as a BTree. In order to operate, JE requires the
complete BTree be available to it.
When database records are created, modified, or deleted, the modifications are represented
in the BTree's leaf nodes. Beyond leaf node changes, database record modifications can also
cause changes to other BTree nodes and structures.
Database Modifications and Syncs
When a write operation is performed in JE, the modified data is written to a leaf node
contained in the in-memory cache. If your JE writes are performed without transactions,
then the in-memory cache is the only location guaranteed to receive a database modification
without further intervention on the part of the application developer.
For some class of applications, this lack of a guaranteed write to disk is ideal. By not writing
these modifications to the on-disk logs, the application can avoid most of the overhead caused
by disk I/O.
However, if the application requires its data to persist persist at a specific point in time, then
the developer must manually sync database modifications to the on-disk log files (again, this is
only necessary for non-transactional applications). This is done using Environment.sync().
Note that syncing the cache causes JE to write all modified objects in the cache to disk. This
is probably the most expensive operation that you can perform in JE.
Pdf bookmarks - add, remove, update PDF bookmarks in C#.net, ASP.NET, MVC, Ajax, WinForms, WPF
Empower Your C# Project with Rapid PDF Internal Navigation Via Bookmark and Outline
create pdf with bookmarks from word; acrobat split pdf bookmark
Pdf bookmarks - VB.NET PDF bookmark library: add, remove, update PDF bookmarks in vb.net, ASP.NET, MVC, Ajax, WinForms, WPF
Empower Your VB.NET Project with Rapid PDF Internal Navigation Via Bookmark and Outline
adding bookmarks in pdf; creating bookmarks in a pdf document
Library Version 12.1.6.0
Backing up and Restoring Berkeley DB Java Edition
Applications
12/7/2015
Getting Started with JE
Page 153
Normal Recovery
Every time a JE environment is opened, normal recovery is run. Because of the way that JE
organizes and manages its BTrees, all it needs is leaf nodes in order to recreate the rest of the
BTree. Essentially, this is what normal recovery is doing – recreating any missing parts of the
internal BTree from leaf node information stored in the log files.
Unlike a traditional database system, JE performs recovery for both transactional and non-
transactional operations. The integrity of the Btree is guaranteed by JE in the face of both
application and OS crashes.
Performing Backups
This section describes how to backup your JE database(s) such that catastrophic recovery
is possible for non-transactional applications. Note that this same material is repeated in
the Berkeley DB, Java Edition Getting Started with Transaction Processing guide, but for
transactional applications. If you are writing transactional applications, you may want to skip
the rest of this chapter and go straight to that book.
To backup your database, you can either take a hot backup or an offline backup. A hot backup
is performed while database write operations are in progress.
Do not confuse hot and offline backups with the concept of a full and incremental backup.
Both a hot and an offline backup are full backups – you back up the entire database. The only
difference between them is how much of the contents of the in-memory cache are contained
in them. On the other hand, an incremental backup is a backup of just those log files modified
or created since the time of the last backup. Most backup software is capable of performing
both full and incremental backups for you.
Performing a Hot Backup
To perform a hot backup of your JE databases, copy all log files (*.jdb files) from your
environment directory to your archival location or backup media. The files must be copied in
alphabetical order (numerical in effect). You do not have to stop any database operations in
order to do this.
Note
If you are using subdirectories to store your log files, then you must backup the
subdirectories, making sure to keep log files in the subdirectory in which JE placed
them. For information on using subdirectories to store your log files, see Multiple
Environment Subdirectories (page 18).
To make this process a bit easier, you may want to make use of the DbBackup helper class. See
Using the DbBackup Helper Class (page 154) for details.
Note that any modifications made to the database since the time of the last environment sync
are not guaranteed to be contained in these log files. In this case, you may want to consider
running an offline backup in order to guarantee the availability of all modifications made to
your database.
VB.NET PDF File Compress Library: Compress reduce PDF size in vb.
document file. Remove bookmarks, annotations, watermark, page labels and article threads from PDF while compressing. Also a preview
pdf bookmark editor; bookmark pdf documents
C# PDF File Split Library: Split, seperate PDF into multiple files
Split PDF file by top level bookmarks. The following C# codes explain how to split a PDF file into multiple ones by PDF bookmarks or outlines.
how to add bookmark in pdf; pdf export bookmarks
Library Version 12.1.6.0
Backing up and Restoring Berkeley DB Java Edition
Applications
12/7/2015
Getting Started with JE
Page 154
Performing an Offline Backup
An offline backup guarantees that you have captured the database in its entirety, including all
contents of your in-memory cache, at the moment that the backup was taken. To do this, you
must make sure that no write operations are in progress and all database modifications have
been written to your log files on disk. To obtain an offline backup:
1. Stop writing your databases.
2. Run Environment.sync() so as to ensure that all database modifications are written
to disk. Note that cleanly closing your environment will also ensure that all database
modifications are written to disk.
3. Copy all log files (*.jdb) from your environment directory to your archival location
or backup media. To make this process a bit easier, you may want to make use of the
DbBackup helper class. See the next section for details.
Note
If you are using subdirectories to store your log files, then you must backup the
subdirectories, making sure to keep log files in the subdirectory in which JE
placed them. For information on using subdirectories to store your log files, see
Multiple Environment Subdirectories (page 18).
You can now resume normal database operations.
Using the DbBackup Helper Class
In order to simplify backup operations, JE provides the DbBackup helper class. This class stops
and restarts JE background activity in an open environment. It also lets the application create
a backup which can support restoring the environment to a specific point in time.
Because you do not have to stop JE write activity in order to take a backup, it is usually
necessary to examine your log files twice before you decide that your backup is complete.
This is because JE may create a new log file while you are running your backup. A second pass
over your log files allows you to ensure that no new files have been created and so you can
declare your backup complete.
For example:
time    files in                    activity
environment
t0     000000001.jdb     Backup starts copying file 1
000000003.jdb
000000004.jdb
t1     000000001.jdb     JE log cleaner migrates portion of file 3 to
000000004.jdb     newly created file 5 and deletes file 3. 
000000005.jdb     Backup finishes file 1, starts copying file 4.
Backup MUST include file 5 for a consistent 
VB.NET PDF File Split Library: Split, seperate PDF into multiple
Demo Code in VB.NET. The following VB.NET codes explain how to split a PDF file into multiple ones by PDF bookmarks or outlines.
how to bookmark a page in pdf document; pdf bookmark
C# PDF File Compress Library: Compress reduce PDF size in C#.net
NET framework. Remove bookmarks, annotations, watermark, page labels and article threads from PDF while compressing. C# class demo
export excel to pdf with bookmarks; bookmark pdf reader
Library Version 12.1.6.0
Backing up and Restoring Berkeley DB Java Edition
Applications
12/7/2015
Getting Started with JE
Page 155
backup!
t2     000000001.jdb     Backup finishes copying file 4, starts and 
000000004.jdb     finishes file 5, has caught up. Backup ends.
000000005.jdb
DbBackup works around this problem by defining the set of files that must be copied for
each backup operation, and freezes all changes to those files. The application can copy that
defined set of files and finish operation without checking for the ongoing creation of new
files. Also, there will be no need to check for a newer version of the last file on the next
backup.
In the example above, if DbBackup was used at t0, the application would only have to copy
files 1, 3 and 4 to back up. On a subsequent backup, the application could start its copying at
file 5. There would be no need to check for a newer version of file 4.
The following code fragment illustrates this class' usage. See the DbBackup javadoc for
additional examples and more information on incremental backups.
package je.gettingStarted;
...
import com.sleepycat.je.util.DbBackup;
...
// Find the file number of the last file in the previous backup
// persistently, by either checking the backup archive, or saving
// state in a persistent file.
long lastFileCopiedInPrevBackup =  ...
Environment env = new Environment(...);
DbBackup backupHelper = new DbBackup(env, lastFileCopiedInPrevBackup);
// Start backup, find out what needs to be copied.
// If multiple environment subdirectories are in use,
// the getLogFilesInBackupSet returns the log file
// name prefixed with the dataNNN/ directory in which
// it resides.
backupHelper.startBackup();
try {
String[] filesForBackup = backupHelper.getLogFilesInBackupSet();
// Copy the files to archival storage.
myApplicationCopyMethod(filesForBackup)
// Update our knowlege of the last file saved in the backup set,
// so we can copy less on the next backup
lastFileCopiedInPrevBackup = backupHelper.getLastFileInBackupSet();
myApplicationSaveLastFile(lastFileCopiedInBackupSet);
}
finally {
.NET PDF SDK - Description of All PDF Processing Control Feastures
Fully featured PDF Viewer in HTML5; Outstanding rendering of PDF documents; Full page navigation, zooming & rotation; Outlines, bookmarks, & thumbnail display;
pdf create bookmarks; how to add a bookmark in pdf
XDoc.Word for .NET, Advanced .NET Word Processing Features
& rotation; Outlines, bookmarks, & thumbnail display; Integrated annotation; More about Web Viewer ▶. Conversion. Word Create. Create Word from PDF; Create Word
create bookmarks pdf files; creating bookmarks pdf files
Library Version 12.1.6.0
Backing up and Restoring Berkeley DB Java Edition
Applications
12/7/2015
Getting Started with JE
Page 156
// Remember to exit backup mode, or all log files won't be cleaned
// and disk usage will bloat.
backupHelper.endBackup();
Performing Catastrophic Recovery
Catastrophic recovery is necessary whenever your environment and/or database have been
lost or corrupted due to a media failure (disk failure, for example). Catastrophic recovery is
also required if normal recovery fails for any reason.
In order to perform catastrophic recovery, you must have a full back up of your databases.
You will use this backup to restore your database. See Performing Backups (page 153) for
information on running back ups.
To perform catastrophic recovery:
1. Shut down your application.
2. Delete the contents of your environment home directory (the one that experienced a
catastrophic failure), if there is anything there.
3. Copy your most recent full backup into your environment home directory. If you are using
subdirectories to store your log files, be sure to place the recovered log files back into
the subdirectory from which they were originally backed up.
4. If you are using a backup utility that runs incremental backups of your environment
directory, copy any log files generated since the time of your last full backup. Be sure to
restore all log files in the order that they were written. The order is important because
it is possible the same log file appears in multiple archives, and you want to run recovery
using the most recent version of each log file. Also, if you are using subdirectories to
store your log files, be sure to maintain the relationship between your log files and the
subdirectory in which JE originally placed them.
5. Open the environment as normal. JE's normal recovery will run, which will bring your
database to a consistent state relative to the changed data found in your log files.
You are now done restoring your database.
Hot Standby
As a final backup/recovery strategy, you can create a hot standby. Note that using hot
standbys requires your application to be able to specify its environment home directory at
application startup time. Most application developers allow the environment home directory
to be identified using a command line option or a configuration or properties file. If your
application has its environment home hard-coded into it, you cannot use hot standbys.
You create a hot standby by periodically backing up your database to an alternative location
on disk. Usually this alternative location is on a separate physical drive from where you
normally keep your database, but if multiple drives are not available then you should at least
put the hot standby on a separate disk partition.
XDoc.Excel for .NET, Comprehensive .NET Excel Imaging Features
zooming & rotation; Outlines, bookmarks, & thumbnail display; Integrated annotation; More about Web Viewer ▶. Excel Convert. Convert Excel to PDF; Convert Excel
bookmarks pdf reader; bookmarks pdf documents
XDoc.PowerPoint for .NET, All Mature Features Introductions
& rotation; Outlines, bookmarks, & thumbnail display; Integrated annotation; More about Web Viewer ▶. PowerPoint Convert. Convert PowerPoint to PDF; Convert
bookmark a pdf file; add bookmarks to pdf file
Library Version 12.1.6.0
Backing up and Restoring Berkeley DB Java Edition
Applications
12/7/2015
Getting Started with JE
Page 157
You failover to your hot standby by causing your application to reopen its environment using
the hot standby location.
Note that a hot standby should not be used as a substitute for backing up and archiving your
data to a safe location away from your operating environment. Even if your data is spread
across multiple physical disks, a truly serious catastrophe (fires, malevolent software viruses,
faulty disk controllers, and so forth) can still cause you to lose your data.
To create and maintain a hot standby:
1. Copy all log files (*.jdb) from your environment directory to the location where you want
to keep your standby. Either a hot or an offline backup can be used for this purpose, but
typically a hot standby is initially created by taking an offline backup of your database.
This ensures that you have captured the contents of your in-memory cache.
Note
If you are using subdirectories to store your log files, then you must backup the
subdirectories, making sure to keep log files in the subdirectory in which JE
placed them. For information on using subdirectories to store your log files, see
Multiple Environment Subdirectories (page 18).
2. Periodically copy to your standby directory any log files that were changed or created
since the time of your last copy. Most backup software is capable of performing this kind
of an incremental backup for you.
Note that the frequency of your incremental copies determines the amount of data that
is at risk due to catastrophic failures. For example, if you perform the incremental copy
once an hour then at most your hot standby is an hour behind your production database,
and so you are risking at most an hours worth of database changes.
3. Remove any *.jdb files from the hot standby directory that have been removed or
renamed to .del files in the primary directory. This is not necessary for consistency, but
will help to reduce disk space consumed by the hot standby.
12/7/2015
Getting Started with JE
Page 158
Chapter 12. Administering Berkeley DB Java
Edition Applications
There are a series of tools and parameters of interest to the administrator of a Berkeley DB
Java Edition database. These tools and parameters are useful for tuning your JE database's
behavior once it is in a production setting, and they are described here. This chapter,
however, does not describe backing up and restoring your JE databases. See Backing up and
Restoring Berkeley DB Java Edition Applications (page 151) for information on how to perform
those procedures.
The JE Properties File
JE applications can be controlled through a Java properties file. This file must be placed in
your environment home directory and it must be named je.properties.
The parameters set in this file take precedence over the configuration behavior coded into the
JE application by your application developers.
Usually you will use this file to control the behavior of JE's background threads, and to control
the size of your in-memory cache. These topics, and the properties parameters related
to them, are described in this chapter. Beyond the properties described here, there are
other properties identified throughout this manual that may be of interest to you. However,
the definitive identification of all the property parameters available to you is described
in the javadoc for the EnvironmentConfig class. Each property has a String constant in
EnvironmentConfig that describes its meaning, default value, and so forth.
Managing the Background Threads
JE uses some background threads to keep your database resources within pre-configured
limits. If they are going to run, the background threads are started once per application
per process. That is, if your application opens the same environment multiple times, the
background threads will be started just once for that process. See the following list for the
default conditions that gate whether an individual thread is run. Note that you can prevent a
background thread from running by using the appropriate je.properties parameter, but this
is not recommended for production use and those parameters are not described here.
The background threads are:
• Cleaner thread.
Responsible for cleaning and deleting unused log files. See The Cleaner Thread (page 159)
for more information.
This thread is run only if the environment is opened for write access.
• Compressor thread.
Responsible for cleaning up the internal BTree as database records are deleted. The
compressor thread ensures that the BTree does not contain unused nodes. There is no need
for you to manage the compressor and so it is not described further in this manual.
Library Version 12.1.6.0
Administering Berkeley DB Java Edition
Applications
12/7/2015
Getting Started with JE
Page 159
This thread is run only if the environment is opened for write access.
• Checkpointer thread.
Responsible for running checkpoints on your environment. See The Checkpointer
Thread (page 159) for more information.
This thread always runs.
The Cleaner Thread
The cleaner thread is responsible for cleaning, or compacting, your log files for you. Log file
cleaning is described in Cleaning the Log Files (page 152).
The following two properties may be of interest to you when managing the cleaner thread:
• je.cleaner.minUtilization
Identifies the percentage of the log file space that must be used for utilized records. If the
percentage of log file space used by utilized records is too low, then the cleaner removes
obsolete records until this threshold is reached. Default is 50%.
• je.cleaner.expunge
Identifies the cleaner's behavior in the event that it is able to remove a log file. If true,
the log files that have been cleaned are deleted from the file system. If false, the log files
that have been cleaned are renamed from NNNNNNNN.jdb to NNNNNNNN.del. You are then
responsible for deleting the renamed files.
Note that the cleaner thread runs only if the environment is opened for write access. Also, be
aware that the cleaner is not guaranteed to finish running before the environment is closed,
which can result in unexpectedly large log files. See Closing Database Environments (page 19)
for more information.
The Checkpointer Thread
Automatically runs checkpoints. Checkpoints and the administration of this thread are
described in the Berkeley DB, Java Edition Getting Started with Transaction Processing guide.
Sizing the Cache
By default, your cache is limited to a percentage of the JVM maximum memory as specified
by the -Xmx parameter. You can change this percentage by using the je.maxMemoryPercent
property or through EnvironmentMutableConfig.setCachePercent(). That is, the maximum
amount of memory available to your cache is normally calculated as:
je.maxMemoryPercent * JVM_maximum_memory
You can find out what the value for this property is by using
EnvironmentConfig.getCachePercent().
Library Version 12.1.6.0
Administering Berkeley DB Java Edition
Applications
12/7/2015
Getting Started with JE
Page 160
Note that you can cause JE to use a fixed maximum cache size by using je.maxMemory or by
using EnvironmentConfig.setCacheSize().
Also, not every JVM is capable of identifying the amount of memory requested via the -Xmx
parameter. For those JVMs you must use je.maxMemory to change your maximum cache size.
The default maximum memory available to your cache in this case is 38M.
Of the amount of memory allowed for your cache, 93% is used for the internal BTree and the
other 7% is used for internal buffers. When your application first starts up, the 7% for buffers
is immediately allocated. The remainder of the cache grows lazily as your application reads
and writes data.
In order for your application to start up successfully, the Java virtual machine must have
enough memory available to it (as identified by the -Xmx command line switch) for both
your application and 7% of your maximum cache value. In order for your application to run
continuously (all the while loading data into the cache), you must make sure your JVM has
enough memory for your application plus the maximum cache size.
The best way to determine how large your cache needs to be is to put your application into a
production environment and watch to see how much disk I/O is occurring. If the application
is going to disk quite a lot to retrieve database records, then you should increase the size of
your cache (provided that you have enough memory to do so).
You can also use the com.sleepycat.je.util.DbCacheSize utility to obtain a rough estimate
of how large your cache needs to be for a given number of records and record characteristics.
The utility returns an estimate of the cache size to hold the specified number of records in
memory. See the DbCacheSize javadoc for information on the utility's usage.
In order to determine how frequently your application is going to disk for
database records not found in the cache, you can examine the value returned by
EnvironmentStats.getNCacheMiss().
EnvironmentStats.getNCacheMiss() identifies the total number of requests for database
objects that were not serviceable from the cache. This value is cumulative since the
application started. The faster this number grows, the more your application is going to disk
to service database operations. Upon application startup you can expect this value to grow
quite rapidly. However, as time passes and your cache is seeded with your most frequently
accessed database records, what you want is for this number's growth to be zero or at least
very small.
Note that this statistic can only be collected from within the application itself or using the
JMX extension (see JConsole and JMX Support (page 11)).
For more information on collecting this statistic, see Environment Statistics (page 23).
The Command Line Tools
JE ships with several command line tools that you can use to help you manage your databases.
They are:
• DbDump
Library Version 12.1.6.0
Administering Berkeley DB Java Edition
Applications
12/7/2015
Getting Started with JE
Page 161
Dumps a database to a user-readable format.
• DbLoad
Loads a database from the output produced by DbDump
• DbVerify
Verifies the structure of a database.
DbDump
Dumps a database to a flat-text representation. Options are:
-f
Identifies the file to which the output from this command is written. The console
(standard out) is used by default.
-h
Identifies the environment's directory. This parameter is required.
-l
Lists the databases contained in the environment. If the -s is not provided, then this
argument is required.
-p
Prints database records in human-readable format.
-r
Salvage data from a possibly corrupt file. When used on a uncorrupted database, this
option should return data equivalent to a normal dump, but most likely in a different
order.
This option causes the ensuing output to go to a file named dbname.dump where
dbname is the name of the database you are dumping. The file is placed in the current
working directory.
-R
Aggressively salvage data from a possibly corrupt file. This option differs from the -r
option in that it will return all possible data from the file at the risk of also returning
already deleted or otherwise nonsensical items. Data dumped in this fashion will
almost certainly have to be edited by hand or other means before the data is ready
for reload into another database.
This option causes the ensuing output to go to a file named dbname.dump where
dbname is the name of the database you are dumping. The file is placed in the current
working directory.
-s
Identifies the database to be dumped. If this option is not specified, then the -l is
required.
Documents you may be interested
Documents you may be interested