* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
Download Aster Database Client Guide - Information Products
Survey
Document related concepts
Entity–attribute–value model wikipedia , lookup
Serializability wikipedia , lookup
Microsoft Access wikipedia , lookup
Extensible Storage Engine wikipedia , lookup
Oracle Database wikipedia , lookup
Functional Database Model wikipedia , lookup
Microsoft SQL Server wikipedia , lookup
Ingres (database) wikipedia , lookup
Concurrency control wikipedia , lookup
Relational model wikipedia , lookup
Versant Object Database wikipedia , lookup
Microsoft Jet Database Engine wikipedia , lookup
Database model wikipedia , lookup
Clusterpoint wikipedia , lookup
Transcript
Aster Database Client Guide Release Number 5.0.3 December 2012 The product or products described in this book are licensed products of Teradata Corporation or its affiliates. Teradata, Active Enterprise Intelligence, Applications-Within, Aprimo, Aprimo Marketing Studio, Aster, BYNET, Claraview, DecisionCast, Gridscale, MyCommerce, Raising Intelligence, Smarter. Faster. Wins., SQL-MapReduce, Teradata Decision Experts, "Teradata Labs" logo, "Teradata Raising Intelligence" logo, Teradata ServiceConnect, Teradata Source Experts, "Teradata The Best Decision Possible" logo, The Best Decision Possible, WebAnalyst, and Xkoto are trademarks or registered trademarks of Teradata Corporation or its affiliates in the United States and other countries. Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc. AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc. Apache, Apache Hadoop, Hadoop, and the yellow elephant logo are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries. Axeda is a registered trademark of Axeda Corporation. Axeda Agents, Axeda Applications, Axeda Policy Manager, Axeda Enterprise, Axeda Access, Axeda Software Management, Axeda Service, Axeda ServiceLink, and Firewall-Friendly are trademarks and Maximum Results and Maximum Support are servicemarks of Axeda Corporation. Data Domain, EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation. GoldenGate is a trademark of Oracle. Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company. Hortonworks, the Hortonworks logo and other Hortonworks trademarks are trademarks of Hortonworks Inc. in the United States and other countries. Intel, Pentium, and XEON are registered trademarks of Intel Corporation. IBM, CICS, RACF, Tivoli, and z/OS are registered trademarks of International Business Machines Corporation. Linux is a registered trademark of Linus Torvalds. LSI is a registered trademark of LSI Corporation. Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the United States and other countries. NetVault is a trademark or registered trademark of Quest Software, Inc. in the United States and/or other countries. Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries. Oracle, Java, and Solaris are registered trademarks of Oracle and/or its affiliates. QLogic and SANbox are trademarks or registered trademarks of QLogic Corporation. Red Hat is a trademark of Red Hat, Inc., registered in the U.S. and other countries. Used under license. SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc. SPARC is a registered trademark of SPARC International, Inc. Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec Corporation or its affiliates in the United States and other countries. Unicode is a registered trademark of Unicode, Inc. in the United States and other countries. UNIX is a registered trademark of The Open Group in the United States and other countries. Other product and company names mentioned herein may be the trademarks of their respective owners. THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN "AS-IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. IN NO EVENT WILL TERADATA CORPORATION BE LIABLE FOR ANY INDIRECT, DIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS OR LOST SAVINGS, EVEN IF EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. The information contained in this document may contain references or cross-references to features, functions, products, or services that are not announced or available in your country. Such references do not imply that Teradata Corporation intends to announce such features, functions, products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions, products, or services available in your country. Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at any time without notice. To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this document. Please email: [email protected]. Any comments or materials (collectively referred to as "Feedback") sent to Teradata Corporation will be deemed non-confidential. Teradata Corporation will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform, create derivative works of, and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, Teradata Corporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, including developing, manufacturing, or marketing products or services incorporating Feedback. Copyright © 2000-2012 by Teradata Corporation. All Rights Reserved. Aster Database Client Guide 3 Table of Contents General Tips for Connecting Clients to Aster Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 ODBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Installing ODBC on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Optional ODBC Setting for bytea-Stored Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Installing ODBC on Linux, Solaris, and MacOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Setting up ODBC for Perl Connectivity on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Setting up ODBC for PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 ODBC Usage Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Aster Database JDBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Aster Database JDBC Driver 5.0.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Differences Between the 5.0.3 JDBC Driver and the Legacy JDBC Driver . . . . . . . . . . . . 19 Before You Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Installing the Aster Database JDBC Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Using the Aster Database JDBC Driver in a Java Application . . . . . . . . . . . . . . . . . . . . . . 20 Parameters for Connecting to Aster Database through JDBC . . . . . . . . . . . . . . . . . . . . . . 21 Behavior and Performance Settings for JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Using Client-Side Cursors in JDBC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Test JDBC Connect Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Tailoring the Behavior of Aster Database SQL to Your Needs . . . . . . . . . . . . . . . . . . . . . . . . . 28 SQL Behavior Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Setting the SQL Behavior Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Syntax for ODBC Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 SSL Security for Aster Database-Client Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 SSL-Related Files and Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 SSL Settings Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Common SSL Configuration Scenarios in Aster Database . . . . . . . . . . . . . . . . . . . . . . . . . 32 Encrypting Data Traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Adding AD-Based SSO Authentication to SSL-Secured Aster Database . . . . . . . . . . . . . . 34 How to Set Configuration Parameters on the Queen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 How to Set Configuration Parameters on the Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Creating Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Processing SQL Statements in JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Processing a Simple Query in JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 JDBC Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Connecting Reporting Tools to Aster Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Connecting Aqua Data Studio to Aster Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Connecting MicroStrategy to Aster Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Aster Database Client Guide 4 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 5 Aster Database Client Guide Connect Using Database Drivers Aster Database provides Open Database Connectivity (ODBC) and Java Database Connectivity (JDBC) drivers for connecting business intelligence (BI) tools. This section explains how to connect BI tools using the Aster Database drivers. General tips: • General Tips for Connecting Clients to Aster Database (page 6). Setting up database drivers: • ODBC Driver (page 7). • Aster Database JDBC Driver (page 19). • ADO.NET driver (a.k.a. Aster Database DNProvider driver) for SSIS, SSRS, and .NET: See Tools for .NET Environments (page 295). • OleDB Driver for SSAS: See Tools for .NET Environments (page 295). Using database drivers: • Processing SQL Statements in JDBC (page 40) • JDBC Issues (page 42) Security for database drivers: • SSL Security for Aster Database-Client Communications (page 30) Connecting BI and query tools: • Connecting Reporting Tools to Aster Database (page 42) General Tips for Connecting Clients to Aster Database Recommended Character Set Is UTF-8 For all tools that you use to connect to databases in Aster, you will typically want to set the default character set to UTF-8. This is particularly important if you plan to use special characters (for example, German letters ä and ß) in a char, varchar, or text column, and it is particularly important if you are connecting from a Windows-based machine. Aster Database Client Guide 6 Connect Using Database Drivers ODBC Driver For example, if you will use an SSH client (e.g., putty) to run ACT or ncluster_loader, make sure you set the SSH client’s default character set to UTF-8. When Querying System Tables with ODBC, Set AUTOCOMMIT to 'OFF' Cursors cannot be declared and used with Aster Database system tables. The default mode of autocommit-on with the ODBC driver declares cursors. Therefore, the ODBC driver should always query system tables by turning AUTOCOMMIT to 'off '. ODBC Driver Teradata Aster provides a standard ODBC driver for Aster Database that is compatible with Microsoft Windows and Linux. The Aster Database ODBC driver may change in any Aster Database release. For this reason, with each new edition of Aster Database, you should reinstall the driver and recompile your applications that include the driver. See the section below that applies to your platform: • Setting up ODBC for PHP (page 17) (page 7) • Installing ODBC on Linux, Solaris, and MacOS (page 11) • Setting up ODBC for Perl Connectivity on Linux (page 16) • Setting up ODBC for PHP (page 17) Installing ODBC on Windows Follow these steps to install the Aster Database ODBC driver on Windows: Procedure 7 1 On the machine where you will install the driver, make sure you have installed the Microsoft Visual C++ 2008 Redistributable Package (x86). If it’s not installed, download it from Microsoft now (choose the version that fits your architecture: 32-bit or 64-bit), and install it. (Note that Microsoft also offers newer versions of the package, such as the Microsoft Visual C++ 2010 Redistributable Package (x86). Teradata Aster has not tested compatibility with these later versions!) 2 Get the Aster Database ODBC driver package (nClusterODBCInstaller_i386.msi for 32-bit Windows or nClusterODBCInstaller_x64.msi for 64-bit Windows) in one of these ways: a Copy the package from your queen node. On the queen, you can find the installers in / home/beehive/clients_all/win32 or in /home/beehive/clients_all/win64. b Download the package from ftp.asterdata.com. Aster Database Client Guide Connect Using Database Drivers ODBC Driver 3 If you are upgrading, use the Windows Add/Remove Programs tool to uninstall the old version. 4 Copy the ODBC driver to the client machine and run the executable (for 32-bit, use nClusterODBCInstaller_i386.msi or, for 64-bit, use nClusterODBCInstaller_x64.msi). A setup wizard will walk you through the installation of Aster Database ODBC as one of the available data sources on your computer. 5 From the Windows Control Panel, double-click Administrative Tools to open the Administrative Tools window. 6 Double-click the Data Sources (ODBC) option to open the ODBC Data Source Administrator dialog box. 7 Click the System DSN tab, and click Add to open the Create New Data Source dialog box. 8 Select the Aster Data ODBC Driver for nCluster data source from the list. 9 Click Finish. The Aster Database Login window appears. Aster Database Client Guide 8 Connect Using Database Drivers ODBC Driver 10 In the Aster Database Login window, enter the following information: • Data Source: Use this field to give this database connection an easy-to-recognize name. • Server: the hostname or IP address of your Aster Database queen. • Port: The port on which your Aster Database queen listens for client connections. The default is 2406. • Database: the name of the database in Aster Database you want to connect to. Default system database is beehive. • Username: Database user name. • Password: Database user’s password. • Fetch Count: See “Throttle Query Results in ACT and Aster Database” on page 120. • SSL Settings: See “SSL Security for Aster Database-Client Communications” on page 30. • SSO Settings: See “Adding AD-Based SSO Authentication to SSL-Secured Aster Database” on page 34. • enable_quoted_identifiers: See “Quoted-Identifier Handling” on page 28. • enable_backslash_escapes: See “Escape Character Handling” on page 28. • Map NUMERIC/DECIMAL to DOUBLE: Teradata Aster recommends that you turn this feature on. 9 Aster Database Client Guide Connect Using Database Drivers ODBC Driver • Bytea As Varchar: The current login window does not provide a check box for specifying that values in a column of datatype bytea should be retrieved in a character representation (as opposed to the default binary representation) but you can set this later in the Windows registry. See “Optional ODBC Setting for bytea-Stored Data” on page 10. 11 Click OK to save the data source information. 12 Click Test Connection to test the connectivity to the database. If the connection is successful, the Aster Database Login window closes automatically. 13 If this window does not close automatically, click OK. Your ODBC setup is complete. Now, in your applications that will query Aster Database, you may connect to Aster Database as an ODBC data source. Optional ODBC Setting for bytea-Stored Data If you retrieve bytea-stored data through the ODBC driver, you can specify whether values in a column of datatype bytea will be retrieved in a character representation, or in the default binary representation. To set this up you must set the ByteaAsVarchar setting. Setting ByteaAsVarchar=1 instructs the ODBC driver to retrieve values in character representation; leaving it unset preserves the binary output representation. • To set this up on Linux, Solaris, or MacOS, see the discussion of the odbc.ini file in “Configure the ODBC Driver on Linux/Solaris/MacOS” on page 13. • To set this up on Windows, see below. For a 64-bit ODBC driver running on 64-bit Windows, and for 32bit driver on 32-bit Windows Set the flag by adding it to the Windows registry entry for the DSN. Using a registry editor, add this line to the registry, taking care to first replace <DSN-NAME> with your Data Source name: [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\<DSN-NAME>] "ByteaAsVarchar"="1" For a 32-bit ODBC driver running on 32-bit Windows Set the flag by adding it to the Windows registry entry for the DSN. Using a registry editor, add this line to the registry, taking care to first replace <DSN-NAME> with your Data Source name: [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\<DSN-NAME>] "ByteaAsVarchar"="1" Aster Database Client Guide 10 Connect Using Database Drivers ODBC Driver For a 32-bit ODBC driver running on 64-bit Windows Set the flag by adding it to the Windows registry entry for the DSN. Using a registry editor, add this line to the registry, taking care to first replace <DSN-NAME> with your Data Source name: [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBC.INI\<DSN-name>] "ByteaAsVarchar"="1" Installing ODBC on Linux, Solaris, and MacOS To install the Aster Database ODBC driver on Linux, Solaris, or MacOS, follow the instructions below. Prerequisites 1 The Aster Database ODBC driver requires libgcc 3.4.6 or higher. 2 On UNIX/Linux systems, the Aster Database ODBC driver requires a driver manager. Teradata Aster recommends that you use the unixODBC driver manager, version 2.2.12, which is compatible with the Aster Database standard ODBC driver for UNIX, libAsterDriver_unixODBC.so. Teradata Aster also supports the iODBC driver manager, version 3.52.3, but if you use the iODBC manager, you must use a different version of the Aster Database ODBC driver, called libAsterDriver.so. No other combination of drivers and driver managers is supported! Install the Driver Manager on Linux/Solaris/MacOS Here, we explain how to install both the driver manager and the Aster Database ODBC driver. If you already have the manager, proceed to “Installing ODBC on Linux, Solaris, and MacOS” on page 11. If your system does not have the unixODBC driver manager installed, install it now as shown here: 1 Download the unixODBC driver manager v 2.2.12, from http://www.unixodbc.org/ unixODBC-2.2.12.tar.gz 2 Install unixODBC by running the following commands: # CFLAGS="-DSIZEOF_LONG=8" ./configure --prefix=/usr \ --sysconfdir=/etc/unixodbc \ --enable-fdb \ --disable-gui && make Wait while it builds and installs. 3 Working as root user, run this: # make install && find doc -name "Makefile*" -exec rm {} \; && chmod 644 doc/{lst,ProgrammerManual/Tutorial}/* && install -v -m755 -d /usr/share/doc/unixODBC-2.2.12 && cp -v -R doc/* /usr/share/doc/unixODBC-2.2.12 11 Aster Database Client Guide Connect Using Database Drivers ODBC Driver 4 Check the installation by typing the following command. This prints version information and lists the names and locations of the configuration files you will need to install or set up. # odbcinst -j If your unixODBC installation is not working properly, check the instructions at http:// www.unixodbc.org/ for help. Next Step: Proceed to the next section, “Configure the ODBC Driver on Linux/Solaris/ MacOS”. Install the Aster Database ODBC Driver on Linux/Solaris/MacOS Once an appropriate driver manager is installed, you can install the Aster Database ODBC driver as shown below. Warning! For MacOS, the Aster Database ODBC Driver supports only MacOS version 10.5 or earlier. 1 Download the Aster Database ODBC driver bundle for your platform. You can get this from Teradata Aster’s website or from your queen node. Do one of the following: • Go to ftp.asterdata.com. Find the appropriate bundle for your release and operating system (for example, clients-odbc-linux64.tar.gz for a 64-bit Linux machine) and download it to your machine. • Connect to your queen node and copy the appropriate driver bundle from /home/ beehive/clients_all. The bundles are in the OS-specific directories, linux32/, linux64/, mac/, solaris64 /, solaris-sparc/, solaris-x86/, win32/, and win64/. 2 Extract the bundle into the directory where you want to install drivers. In this example, we’ll assume you will install the driver in /usr/local/lib. Once extracted, you will see the directory, stage/, that includes the driver. 3 Change to the Aster Database driver directory: # cd stage/clients-odbc-linux64 4 Edit your LD_LIBRARY_PATH or DYLD_LIBRARY_PATH environment variable, adding the Aster Database driver directory path to it. This folder has the path <install location>/stage/clients-odbc-linux64/Libs. Edit the appropriate environment settings file to do this (for example, edit the ~/.bashrc file if you want to set it for the current user on a typical Linux environment). For this example, we will set it for the current session only. To follow this example, type the export command shown below. (Note that for MacOS only, the environment variable is called DYLD_LIBRARY_PATH, not LD_LIBRARY_PATH.) export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/stage/clientsodbc-linux64/Libs Aster Database Client Guide 12 Connect Using Database Drivers ODBC Driver 5 Add or edit the ODBCSYSINI environment variable, setting it to the directory where your ODBC connection settings files (odbc.ini and odbcinst.ini) will reside. To follow this example, let’s assume we are working as user “mjones” and will save the configuration files to our home directory /home/mjones. export ODBCSYSINI=/home/mjones 6 Check that the Aster Database ODBC driver library can find all its dependencies. Assuming we have installed in /usr/local/lib, we would type (on Linux or Solaris): # cd /usr/local/lib # ldd stage/clients-odbc-linux64/ODBCDriver/ libAsterDriver_unixODBC.so \ On MacOS, we would type: # cd /usr/local/lib # otool -L stage/clients-odbc-linux64/ODBCDriver/ libAsterDriver_unixODBC.dylib \ If no “not found” messages appear, then all the required libraries have been linked. We require libgcc 3.4.6 or higher. Configure the ODBC Driver on Linux/Solaris/MacOS Once the Aster Database ODBC driver is installed, you must configure it as shown below. 1 Get the templates for the ODBC connection settings files. Copy these files from the Aster Database driver’s Setup directory to the user’s home directory. The files you need are aster.ini, odbc.ini and odbcinst.ini: # # # # cd cp cp cp /usr/local/lib/stage/clients-odbc-linux64/Setup odbc.ini ~ odbcinst.ini ~ aster.ini ~/.aster.ini Note that we have also renamed the aster.ini file, adding a dot at the beginning of the file name. You must do this. 2 Edit the .aster.ini file, setting the ErrorMessagesPath to point to the ErrorMessages subdirectory in the Aster Database driver directory. For this example, we edit the last line in the file to read: ErrorMessagesPath=/usr/local/lib/stage/clients-odbc-linux64/ErrorMessages Tip! At this point, you can run “odbcinst -j” to find out where the ODBC driver expects to find its configuration files. 13 3 ErrorMessagesPath=/usr/local/lib/stage/clients-odbc-linux64/ErrorMessages 4 In a text editor, edit the odbc.ini file, making the following changes: a Set SERVER to the hostname or IP address of your Aster Database queen. b Set PORT to 2406, the standard port on which your Aster Database queen listens for client connections. c Set DATABASE to the name of the database in Aster Database you want to connect to. Aster Database Client Guide Connect Using Database Drivers ODBC Driver d Optionally, you may set UID and PWD to your Aster Database SQL username and password, respectively. e Finally, Teradata Aster recommends that you add the setting, NumericAndDecimalAsDouble=1. f If you retrieve bytea-stored data through the ODBC driver, you can specify whether values in a column of datatype bytea will be retrieved in a character representation, or in the default binary representation. To have the ODBC driver to retrieve values in character representation, add the setting, ByteaAsVarchar=1 to your odbc.ini; if you leave it unset, the driver preserves the binary output representation of bytea data. g Optionally, you can set a number of other database connection behavior settings. These include enable_quoted_identifiers (see “Quoted-Identifier Handling” on page 28), enable_backslash_escapes: See “Escape Character Handling” on page 28. For this example, we set the contents of odbc.ini to read: [ODBC Data Sources] Aster Database ODBC for nCluster DSN=AsterDriver [Aster Database ODBC for nCluster DSN] Driver=AsterDriver SERVER=10.50.52.100 PORT=2406 DATABASE=beehive NumericAndDecimalAsDouble=1 # UID=<USERNAME> # PWD=<PASSWORD> Tip! You can have multiple data sources. The name “Aster Database ODBC for nCluster DSN” in the odbc.ini file is just a default name that Teradata Aster has given to the sample data source. You can rename this source and add more, as shown in this example: [ODBC Data Sources] my_1st_source=AsterDriver my_2nd_source=AsterDriver [my_1st_source] Driver=AsterDriver SERVER=10.50.52.100 ... [my_2nd_source] Driver=AsterDriver SERVER=10.42.43.100 ... Aster Database Client Guide 14 Connect Using Database Drivers ODBC Driver 5 In a text editor, edit the odbcinst.ini file, setting the Driver parameter to the Aster Database driver directory path. For this example, we set the contents of odbcinst.ini to read: [AsterDriver] Driver=/usr/local/lib/stage/clients-odbc-linux64/ODBCDriver/ libAsterDriver_unixODBC.so IconvEncoding=UCS-4LE On MacOS, it will look like: [AsterDriver] Driver=/usr/local/lib/stage/clients-odbc-linux64/ODBCDriver/ libAsterDriver_unixODBC.dylib IconvEncoding=UCS-4LE The installation and configuration are complete. Test the installation Once the driver is installed and configured, you should test it: The unixODBC driver manager comes with a tool called “isql” that you can use to test the driver. You can test your connection now by connecting to Aster Database using the isql tool. 1 Type the command as shown below. Here, we put the data source name in single quotes because it contains spaces. The “beehive” and “beehive” are the default username and password in a new Aster Database installation: # isql -v 'Aster Database ODBC for nCluster DSN' beehive beehive 2 A “Connected!” message indicates that the driver is working correctly: +---------------------------------------+ | Connected! | | | | sql-statement | | help [tablename] | | quit | | | +---------------------------------------+ SQL> 3 Set-up is complete. Troubleshooting If after installation you cannot connect: 1 Find the library libodbcinst.so and note its path. 2 Set the LD_LIBRARY_PATH environment variable so that it includes the directory that contains libodbcinst.so. For example, if the library is in /usr/lib64, then you will type: export LD_LIBRARY_PATH=/usr/lib64:$LD_LIBRARY_PATH 15 Aster Database Client Guide Connect Using Database Drivers ODBC Driver Setting up ODBC for Perl Connectivity on Linux To install the Aster Database ODBC driver and configure your environment to allow Perl scripts to connect to the database through the driver, follow these steps. These instructions assume you have installed Perl on your workstation, and that the Aster Database queen is reachable on the network. Follow these steps to provide an Aster Database connection your Perl scripts can use: 1 Set up your /etc/resolv.conf and /etc/nsswitch.conf for accessing the Aster Database queen. 2 Make sure that an ODBC driver manager is installed and configured. Follow the instructions in “Install the Driver Manager on Linux/Solaris/MacOS” on page 11. 3 Install and configure Aster Database ODBC. Follow the instructions in “Configure the ODBC Driver on Linux/Solaris/MacOS” on page 13. 4 The server connection information is set in the odbc.ini file, as explained in the ODBC installation sections of this document, “Installing ODBC on Linux, Solaris, and MacOS” on page 11. On Windows, the server connection information is set using the ODBC Data Source Administrator tool as explained in “Setting up ODBC for PHP (page 17)” on page 7. 5 In /root type $ perl -eshell -MCPAN 6 Get the latest packages and install them by entering: $ install Bundle::CPAN $ install DBI 7 Rebuild and install DBD::ODBC. $ export LD_LIBRARY_PATH=/home/beehive/toolchain/x86_64-unknownlinux-gnu/unixODBC-2.2.12/lib $ export PATH=$PATH:/home/beehive/toolchain/x86_64-unknown-linuxgnu/unixODBC-2.2.12/bin $ which odbc_config /home/beehive/toolchain/x86_64-unknown-linux-gnu/unixODBC-2.2.12/ bin/odbc_config $ odbc_config --cflags -DHAVE_UNISTD_H -DHAVE_PWD_H -DHAVE_SYS_TYPES_H -DHAVE_LONG_LONG -DSIZEOF_LONG=8 $ perl -eshell -MCPAN cpan[1]> force install DBD::ODBC 8 Run odbcinst -j to see where the .ini files are being picked up: $ odbcinst -j 9 Run the following Perl script to check your installation. If everything is set correctly, it will run without an error. If you encounter problems, check the data source name (“DSN”) in the connect statement. In the example below, the username and password of the database are “beehive” and “beehive”: Aster Database Client Guide 16 Connect Using Database Drivers ODBC Driver #!/usr/bin/perl use DBI; use DBD::ODBC; # Connect to ODBC DSN and turn off AutoCommit my $dbh = DBI->connect('dbi:ODBC:nc',"beehive","beehive", {AutoCommit => 0}); $dbh->do("BEGIN"); $dbh->do("set random_page_cost to '4'"); $dbh->do("set enable_seqscan to 'off'"); $dbh->disconnect; Setting up ODBC for PHP To set up PHP to work with ODBC, first follow all of the instructions to set up ODBC on Linux: “Installing ODBC on Linux, Solaris, and MacOS” on page 11. As described in the instructions, you should use unixODBC 2.2.12 and build it with the CFLAG, SIZEOF_LONG=8. The same will apply to building PHP when compiled to be used with unixODBC. Here are the supported versions: • PHP 5.2.16 • Apache 2.2.3 PHP To set up PHP: 1 Make sure Apache is installed and make note of the directory. For this example, we will assume Apache is installed at /usr/local/apache 2 Ensure that unixODBC has been installed as described above. 3 Download the source for PHP 5.2.16 and extract it to the desired directory. The following setup instructions should be used for PHP: $ CFLAGS="-DSIZEOF_LONG=8" ./configure --with-apxs2=/usr/local/ apache/bin/apxs --with-zlib --with-unixODBC --with-pdo-odbc=unixODBC $ make && make install $ cp -p .libs/libphp5.so /usr/local/apache/modules Apache and PHP Apart from the typical PHP-Apache setup, there are two things to keep in mind: 1 Ensure that the Linux system is set up to find the libraries that the ODBC driver requires. a Add the <INSTALL-DIR>/Libs and <INSTALL-DIR>/ODBCDriver paths to the /etc/ ld.so.conf file, where <INSTALL-DIR> is the location for the ODBC installation. b The following commands should be executed to refresh the ld cache and restart the Apache web server: $/sbin/ldconfig $/etc/init.d/apachectl restart 17 Aster Database Client Guide Connect Using Database Drivers ODBC Driver 2 To make sure that the ODBCSYSINI environment variable is available when PHP calls are made, use the following line in your PHP code: #given ODBCSYSINI is to be set to /etc then: putenv("ODBCSYSINI=/etc") Tip! You should not set up your own PHP or use /etc/init.d/apachectl on the queen for your own web pages. ODBC Usage Notes Avoid using bind_param with SQL_DECIMAL When using the bind_param method call with decimal fields, you should not explicitly specify SQL_DECIMAL as the parameter bind type. If you do this, and the parameter value has a fractional digital part, the factional part changes to 0 after applying bind_param. The DBD::ODBC bind_param implementation makes this conversion when specifying SQL_DECIMAL/SQL_NUMERIC as the parameter bind type. Note that bind_param works fine when SQL_DECIMAL is not explicitly specified, so you should avoid this when passing decimal fields. Bind columns without specifying a SQL datatype Use the Perl API without specifying a SQL datatype the Aster datatypes, as in the example: $rc = $sth->bind_col($column_number, \$var_to_bind); Avoid specifying the SQL datatype to bind to the column, as in: $rc = $sth->bind_col($column_number, \$var_to_bind, $bind_type); This will work fine when binding boolean and character columns with DBI::SQL_CHAR, but for the other datatypes, this will cause two issues: 1 If you specify a numeric SQL type in bind_col, corrupt data may be returned. Numeric types include SQL_INTEGER, SQL_SMALLINT, SQL_DOUBLE, SQL_REAL, SQL_NUMERIC/SQL_DECIMAL, SQL_BIT, SQL_TIME, SQL_TIMESTAMP, SQL_DATE, and SQL_DATETIME. 2 If you specify a SQL_VARCHAR type in bind_col, an error may be returned. The error looks like: • On Unix ODBC: “DBD::ODBC::st fetch failed: [unixODBC][Driver Manager]Invalid application buffer type (SQL-HY003)” • On Windows ODBC: “DBD::ODBC::st fetch failed: [Microsoft][ODBC Driver Manager] Program type out of range (SQL-HY003)” This issue has been observed with the following software versions: • Perl 5.8.9 • DBD-ODBC 1.3.1 • DBI-1.616 Aster Database Client Guide 18 Connect Using Database Drivers Aster Database JDBC Driver Aster Database JDBC Driver JDBC is an API for the Java programming language that provides methods for querying and updating data in a relational database. The Aster Database JDBC driver enables your Java applications and reporting tools to retrieve data directly from Aster Databases. The Aster Database JDBC driver is a Type 4 JDBC driver that implements the JDBC 3 specification. • Aster Database JDBC Driver 5.0.3 (page 19) • Differences Between the 5.0.3 JDBC Driver and the Legacy JDBC Driver (page 19) • Before You Start (page 20) • Installing the Aster Database JDBC Driver (page 20) • Using the Aster Database JDBC Driver in a Java Application (page 20) • Parameters for Connecting to Aster Database through JDBC (page 21) • Behavior and Performance Settings for JDBC (page 22) • Using Client-Side Cursors in JDBC (page 23) • Test JDBC Connect Program (page 25) • Processing a Simple Query in JDBC (page 41) Aster Database JDBC Driver 5.0.3 This version of the JDBC driver adds these capabilities to those that were already supported in the legacy JDBC driver: • Ability to handle larger data sets than the legacy JDBC driver; doesn’t try to load whole result set onto the client in all cases • Support for multibyte characters in data and user metadata UTF-8 encoding • Support for Single Sign-On (SSO) authentication • Support for Secure Socket Layers (SSL) encrypted communications • Support customized connection parameters • Support configuring statement FetchSize to limit the data being returned • Support server side cursors • Support specifying maximum number of rows Differences Between the 5.0.3 JDBC Driver and the Legacy JDBC Driver These are important differences between the 5.0.3 JDBC driver and the legacy JDBC driver: 19 • JDBC only supports scrollable forward cursors. Only the con.createStatement (ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY) and connection.createStatement() functions are supported. The Other parameter values like ResultSet.TYPE_SCROLL_INSENSITIVE and ResultSet.CONCUR_UPDATABLE are not supported. • The executeBatch() function throws a SQL exception (java.sql.SQLException). Aster Database Client Guide Connect Using Database Drivers Aster Database JDBC Driver • The result set cannot be accessed after an explicit commit. • After running PreparedStatement.executenatch(), you must set all bind values or else the driver throws an error. • The java.sql.PreparedStatement.setObject() function does not throw exceptions for invalid java.sql.Types.TINYINT values. Instead, the function wraps the values around. This behavior complies with the Java standard. • ResultSetMetaData cannot be accessed after a ResultSet reset. • The driver cannot establish a connection to the database when there are white space characters to the left of the connection string. • If the JDBC connection is lost when using Aqua Data Studio, a new connection is not initiated automatically. The next command issued will return an error. The user will need to re-initiate a connection to the database. • The DatabaseMetaData.getBestRowIdentifier() function is not supported. • The ResultSet.getArray() function is not supported. • You can call com.asterdata.ncluster.Driver.ASTER_BUILD_VERSION() to get JDBC version information. For detailed version information, check the MANIFEST.MF file. Before You Start The SSO support in the JDBC driver is based on Quest Authentication service. You must acquire the SSO license from Quest in order to take advantage of SSO support in this client. This support is for connecting to Aster Database only, and not for connecting through the Teradata Connector or SQL-H. Installing the Aster Database JDBC Driver Follow these steps to install the Aster Database JDBC driver: 1 2 Obtain the ZIP package that contains the Aster Database JDBC driver (for example, AsterJDBC_indep_indep.05.00.03.00.zip): • Obtain the file from the Aster ftp server or • Copy the package from your queen node. On the queen, you can find the installers in / home/beehive/clients_all/<platform>. Unzip the ZIP package. The resulting folder contains multiple JAR file. 3 Copy the JAR files to a location in the classpath of the application that uses the driver. Using the Aster Database JDBC Driver in a Java Application Follow these steps to integrate the Aster Database JDBC driver into your Java application: 1 Aster Database Client Guide Set the CLASSPATH environment variable to include the paths of the JAR files extracted from the Aster Database JDBC driver package. 20 Connect Using Database Drivers Aster Database JDBC Driver • Use the Java -classpath flag at the command line to add the paths to the CLASSPATH environment variable. For example, if you place the JAR files in /usr/jars, then add the path like this: java -classpath /usr/my_program /usr/jars/ or • Add the paths to the driver to the CLASSPATH environment variable. For example: export CLASSPATH=/usr/jars/:$CLASSPATH 2 In your application: a Import the java.sql package like this: import java.sql.*; b Load the driver using the Class.forName() method: Class.forName("com.asterdata.ncluster.Driver"); c Define the username, password, and url (including the host, port, and database) parameters, which are needed to connect to the database. For example: String username = "user"; String password = "password"; String url = "jdbc:ncluster://myhost:2406/database"; For more information about the URL format, see “Required Parameters” on page 21. d Get a Connection instance from JDBC using the DriverManager.getConnection() method: try { Connection conn = DriverManager.getConnection(url, username, password); } catch (SQLException ex) { // could not connect } NOTE: The getConnection method throws a “No driver available SQLException” exception if CLASSPATH does not contain the path for the JDBC driver, or if the parameters are incorrect. Parameters for Connecting to Aster Database through JDBC Required Parameters To establish a connection to an Aster Database using the Aster Database JDBC driver, you must provide the driver with the URL to use to connect to the database. The URL has this format: jdbc:ncluster://<Host:Port>/<Database> 21 Aster Database Client Guide Connect Using Database Drivers Aster Database JDBC Driver The URL needs three parameters to connect to an Aster Database: Table 1 - 1: Parameters in URL to connect to an Aster Database Parameter Required? Description Host Optional The name of the server where the database resides. To specify an IPv6 address, enclose the this parameter in square brackets. For example: jdbc:ncluster://[::1]:2406/nCluster Default is localhost. Port Optional The port number that the database server is listening on. Default is 2406. Database Required The database name. In addition, to the URL, you must also provide the username and password needed to access the Aster Database, which you can get from your Aster Database administrator. Optional Parameters You can set the Autocommit and fetch_count settings for the connection in the URL by adding the autocommit and fetch_count parameters. See “Frequently Used JDBC Settings” on page 22. If your application will query large tables, you should set autocommit to false, and you should declare a fetch_count for the connection. By doing this, you enable the connection to use distributed cursors for improved performance. Behavior and Performance Settings for JDBC When using the Aster Database JDBC driver, you make most behavior and performance settings in your SQL code using the SET command, as explained in “SET” on page 778. You can also use a number of standard JDBC driver methods for setting behavior and performance options, such as setAutoCommit() and setPrepareThreshold(). The scope of these variables are limited to the scope of the transaction. After the commit() call, the transaction variables revert to their original values. In order to limit the transaction variables to a particular query, the variables need to be saved prior to being set and once the query is executed the variables must be set back to their original values. Frequently Used JDBC Settings • autocommit: Boolean value that sets the autocommit behavior for the connection, true to turn on autocommit (each statement, by default concluded with a semicolon, is run immediately in the database) or false for off (you must COMMIT your transaction to run it). You can set this in the connection URL with the autocommit parameter (for example, jdbc:ncluster://10.80.50.100:2406/beehive?autocommit=false) or in the Java code for your connection with Connection.setAutoCommit(). The default is true. Aster Database Client Guide 22 Connect Using Database Drivers Aster Database JDBC Driver Unsupported JDBC Settings Most JDBC option-setting methods in the Aster Database driver exhibit the standard JDBC behavior, but there are exceptions. Please note: • setReadOnly(): Not supported; Aster Database does not allow changing connection type to read-only. • setTransactionIsolation(): Not supported; Aster Database does not allow changing transaction isolation levels. Example Code Snippet That Sets Performance Tuning Variables Assuming a Connection conn and a Query query, we can set some performance tuning variables for a particular transaction like this: // remember the current autocommit state boolean autoCommit = conn.getAutoCommit(); // turn off auto commits conn.setAutoCommit(false); // create a statement with transaction variables set // which will be used for this query Statement stmt = conn.createStatement(); stmt.executeUpdate("SET enable_hashjoin = 'false'"); stmt.executeUpdate("SET enable_mergejoin = 'false'"); stmt.executeUpdate("SET enable_nestloop='true'"); stmt.executeUpdate("SET random_page_cost = '4.0'"); ResultSet resultSet = statement.executeQuery(query); // commit the transaction (assumes the query has // already been executed externally) conn.commit(); // set the autocommit state back conn.setAutoCommit(autoCommit); // process the result set while (resultSet.next()) { // do something } stmt.close(); resultSet.close(); In the example above, the scope of the SET variables is limited to the commands between the autoCommit(false) and commit() lines. Using Client-Side Cursors in JDBC To give you control over the latency of initial query results, the Aster Database JDBC driver supports client-side cursors. Client-side cursors let you avoid retrieving all the result rows for a query at once. Instead, you specify the number of rows that should be retrieved to the client at a time. When that set is exhausted, the next page of rows is retrieved by repositioning the cursor. 23 Aster Database Client Guide Connect Using Database Drivers Aster Database JDBC Driver Observe the following guidelines when working with cursors: 1 Turn off autocommit mode for the Connection object. See “Using Cursors in Your Code”, below. 2 The ResultSet object that receives the output of your Statement cannot be a scrollable ResultSet. That is, it must have the type, ResultSet.TYPE_FORWARD_ONLY. This is the default, so you need not rewrite your code. 3 If your application will query large tables, you should make sure your ResultSet can use distributed cursors. To do this, a make sure the ResultSet is not updatable (ResultSet.CONCUR_READ_ONLY) b make sure it’s not scrollable (ResultSet.TYPE_FORWARD_ONLY) c make sure it does not have HOLD enabled (ResultSet.CLOSE_CURSORS_AT_COMMIT). d Also, the application should connect with autocommit set to false and the connection must have a specified fetch_count. Tip! When working with ResultSets of type ResultSet.TYPE_FORWARD_ONLY, you cannot scroll backwards, nor can you jump to any location in the ResultSet other than the next row. 4 In the Statement object, you must pass a single query, not multiple queries strung together with semicolons. 5 You must set the statement’s fetch_count using the Statement.setFetchSize(int rows) command. This instructs the driver to fetch the specified number of rows at a time from the database. If the fetch size is not set, the driver fetches the full set of rows that match the query. 6 To help ensure a quick response when a page of rows is exhausted, the JDBC driver, by default, pre-fetches and caches ten pages of results from the database. A page is one fetch_count worth of rows. You can set the number of pages to be pre-fetched, or you can disable pre-fetching if desired. Using Cursors in Your Code The driver fetches fetch_count number of rows (as set with Statement rows)) from Aster Database and exposes them to the database application as a “rows” data structure. The default fetch_count is zero, so you must set a fetch_count if you wish to use cursors. With ResultSet.next(), your application iterates over the rows data structure. When all rows in the rows data structure have been processed, the next call to next() will force the fetching a new set of fetch_count number of rows, and so on. To use cursors, set the fetch size of your SQL statement using the setFetchSize(int rows) method. Later, setting the fetch_count back to 0 will cause all rows to be retrieved when the query runs (the default behavior). Aster Database Client Guide 24 Connect Using Database Drivers Aster Database JDBC Driver Tip! In the example below, we set the Autocommit setting and the FetchSize setting using the setAutoCommit() and setFetchSize() methods, but you also have the option of setting these in the JDBC connection parameters when you make the connection. See “Frequently Used JDBC Settings” on page 22. Example That Uses Client-Side Cursors Assuming a Connection conn, you can set the FetchSize like this: // Remember the current autocommit state boolean autoCommit = conn.getAutoCommit(); // Make sure autocommit is off conn.setAutoCommit(false); Statement st = conn.createStatement(); // Turn use of the cursor on by setting FetchSize, expressed in rows st.setFetchSize(50); ResultSet rs = st.executeQuery("SELECT * FROM mytable"); // Set the autocommit state back conn.setAutoCommit(autoCommit); while (rs.next()) { System.out.print("a row was returned."); } rs.close(); // Close the statement. st.close(); Disabling Cursors Cursors are enabled by default. To turn them off, set the FetchSize to zero. Assuming a statement st and a ResultSet rs, you would do this as shown here: st.setFetchSize(0); rs = st.executeQuery("SELECT * FROM mytable"); while (rs.next()) { System.out.print("many rows were returned."); } Test JDBC Connect Program This program can be used as a template for your JDBC connectivity: // JDBC Test Program import java.sql.Connection; import java.sql.DatabaseMetaData; import java.sql.DriverManager; import java.sql.SQLException; import java.sql.Statement; import java.sql.ResultSet; public class jdbctest { static String userid="beehive", password = "beehive"; // Change the IP address to the node you want to connect to. 25 Aster Database Client Guide Connect Using Database Drivers Aster Database JDBC Driver static String url = "jdbc:ncluster://10.60.3.100:2406/beehive"; //2.0 static Connection con = null; public static void main(String[] args) throws Exception { Connection con = getJDBCConnection(); if(con!= null){ try { int count = 0; System.out.println("Got Connection."); DatabaseMetaData meta = con.getMetaData(); System.out.println("getDriverName: "+meta.getDriverName()); System.out.println("getDriverVersion: "+meta.getDriverVersion()); System.out.println("getDriverMajorVersion: "+meta.getDriverMajorVersion()); System.out.println("getDriverMinorVersion: "+meta.getDriverMinorVersion()); System.out.println("getDatabaseProductName: "+meta.getDatabaseProductName()); System.out.println("getDatabaseProductVersion: "+meta.getDatabaseProductVersion()); System.out.println("getIdentifierQuoteString: "+meta.getIdentifierQuoteString()); System.out.println("\ngetSQLKeywords: "+meta.getSQLKeywords()); System.out.println("\ngetNumericFunctions: "+meta.getNumericFunctions()); System.out.println("\ngetStringFunctions : "+meta.getStringFunctions()); System.out.println("getSystemFunctions : "+meta.getSystemFunctions()); System.out.println("getTimeDateFunctions : "+meta.getTimeDateFunctions()); System.out.println("getSearchStringEscape : "+meta.getSearchStringEscape()); System.out.println("getExtraNameCharacters : "+meta.getExtraNameCharacters()); System.out.println("getCatalogTerm : "+meta.getCatalogTerm()); System.out.println("getCatalogSeparator : "+meta.getCatalogSeparator()); System.out.println("getURL : "+meta.getURL()); System.out.println("getUserName : "+meta.getUserName()); System.out.println("getMaxCursorNameLength : "+meta.getMaxCursorNameLength()); System.out.println("getMaxSchemaNameLength : "+meta.getMaxSchemaNameLength()); System.out.println("getMaxProcedureNameLength : "+meta.getMaxProcedureNameLength()); System.out.println("getMaxCatalogNameLength : "+meta.getMaxCatalogNameLength()); System.out.println("getMaxColumnsInIndex : "+meta.getMaxColumnsInIndex()); System.out.println("supportsSubqueriesInComparisons : "+meta.supportsSubqueriesInComparisons()); System.out.println("getMaxConnections : "+meta.getMaxConnections()); System.out.println("getMaxColumnsInTable : "+meta.getMaxColumnsInTable()); System.out.println("isReadOnly : "+meta.isReadOnly()); System.out.println("\ngetCatalogs:"); ResultSet res = meta.getCatalogs(); while (res.next()) { System.out.println(res.getString(1)); } Aster Database Client Guide 26 Connect Using Database Drivers Aster Database JDBC Driver System.out.println("\ngetTables:"); res.close(); res = meta.getTables(null,null,"%",null); while (res.next()) { System.out.println(res.getString(1) +res.getString(2) +res.getString(3) +res.getString(4)); } System.out.println(""); res.close(); res = meta.getTableTypes(); System.out.println("\ngetTableTypes:"); while (res.next()) { System.out.println(res.getString(1)); } res.close(); Statement stmt=con.createStatement(); ResultSet rs = stmt.executeQuery("select count(*) from page_views"); while (rs.next()) { System.out.println(rs.getInt(1)); } rs.close(); stmt.close(); con.close(); } catch(SQLException ex) { System.err.println("SQLException: " + ex.getMessage()); } }else{ System.out.println("Could not Get Connection"); } } public static Connection getJDBCConnection(){ try { Class.forName("com.asterdata.ncluster.Driver"); } catch(java.lang.ClassNotFoundException e) { System.err.print("ClassNotFoundException: "); System.err.println(e.getMessage()); } try { con = DriverManager.getConnection(url,userid, password); } catch(SQLException ex) { System.err.println("SQLException: " + ex.getMessage()); } return con; } } 27 Aster Database Client Guide Connect Using Database Drivers Tailoring the Behavior of Aster Database SQL to Your Needs Tailoring the Behavior of Aster Database SQL to Your Needs This section explains how to set parameters that customize the behavior of Aster Database SQL. SQL Behavior Parameters Escape Character Handling enable_backslash_escapes: Set to “on” (the default), Aster Database allows backslash escape strings in your constants. The escape strings are C-like backslash escape sequences, each introduced with a backslash character (\). Set to “off ”, Aster Database does not recognize backslash escape strings in your constants unless the constant is prefixed with a letter E before its opening single quote. In any constant not prefixed with the letter E, a backslash is interpreted simply as a backslash character. Quoted-Identifier Handling enable_quoted_identifiers: This setting affects the way Aster Database processes strings enclosed in double-quote characters ("..."). With enable_quoted_identifiers='on' (the default), Aster Database follows the standard behavior of interpreting each double-quoted string as an identifier (a column, table, schema, or function name). With enable_quoted_identifiers='off', each double-quoted string is interpreted as a literal string constant. Any printable character may be represented in a double-quoted string. See “Quoted Identifiers” on page 916. Setting the SQL Behavior Parameters At the SQL Prompt You can set these parameters from the SQL prompt by executing SET commands in the form: SET SESSION <parameter name> = {'<param setting>'}; For example: SET SESSION enable_backslash_escapes = {'on'|'off'}; and SET SESSION enable_quoted_identifiers = {'on'|'off'}; In the Aster Database ODBC Driver The Aster Database ODBC-NG driver allows you to set Aster Database SQL behavior parameters like, for example, enable_backslash_escapes. The connection parameters are: • enable_backslash_escapes={on|off} • enable_quoted_identifiers={on|off} Aster Database Client Guide 28 Connect Using Database Drivers Tailoring the Behavior of Aster Database SQL to Your Needs These can be set in the DSN configuration (i.e., the odbc.ini file or Windows registry). Alternatively, a connecting application may set these options in the connection string when connecting without a registered DSN. Syntax for ODBC Commands This section lists some ODBC commands for which the syntax differs from the native Aster Database syntax. Note that comments and parameter markers are not allowed in these commands. However, the prepare/execute model is supported. COPY FROM/TO Semantics and overall flow of execution for COPY is the same as for the Aster Database Loader Tool. See “Aster Database Loader Tool” on page 375. Syntax COPY table [(column list)] FROM <quoted file name> ...COPY attributes or COPY table [(column list)] TO <quoted file name> ...COPY attributes The COPY command accepts a quoted file name and streams the data into or out of Aster Database using the Aster Database Loader Tool protocol for maximum throughput. For more detailed syntax, see COPY (page 711). INSTALL The INSTALL command is similar to the ACT command “\install <FILE> [[<SCHEMA>/ ]<FILE_ALIAS>]” on page 127, and supports SQL-MR security semantics. See “SQLMapReduce Security” on page 246. Syntax INSTALL FILE <quoted file name> [[<schema>/]<file alias>] • The schema name must be quoted if it contains spaces or mixed case. • The file alias must be quoted. UNINSTALL The UNINSTALL command supports SQL-MR security semantics. See “SQL-MapReduce Security” on page 246. Syntax UNINSTALL FILE <quoted file name> [[<schema>/]<file alias>] • The schema name must be quoted if it contains spaces or mixed case. • The file alias must be quoted. DOWNLOAD The DOWNLOAD command is similar to the ACT command “\download [[<SCHEMA>/ ]<FILE_ALIAS>] <FILE>” on page 127, and supports SQL-MR security semantics. See “SQLMapReduce Security” on page 246. 29 Aster Database Client Guide Connect Using Database Drivers SSL Security for Aster Database-Client Communications Syntax DOWNLOAD FILE <quoted file name> [[<schema>/]<file alias>] • The schema name must be quoted if it contains spaces or mixed case. • The file alias must be quoted. SSL Security for Aster Database-Client Communications Aster Database provides the option to use SSL to secure communications between secondgeneration Aster Database ODBC clients (“2nd-gen ODBC clients”) and the Aster Database queen. In Aster Database versions 4.5 and later, by default, a 2nd-gen ODBC client running on Windows or Linux sends all of its communications to Aster Database over an SSL-encrypted connection. By default, results and other data returned from Aster Database to the client are NOT encrypted. This default configuration can be changed to suit your needs, as explained in the sections that follow. Important note for upgraders: Most pre-version-4.6 Aster Database drivers and the pre-4.6 ACT client do not support SSL. During your upgrade to Aster Database 4.6, you must replace all Aster Database drivers and ACT clients that connect to your Aster Database installation. Port Number The Aster Database queen port number for SSL connections is the same as the regular client connection port: 2406. Port 2406 is multiplexed to support both secure sockets layer (SSL) connections and unencrypted connections. Contents of This Section This section contains: • SSL-Related Files and Settings (page 30) • SSL Settings Reference (page 31) • Common SSL Configuration Scenarios in Aster Database (page 32) • Encrypting Data Traffic (page 33) • Adding AD-Based SSO Authentication to SSL-Secured Aster Database (page 34) • How to Set Configuration Parameters on the Queen (page 35) • How to Set Configuration Parameters on the Client (page 35) • Creating Certificates (page 40) SSL-Related Files and Settings As shipped, the queen has the following files related to SSL communications and set-up: • Aster Database Client Guide Private key: Default one is /home/beehive/certs/server.key 30 Connect Using Database Drivers SSL Security for Aster Database-Client Communications • Self-signed PEM certificate (that is, the base64-encoded ASCII representation of the certificate only; this is the version of the certificate that starts with "-----BEGIN CERTIFICATE-----" and ends with "-----END CERTIFICATE-----"). The default one is / home/beehive/certs/server.cert • Another copy of the self-signed certificate, also in PEM format, but this time formatted in X.509 structure. Note! This file may be missing from your Aster Database installation. To work around this problem, you must create the default PEM file from the server.cert file, saving it as /home/beehive/certs/server.pem. To create it, log in to the queen as root, change directories to /home/beehive/certs, and type: # openssl x509 -in server.cert -text >> server.pem • The queen’s SSL-related settings (see “SSL Settings Reference” on page 31) in the Aster Database queen configuration file, /home/beehive/config/procmgmtConfigs/ coordinator.cfg On the client side, the files related to SSL and its configuration are: • Copy of the queen’s public key in PEM format. This is a copy of the queen’s server.pem. For example, you might save it as /home/mjones/certs/server.pem • The client’s SSL-related settings (see “Client-Side SSL Settings” on page 32), stored: • for Linux, in the client’s odbc.ini file; and • for Windows, in the ODBC parameter fields of the registry SSL Settings Reference This section provides a reference to the available SSL settings on the Aster Database queen. Queen-Side SSL Parameters Below, we list the configuration flags that can be used on the queen to tune SSL behavior. Most queen-side flags have a corresponding client-side flag. When you change a flag on one side (client or server), you will typically have to make appropriate changes to the other side. • disallowPeerWithoutCertificates: If this flag is set, the client cannot communicate with its peer (server) without a valid certificate. This flag is defaulted to FALSE. • allowSelfSignedPeer: If this flag is set, Aster Database allows connections from clients with self-signed certificates. Defaults to TRUE. • Set either trustedCAFileName or trustedCAPath, depending on whether you have one or many CA certificates: • trustedCAFileName: The pathname of the single PEM-formatted CA certificate that Aster Database trusts. (You also have the option of trusting multiple CA certificates; see trustedCAPath, below.) Whenever the queen gets a certificate from the peer, the queen traverses the certificate chain to verify that the certificate specified by trustedCAFileName is part of the chain. If so, the peer is allowed to connect. • trustedCAPath: Directory containing PEM-formatted CA certificates that Aster Database trusts. The files inside this directory are looked up based on the CA subject name hash value. • 31 sslCertificatePath: SSL certificate location. Aster Database Client Guide Connect Using Database Drivers SSL Security for Aster Database-Client Communications • sslPrivateKeyPath: SSL private key location. • sslFileType: The formatting type of the certificate. Set this to a string value of 1 for PEM-encoded certs (called “SSL_FILESYSTEM_PEM” on the client side) or 2 for ASN1encoded certs (called “SSL_FILETYPE_ASN1” on the client side). Default is 1. • secureMuleServer: If set, Aster Database will be configured to use a secure channel for its communication. If secureMuleServer is enabled, the configuration flags sslCertificatePath and sslPrivateKeyPath should be appropriately set. Client-Side SSL Settings Below, we list the configuration flags that can be used on the client side to tune SSL behavior. These settings work only with the 2nd-generation Aster Database ODBC client. Most clientside flags have a corresponding queen-side flag. When you change a flag on one side (client or server), you will typically have to make appropriate changes to the other side. • • EnableSSL: Enables/disables the use of SSL (string value of 0 for false, or 1 for true). • 0 = Disable SSL (default) • 1 = Enable SSL SSLEncryptReads: Determines whether the client expects data returned from database to be encrypted (string value of 0 for false, or 1 for true). • • 0 = query results are unencrypted (the default) • 1 = query results are encrypted SSLAllowSelfSignedPeer: Determines whether the client allows peers with self signed certificates to communicate (string value of 0 for false, or 1 for true; default is 1). • SSLFileType: The certificate file type. A string value; one of: • SSL_FILETYPE_PEM (the default) • SSL_FILETYPE_ASN1 • SSLPrivateKeyPath: Path to the private key to be used. Optional. (A string value.) • SSLCertificatePath: Path to the SSL certificate to be used. (A string value.) • Set either SSLTrustedCADir or SSLTrustedCAFilename, depending on whether you have one or many CA certificates: • SSLTrustedCADir: Path to the directory containing CA certificates in PEM format. (A string value.) • SSLTrustedCAFilename: Filename of CA certificate in PEM format. (A string value.) Common SSL Configuration Scenarios in Aster Database This section presents common SSL configuration scenarios and shows how to set up each one. The scenarios are: • Scenario 1: Allowing connections from clients without certificates (page 33) In all of the scenarios, we instruct you to set parameters on the queen and on the client. For instructions, see: • Aster Database Client Guide For the queen: “How to Set Configuration Parameters on the Queen” on page 35; and 32 Connect Using Database Drivers SSL Security for Aster Database-Client Communications • For clients: “How to Set Configuration Parameters on the Client” on page 35 Scenario 1: Allowing connections from clients without certificates In this scenario, we edit the Aster Database SSL configuration to allow connections from clients that have no certificate. In such a configuration, any 2nd-generation Aster Database ODBC client can establish an SSL-secured connection, provided the user authenticates successfully with Aster Database. Communications from the client to Aster Database (for example, queries submitted to the database) are SSL encrypted, and query results travel in the clear. Queen-Side Settings Make the following settings on the queen: • disallowPeerWithoutCertificates=false • allowSelfSignedPeer=true • trustedCAFileName=/home/beehive/certs/server.pem • sslCertificatePath=/home/beehive/certs/server.cert • sslPrivateKeyPath=/home/beehive/certs/server.key • sslFileType=1 (A value of “1” means SSL_FILETYPE_PEM.) • Ensure that secureWrites is set to false • Ensure that secureMuleServer is set to true • There is no need to set the trustedCAPath parameter. Client-Side Settings Make the following settings on each ODBC client: • EnableSSL=1 • SSLEncryptReads=0 • SSLAllowSelfSignedPeer=1 • SSLFileType=SSL_FILETYPE_PEM • There is no need to set the other SSL settings such as SSLPrivateKeyPath. Encrypting Data Traffic By default, Aster Database encrypts only control-path communications, such as the login credentials an ODBC user submits, and the queries he or she submits. For implementations that demand greater security, Aster Database also gives you the option of SSL-encrypting the data traffic as the queen returns it to the client. Warning. All other things being equal, switching any network connection from unencrypted to SSL-encrypted has the effect of reducing the maximum available rate of data transmission on that connection. 33 Aster Database Client Guide Connect Using Database Drivers SSL Security for Aster Database-Client Communications To set this up: Queen-Side Settings Make the following settings on the queen: • secureWrites=true Client-Side Settings Make the following settings on each ODBC client: • SSLEncryptReads=1 Adding AD-Based SSO Authentication to SSL-Secured Aster Database If your Aster Database is configured to authenticate users against Active Directory (“AD”), you can configure your 2nd-generation Aster Database ODBC clients to authenticate against AD, too. With this configuration in place, each ODBC client will be required to authenticate against AD when it tries to connect to Aster Database. If the ODBC client authenticates successfully, an SSL channel is established automatically for communication between Aster Database and the client. To set this up: Queen-Side Settings Make the following settings on the queen: 1 Set up Aster Database user authentication as explained in “Set Up Active Directory Authentication with Single Sign-On” on page 336. 2 Configure the queen SSL configuration flags as described in one of the scenarios above which you are planning on implementing. (For example, see “Scenario 1: Allowing connections from clients without certificates” on page 33 Client-Side Settings Do the following: 1 Set the flags in the client’s ODBC configuration file or registry as described in your chosen scenario from above. 2 Set the EnableSSO flag in the client’s ODBC configuration file: • 3 EnableSSO=1 If EnableSSO is set to 1, you must also: • Ensure that ServerIP is set to the fully qualified domain name of the Aster Database queen and not to an IP address. • For 64-bit Linux machines: The ODBC driver assumes that libvas-gssapi.so is present at /opt/quest/lib64/. If /opt/quest/lib64/libvas-gssapi.so does not exist, locate libvas-gssapi.so by referring to the VAS documentation and set the GSSPath parameter to point to the installed location of libvas-gssapi.so. For example, if libvas-gssapi.so is deployed at /usr/lib64, then the GSSPath parameter needs to be set to /usr/lib64 in the ODBC.ini config file as shown below: GSSPath=/usr/lib64 Aster Database Client Guide 34 Connect Using Database Drivers SSL Security for Aster Database-Client Communications • For 32-bit Linux machines: The ODBC driver assumes that libvas-gssapi.so is present at /opt/quest/lib/. If /opt/quest/lib/libvas-gssapi.so does not exist, locate libvas-gssapi.so by referring to the VAS documentation and set the GSSPath parameter to point to the installed location of libvas-gssapi.so. For example, if libvas-gssapi.so is deployed at /usr/lib, then the GSSPath parameter needs to be set to /usr/lib in the ODBC.ini config file as shown below: GSSPath=/usr/lib How to Set Configuration Parameters on the Queen Many procedures in this document ask you to set configuration parameters on the Aster Database queen. Below, we explain how to do this. Persistent Setting of Parameters To edit a setting (and have your edit survive reboots), make the setting as shown below. Settings you change in this manner will survive reboots and soft restarts but they will not survive upgrades. 1 Login as root into queen and use a text editor to open the file, /home/beehive/config/ procmgmtConfigs/coordinator.cfg 2 Find the “queenExec” section which looks like: "taskName": "queenExec", "nodeIps": "REPLACE_NODE_IP", "executableLocation": "/home/beehive/bin/exec/queenExec", "maxTaskRestarts": -1 3 Add the executableArgs section to the above section as shown below: "executableArgs": "<flags in CSV format>" For example, executableArgs for Scenario 1 (described earlier in this chapter) will look like: "taskName": "queenExec", "nodeIps": "REPLACE_NODE_IP", "executableLocation": "/home/beehive/bin/exec/queenExec", "maxTaskRestarts": -1, "executableArgs": "--disallowPeerWithoutCertificates=false, --allowSelfSignedPeer=true,--trustedCAFileName=/home/beehive/certs/ server.pem,--sslCertificatePath=/home/beehive/certs/server.cert, --sslPrivateKeyPath=/home/beehive/certs/server.key,--sslFileType=1" 4 Soft restart and activate the cluster. How to Set Configuration Parameters on the Client This section explains how to set up the 2nd-generation Aster Database ODBC client for SSL communications with Aster Database. Consult the section that applies to your operating system: 35 • “Linux ODBC DSN Set-Up”, below; or • “Windows ODBC DSN Set-Up” on page 36 Aster Database Client Guide Connect Using Database Drivers SSL Security for Aster Database-Client Communications Linux ODBC DSN Set-Up On a UNIX-like systems, DSNs are added by setting parameters in the odbc.ini file Sample ODBC.INI: This sample assumes your queen machine is called cqueen.asterengqa.com and that you are following Scenario 1 (outlined earlier in this chapter): [ODBC Data Sources] AsterTest=AsterDriverTest [AsterTest] Driver=AsterDriverTest SERVER=cqueen.asterengqa.com DATABASE=beehive PORT=2406 UID=testuser13 PWD=testuser133 SQLSupportedConversions=3 NumericAndDecimalAsDouble=1 EnableSSO=0 GSSPath= EnableSSL=1 SSLEncryptReads=0 SSLAllowSelfSignedPeer=1 SSLFileType=SSL_FILETYPE_PEM SSLPrivateKeyPath= SSLCertificatePath= SSLTrustedCADir= SSLTrustedCAFilename= Sample ODBCINST.INI: This sample assumes you have installed the driver in /Drivers/AsterDriver/ODBCDriver: [AsterDriverTest] Driver=/Drivers/AsterDriver/ODBCDriver/libAsterDriver_unixODBC.so IconvEncoding=UCS-4LE Sample aster.ini: This sample assumes you want to log error messages in /Drivers/AsterDriver: [driver] DriverManagerEncoding=UTF-32 DSILogging=1 ErrorMessagesPath=/Drivers/AsterDriver/ErrorMessages Windows ODBC DSN Set-Up On Windows, DSNs are added by modifying the Windows Registry using regedit.exe or using a .reg file. The standards surrounding key names (such as whether to use “Server” or “servername”) used in a connection string for ODBC driver are loose, so please take care to follow the examples we provide. Aster Database Client Guide 36 Connect Using Database Drivers SSL Security for Aster Database-Client Communications Details for setting the values in the registry are given below. Choose the section that fits your needs and client type: • “Adding a driver to a Windows 32-bit operating system”, below. • “Adding a 64-bit driver to a Windows 64-bit operating system” on page 38 • “Adding a 32-bit driver to a Windows 64 bit operating system” on page 39 Adding a driver to a Windows 32-bit operating system Make the following registry settings: Driver for 32-bit Windows Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC] [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI] [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\AsterDriver32] "Driver"="C:\\AsterDriver-Win32\\ODBCDriver\\AsterDataODBCDSII.dll" [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\ODBC Drivers] "AsterDriver32"="Installed" [HKEY_LOCAL_MACHINE\SOFTWARE\Aster] [HKEY_LOCAL_MACHINE\SOFTWARE\Aster\Driver] "DSILogging"="0" "ErrorMessagesPath"="C:\\AsterDriver-Win32\\ErrorMessages" "DriverManagerEncoding"="UTF-16" The values in the keys above can be modified depending on where the driver is located on the local machine and what the name of the driver should be. The values above are based on the assumption that the driver folder is at "C:\AsterDriver-Win32" and the name of the driver is "AsterDriver32". For an example .reg file that makes these settings, contact Teradata support. DSN for 32-bit Windows To add a DSN for the above driver setup in the registry, make these entries in the registry: [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC] [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI] [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\AsterDSN32] "driver"="AsterDriver32" "SERVER"="10.51.12.100" "DATABASE"="beehive" "PORT"="2406" "UID"="beehive" "PWD"="beehive" "SQLSupportedConversions"="3" "NumericAndDecimalAsDouble"="1" "EnableSSO"="0" "SSLKeyFile"="\"\"" "GSSPath"="" "EnableSSL"="1" "SSLEncryptReads"="1" "SSLAllowSelfSignedPeer"="0" "SSLFileType"="SSL_FILETYPE_PEM" "SSLPrivateKeyPath"="\"\"" "SSLCertificatePath"="\"\"" "SSLTrustedCADir"="\"\"" "SSLTrustedCAFilename"="\"\"" 37 Aster Database Client Guide Connect Using Database Drivers SSL Security for Aster Database-Client Communications "EnableSSO"="0" [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\ODBC Data Sources] "AsterDSN32"="AsterDriver32" Adding a 64-bit driver to a Windows 64-bit operating system Below we list the registry entries for setting up a 64-bit driver on Windows. Make the registry settings shown below: • 64-bit driver for 64-bit Windows • 64-bit DSN for 64-bit Windows 64-bit driver for 64-bit Windows Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC] [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI] [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\AsterDriver64] "Driver"="C:\\AsterDriver-Win64\\ODBCDriver\\AsterDataODBCDSII.dll" [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\ODBC Drivers] "AsterDriver64"="Installed" [HKEY_LOCAL_MACHINE\SOFTWARE\Aster] [HKEY_LOCAL_MACHINE\SOFTWARE\Aster\Driver] "DSILogging"="0" "ErrorMessagesPath"="C:\\AsterDriver-Win64\\ErrorMessages" "DriverManagerEncoding"="UTF-16" 64-bit DSN for 64-bit Windows To add a DSN for the above driver setup in the registry, make these entries in the registry: Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC] [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI] [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\AsterDSN64] "driver"="AsterDriver64" "SERVER"="10.51.12.100" "DATABASE"="beehive" "PORT"="2406" "UID"="beehive" "PWD"="beehive" "SQLSupportedConversions"="3" "NumericAndDecimalAsDouble"="1" "EnableSSO"="0" "SSLKeyFile"="\"\"" "GSSPath"="" "EnableSSL"="1" "SSLEncryptReads"="1" "SSLAllowSelfSignedPeer"="0" "SSLFileType"="SSL_FILETYPE_PEM" "SSLPrivateKeyPath"="\"\"" "SSLCertificatePath"="\"\"" "SSLTrustedCADir"="\"\"" "SSLTrustedCAFilename"="\"\"" "EnableSSO"="0" [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\ODBC Data Sources] "AsterDSN64"="AsterDriver64" Aster Database Client Guide 38 Connect Using Database Drivers SSL Security for Aster Database-Client Communications Above, the name of the DSN for the 64-bit driver is AsterDSN64. The server being connected to is 10.51.12.100. Adding a 32-bit driver to a Windows 64 bit operating system Some applications running on a Windows 64-bit machine require a 32-bit driver. The 32-bit operations work on Windows 64 bit machines under a mechanism called “Wow6432Node.” Below we list the registry entries for setting up 32-bit drivers on Windows. Make the registry settings shown below: • 32-bit driver on 64-bit Windows • 32-bit DSN on 64-bit Windows 32-bit driver on 64-bit Windows Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC] [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBCINST.INI] [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBCINST.INI\AsterDriver32 ] "Driver"="C:\\AsterDriver-Win32\\ODBCDriver\\AsterDataODBCDSII.dll" [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBCINST.INI\ODBC Drivers] "AsterDriver32"="Installed" [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Aster] [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Aster\Driver] "DSILogging"="0" "ErrorMessagesPath"="C:\\AsterDriver-Win32\\ErrorMessages" "DriverManagerEncoding"="UTF-16" The values in the keys above can be modified depending on where the driver is located on the local machine and what the name of the driver should be. The values above are based on the assumption that the driver folder is at "C:\AsterDriver-Win32" for 32 bit drivers and the name of the driver is "AsterDriver32". For an example .reg file that makes these settings, contact Teradata support. 32-bit DSN on 64-bit Windows To add a DSN for the above driver setup in the registry, make these entries in the registry: [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC] [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBC.INI] [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBC.INI\AsterDSN32] "driver"="AsterDriver32" "SERVER"="10.51.12.100" "DATABASE"="beehive" "PORT"="2406" "UID"="beehive" "PWD"="beehive" "SQLSupportedConversions"="3" "NumericAndDecimalAsDouble"="1" "EnableSSO"="0" "SSLKeyFile"="\"\"" "GSSPath"="" "EnableSSL"="1" "SSLEncryptReads"="1" "SSLAllowSelfSignedPeer"="0" 39 Aster Database Client Guide Connect Using Database Drivers Processing SQL Statements in JDBC "SSLFileType"="SSL_FILETYPE_PEM" "SSLPrivateKeyPath"="\"\"" "SSLCertificatePath"="\"\"" "SSLTrustedCADir"="\"\"" "SSLTrustedCAFilename"="\"\"" [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBC.INI\ODBC Data Sources] "AsterDSN32"="AsterDriver32" Above, the name of the DSN for the 32-bit driver is AsterDSN32. The server being connected to is 10.51.12.100. Creating Certificates Creating a Self-Signed Certificate You may to create your own self-signed certificate. The high-level steps for doing this using the OpenSSL tool are shown here, assuming you create a private key file called “host.key”: openssl genrsa 1024 > host.key chmod 400 host.key openssl req \-new \-x509 \-nodes \-sha1 \-days 365 \-key host.key > host.cert Regenerating SSL Certificates/Private Key During Aster Database Installation You may manually regenerate the default private key and certificate using the following command on the queen: 1 Working as root user, perform a soft shutdown on Aster Database: # ncli system softshutdown 2 Wait for the system to shut down, and then run the resetCert command: # /home/beehive/bin/lib/configure/ConfigureNCluster.py --resetCert This will back up any existing server.key/server.cert files present in /home/beehive/certs and generate a new private key and certificate file. Processing SQL Statements in JDBC You can execute SQL statements by using a Statement or a PreparedStatement instance. Sometimes it is more convenient to use a PreparedStatement object for sending SQL statements to the database. This special type of statement is derived from the more general class, Statement, that you already know. If you want to execute a Statement object many times, it normally reduces execution time to use a PreparedStatement object instead. The main feature of a PreparedStatement object is that, unlike a Statement object, it is given an SQL statement when it is created. The advantage to this is that in most cases, this SQL Aster Database Client Guide 40 Connect Using Database Drivers Processing SQL Statements in JDBC statement is sent to the DBMS right away, where it is compiled. As a result, the PreparedStatement object contains not just an SQL statement, but an SQL statement that has been precompiled. This means that when the PreparedStatement is executed, the DBMS can just run the PreparedStatement SQL statement without having to compile it first. Processing a Simple Query in JDBC This example will issue a simple query and print out the first column of each row using a Statement. Statement st = conn.createStatement(); ResultSet rs = st.executeQuery("SELECT * FROM mytable WHERE columnf = 500"); while (rs.next()) { System.out.print("Column 1 returned "); System.out.println(rs.getString(1)); } rs.close(); st.close(); This example issues the same query as before but uses a PreparedStatement and a bind value in the query. int fvalue = 500; PreparedStatement st = conn.prepareStatement("SELECT * FROM mytable WHERE columnf = ?"); st.setInt(1, fvalue); ResultSet rs = st.executeQuery(); while (rs.next()) { System.out.print("Column 1 returned "); System.out.println(rs.getString(1)); } rs.close(); st.close(); The instance returns a ResultSet containing the results. Aster Database does not support cursor-based server-side caching of results which would save a small amount of time in parsing. To retrieve data from the ResultSet instance, call next(), which returns true if there are results. The ResultSet instance can be closed by calling close(), or if another query is issued using the same Statement instance that was used to create this ResultSet. Statement stmt=con.createStatement(); ResultSet rs = stmt.executeQuery("select count(*) from page_views"); while (rs.next()) { System.out.println(rs.getInt(1)); } rs.close(); stmt.close(); You can also run Update/Insert/Delete statements and Create/Drop Table statements using the same method. 41 Aster Database Client Guide Connect Using Database Drivers JDBC Issues JDBC Issues Infinity and Negative Infinity Timestamp Conversion The JDBC driver converts 'infinity' and '-infinity' to specific TimeStamp values (a very large and a very tiny TimeStamp) which can cause unexpected results on the client side. Aqua Data Studio and other client tools, like SQL Assistant JAVA edition also have this issue. These tools do not support 'infinity' and '-infinity' in the timestamp datatype. If they encounter these values, they will display specific TimeStamp values (a very large and a very tiny TimeStamp). Connecting Reporting Tools to Aster Database This section shows how to connect various reporting and query tools to Aster Database: • Connecting Aqua Data Studio to Aster Database (page 42) • Connecting MicroStrategy to Aster Database (page 43) • See also: Connect Using Database Drivers (page 6) Connecting Aqua Data Studio to Aster Database ADS support is being deprecated. AquaFold’s ADS lets you perform DDL operations and query data interactively, and it provides tools that help you write and manage queries efficiently. ADS is a third-party tool available for purchase from Aqua Fold directly. Aster Database is compatible with ADS version 10.0.2 with patch ads-10.0.7_03-patch.zip. Install ADS This section explains how to install ADS on your client workstation and connect to an Aster Database. 1 Download Aqua Data Studio version 10.0.2 or later from http://www.aquafold.com/ downloads.html 2 Install Aqua Data Studio on your client workstation as explained in your version of the Aqua Data Studio documentation at http://docs.aquafold.com/ aquadatastudio_11_documentation.html 3 Start Aqua Data Studio. 4 Select the command Server: Register Server. 5 In the list, select the “Aster nCluster Driver.” 6 Fill in the tabs as required. Aster Database Client Guide 42 Connect Using Database Drivers Connecting Reporting Tools to Aster Database Apply the ADS Patch 1 Download the patch from AquaFold: http://dd1.aquafold.com/download/v10.0.0/ads-10.0.7_03-patch.zip 2 Unzip the patch files. 3 Replace the files under C:\Program Files\Aqua Data Studio 10.0 - 64bit\lib with the files from ads-10.0.7_03-patch.zip. 4 Restart ADS. Connecting MicroStrategy to Aster Database Observe the following guidelines when connecting MicroStrategy to Aster Database. In this section: Versions | Platforms Supported | Limitations | Set-up Instructions | Best Practices Versions MicroStrategy 9 or later is required, and Aster Database 3.0.1 or later is required. Platforms Supported Aster Database supports Intelligence Server clients running on Windows XP and Windows Vista with the Aster Database ODBC driver for Windows. Limitations Aster Database is only certified as a warehouse with MicroStrategy. Aster Database cannot be used as a repository. Set-up Instructions To connect MicroStrategy to Aster Database, follow the steps below. Prerequisites Make sure the following patches are applied to your MicroStrategy installation: MicroStrategy 8: Contact MicroStrategy Customer support for • DATABASE.PDS file that's certified with Aster Database • DTMAPPING.PDS file that's certified with Aster Database MicroStrategy 9: Contact MicroStrategy Customer support for • DTMAPPING.PDS file that works with Aster Database MicroStrategy 9.0.1 and above: No changes required 43 Aster Database Client Guide Connect Using Database Drivers Connecting Reporting Tools to Aster Database Install Drivers On the client machine where MicroStrategy runs, install the database drivers: 1 Install the Aster Database ODBC driver. This is available in the /home/beehive/clients directory on your Aster Database queen. See “ODBC Driver” on page 7 for installation instructions. 2 Install the MicroStrategy VLDB driver, version 9 or later. Configure Drivers and Library Paths 1 2 Make sure the following are installed, and make sure that your Microstrategy installation’s LD_LIBRARY_PATH includes them: • libstdc++.so.6 • libgcc_s.so.1 Edit Microstrategy’s ODBC.sh file so that the Microstrategy installation can find the Aster Database ODBC driver. To do this, modify {MSTR_HOME}/env/ODBC.sh and add or modify the Aster section of the file. In this section, do two things: a Include the Aster Database ODBC driver library in the LD_LIBRARY_PATH. b Make sure there is an export ODBCSYSINI line in the section. This line points to the odbc.ini that the Microstrategy application will use. Below, we show an example setup from a sample {MSTR_HOME}/env/ODBC.sh file: ASTER_PATH='/usr/local/lib/stage/<client_directory_for_OS>/ ODBCDriver: \ /usr/local/lib/stage/<client_directory_for_OS>/Libs' if [ "${ASTER_PATH}" != '<ASTER_PATH>' ]; then export ASTER_PATH mstr_append_path LD_LIBRARY_PATH "${ASTER_PATH:?}" export LD_LIBRARY_PATH export ODBCSYSINI=/export/home/beehive/MicroStrategy fi 3 Modify your ${ODBCSYSINI}/odbc.ini to include the new ODBC DSN [ODBC Data Sources] aster=AsterDriver [aster] Driver=/usr/local/lib/stage/<client_directory_for_OS>/ODBCDriver/ libAsterDriver_unixODBC.so SERVER=<server_ip> PORT=2406 DATABASE=<database> UID=<uid> PWD=<passwd> 4 Modify your ${ODBCSYSINI}/odbcinst.ini to include the Aster Database ODBC settings as shown in the example below: [AsterDriver] Driver=/usr/local/lib/stage/<client_directory_for_OS>/ODBCDriver/ libAsterDriver_unixODBC.so IconvEncoding=UCS-4LE Aster Database Client Guide 44 Connect Using Database Drivers Connecting Reporting Tools to Aster Database Connecting to an Aster Database 1 Open your MicroStrategy project and choose Intelligence Server as your connection option. 2 Use the Configuration Wizard to create a New Project Source. 3 Create a New Database Instance and give it a name. 4 In the Connection Type field, choose Aster Database nCluster. 5 Create a New Database Connection and give it a name. 6 Create a new ODBC System DSN and give it a name. Once you have saved the System DSN, you can create reports in MicroStrategy that use the data from your Aster Database. In your Logical Table definitions in MicroStrategy, you can create queries that use special Aster Database tools such as nPath. Best Practices By following the guidelines below, you can avoid common errors in Aster DatabaseMicroStrategy integration. Schema changes • If your schema contains NUMERIC(X,0) type columns, you should replace these with INT or BIGINT type columns for a higher probability of success with existing MicroStrategy reports. • For your small- to medium-sized tables that have no BIGINT or INT columns, you should create the tables in Aster Database as replicated dimension tables. This takes more space in the cluster, but works better with MicroStrategy. Operational items When pointing an existing MicroStrategy report from another database to Aster Database, the warehouse schema should be “UPDATED” the first time when pointed to an Aster Database Instance. This updates the metadata inside MicroStrategy for correct MicroStrategy columns. This is particularly important when a schema is ported from some other database to Aster Database. SQL query changes • 45 To use Aster Database’s nPath and other custom SQL-MapReduce functions: • Reports must be created as free-form SQL type reports in MicroStrategy. • Teradata Aster recommends that you embed the query in an MicroStrategy logical table and build the reports on top of that. • If there are existing reports that need to run on Aster Database, some tweaking may be needed in the VLDB Settings of MicroStrategy depending on the complexity of the dynamically generated queries. For example, you may need to turn off TEMP table creation, and so on. This is very rare, but editing VLDB settings can be useful in some cases. • If the following error appears in queries: “Unable to find function to convert from <x> to <y>”, and if x and y are datatypes like int, float, and so on, then you may need a workaround to explicitly cast the column types. Contact Teradata Support for help on this. Aster Database Client Guide Index A Active Directory authentication SSL connections and 34 Aster Database connecting, overview 6 Aster Database configuration settings SQL behavior 28 B backslash allow backslash escapes 28 bytea handling bytea data in ODBC 10 C certificate 40 for ODBC connection 40 character set, default 6 characters, special 6 client recommended client settings 6 client settings, recommended 6 client-side cursors in JDBC 23 configuration queen system parameters 35 configuration settings SQL behavior 28 connect 6 JDBC driver 19 MicroStrategy 43 ODBC driver 7 connecting 6 overview 6 through JDBC 21 coordinator.cfg 35 cursor distributed 24 JDBC, cursors in 23 customizing SQL behavior 28 ODBC 7 ODBC for Perl scripts 16 distributed cursors 24 drivers 6 JDBC 19 ODBC 7 ODBC for Perl scripts 16 E E prefix 28 enable_quoted_identifiers 28 encryption 30 of query results 33 SSL for ODBC 30 escape character allow backslash escapes 28 export JDBC driver 19 ODBC driver 7 J Java JDBC statements 40 JDBC 19 connecting through JDBC 21 cursors in 23 driver 19 how to write applications that use JDBC 40 query example 41 sample test program 25 L loading JDBC driver 19 ODBC driver 7 M MicroStrategy, connections for 43 D O data encrypting data traffic 33 database drivers 6 JDBC 19 ODBC 7 bytea handling 10 driver 7 ODBC driver Aster Database Client Guide 46 for MicroStrategy 43 installing for use with Perl scripts 16 installing on Linux 11 installing on Windows 7 SSL settings 32 P parameter setting queen system parameters 35 Perl scripts, ODBC driver for 16 preferences SQL settings 28 PreparedStatement in JDBC 40 Q queen system parameters, setting 35 query via Java JDBC calls 40 quoted identifier enable in Aster Database 28 T tools MicroStrategy 43 U umlauts 6 UTF-8 recommended client settings 6 utilities JDBC driver 19 ODBC driver 7 W workaround certificate, missing self-signed cert 31 R recommended client settings 6 reporting tools MicroStrategy 43 S security SSL for ODBC 30 settings enable_backslash_escapes 28 enable_quoted_identifiers 28 SQL settings 28 SSL connection settings 31 SQL customizing SQL behavior 28 parameters that set SQL behavior 28 SSL 30 with Active Directory authentication 34 SSL for ODBC 30 certificates for 40 client settings 32 common configuration scenarios 32 encryption of query results 33 how to set up on client 35 how to set up on queen 35 queen settings 31 reference to Aster Database SSL settings 31 SSO for ODBC connections 34 Statement in JDBC 40 47 Aster Database Client Guide