Namespaces and Databases
This page describes how InterSystems IRIS® data platform organizes data and code.
Introduction to Namespaces and Databases
In InterSystems IRIS, any code runs in a namespace, which is a logical entity. A namespace provides access to data and to code, which is stored (typically) in multiple databases. A database is a file — an IRIS.DAT file. InterSystems IRIS provides a set of namespaces and databases for your use, and you can define additional ones.
In a namespace, the following options are available:
-
A namespace has a default database in which it stores code; this is the routines database for this namespace.
When you write code in a namespace, the code is stored in its routines database unless other considerations apply. Similarly, when you invoke code, InterSystems IRIS looks for it in this database unless other considerations apply.
-
A namespace also has a default database to contain data for persistent classes and any globals you create; this is the globals database for this namespace.
So, for example, when you access data (in any manner), InterSystems IRIS retrieves it from this database unless other considerations apply.
The globals database can be the same as the routines database, but it is often desirable to separate them for maintainability.
-
A namespace has a default database for temporary storage.
-
A namespace can include mappings that provide access to additional data and code that is stored in other databases. Specifically, you can define mappings that refer to routines, class packages, entire globals, and specific global nodes in non-default databases. (These kinds of mappings are called, respectively, routine mappings, package mappings, global mappings, and subscript-level mappings. )
When you provide access to a database via a mapping, you provide access to only a part of that database. The namespace cannot access the non-mapped parts of that database, not even in a read-only manner.
Also, it is important to understand that when you define a mapping, that affects only the configuration of the namespace. It does not change the current location of any code or data. Thus when you define a mapping, it is also necessary to move the code or data (if any exists) from its current location to the one expected by the namespace.
Defining mappings is a database administration task and requires no change to class/table definitions or application logic.
-
Any namespace you create has access to most of the InterSystems IRIS code library. This code is available because InterSystems IRIS automatically establishes specific mappings for any namespace you create.
To find tools for a particular purpose, see the InterSystems Programming Tools Index.
-
When you define a namespace, you can cause it to be interoperability-enabled. This means that you can define a production in this namespace. A production is a program that uses InterSystems IRIS Interoperability features and integrates multiple separate software systems; to read about this, see Introducing Interoperability Productions.
Mappings provide a convenient and powerful way to share data and code. Any given database can be used by multiple namespaces. For example, there are several system databases that all customer namespaces can access, as discussed later in this page.
You can change the configuration of a namespace after defining it, and InterSystems IRIS provides tools for moving code and data from one database to another. Thus you can reorganize your code and data during development, if you discover the need to do so. This makes it possible to reconfigure InterSystems IRIS applications (such as for scaling) with little effort.
Locks, Globals, and Namespaces
Because a global can be accessed from multiple namespaces, InterSystems IRIS provides automatic cross-namespace support for its locking mechanism. A lock on a given global applies automatically to all namespaces that use the database that stores the global.
Database Basics
An InterSystems IRIS database is an IRIS.DAT file. You create a database via the Management Portal. Or if you have an existing InterSystems IRIS database, you can configure InterSystems IRIS to become aware of it.
Database Configuration
For any database, InterSystems IRIS requires the following configuration details:
-
Logical name for the database.
-
Directory in which the IRIS.DAT file resides. When you create a database in the Management Portal, you are prompted to choose or create a subdirectory within the system manager’s directory (install-dir/Mgr), but you can store the database file in any convenient directory.
Tip:It is convenient to use the same string for the logical name and for the directory that contains the IRIS.DAT file. The system-provided InterSystems IRIS databases follow this convention.
Additional options include the following:
-
Default directory to use for file streams used by this database.
This is important because your users will need write access to this directory; if not, your code will not be able to create file streams.
-
Collation of new globals.
-
Initial size and other physical characteristics.
-
Option to enable or disable journaling. Journaling tracks changes made to an InterSystems IRIS database, for up-to-the-minute recovery after a crash or restoring your data during system recovery.
In most cases, it is best to enable journaling. However, you might want to disable journaling for designated temporary work spaces; for example, the IRISTEMP database is not journaled.
-
Option to mount this database for read-only use.
If a user tries to set a global in a read-only database, InterSystems IRIS returns a <PROTECT> error.
In most cases, you can create, delete, or modify database attributes while the system is running.
Database Features
With each database, InterSystems IRIS provides physical integrity guarantees for both the actual data and the metadata that organizes it. This integrity is guaranteed even if an error occurs during writes to the database.
The databases are automatically extended as needed, without manual intervention. If you expect a particular database to grow and you can determine how large it will become, you can “pre-expand” it by setting its initial size to be near the expected eventual size. If you do so, the performance is better.
InterSystems IRIS provides a number of strategies that allow high availability and recoverability. These include:
-
Journaling — Introduced earlier.
-
Mirroring — Provides rapid, reliable, robust, automatic failover between two InterSystems IRIS systems, making mirroring the ideal automatic failover high-availability solution for the enterprise.
-
Clustering — There is full support of clustering on operating systems that provide it.
InterSystems IRIS has a technology for distributing data and application logic and processing among multiple systems. It is called the Enterprise Cache Protocol (ECP). On a multiserver system, a network of InterSystems IRIS database servers can be configured as a common resource, sharing data storage and application processing, with the data distributed seamlessly among them. This provides increased scalability as well as automatic failover and recovery.
Database Portability
InterSystems IRIS databases are portable across platforms and across versions, with the following caveat:
-
On different platforms, any file is either big-endian (that is, most-significant byte first) or little-endian (least-significant byte first).
InterSystems IRIS provides a utility to convert the byte order of an InterSystems IRIS database; it is called cvendian. This is useful when moving a database among platforms of the two types.
System-Supplied Databases
InterSystems IRIS provides the following databases:
Read-only database contains additional code needed for InterSystems IRIS Interoperability features, specifically the ability to create productions, which integrate separate software systems.
If you create a namespace that is interoperability-enabled, that namespace has access to the code in this database.
Read/write database used for audit records. Specifically, when you enable event logging, InterSystems IRIS writes the audit data to this database.
Read-only database that includes the object, data type, stream, and collection classes and many other class definitions. It also includes the system include files, generated INT code (for most classes), and generated OBJ code.
InterSystems does not support moving the IRISLIB database.
Read/write database that contains items used internally by InterSystems IRIS, such as cached SQL queries and CSP session information.
No customer application should directly interact with the IRISLOCALDATA database. This database is purely for internal use by InterSystems IRIS.
Read/write database includes utilities and data related to system management. It is intended to contain specific custom code and data of yours and to preserve that code and data upon upgrades.
This database contains or can contain:
-
Users, roles, and other security elements (both predefined items and ones that you add).
For reasons of security, the Management Portal handles this data differently than other data; for example, you cannot display a table of users and their passwords.
-
Data for use by the NLS (National Language Support) classes: number formats, the sort order of characters, and other such details. You can load additional data.
-
Your own code and data. To ensure that these items are preserved upon upgrades, use the naming conventions in Custom Items in IRISSYS.
InterSystems does not support moving, replacing, or deleting the IRISSYS database.
The directory that contains this database is the system manager’s directory. The messages log (messages.log) is written to this directory, as are other log files.
For additional detail on IRISSYS, see Using Resources to Protect Assets.
Read/write database used for temporary storage. InterSystems IRIS uses this database, and you can also use it. Specifically, this database contains temporary globals. For details, see Temporary Globals and the IRISTEMP Database.
An initially empty read/write database meant for your custom code. You do not have to use this database.
Databases that provide code for IRIS for Health™ and for HealthShare®. Not available in other products.
Databases that provide access to HealthShare® features; applies only to HealthShare. Not available in other products.
Read/write database used for temporary storage used internally by InterSystems IRIS. This database is not journaled, not mirrored, and has no public permissions; it is used to store temporary globals.
No customer application should directly interact with the HSSYSLOCALTEMP database. This database is purely for internal use by InterSystems IRIS.
System-Supplied Namespaces
InterSystems IRIS provides the following namespaces:
The namespace in which it is possible to execute privileged system code. See %SYS Namespace.
An initially empty namespace meant for your custom code. You do not have to use this namespace.
A namespace configured to support interoperability productions. That is, this namespace is interoperability-enabled.
Namespaces that provide access to features for IRIS for Health™ and for HealthShare®. Not available in other products.
Namespaces that provide access to HealthShare® features; applies only to HealthShare. Not available in other products.
A namespace that provides access to the HSSYSLOCALTEMP database.
%SYS Namespace
The %SYS namespace provides access to code that should not be available in all namespaces — code that manipulates security elements, the server configuration, and so on.
For this namespace, the default routines database and default globals database is IRISSYS. If you follow certain naming conventions, you can create your own code and globals in this namespace and store them in the IRISSYS database; see Custom Items in IRISSYS.
What Is Accessible in Your Namespaces
When you create a namespace, the system automatically defines mappings for that namespace. As a result, in that namespace, you can use the following items (provided you are logged in as a user with suitable permissions for these items):
-
Any class whose package name starts with a percent sign (%). This includes most, but not all, classes provided by InterSystems IRIS.
-
All the code stored in the routines database for this namespace.
-
All the data stored in the globals database for this namespace.
-
Any routine whose name starts with a percent sign.
-
Any include file whose name starts with a percent sign.
-
Any global whose name starts with a caret and a percent sign (^%). These globals are generally referred to as percent globals. Note that via global mappings or subscript level mappings, it is possible to change where percent globals are stored, but that has no effect on their visibility. Percent globals are always visible in all namespaces.
-
Your own globals with names that start ^IRIS.TempUser — for example, ^IRIS.TempUser.MyApp. If you create such globals, these globals are written to the IRISTEMP database.
-
If the namespace is interoperability-enabled, you can use code in the Ens and EnsLib packages. The CSPX and EnsPortal packages are also visible but these are not meant for direct use.
If a namespace is interoperability-enabled, you can define a production in this namespace. To read about this, see Introducing Interoperability Productions.
-
Any additional code or data that is made available via mappings defined in this namespace.
Via extended global references, your code can access globals that are defined in other namespaces. For information, see Global Structure.
The InterSystems IRIS security model controls which data and which code any user can access.
System Globals in Your Namespaces
Your namespaces contain additional system globals, which fall into two rough categories:
-
System globals that are in all namespaces. These include the globals in which InterSystems IRIS stores your routines, class definitions, include files, INT code, and OBJ code.
-
System globals that are created when you use specific InterSystems IRIS features. For example, if you use Analytics in a namespace, the system creates a set of globals for its own internal use.
In most cases, you should not manually write to or delete any of these globals. See Global Naming Conventions.
Stream Directory
In any given namespace, when you create a file stream, InterSystems IRIS writes a file to a default directory and then later deletes it.
This is important because your users will need write access to this directory; if not, your code will not be able to create file streams.
The default directory is the stream subdirectory of the globals database for this namespace.
See Also
For more information on the topics covered in this page, see the following:
-
Using Globals has information on working with globals, including using extended references.
-
Using cvendian to Convert Between Big-endian and Little-endian Systems has information on cvendian.
-
High Availability Guide has information on high availability and recoverability.
-
Scalability Guide has information on distributed caching and sharding.
