Chapter 4. Adding a Database

Documentation

Home » Documentation » Enterprise Manager Guide

Chapter 4. Adding a Database

The Enterprise Manager makes it easy to manage databases. The first step is to add the database to the management interface, specifying how you want the database configured, in terms of sites per host, K-safety, and so on.

4.1. Configuring the Database

To add a new database to the Enterprise Manager, click on the Add button at the top of the database list, which brings up the Add Database dialog box. (If this is your first time using Enterprise Manager or if you have no databases defined, the Add Database dialog is displayed automatically.)

Figure 4.1. Add Database Dialog

Add Database Dialog

The Add Database dialog box lets you set the basic properties for the database, including the application catalog, the number of sites per host, the K-safety value, and so on. You can also load user definitions and set up automated snapshots.

Table 4.1, “Database Configuration Settings” describes each of the fields in the dialog box in detail. In some cases you can take the default settings or leave the field blank. But the four areas of the configuration screen you want to make sure to fill out are the database name, the application catalog, the partitioning and K-safety settings, and the destination directory.

  • The name and description are what the Enterprise Manager uses to identify your database. The name is shown in the list of databases on the left and the description is included on the dashboard. Provide a meaningful name that helps you identify your database.

  • The application catalog defines the schema and stored procedures that your database will use. You must load an existing catalog before you can complete the Add Database dialog.

  • The sites per host and K-safety fields are important aspects of the database configuration. Sites per host indicates how many partitions are created on each node of the cluster and K-safety specifies how many replicates are created (to ensure availability in case of node failure). See the Using VoltDB guide for more information about these features. However, it is important to make sure these settings are appropriate for your hardware configuration and the needs of your database application.

  • The destination directory specifies where the Enterprise Manager puts files it needs to run VoltDB on the individual servers. The Enterprise Manager will create this directory if it doesn't already exist. But make sure that the SSH user account has permissions to create and write into the specified directory.

Table 4.1. Database Configuration Settings

Database Settings
FieldDescription
Database name

A short, meaningful name identifying the database. The Enterprise Manager uses this name to identify the database in lists and dialog boxes.

Database descriptionA longer description of the purpose of the database. The description is shown in the dashboard only.
Sites per host

The number of sites to create on each cluster node.

K-safety

The K-safety value you wish to set for the database cluster. See the chapter on "Availability" in Using VoltDB for more information about K-safety.

Enable securityCheck this box if you want to enable security. If you enable security, your catalog must include the definition of one or more roles and you must import a set of user definitions using the "Load Users" function described below. See the chapter on "Security" in Using VoltDB for more information
Enable network partition detectionNetwork partition detection is enabled by default when running with K-safety. You can uncheck this box if you want to disable the feature, however disabling partition detection is not recommended.. See the chapter on "Availability" in Using VoltDB for more information
Enable command loggingCheck this box if you want to enable command logging. Command logging enhances availability by creating a record of all the stored procedure invocations as they occur. Then, in case of unexpected failure, the log can be "replayed" automatically on startup, recreating the database contents. See the chapter on "Command Logging and Recovery" in Using VoltDB for more information.
Destination directory

The directory on the remote nodes that the Enterprise Manager uses for storing files. This directory must be valid on all nodes of the cluster and should be a complete (absolute) path. Use of a relative path for the destination directory is not recommended, since the default directory for the remote process is not guaranteed to be the same each time.

Load users

If security is enabled, you must include user definitions as part of your configuration. At least one of the users must be assigned a role with sysproc privileges.[1] This is the user that the Enterprise Manager uses to interact with the database once it is started.

If security is not enabled, user definitions are optional.

Rather than define each user separately, the Enterprise Manager lets you define users in a VoltDB deployment file and then upload that deployment file into the configuration. This way you can reuse user definitions for multiple databases.

To load users, click on the Browse...[2] button and select a valid VoltDB deployment file. The Enterprise Manager imports the user definitions from that file. (Note that only the user definitions are loaded; the other settings within the deployment file are ignored.)

[1] Currently, there is a limitation that the user the Enterprise Manager uses must be assigned only one role. If no users are assigned to a single role with sysproc privileges, the Enterprise Manager will not be able to perform certain tasks.

[2] The exact wording of buttons and controls may vary from browser to browser. Use the appropriate interface widgets for your environment to complete the described actions.

Catalog Settings
FieldDescription
Upload catalog

You must specify the schema for your database by loading an existing VoltDB catalog. Click on the Browse...[2] button and select a catalog JAR file to load. The Enterprise Manager then opens and validates the contents of the catalog. Once you load a catalog, the fields above the Upload catalog field display a summary of information about the catalog.

Snapshot Settings
FieldDescription
Frequency

Snapshot frequency indicates how often (in seconds) an automated snapshot will be taken of the database. By default, the frequency is zero, or no automated snapshots. If you want periodic snapshots of the database, specify the frequency for the snapshots in this field as a whole number of seconds. (For example, 300 seconds for snapshots every 5 minutes.)

Snapshots retained

If you are using automated snapshots, the snapshots will use up more and more disk space over time. To avoid this situation, you must specify a maximum number of snapshots to keep on the database servers. When an automated snapshot is taken, if there are more snapshots than specified, the oldest snapshot is deleted.

Copy snapshots to management server

By selecting this checkbox, the automated snapshots are copied from the database servers to the management server. Snapshots must be copied to the management server if you want to use them later in the Enterprise Manager to restore a snapshot when you start the database.

When snapshots are copied to the management server, they are not deleted from the database server(s). It is a good idea to both enable the copying of automated snapshots and set a small value for the number of snapshots retained, to avoid excessive disk usage.

Note that the retention setting affects snapshots on the database servers only. It does not purge snapshots on the management server. It is a good idea to periodically review and delete old snapshots on the management server. (See Section 8.3, “Preventative Maintenance Using Snapshots” for more information on managing snapshots.)


Once you complete filling out the dialog box, click the Create button to add the database to the dashboard.