Skip to main content

Configuring Local Databases

This page provides information on configuring local databases in InterSystems IRIS® data platform. Note that you can make most database configuration changes dynamically; you can create and delete databases and modify database attributes while the system is running.

Database Considerations

For background information, see Namespaces and Databases. This section presents additional concepts relevant to system administrators.

Caution:

On Windows systems, do not use file compression on IRIS.DAT database files. (Files are compressed by right-clicking a file or folder in Windows Explorer and selecting Properties, then Advanced, then Compress contents to save disk space; once compressed, a folder name or filename is rendered in blue in Windows Explorer.) If you compress a IRIS.DAT file, the instance to which it belongs will fail to start, with misleading errors.

Database Size and Growth

InterSystems IRIS databases dynamically expand as needed (assuming free space is available), though you can specify a maximum size. A database can grow until it is 32 terabytes if you are using the default 8KB block size.

The Database Cache

Each InterSystems IRIS system maintains a database cache — a local, shared memory buffer used to cache data retrieved from the physical databases. This cache greatly reduces the amount of costly I/O operations required to access data and provides much of the performance benefits of InterSystems IRIS. (For information about allocating the database cache, see Memory and Startup Settings.)

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 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.

Rules for Database Names

The following rules apply to a database name:

  • It must be between one and 64 characters long

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

For information on system-supplied databases, see System-Supplied Databases.

Viewing Local Databases

To view the local databases, navigate to the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).

The Local Databases page displays the following information about the databases on your system:

  • Name — Database name.

  • Mirror — If the database is mirrored, the name of the mirror; for more information see Add Databases to the Mirror.

  • Directory — Location of the IRIS.DAT file.

  • Size (MB) — Size of the database in megabytes.

  • Status — Specifies whether or not the database is mounted, unmounted, or dismounted; if it is mounted, specifies whether it has read-only or read-write permission. For more information, see “The Local Databases List Information” table in Maintaining Local Databases.

  • Resource Name — The name of the database resource that governs access to the database; for more information, see Using Resources to Protect Assets.

  • Encrypted — Specifies whether or not the database is encrypted; for more information, see Encryption Guide.

  • Journal Specifies whether or not the database is journaled; for more information, see Journaling.

You can use this page to:

Creating a Local Database

To create a local database:

  1. Navigate to the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).

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

  3. Enter a database name in the text box. A database name must not already be in use within the InterSystems IRIS instance; also see Rules for Database Names.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. Select whether or not you want to journal globals in this database from the Journal globals? drop-down list. See 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.

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

  10. 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.

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

  12. 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)

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

  14. Click Finish to add your database.

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

Note:

To protect you from accidentally corrupting a database, you cannot open or write to an operating system file called IRIS.DAT, even if it is not a mounted database.

Editing a Local Database’s Properties

To edit a local database’s properties:

  1. Navigate to the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).

  2. Click the name of the database.

    The information displayed varies depending on whether or not the database is mirrored. See the sections for:

Editing Nonmirrored Local Database Properties

If you are editing a nonmirrored database, the system displays the following properties (Create a Local Database describes many of these fields).

  • Name

  • Directory (this setting must always reflect the location of the IRIS.DAT database file)

  • Encrypted (cannot be changed)

  • Mirrored — Click Add to Mirrormirror_name to add the database to the mirror in which the InterSystems IRIS instance is the primary failover member. (This option is available only when the instance is the primary in a mirror.) See Add an Existing Database to the Mirror.

  • Block Size (Bytes) (cannot be changed)

  • Size (MB) — There are three size settings, as follows:

    • Change Current to modify the current size of the database.

      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.

    • Expansion sets the amount by which to expand the database when required; the default (and recommended) setting of zero (0) indicates 12% of current size or 10 MB, whichever is larger. When using 12% of the current size, the expansion size will not be greater than 1GB.

    • Maximum specifies the maximum size to which the database can grow, in megabytes; the default setting of zero (0) indicates no maximum. To modify this setting, you can enter a new number of MB, or you can precede a number by + or -, for example +10 or -20, to enlarge or reduce the maximum by the specified amount. When you reduce the maximum size of a database, you are warned and must confirm the action. Note, the IRISAUDIT database must be configured to have no maximum size.

  • Resource Name — Select the resource with which to associate the database. Click the resource icon next to the drop-down to display the Resources page so you can create a resource.

  • New Global — Specify attributes for new globals.

  • Global Journal State — Select to enable journaling, clear to disable. See Journaling.

  • Preserve global attributes on delete — Specify whether a global’s directory entry and attributes should be preserved when it is deleted; attributes include collation, journaling status, and growth pointer. Select to preserve a global’s directory entry and attributes when the global is entirely deleted; clear to remove the directory entry and attributes.

  • Mount Read-Only — Select to specify that the database be mounted as read-only; clear to specify that it be mounted as read-write.

  • Mount Required at Startup — Select to indicate that the database must be mounted when InterSystems IRIS starts up; if the database cannot be mounted, InterSystems IRIS does not start. This lets you ensure that journal recovery and transaction rollback can be performed on the database before startup following a crash (as described in Journaling). Clear to let InterSystems IRIS start without first mounting the database.

    Note:

    By default, this setting is selected for required InterSystems IRIS databases (for example, IRISLIB and IRISAUDIT) and cannot be changed. The default is cleared but can be selected for databases that you create, as well as the USER and ENSLIB databases). For additional information about database status and explicitly dismounting and mounting databases, see “The Local Databases List Information” table in Maintaining Local Databases.

  • Stream Location — Click the Browse button to select the directory in which streams associated with this database are stored. By default, the stream location for a local database is a subdirectory named stream in the database Directory, which is one of the above fields (for example, install-dir\mgr\DB1\stream).

    Note:

    InterSystems recommends that you use the default location.

