Derby system

A Derby database exists within a system.

A Derby system is a single instance of the Derby database engine and the environment in which it runs. It consists of a system directory, zero or more databases, and a system-wide configuration. The system directory contains any persistent system-wide configuration parameters, or properties, specific to that system in a properties file called derby.properties. This file is not automatically created; you must create it yourself.

The Derby system is not persistent; you must specify the location of the system directory at every startup.

However, the Derby system and the system directory is an essential part of a running database or databases. Understanding the Derby system is essential to successful development and deployment of Derby applications. As the following figure shows, Derby databases live in a system, which includes system-wide properties, an error log, and one or more databases.

Figure 1. Derby system

The system directory can also contain an error log file called derby.log (see The error log).

Each database within that system is contained in a subdirectory, which has the same name as the database (see A Derby database).

In addition, if you connect to a database outside the current system, it automatically becomes part of the current system.

When you use the embedded driver, Derby database files and log files normally have whatever default permissions you specify for your file system. If you are running with Java SE 7 or later, however, you can enhance security by restricting file access to the user who creates the database. To do this, set the system property derby.storage.useDefaultFilePermissions to false. See the Derby Reference Manual for details.

• One Derby instance for each Java Virtual Machine (JVM)
  You could potentially have two instances of a Derby system running on the same machine at the same time. Each instance must run in a different Java Virtual Machine (JVM).
• Booting databases
  The default configuration for Derby is to boot (or start) a database when an application first makes a connection to it. When Derby boots a database, it checks to see if recovery needs to be run on the database, so in some unusual cases booting can take some time.
• Shutting down the system
  In an embedded environment, when an application shuts down, it should first shut down Derby.
• Defining the system directory
  You define the system directory when Derby starts up by specifying a Java system property called derby.system.home.
• The error log
  Once you create or connect to a database within a system, Derby begins outputting information and error messages to the error log. Typically, Derby writes this information to a file called derby.log in the system directory.
• derby.properties
  The text file derby.properties contains the definition of properties, or configuration parameters that are valid for the entire system.
• Double-booting system behavior
  Derby prevents two instances of itself from booting the same database by using a file called db.lck inside the database directory.
• Recommended practices
  When developing Derby applications, create a single directory to hold your database or databases.