Configuring Databases

Database Total Limit

The absolute limit on the number of databases that can be configured within a single InterSystems IRIS instance (given sufficient storage space) is 15,998. There are other limitations as follows:

• The directory information for databases cannot exceed 256 KB. This means that if the average length of a database directory name is longer, an instance can have fewer total databases. The following formula describes this relation:

  maximum_DBs = 258048/ (avg_DB_path_length + 3)

  For example, if all database directory paths are of the form c:\InterSystems\IRIS\mgr\DBNNNN\, the average length is 33 bytes. Thus, the maximum number of databases is 7,168, calculated as follows: 258048/ (33 + 3) = 7168.

• Mirrored databases count twice toward the absolute limit of 15,998. If all databases on the instance are mirrored, the effective limit is 7,499 databases. This is because InterSystems IRIS creates two database definitions for mirrored databases; one for the directory path (c:\InterSystems\IRIS\mgr\DBNNNN\), and one for the mirror definition (:mirror:MIRRORNAME:MirrorDBName).

• The number of databases that can be in use simultaneously is limited by the operating system’s restriction on the number of open files (either per process or system-wide). InterSystems IRIS reserves approximately half of the operating system’s open file allocation for its own use and devices.

Database Configuration Considerations

The following are tips to consider to consider when configuring databases:

• InterSystems IRIS provides a seamless option to spread data across multiple physical database (IRIS.DAT) files. Therefore, you can build applications with multiple databases or splitting data by global or subscript-level mappings, as appropriate.

• Keep database sizes within a manageable value based on the infrastructure available for administration tasks such as backup, restore, integrity checks, etc.

• It is recommended that stream globals (if storing streams within IRIS.DAT database files) be global mapped to a separate database, and that the stream database(s) be configured with a large (64 KB) block size.

• Depending on your workload, it may be beneficial to consider alternate (larger) block sizes than the default 8 KB database block size. For general guidelines, see Large Block Size Considerations below.

Large Block Size Considerations

In addition to the 8 KB (default) block size supported by InterSystems IRIS (which is always enabled), you can also enable the following block sizes:

• 16 KB (16384)

• 32 KB (32768)

• 64 KB (65536)

However, you should exercise caution when creating your database to use large block size because using them can impact the performance of the system. Consider the following before enabling and using large block sizes:

• If your application workload consists primarily of sequential inserts or sequential reads/queries, large block sizes may improve performance.

• If your application workload consists primarily of random inserts or random reads/queries, large block sizes may degrade performance. Since larger block sizes result in fewer blocks being cached for a given total size of database cache, to reduce the impact on random database access, you should also consider making more total memory available as database cache.

• For index-type databases, the default block size (8 KB) ensures optimum performance; larger block sizes potentially degrade performance. If you are considering larger block sizes for your data, you should consider mapping index globals to a separate 8 KB block size database.

To create a database that uses block sizes other than the supported blocks, do the following:

1. Enable the block sizes using the setting on the Startup Settings page (System Administration > Additional Settings > Startup); see DBSizesAllowed.

2. Configure the database cache for the enabled block size on the Startup Settings page (System Administration > Additional Settings > Startup), as described in Memory and Startup Settings.

3. Restart InterSystems IRIS.

4. Create the database as described in Create Local Databases.

Database Compatibility Considerations

As described in the Create a Local Database procedure, you can copy or move an InterSystems IRIS database to an instance other than the one in which it was created by copying or moving its IRIS.DAT file, or temporarily mount a database created in another instance on the same system. You can also restore a backup of a database (see Backup and Restore) to an instance other than its original instance. To avoid data incompatibility, however, the following requirements must be met:

• The target (new) instance must use the same character width (8-bit or Unicode; see Character Width SettingOpens in a new tab) and the same locale (see Using the NLS Settings Page of the Management Portal) as the instance that created the database.

  The one exception to this requirement is that an 8-bit instance using a locale based on the ISO 8859 Latin-1 character set is compatible with a Unicode instance using the corresponding wide character locale. For example, a database created in an 8-bit instance using the enu8 locale can be used in a Unicode instance using the enuw locale.

