Skip to main content

Configuring Databases

A database is a IRIS.DAT file you create using the Database Wizard. An InterSystems IRIS database holds data in multidimensional arrays called globals and executable content called routines, as well as class and table definitions. Globals and routines encompass such things as methods, classes, web pages, SQL, BASIC, and JavaScript files.

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.

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.

You can make most database configuration changes dynamically; you can create and delete databases and modify database attributes while the system is running.

Note:

These topics describe the process of manually configuring databases using the Management Portal. 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 database 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.

Background

InterSystems IRIS stores data — persistent multidimensional arrays (globals) as well as executable code (routines) — in one or more physical structures called databases. A database consists of one or more physical files stored in the local operating system. An InterSystems IRIS system may (and usually does) have multiple databases.

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

InterSystems IRIS applications access data by means of a namespace. A namespace provides a logical view of data (globals and routines) stored in one or more physical databases. An InterSystems IRIS system may (and usually does) have multiple namespaces. InterSystems IRIS maps the data visible in a logical namespace to one or more physical databases. This mapping provides applications with a powerful mechanism for changing an application’s physical deployment without changing application logic.

In the simplest case, there is a one-to-one correspondence between a namespace and a database, but many systems take advantage of the ability to define a namespace that provides access to data in multiple databases. For example, a system could have multiple namespaces, each of which provides a different logical view of the data stored within one or more physical databases.

Database Considerations

This section discusses the following topics:

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), described in the DBSizesAllowed entry in Configuration Parameter File Reference.

  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 the “Backup and Restore” chapter of the Data Integrity Guide) 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 in the Installation Guide) 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 section of the “Migration and Conversion Utilities” chapter of Specialized System Tools and Utilities) 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 in the “Backup and Restore” chapter of the Data Integrity Guide.

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 in the “Mirroring” chapter of the High Availability Guide.

  • 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 in the “Managing InterSystems IRIS” chapter of this guide.

  • 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 the “Journaling” chapter of the Data Integrity Guide.

You can use this page to:

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” chapter of the Data Integrity Guide.

    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 in the “Journaling” chapter of the Data Integrity Guide.

  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 in the “Mirroring” chapter of the High Availability Guide 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.

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.

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

Click the name of a nonmirrored database to view the following database properties and change some of them. (The “Create a Local Database” section 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 the Add to Mirrormirror_name link 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 in the “Mirroring” chapter of the High Availability Guide for more information.

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

  • 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 the “Journaling” chapter of the Data Integrity Guide.

  • 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 the “Journaling” chapter of the Data Integrity Guide). 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 in the “Managing InterSystems IRIS” chapter of this guide.

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

Edit Mirrored Local Database Properties

Click the name of a mirrored database to view and change some of the following database properties; see definitions in the previous section.

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 in the “Mirroring” chapter of the High Availability Guide), a mirrored database’s file streams are not mirrored. (For information about file streams, see the “Working with Streams” chapter of Defining and Using Classes.)

    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 the “Journaling” chapter of the Data Integrity Guide) 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 in the “Managing InterSystems IRIS” chapter of this guide.

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

    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 in the “Mirroring” chapter of the High Availability Guide.

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.

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

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.

Remote Databases

A remote database is a database that is physically located on another server system, as opposed to a local database which is physically located on the local server system.

From the Remote Databases page you can perform the following tasks:

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 in the “Horizontally Scaling Systems for User Volume with InterSystems Distributed Caching” chapter of the Scalability Guide.

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.

FeedbackOpens in a new tab