Quick Start: Progress DataDirect® for ODBC for MongoDBTM Driver on UNIX and Linux (32-bit and 64-bit)

The following basic information enables you to connect with and test your driver immediately after installation. For installation instructions, see the Progress DataDirect for ODBC Drivers Installation Guide. This Quick Start covers the following topics:

Driver Requirements

Environment Setup

Test Loading the Driver

Connecting to a Database

Testing the Connection

Tuning the Drivers for Optimal Performance

ODBCHOME in the following sections refers to your installation directory path determined at installation.

Driver Requirements

The driver requires a Java Virtual Machine (JVM): J2SE 6 or higher. Before you configure a data source for the driver, you must set the library path environment variable for your operating system to the directory containing your JVM's libjvm.so [sl | a] file, and that directory's parent directory. The library path environment variable is:

        LD_LIBRARY_PATH on Linux, Oracle Solaris, and HP-UX Itanium

        SHLIB_PATH on HP-UX PA-RISC

        LIBPATH on AIX

For AIX Users: Before you can use the driver, you must set the LIBPATH environment variable to include the paths containing the libjvm.so library and the libnio.so library, which are installed in a subdirectory of your Java Development Kit (JDK). For example, you would add the following paths for Java 6 installed in the /usr directory:

:/usr/java6/jre/lib/ppc/classic:/usr/java6/jre/lib/ppc

In this example, /usr/java6/jre/lib/ppc/classic is the location of libjvm.so, while /usr/java6/jre/lib/ppc is the location of libnio.so.

Environment Setup

1       Check your permissions: Log in as a user with full r/w/x permissions recursively on the entire Progress DataDirect for ODBC Drivers installation directory.

2       Determine which shell you are running: From the login shell, execute the echo $SHELL command.

3       Run the DataDirect setup script to set variables: Two scripts, odbc.csh and odbc.sh, are installed in the installation directory. For Korn, Bourne, and equivalent shells, execute odbc.sh. For a C shell, execute odbc.csh. After running the setup script, execute the env command to verify that the ODBCHOME/lib directory has been added to your shared library path.

4       Set ODBCINI variable: Progress DataDirect for ODBC Drivers install a default odbc.ini file, where your data sources reside, in the installation directory. You must set the ODBCINI environment variable to point to the path of the odbc.ini file. For example:

$ ODBCINI= ODBCHOME/odbc.ini; export ODBCINI

Test Loading the Driver

The ivtestlib (32-bit drivers) and ddtestlib (64-bit drivers) test loading tools are provided to verify that the driver can be loaded into memory; they are located in the ODBCHOME/bin directory. For example, to load the 32-bit driver, you would enter:

$ ivtestlib ODBCHOME/lib/ivmongonn.zz

where nn represents the driver level number and zz represents the extension.

If the load is successful, the test loading tool returns a success message along with the version string of the driver. If the driver cannot be loaded, test loading tool returns an error message explaining why.

Connecting to a Database

The following procedure is applicable to all UNIX/Linux systems.

Defining a Data Source in the odbc.ini

The default odbc.ini file installed in the installation directory is a template in which you create data source definitions. You enter your site-specific database connection information using a text editor. Each data source definition must include the keyword Driver=, which is the full path to the driver.

The following examples show the minimum connection string options that must be set to complete a test connection, where xx represents iv for 32-bit or dd for 64-bit drivers, nn represents the driver level number, and zz represents the extension. The values for the options are samples and are not necessarily the ones you would use.

To configure a connection, you might enter:

[MongoDB]
Driver=ODBCHOME/lib/xxmongonn.zz
Database=mongodb2

HostName=MongodbServer
PortNumber=27017

SchemaDefinition=~/progress/datadirect/mongodb_schema/MongodbServer.config

Connection Options

        Database: The name of the database to which you want to connect by default. The default is INFORMATION_SCHEMA.

Important: This value is case-insensitive if you have access privileges to query the list of databases on the server. If you do not have access, it is case-sensitive.

        HostName: Either the name or the IP address of the server to which you want to connect.

        PortNumber: The port number of the server listener. The default is 27017.

        SchemaDefinition: The name and location of the configuration file where the relational map of native data is written. The driver either creates or looks for this file when connecting to the database. The default is:

        ~/progress/datadirect/mongodb_schema/hostname.config

where:

hostname is the value specified for the HostName connection option.

Testing the Connection

The Progress DataDirect for ODBC for MongoDB driver installation includes a program named example that can be used to connect to a data source and execute SQL. The application is located in the ODBCHOME/example directory. To run the program, type example and follow the prompts to enter your data source name, user name, and password. If successful, a SQL> prompt appears and you can type in SQL Statements such as

SELECT * FROM accounts

If example is unable to connect, the appropriate error message appears.

Tuning the Drivers for Optimal Performance

The drivers have connection options that directly affect performance. To tune these drivers for performance, set the following connection options:

If your application does not use threads

ApplicationUsingThreads=0

If your application requires encryption of data

Controlled by EncryptionMethod=. Data encryption may adversely affect performance because of the additional overhead (mainly CPU usage) required to encrypt and decrypt data

If you know the typical fetch size for your application

FetchSize= the number of rows your application is configured to retrieve. Smaller fetch sizes can improve the initial response time of the query. Larger fetch sizes improve overall fetch times at the cost of additional memory.

If your application retrieves large sets of data

ResultMemorySize= controls the maximum size of an intermediate result set the driver holds in memory. When the size of an intermediate result sets exceed the limit determined by this option, the driver writes to disk, which results in performance loss. Increase the value specified to improve performance.

Note: If the size of an intermediate result set exceeds the available heap size used by the JVM, an out of memory error is returned. If you receive this error, decrease the value specified until results are successfully returned. Alternatively, you can increase the available memory by adjusting the JVMArgs option.

JVMArgs= specifies the heap size used by the JVM. Used in conjunction with the Result Memory Size connection option, you can address memory and performance concerns by increasing the maximum Java heap size to ensure that result sets fit easily within the free heap space. For example, for a heap size of 1024 MB, specify JVMArgs={-Xmx1024m}.

If your application does not require the most recent version of data

ReadPreference=secondary | secondaryPreferred

 

When connecting to a replica set, reading from secondary members (read-only server nodes) can improve performance by distributing queries across secondary members and reducing the demand on the primary member (read-write server node).

© 2016. Progress Software Corporation. All rights reserved.

5/16, 8.0.1