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.
The following sections describe in detail how to create, configure, and maintain local databases. As a supplement, Managing Database SizeOpens in a new tab presents a brief video introduction to database sizing and expansion.
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.
-
When necessary, you can set up your database up to use multiple volumes.
-
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:
-
Enable the block sizes using the setting on the Startup Settings page (System Administration > Additional Settings > Startup); see DBSizesAllowed.
-
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.
-
Restart InterSystems IRIS.
-
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.
Multivolume Databases
In the default configuration, your database uses a single IRIS.DAT file. You can configure your database to expand automatically into additional volumes (IRIS–0001.VOL, IRIS–0002.VOL, and so on) upon reaching a specified size threshold. You can also deliberately expand your database into additional volumes. Additional volumes may reside in the same directory as IRIS.DAT and/or a set of additional directories.
Using multiple volumes does not allow your database to exceed its maximum size; The aggregate size of your database volumes must still conform to the normal maximum. Instead, this feature allows your database to grow to that total size as a series of volume files, optionally over multiple file systems, for the sake of operating system and storage manageability.
Best practice is to keep the size of volumes as large as possible within operating-system-level constraints, and to expand to additional directories only if extending the file system containing the database is not practical. In general, this feature should be used only when required by external size constraints; it is not needed to aid in operations within InterSystems IRIS itself. Multiple volumes are a simpler alternative to using global and subscript-level mapping to manage size constraints.
You can manage the creation, configuration, and organization of database volumes in the management portal, using the ^DATABASE utility, or via the members of the SYS.DatabaseOpens in a new tab class.
Configuring a Multivolume Database
Each database has a configurable new volume threshold size to control the automatic creation of new volumes. If this threshold is zero (the default), new volumes are not created. Otherwise, when IRIS.DAT or the current volume file reach the threshold size, a new volume is created.
When a new volume threshold is configured, the expansion size parameter of the database continues to function normally: automatic expansion triggered by application demand adds this size to the database, and if 0, the system selects a reasonable expansion amount. When new volumes are created by automatic expansion, they are created at this initial size; they are not initialized to be the new volume threshold. Therefore setting an appropriately large new volume threshold does not cause the database to expand in larger units than it would otherwise.
New volumes are created in a specific, configurable new volume directory. By default, all volumes are created and reside in the directory that contains IRIS.DAT. This is the simplest configuration. However, if file system constraints require it, you can distribute volume files into different directories.
The database maintains a volume directory list, a list of all directories used for volumes of this database. If no database volumes are located in directories other than the default this list is empty. Each additional volume directory contains an iris.dbdir file, which serves to identify the database directory that is using the volume directory and prevents multiple databases from using the same volume directory. This file is a text file containing one line, the primary database directory, and it can be inspected by the administrator at any time. It is never deleted; it persists across restarts, and it must exist with the expected contents in order for the database to be mounted. Note that additional volume directories do not have an iris.lck file; only the primary directory does.
New volumes can be created by the administrator at any time in the same directory or a different directory. This is true regardless of whether a new volume threshold is set or not. In this way, even if no file size limitation is specified, the database can be expanded into another file, file system, or storage device if it becomes needed.
Moving or Copying Volume Files
Moving or copying volume files requires that the database be dismounted or that InterSystems IRIS be cleanly shut down.
If the volume directory list is empty, so all volume files have been created in the same directory as the IRIS.DAT, the contents of that directory can be moved or copied just as a single-volume IRIS.DAT file can be.
When volume files are in one or more other directories, you can move database volumes freely among the directory containing IRIS.DAT and the volume directory list maintained in the database. When you next mount the database, it looks for volumes in these directories and mounts them correctly.
However, if volume files are moved to another location that is not in the volume directory list or the directory containing IRIS.DAT, you must use the ^DATABASE utility, option 16, Manage multi-volume database properties to update the volume directory list before the database will mount successfully.
This is particularly relevant when a database with volumes outside of the directory containing IRIS.DAT is copied to another system with a different directory structure. When using ^DATABASE to modify the volume directory list, the additional volume directories in the updated list must either have no iris.dbdir file, or must have one that already matches the primary database directory. If the iris.dbdir file was copied from another system along with the volume files and the target system has a different directory structure. the iris.dbdir file should be deleted before modifying the volume directory list.
Similarly if the volume files are to be collapsed into a smaller set of directories, the administrator can use ^DATABASE to update the set of directories and then delete the unused directories from the file system.
Regardless of whether additional volume directories are used, IRIS.DAT and all of the IRIS-*.VOL files that comprise a database must be treated as a set. They must be copied and restored as a set. A series of internal reference checks are automatically performed at mount time to avoid common mistakes and prevent mounting a database whose set of volumes does not appear intact.
Updating the volume directory list can only be done using ^DATABASE; the management portal does not include support for this process.
New Volume Error Behavior
-
If creation of a new volume fails during an automatic expansion, the expansion continues in the last volume rather than triggering <FILEFULL> errors in the application.
-
In the special case that expansion of the last volume runs out of space before reaching the new volume threshold and a different new volume directory has already been specified, a new volume will be created in the new volume directory to continue the expansion, leaving the last volume smaller than the threshold size.
-
Other errors do not cause the system to produce volumes outside the parameters defined by the new volume threshold and the new volume directory. In particular, if an expansion in the specified new volume directory fails, the system does not automatically try other directories in the volume directory list.
The Multi-Volume Properties Page
This management portal page allows you to view and configure the properties of the volumes that comprise your database. To reach this page, navigate to the Local Databases page (System Administration > Configuration > System Configuration > Local Databases) and click the Volumes button associated with the desired database.
The Multi-Volume Properties page displays the following information:
-
Directory— The directory that contains the IRIS.DAT file associated with your database.
-
Number of Volumes— The number of volumes in your database. A value of 1 indicates that only the IRIS.DAT file is in use, no IRIS-*.VOL files.
-
Total Database Size— The aggregate size of your database, including all volumes.
-
New Volume Threshold Size— The maximum size the current volume (or IRIS.DAT) can reach before triggering the creation of a new volume.
-
Directory for New Volumes— The directory in which new volumes will be created.
-
Database Volumes— A listing of the volumes that comprise your database, organized either by volume number or by the directory that contain them. Volume 0 is typically IRIS.DAT.