Installing Mimer SQL
|
|
The Mimer SQL software installation on macOS is expected to be completed in less than a minute, and creating the initial data dictionary and starting the database server will only take just a little longer.
Download a suitable distribution package from https://developer.mimer.com/downloads and follow the instructions given below. The Mimer SQL distribution is provided as a PKG package file.
It is really simple to get going!
To get up-and-running with Mimer SQL is usually made in a minute or two. Here is a quick step-by-step instruction using a sample macOS distribution package. The details will be given in the following sections.
You can either use the installed apps to get going, see Using the Mimer SQL apps, or via the macOS Terminal application, see From the Terminal application.
1Download package
Download Mimer SQL for macOS from https://developer.mimer.com/products/downloads/.
2Install the package
Install Mimer SQL by double-clicking the downloaded .pkg file, using the Apple Installer.
3Create a database
Open the Mimer SQL Database Install application, obtained when installing Mimer SQL.
4Control the database
Use the application Mimer SQL Database Admin to control the created Mimer SQL database.
5Access the database
Use the provided DbVisualizer app for database access. For example, if the example environment was chosen to be installed, connect to the database using the ident MIMER_STORE with password ‘GoodiesRUs’.
1Download package
Download Mimer SQL for macOS from https://developer.mimer.com/products/downloads/.
2Install the package
From the Terminal application, usually located in the Utilities folder, the distribution package can be installed as follows:
$ sudo installer -pkg mimersql1107-11.0.7F-41154_macosxi_64.pkg -target /
Password:
installer: Package name is Mimer SQL
installer: Installing at base path /
installer: The install was successful.
$
3Create a database
Run dbinstall to create the initial Mimer SQL database named ‘testdb’. Specify -e to include an example environment:
# dbinstall -e testdb
4Control the database
Verify the database server status by using the Mimer SQL administration tool mimadmin, which can be used to control the database:
# mimadmin testdb
5Access the database
From the Terminal application, use bsql to access the database and the example environment as follows, using the ident MIMER_STORE with password ‘GoodiesRUs’:
# bsql testdb
Mimer SQL Command Line Utility Version 11.0.6C Beta Test
Copyright (C) Mimer Information Technology AB. All rights reserved.
Username: mimer_store
Password:
SQL>select * from categories;
category_id category
=========== ====================
1 Music
2 Books
3 Video
3 rows found
SQL>exit;
#
Why do we need sudo access to install?
To provide for a complete and proper easy-to-use installation, the procedure when installing Mimer SQL is doing all needed installation actions automatically. This includes updates to operating system locations, such as /usr/local/bin, /usr/local/lib and /etc. For example, the following tasks are handled:
•TCP/IP settings for Mimer SQL client/server access (using the launchd daemon with /Library/LaunchDaemons/com.mimer.mimersqlPortListen.plist)
•autostart settings for Mimer SQL databases (using the launchd daemon with /Library/LaunchDaemons/com.mimer.mimersqlAutoStart11.plist)
•desktop menu items
•system wide Mimer SQL database catalog (/etc/sqlhosts)
•system wide ODBC data source catalog (typically /etc/odbc.ini and /etc/odbcinst.ini)
•system wide Mimer SQL man-page setup (/usr/man, or /usr/local/share/man)
•easy access for Mimer SQL programs and libraries (/usr/local/bin and /usr/local/lib)
To achieve this, the installation requires sudo access (administration authority), or it has to be executed as root.
On an x86-64 based computer, at least macOS 10.15 (Catalina) has to be used.
On an ARM based computer, at least macOS 11.0 (Big Sur) has to be used.
The amount of physical memory used by the database server process is determined by parameters in the local database definition, whose initial default values are determined by looking at the amount of installed memory.
See The multidefs parameter file for further details.
Also see the chapter Managing a database server in the Mimer SQL System Management Handbook, for the use of system resources.
The amount of virtual memory that the database server process can use is limited by the operating system.
Which components will be installed?
The complete Mimer SQL distribution contains the following:
•Tools, libraries, examples, man-pages, etc.
•A complete documentation set in PDF format.
•An ODBC Driver, available in the libmimodbc shared library - see the chapter Mimer SQL and the ODBC API, in Programmer’s Manual. This driver can be used for direct access to a Mimer SQL database, or it can be used with a third party ODBC Driver Manager, for example unixODBC, or iODBC.
•A JDBC Driver, type-4, written in 100% Java - see the chapter Mimer SQL and the JDBC API, in Programmer’s Manual.
•Various other database API’s, like Embedded SQL, Module SQL and a native Mimer C API.
•GUI application for database installation, called Mimer SQL Database Install.
•GUI application for database administration, called Mimer SQL Database Admin.
•GUI application for database access and interaction, called DbVisualizer.
•GUI application for the PSM debugger.
The default installation location is /opt, where a sub directory named according to the package is created. For example, if Mimer SQL 11.0.0A is installed, an installation path like /opt/mimersql1100-11.0.0A is used. This Mimer SQL main installation directory then contains the following sub directories:
•bin - contains Mimer SQL tools, and other executable files.
•doc - contains Mimer SQL documentation.
•examples - contains example files.
•include - contains various header files that may be needed when developing with Mimer SQL.
•lib - contains library files.
•man - contains Mimer SQL man pages.
•misc - contains various additional files, like desktop menu system resources.
Additional Python interface
The Python interface towards Mimer SQL is downloaded and installed separately using the following command:
python -m pip install mimerpy
Running several Mimer SQL versions in parallel
If it is desirable to run two or more Mimer SQL versions in parallel on a host computer, this is fully feasible. Just be sure to do a proper setup of related environment variables to point to the version currently targeted, see Environment Variables.
To start the installed database server and to establish connections to the database, a license key is required. A key valid for development and evaluation only is included in the Mimer SQL distribution. This key is usually installed automatically during installation of the Mimer SQL package.
Whenever a user connects to a Mimer SQL database, the computer identification and the license key will be checked by the database server to determine access rights. If access is denied, the connect attempt will be aborted and an error message will be shown.
The Mimer SQL license key contains the following (encrypted) information:
•The maximum number of users that may use the database servers running on the same computer node at any one time.
•The maximum number of network users that may use the database servers running on the same computer node at any one time.
•The ID of the computer (in the case of a specific key) or a lifeboat key which is valid for any computer of the platform type for which it was issued (e.g. any macOS machine).
•Version number.
•Expiration date for the key.
The key data is case insensitive and space characters are ignored.
The mimlicense application is used to administrate the license key file. See MIMLICENSE - Managing the license key in System Management Handbook for information on how to use it. The following command will list the licenses installed:
# mimlicense -l
As mentioned above, for a production system a commercial license is required. A new key will also be needed if the key expires, if the number of Mimer SQL users is increased or if new Mimer SQL functionality is added.
The Mimer SQL license key is provided by your Mimer SQL distributor. In order to be able to generate the key, your Mimer SQL distributor must know the ID of the computer on which the database server will run.
The ID of a macOS machine is obtained by using the following command:
# mimlicense -i
Once the software is installed, the next step is to build a Mimer SQL database by using the dbinstall command. (On macOS there is also a GUI frontend application for the dbinstall command, named Mimer SQL Database Install. Here follows the description of the command line command.)
As mentioned before, the dbinstall command requires sudo access, or must be executed by root. If not started from a privileged shell sudo password will be asked for:
# dbinstall [<database name>]
If a database name is given, the dbinstall session is completed with default settings used as far as possible. Otherwise, during the dbinstall session, database name, database location, and password for the database administrator (i.e. SYSADM) will be asked for. There will also be options for installing example environments, etc. When the session is completed, a fully operational database is available - enabled for client/server access over TCP and automatic start at reboot.
Note:dbinstall creates all system databank files in the given database server home directory. In a production system it is recommended that the SYSDB, TRANSDB and LOGDB files are located on separate disks due to performance and reliability reasons. You can read more about this in the Mimer SQL System Management Handbook part of the Mimer SQL Documentation Set (found at the Documentation page).
Once the database is up and running it may be of interest to provide for remote access. To achieve this the database should be registered as a REMOTE on each node in the network from which it is to be accessed - see more on database registration below.
Now the database is ready for data storage, creating a storage structure build on idents and data objects using the data definition statements in Mimer SQL.
To summarize, the dbinstall command performs all necessary installation steps to create an initial database and getting it up and running. The options available in dbinstall give opportunities to control and carry out the following:
•Deciding a database home directory
•Registering the database
•Deciding the SYSADM password
•Creating the system databanks, including the data dictionary
•Deciding owner of the database
•Setting up the networking environment
•Setting up autostart procedure
•Setting up a data source definition for ODBC use
•Creating an example database
•Creating a basic development setup with a user that has an OS_USER login (see the Mimer SQL Reference Manual for details)
•Creating the default database configuration file
•Starting the database created
Many of these tasks are described in a more general and detailed manner further on in this document.
Upgrading an existing database
If you are upgrading an existing database from an earlier version of Mimer SQL, please see the Mimer SQL Release Notes for detailed information. The Release Notes document is provided within each Mimer SQL distribution package. In short the steps are as follows:
1Install the new Mimer SQL version in parallel with your existing Mimer SQL.
2Stop the database.
3Make sure the new Mimer SQL version is the one accessed, and run the sdbgen -u database command from the new Mimer SQL version.
4Start the database with the database server program from the new Mimer SQL version.
What happens to the databases?
The commands described below will remove the given software installation, but any databases using the installation will remain intact. Since databases may contain valuable data, the removal of databank files is not performed unless an explicit call to dbuninstall, specifying removal of data, is done.
If a database, and its databank files, is going to be removed, use the dbuninstall command. When executed, a question will be raised asking if specified database should be removed, i.e. permanently deleted.
# dbuninstall <database_name>
The database registration file is used to list all the databases that are accessible to a Mimer SQL application from the node on which it resides. All users must have read access to the sqlhosts file on the machine they are using in order to run applications and utilities accessing Mimer SQL databases. The standard location for this file is /etc/sqlhosts. By using the environment variable name MIMER_SQLHOSTS, another file can be used.
In a network environment, the name of a database must be registered on each node from which it is to be accessed. A database is created as a local database on the node where it resides, and it is defined as a remote database on each other node in the network from which access to it is required. For general information on how to make databases accessible, refer to Registering the Database in System Management Handbook.
The program mimsqlhosts can be used to manage the contents of the local sqlhosts file instead of editing it manually. To list the complete content of the sqlhosts file, simply use the following command:
# mimsqlhosts
When the dbinstall command is used to install a local database, an entry for it is automatically added to the LOCAL section of the sqlhosts file on that node, see LOCAL section.
If the file is not found, a default sqlhosts file is automatically generated. (See the mimsqlhosts and sqlhosts man-pages).
The sqlhosts file structure
The SQLHOSTS file contains three sections; DEFAULT, LOCAL and REMOTE.
The names of the local databases on the current node are listed in the LOCAL section, see LOCAL section, and the names of the remote databases accessible from the node are listed in the REMOTE section, see REMOTE section.
One of the local or remote databases can be set to be the default database for the node by specifying its name in the DEFAULT section, see DEFAULT section.
Database names may, in general, be up to 128 characters long and are case-insensitive.
A line of text beginning with the character sequence -- is interpreted as a comment in the sqlhosts file.
The default SQLHOSTS file
When the first Mimer SQL system is installed on a node, the following default sqlhosts file is automatically generated:
-- ------------------------------------------------------------------------
--
-- S Q L H O S T S
-- ===============
--
-- This file contains a list of all databases, local and remote, accessible
-- from the node where the file resides.
--
-- The DEFAULT label
-- -----------------
-- Name of default database. Can be either a REMOTE or LOCAL database name.
-- Can be overridden by setting MIMER_DATABASE to the name of a database.
--
-- The LOCAL label
-- ---------------
-- A list of all local databases on the current node, containing the
-- database name and a directory specification (Path).
-- UNIX Path - database home, and directory path for databank lookup.
-- VMS Path - database home.
--
-- The REMOTE label
-- ----------------
-- A list of all remote databases containing the database name, the database
-- node, the protocol to be used, the protocol interface and the protocol
-- service to be used.
--
-- Protocol, Interface and Service may be defaulted by entering ''.
--
-- Node - network node name for computer on which the database resides.
-- Protocol - currently tcp is supported. (tcp or '' should be specified)
-- Interface - currently not used ('' should be specified).
-- Service - corresponds to the port number used in TCP/IP. The port number
-- Default is 1360, i.e. the port number reserved for MIMER.
-- On UNIX: The port number may either be a number or a name of a
-- service stored in the /etc/services file.
--
-- ===========================================================================
DEFAULT:
--
-- Database
-- ------------------------------------------------------------------------
example_localdb
-- ===========================================================================
LOCAL:
--
-- Database Path
-- ------------------ -----------------------------------------------------
SINGLE .
example_localdb /directory
-- ===========================================================================
REMOTE:
--
-- Database Node Protocol Interface Service
-- ------------------ ------------------ -------- --------- ---------------
example_remotedb server_nodename '' '' 1360
The DEFAULT section contains a single line that specifies the default database which will be used by a Mimer SQL application or command that does not explicitly specify a database to connect to, see The Default Database section in System Management Handbook.
The default database should be one of those listed in the LOCAL or REMOTE sections.
The LOCAL section contains a list of all the local databases residing on the current machine, see The Local Database section in System Management Handbook.
Each line under the LOCAL keyword should contain two fields, separated by one or more blanks or tab characters. The first field specifies the database name, and the second specifies the location.
The location field is usually a single directory path, referred to as the database home directory. But, it may also be a colon (:) separated search path specification, where each directory included in the path list can hold databank files for the Mimer SQL database server. In that case the first directory in the search path is taken as the database home directory and the other directories in the search path will be used to locate databank files which have a file specification stored in the data dictionary without an explicit directory.
Using a path list is one way to arrange for having databank files on separate disks for optimal performance and reliability - see the System Management Handbook.
The REMOTE section contains a list of all accessible databases that reside on other nodes in the network environment, see the section Accessing a Database Remotely in System Management Handbook.
Access to these databases is provided by using TCP/IP to establish a client/server connection to the remote machine.
Each entry in the REMOTE section contains up to five fields, separated by spaces and/or tab characters.
The DATABASE field specifies the name of the remote database.
The NODE field should specify the network node name of the remote machine. If the TCP/IP interface is used, the IP address may be specified here.
The PROTOCOL field should specify tcp or two single quotation marks ''.
The INTERFACE field is currently not used. Specify '' (two single quotation marks) here.
If using TCP/IP, the SERVICE field specifies the TCP/IP port number the database server uses. The default is 1360, which has been reserved by Mimer Information Technology AB for Mimer SQL client/server communication.
When TCP/IP is used, the value in the SERVICE field may be the actual port number, the name of a service stored in the /etc/services file or two single quotation marks '' for the default value 1360.
The remote section parameters are summarized below, depending on the protocol selected. The character sequence '' is two single quotation marks, and specifies the default value for a parameter:
|
Parameter |
Explanation |
|
DATABASE |
Remote database name |
|
NODE |
TCP/IP node name or IP number |
|
PROTOCOL |
'', TCP or tcp |
|
INTERFACE |
'' (two single quotation marks) |
|
SERVICE |
TCP/IP_port_number, TCP/IP service name or ''. (When '' is used to specify the default SERVICE, the TCP/IP port number 1360 will be used.) |