Simba MongoDB ODBC Driver with SQL Connector User …€¦ · Simba MongoDB ODBC Driver with SQL Connector . User Guide . Last Revised: March 14, 2013 . Simba Technologies Inc

Simba MongoDB ODBC Driver with SQL Connector

User Guide

Last Revised: March 14, 2013

Simba Technologies Inc.

Simba MongoDB ODBC Driver with SQL Connector User Guide

www.simba.com i

Copyright ©2012-2013 Simba Technologies Inc. All Rights Reserved.

Information in this document is subject to change without notice. Companies, names and data used in examples herein are fictitious unless otherwise noted. No part of this publication, or the software it describes, may be reproduced, transmitted, transcribed, stored in a retrieval system, decompiled, disassembled, reverse-engineered, or translated into any language in any form by any means for any purpose without the express written permission of Simba Technologies Inc.

Trademarks

Simba, the Simba logo, SimbaEngine, SimbaEngine C/S, SimbaExpress and SimbaLib are registered trademarks of Simba Technologies Inc. All other trademarks and/or servicemarks are the property of their respective owners.

Contact Us

Simba Technologies Inc. 938 West 8th Avenue Vancouver, BC Canada V5Z 1E5

www.simba.com

Telephone +1 (604) 633-0008 sales: extension 2, support: extension 3 Fax +1 (604) 633-0004

Information and product sales: [email protected]

Technical support: [email protected]

Follow us on Twitter:

@simbatech

Printed in Canada

mailto:[email protected]


www.simba.com ii

Table of Contents Introduction ........................................................................................................................................................1

Contact Us ...........................................................................................................................................................1

Windows Driver ..................................................................................................................................................2 System requirements .................................................................................................................................2 Installation .....................................................................................................................................................2 Configuration ...............................................................................................................................................5 Schema definition .......................................................................................................................................9

Features ............................................................................................................................................................. 10 SQL Connector ........................................................................................................................................... 11 Data Types ................................................................................................................................................... 11 Authentication .......................................................................................................................................... 13 Catalog Support ........................................................................................................................................ 13

Third Party Trademarks ................................................................................................................................ 14


www.simba.com 1

Introduction The Simba MongoDB ODBC Driver enables Business Intelligence (BI), analytics and reporting on data that is stored in MongoDB databases. It complies with the ODBC 3.52 data standard and adds important functionality such as Unicode and 32- and 64-bit support for high-performance computing environments on all platforms.

ODBC is one the most established and widely supported APIs for connecting to and working with databases. At the heart of the technology is the ODBC driver, which connects an application to the database. For more information about ODBC, see http://www.simba.com/odbc.htm. For complete information on the ODBC 3.52 specification, see the MSDN ODBC Programmer's Reference, available from the Microsoft web site at http://msdn.microsoft.com/en-us/library/ms714562(VS.85).aspx

Contact Us If you have difficulty using Simba MongoDB ODBC Driver with SQL Connector, please contact our support staff. We welcome your questions, comments, and feature requests. Please have a detailed summary of the client and server environment (OS version, patch-level, MongoDB distribution version, configuration etc.) ready, before you call or write to us. Supplying this information accelerates support.

By telephone:

Call (604) 633-0008 and press 3

Customer Support is available Monday – Friday, from 8 a.m. until 5 p.m. Pacific Time.

By fax or e-mail:

Fax (604) 633-0004

Send e-mail to [email protected]

On the Internet:

Visit us at www.simba.com.

Follow us on Twitter: @simbatech

http://www.simba.com/odbc.htm

http://msdn.microsoft.com/en-us/library/ms714562(VS.85).aspx

http://msdn.microsoft.com/en-us/library/ms714562(VS.85).aspx

mailto:[email protected]

http://www.simba.com/


www.simba.com 2

Windows Driver System requirements

• Windows® XP with SP3, Windows® Vista, Windows® 7 Professional or Windows® 2008 R2. Both 32-bit and 64-bit editions are supported.

• 25 MB of available disk space.

Installing the driver requires administrator privileges.

Installation There are two versions of the driver for Windows:

• SimbaMongoDBODBC32.msi for 32-bit editions of Windows

• SimbaMongoDBODBC64.msi for 64-bit editions of Windows

The version of the driver that you select should match the bitness of the application. For example, if the application is 64-bit then you should install the 64-bit driver. It is allowable to install both versions of the driver.

The following document explains how to use ODBC on 64-bit editions of Windows: http://www.simba.com/docs/HOW-TO-32-bit-vs-64-bit-ODBC-Data-Source-Administrator.pdf.

http://www.simba.com/docs/HOW-TO-32-bit-vs-64-bit-ODBC-Data-Source-Administrator.pdf


www.simba.com 3

To install the driver: 1. Double-click the appropriate MSI file.

The Simba MongoDB ODBC Driver Setup window opens.