• If the source and target instances are on systems of different endianness, the database must be converted to the endianness of the target instance before being used.

  Depending on the platform, multibyte data is stored with either the most significant byte or the least significant byte in the lowest memory address (that is, first): when the most significant byte is stored first, it is referred to as “Big-endian;” when the least significant byte is stored first, it is referred to as “Little-endian.”

  When defining a database using an existing IRIS.DAT created on a system of different endianness, use the cvendian utility (see the Using cvendian to Convert Between Big-endian and Little-endian Systems) to convert the database before you use it. When restoring a backup of a database to a system of different endianness than the source system, see Considering Endianness.

Create a Local Database

To create a local database, navigate to the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).

1. Click Create New Database to open the Database Wizard.

2. Enter a database name in the text box. A database name must:

   • not already be in use within the InterSystems IRIS instance

   • be between one and 30 characters long

   • start with an alphabetic character or an underscore; the remainder can include alphanumeric characters, dashes, or underscores

3. The first time you create a local database in an InterSystems IRIS instance using a particular browser, you must either

   • enter the name of the database directory, in which case this directory, containing the IRIS.DAT file, is created in c:\InterSystems\mgr once you confirm it

   • click the folder icon to browse to an existing directory, in which case the IRIS.DAT file is created in that directory

   Thereafter, by default a directory of the same name as the database name you provide, containing the IRIS.DAT file, is created in the same location as the previous database directory. For example, if you first create database db22 in any directory under c:\InterSystems\mgr, when you click Create New Database again and enter db33 in the Enter the name of your database box, c:\InterSystems\mgr\db33 is automatically filled into the Database directory text box. If you change this to c:\InterSystems\db33 and create db33, the base directory c:\InterSystems will be filled in the next time.

   Note:

   InterSystems does not support the use of symbolic links when configuring database directories.

4. Click Next to continue configuring the database. If a IRIS.DAT file already exists in the directory you specified, you are warned of this and can either

   • Click Finish to use the existing file, in which case all of the databases characteristics are determined by the IRIS.DAT file. You would typically do this when copying or moving a database from another instance, or temporarily mounting a database created in another instance on the same system.

   • Click Back to specify another directory, then click Next again to continue specifying the characteristics of the new database in the next step.

5. In the Initial Size text box, type the number of megabytes for your database size (the default is 1 MB).

   Note:

   You cannot create or edit a database so that its size is larger than the total available disk space. If the size you specify is within 90% of the disk's free space, you are warned and must confirm the action.

6. Select the desired block size from the Block size for this database will be drop-down list. By default, all new databases are created with a Block Size of 8 KB.

   Caution:

   Do not select block sizes other than 8 KB from the drop-down list unless you have read and understand the guidelines described in Large Block Size Considerations/

7. Select whether or not you want to journal globals in this database from the Journal globals? drop-down list. See the Journaling.

   Note:

   If you are configuring the database to store temporary globals, setting the Journal globals property to No is not the same as storing the temporary globals in IRISTEMP; for more information, see Using Temporary Globals and IRISTEMP.

8. If encryption is activated, you can encrypt this database by selecting Yes for Encrypt Database?.

9. If the instance is part of a mirror, you can add this database to the mirror by selecting Yes for Mirrored Database?. See Add Databases to the Mirror for information about creating mirrored databases.

10. From this panel onward, you can click Next. to continue configuring the database or Finish to accept the remaining defaults

11. Choose the resource to control access to this database:

    • Default — %DB_%DEFAULT

    • Existing — Choose from a list of existing database resources

    • New — Create a new database resource (the new name defaults to %DB_% database name)

12. Click Next to view a list of the database attributes.

13. Click Finish to add your database.

You are now ready to configure and manage your new database.

Edit a Local Database’s Properties

The information displayed varies depending on whether or not the database is mirrored. This section identifies the fields for:

• Edit Nonmirrored Local Database Properties

• Edit Mirrored Local Database Properties

Relocate a Local Database

To move a local database’s IRIS.DAT file to a different directory, you must do the following:

1. Make note of the current database directory. You can view this information from the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).

2. Perform a clean shut down of the instance, such as by using the iris stop command.

3. Copy the IRIS.DAT file and the stream directory from the current database directory to the desired location.

   Important:

   If there is an iris.lck file in the database directory, do not attempt to move the database. This means the database is still in use, and attempting to move it could lead to unforeseen problems. Contact the InterSystems Worldwide Response Center (WRC)Opens in a new tab for assistance.

   Note:

   InterSystems does not support the use of symbolic links when configuring database directories, and recommends choosing a fully resolved physical path for the new database location.

4. Open the iris.cpf file for the instance in a text editor. This file is usually located in the installation directory.

5. Locate the name of the database beneath the [Databases] section. Replace the old directory path with the new path, then save iris.cpf.

6. Start the InterSystems IRIS instance, and view the Local Database page to confirm that the directory is set to the new location. If the database is mirrored, it needs to be activated and caught up.

7. Delete the old database directory.

Delete a Local Database

To delete a local database, click the Delete link in the appropriate row. The Delete Database page displays information about the database you are deleting, and lets you:

• Select the namespaces mapped to this database for deletion. You cannot delete a database if a namespace is mapped to it, so unless you select all of the listed namespaces you cannot delete the database.

  You cannot delete namespaces that are also mapped to other databases. When this is the case, a link is provided to take you to the Namespaces page, where you can modify the database mappings of the namespaces involved. After you delete all mappings to another database, that database will be removed from the list of databases you have to delete.

• You can choose to delete the database’s IRIS.DAT file, if and only if:

  • No other databases use this IRIS.DAT file.

  • You have marked all namespaces mapped to the database for deletion.

  If these conditions are not met, you can still delete the database from the current configuration, but the IRIS.DAT file cannot be deleted.

• Confirm that you want to delete the database after reviewing information about it by clicking Delete Database Now.

If you cannot or chose not to delete the IRIS.DAT file, the database is still removed from the Databases section of the InterSystems IRIS parameters file and therefore from the list of local databases displayed by the Management Portal.

Add a Remote Database

You can define a remote database on the local server if the database’s host is configured on that server as a distributed cache data server. For instructions for adding a data server, see Configuring an Application Server.

To add a remote database, follow these steps:

1. Navigate to the Remote Databases page (System Administration > Configuration > System Configuration > Remote Databases) and click Create Remote Database to launch the wizard.

2. Select the data server that hosts the database from the Remote Server drop down.

3. Choose how you want to specify the remote database directory from the Remote Directory radio buttons:

   • Select databases from a list lets you choose from a drop-down list of database directories on the remote server. If the remote data server cannot currently be reached, the drop-down list is empty.

   • Enter your own database specification lets you enter the database directory directly, but the Portal does not validate your entry.

4. Enter a database name (its name on the local server; it does not need to match its name on the remote server). You have defined a remote database.

   Database names are between 1 and 30 characters long, can start with an alphabetic character or an underscore. The remaining characters can be alphanumeric, a dash, or an underscore.

5. You can optionally specify the directory in which streams associated with this database are stored. By default, the stream location for a remote database is the InterSystems IRIS Temp directory (install-dir\mgr\Temp).

   Note:

   InterSystems recommends that you use the default location.

6. Click Save to configure the remote database.

You can click the Edit link for a remote database at any time to modify the remote database fields.

Delete a Remote Database

To delete a remote database, click the Delete link in the appropriate row. The Delete Database page displays information about the database you are deleting, and lets you:

• Select the namespaces mapped to this database for deletion. You cannot delete a database if a namespace is mapped to it, so unless you select all of the listed namespaces you cannot delete the database.

  You cannot delete namespaces that are also mapped to other databases. When this is the case, a link is provided to take you to the Namespaces page, where you can modify the database mappings of the namespaces involved. After you delete all mappings to another database, that database will be removed from the list of databases you have to delete.

• Confirm that you want to delete the database after reviewing information about it by clicking Delete Database Now.

This action simply removes the database from the local instance’s remote database configuration; the actual database and its local configuration on its host are not affected.