Editing Mirrored Local Database Properties

If you are editing a mirrored database, the system displays the following properties (Create a Local Database describes many of these fields).

Note:

Journaling is required for a mirrored database, therefore the Global Journal State setting does not appear.

  • Name

  • Mirror Name — Name by which the database is identified within the mirror; cannot be changed.

  • Directory (this setting must always reflect the location of the IRIS.DAT database file)

  • Encrypted (cannot be changed)

  • Stream Location — Click the Browse button to select the directory in which streams associated with this database are stored. By default, the stream location for a local database is a subdirectory named stream in the database Directory, which is one of the above fields (for example, install-dir\mgr\DB1\stream).

    Note:

    Like other database-related data that is not contained in the database itself (see Mirror Configuration Guidelines), a mirrored database’s file streams are not mirrored. (For information about file streams, see Working with Streams.)

    InterSystems recommends that you use the default location.

  • Resource Name — Select the resource with which to associate the database. Click the resource icon next to the drop-down to display the Resources page so you can create a resource.

  • Block Size (Bytes) (cannot be changed)

  • Collation — Among global attributes, only the collation attribute can be changed, for new globals only.

  • Preserve global attributes on delete — Specify whether a global’s directory entry and attributes should be preserved when it is deleted; attributes include collation, journaling status, and growth pointer. Select to preserve a global’s directory entry and attributes when the global is entirely deleted; clear to remove the directory entry and attributes.

  • Mount Read-Only — Select to specify that the database be mounted as read-only; clear to specify that it be mounted as read-write.

  • Mount Required at Startup — Select to indicate that the database must be mounted when InterSystems IRIS starts up or becomes a mirror primary; if the database cannot be mounted, InterSystems IRIS does not start or become primary. This lets you ensure that journal recovery and transaction rollback can be performed on the database before startup following a crash (as described in Journaling) and that open transactions on the former primary have been rolled back as part of failover. Clear to let InterSystems IRIS start without first mounting the database. For additional information about the Mount Required at Startup setting, see “The Local Databases List Information” table in Maintaining Local Databases.

  • Local Properties — This area contains three size settings, as follows:

    • Change Size to modify the current size of the database.

      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.

    • Expansion sets the amount by which to expand the database when required (and assuming free space is available); the default (and recommended) setting of zero (0) indicates 12% of current size or 10 MB, whichever is larger.

    • Maximum specifies the maximum size to which the database can grow, in megabytes; the default setting of zero (0) indicates no maximum. To modify this setting, you can enter a new number of MB, or you can precede a number by + or -, for example +10 or -20, to enlarge or reduce the maximum by the specified amount. When you reduce the maximum size of a database, you are warned and must confirm the action. Note, the IRISAUDIT database must be configured to have no maximum size.

    This area also contains the current, expansion, and maximum size settings for Other System — if the current instance is a failover member, this is the other failover member; if the current instance is an async member, this is the first failover member that the async could obtain the information from. For important information about how the properties of a mirrored database on the backup and async mirror members are synchronized with those on the primary, see Mirrored Database Considerations.

Relocating a Local Database

To move a local database’s IRIS.DAT file to a different directory, 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. Delete the old database directory.

  7. Start the InterSystems IRIS instance, and view the Local Database page to confirm that the directory is set to the new location.

  8. If the database is mirrored, use ^MIRROR to remove the original location of the mirrored database. Specifically use the option Mirror management > Remove Mirrored Database.

    Then activate and catch up the mirror.

Important:

After you relocate a local database directory, you must also update any systems that access the database remotely (such as ECP application servers). On each remote system, update the remote database directory to the new location, as described in Configuring Remote Databases.

Deleting 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.

Programmatically Configuring a Database

InterSystems IRIS also contains programmatic tools that are useful for automating database configuration. You can use the Config.DatabasesOpens in a new tab class to create and configure databases; see the InterSystems Class Reference for more information.

You can also configure databases using the ^DATABASE command line utility.

Another method for configuring databases is to include the CreateDatabase, ModifyDatabase, or DeleteDatabase operations in conjunction with configuration merge. Configuration merge allows you to customize an InterSystems IRIS instance by applying a declarative merge file, which specifies settings and operations to apply to that instance. For more information about this feature, see Using Configuration Merge to Deploy and Reconfigure InterSystems IRIS.

See Also

FeedbackOpens in a new tab