2. Click Next. The End-User License Agreement page is displayed.


www.simba.com 4

3. Select the "I accept the terms in the License Agreement" checkbox and then, click Next. The Destination Folder page is displayed.

4. Click Next. The Ready to install Simba MongoDB ODBC Driver page is displayed.

5. Click Install.


www.simba.com 5

6. When the Windows User Account Control window appears, click Yes. When the installation is finished, the Completed the Simba MongoDB ODBC Driver Setup Wizard page is displayed.

7. Click Finish. The Simba MongoDB ODBC Driver installation is complete. The next step is to create a Data Source Name.

Configuration

Create a Data Source Name (DSN) 1. Click the Start button .

2. Click All Programs.

3. Click the Simba MongoDB ODBC Connector 1.0 (64-bit) or the Simba MongoDB ODBC Connector 1.0 (32-bit) program group. If you installed both versions of the driver, you will see two program groups.

Because DSNs are bit-specific, select the version that matches the bitness of your application. For example, a DSN that is defined for the 32-bit driver will only be accessible from 32-bit applications.


www.simba.com 6

4. Click 64-bit ODBC Driver Manager or 32-bit ODBC Driver Manager. The ODBC Data Source Administrator window opens.

5. Click the Drivers tab and verify that the Simba MongoDB ODBC Driver is displayed in the list

of ODBC drivers that are installed on your system.

6. Click the System DSN tab to create a system DSN or click the User DSN tab to create a user DSN. Note: A system DSN can be seen by all users that login to a workstation. A user DSN is specific to a user on the workstation. It can only be seen by the user who creates it.

7. Click Add. The Create New Data Source window opens.


www.simba.com 7

8. Select Simba MongoDB ODBC Driver and then click Finish.

The Simba MongoDB ODBC Connector Setup window opens.

9. In the Data Source Name text box, type a name for your DSN.

10. Optionally, in the Description text box, enter a description.

11. In the Host text box, type the name or IP address of the host that your MongoDB instance is running on.

12. In the Port text box, type the port that your MongoDB instance is using.

13. In the Database text box, type the name of your MongoDB database.

14. In the Username text box, type your MongoDB username.

15. Optionally, click Advanced Options. The advanced options are described in more detail in the section, Advanced options.

16. Optionally, click Schema Definition. Schema definition is described in more detail in the section, Schema definition.


www.simba.com 8

17. Click OK to finish the configuration and close the Simba MongoDB ODBC Driver Setup window.

18. Click OK to close the ODBC Data Source Administrator window.

Advanced options

The advanced configuration settings can be set any of the following ways:

• with the Simba MongoDB ODBC Driver Setup wizard

• with the database connection string

• with registry settings

The following advanced configuration settings are available:

Option Name Default Value

Description

Rows fetched per block

4096 The number of rows to be fetched per block.

Default string column length

255 The default string column length to use. MongoDB does not provide the length for String columns in its column metadata. This option allows you to tune the length of String columns.

EnableAuthentication 0 Enable user/password authentication during connection. The default of 0 disables this option.

UseSqlWVarchar 0 Map the MongoDB String type to SQL_WVARCHAR instead of SQL_VARCHAR. The default of 0 causes the String type to be mapped to SQL_VARCHAR.

SlaveOk 0 If you have a MongoDB server that is replicated, such that you have secondary servers, then selecting the SlaveOk checkbox allows the system to send queries to the replicated servers as well as to the primary server. If the SlaveOk option is not selected, then all queries go through the primary server.

Set advanced options using the Simba MongoDB ODBC Driver Setup wizard 1. Follow the steps described in the section Create a Data Source Name (DSN).

2. Click Advanced Options. The Advanced Options window opens.


www.simba.com 9

3. Type new values in the text boxes and then click OK.

Set advanced options using the database connection string

An example of a connection string that sets advanced options is as follows:

DSN=Sample Simba MongoDB DSN; Host=192.168.100.100; Port=27017; Database=mydb; UID=myusername; PWD=<password>; RowsFetchedPerBlock=2000; DefaultStringColumnLength=100; EnableAuthentication=1; UseSqlWVarchar=0; SlaveOk=1

Note: Connection string settings override registry settings.

Schema definition 1. Follow the steps described in the section Create a Data Source Name (DSN).

2. Click Schema Definition. An authentication window will open if authentication is enabled via the advanced options.


www.simba.com 10

3. If the authentication window has been displayed, type the database name, username and password and then click OK, upon which the Schema Definition window will open. Otherwise, the Schema Definition window will open immediately.

4. In the Table Name drop-down menu, select a table to work with.

5. The Columns pane displays the name and data type of the columns in the table. The data type is inferred from a sample of the rows that is taken from the table. To change the sample size, in the rows text box, type a number of rows and then click Sample.

6. Optionally, click Add to add a column to your schema definition.

7. Optionally, click Remove to remove a column from your schema definition.

8. The Data Preview pane displays a preview of the data that is contained in the table.

9. Click OK.

The schema data is stored in a collection called “Mersenne_Collection_Metadata”, and if needed this collection can be copied to other MongoDB instances to copy the schema definitions to that instance. Note that removing this collection will also remove any schema definitions that have been saved.


www.simba.com 11

Features SQL Connector

To allow applications to use normal SQL queries against MongoDB, we have added the SQL Connector feature to translate standard SQL-92 queries into equivalent MongoDB API calls. This allows standard queries that BI tools execute to run against your MongoDB instance.

Data Types The following data types are supported:

o String o Boolean o NumberLong o NumberInt o NumberDouble o BinData o Date o jstOID o Object (see below for more information) o Array (see below for more information)

The following types are not yet supported:

o Code o CodeWScope o DBRef o JSTypeMax o MinKey o MaxKey o RegEx o Symbol o Timestamp

Embedded documents

Embedded documents in MongoDB are represented as nested columns in the Simba MongoDB ODBC Driver. Consider the following document:

{contact: {address: {street: “1-123 Broadway”, city: “Vancouver”}}, phone “+12345678”}


www.simba.com 12

The driver will identify the following columns for this document:

Column MongoDB Data Type Data

contact.address.street String 1-123 Broadway

contact.address.city String Vancouver

contact.phone String +12345678

These columns will act in the same way as any other column when being mapped to SQL data types or when generalizing data types.

If there are different fields within a document, then only the most general fields will be identified as columns. Consider the following two documents:

{contact: {address: {street: “1-123 Broadway”, city: “Vancouver”}}, phone “+12345678”}

{contact: {address: “22 Cambie, Vancouver”}, phone “+87654321”}

In these documents, contact.address is not an embedded document in the second document and hence it will be considered as a String instead of another embedded document. The driver will identify the following columns for this document:


contact.address String • {street: “1-123 Broadway”, city: “Vancouver”}

• 22 Cambie, Vancouver

contact.phone String • +12345678

• +87654321

These columns can be used in a SQL query just like any other column, however they will need to be quoted as they contain the separator character. For example:

SELECT “contact.address”, “contact.phone” FROM Contacts

Arrays

Arrays in MongoDB are also represented as nested columns in the Simba MongoDB ODBC Driver. Consider the following array:

values: [“hello”, 1.0, {v1: {v2: “this is an embedded document”}}]

The driver will identify the following columns:


values.0 String Hello

values.1 Double 1.0

values.2.v1.v2 String this is an embedded document


www.simba.com 13

The column names include the index of the item in the array that the column represents, starting with an index of 0. In other words, the first element of the array will use a suffix of “.0”, the second element will use “.1”, and so on.

If there are two fields with the same name where one is an embedded document and the other is an array, then that field will not be represented as nested, instead its data type will be generalized to String.

These columns will act in the same way as any other column when being mapped to SQL data types or when generalizing data types.

These columns can be used in a SQL query just like any other column, however they will need to be quoted as they contain the separator character. For example:

SELECT “values.0”, “values.1”, “values.2.v1.v2” FROM Contacts

Authentication The Simba MongoDB ODBC Driver leverages MongoDB’s built in authentication. This requires users to supply a user name and password for authentication. If your MongoDB instance does not use authentication, then you can disable this from the configuration dialog. See Advanced options for more details.

Catalog Support The Simba MongoDB ODBC Driver supports catalogs by using the name of the MongoDB database as the catalog in order to make it easy for the driver to work with various ODBC applications.


www.simba.com 14

Third Party Trademarks ICU License - ICU 1.8.1 and later

COPYRIGHT AND PERMISSION NOTICE

Copyright (c) 1995-2010 International Business Machines Corporation and others

All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder.

All trademarks and registered trademarks mentioned herein are the property of their respective owners.

OpenSSL

Copyright (c) 1998-2008 The OpenSSL Project. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. All advertising materials mentioning features or use of this software must display the following acknowledgment: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)"

4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected].

5. Products derived from this software may not be called "OpenSSL" nor may "OpenSSL" appear in their names without prior written permission of the OpenSSL Project.

6. Redistributions of any form whatsoever must retain the following acknowledgment: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/)"

THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Expat


www.simba.com 15

"Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ""Software""), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ""AS IS"", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NOINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE."

libcurl

COPYRIGHT AND PERMISSION NOTICE

Copyright (c) 1996 - 2012, Daniel Stenberg, <[email protected]>.

All rights reserved.

Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder.

Documents

Simba MongoDB ODBC Driver with SQL Connector User …€¦ · Simba MongoDB ODBC Driver with SQL Connector . User Guide . Last Revised: March 14, 2013 . Simba Technologies Inc