Progress DataDirect® for ODBC for Amazon Redshift™ Wire Protocol Driver Quick Start for UNIX/Linux

Release 8.0.0

Quick Start: Progress DataDirect for ODBC for Amazon Redshift Wire Protocol Driver for UNIX/Linux

This quick start provides basic information that allows you to install and test connect with your driver. To take full advantage of the features and functionality available for your driver, refer to the product documentation library at: Progress DataDirect Documentation Library

Note: OEM CUSTOMERS: Refer to the Progress DataDirect for ODBC Drivers Distribution Guide for information on installing, branding, unlocking, and distributing your branded drivers.

This quick start covers the following topics:

• Before You Start on page 3 • Requirements and Support on page 4 • Downloading the Driver on page 4 • Installing the ODBC Driver on UNIX/Linux on page 4 • Environment Configuration on page 6 • Configuring a Data Source on page 7 • Testing the Connection on page 8 • Tuning for Performance on page 8 • Troubleshooting Setup/Connection Issues on page 10 • Additional Resources on page 11

Before You Start

Before you get started, you need the following:

• Appropriate user permissions to modify your environment and to read, write, and execute various files in the DataDirect for ODBC installation directory . • Connection information: • Database Name: The name of the database to which you want to connect. • Host Name: The endpoint for the Amazon Redshift cluster to which you want to connect. • Port Number: The port number of the server listener.

enter product name here: Quick Start for UNIX/Linux: Version 8.0.0 3 Chapter 1: Quick Start: Progress DataDirect for ODBC for Amazon Redshift Wire Protocol Driver for UNIX/Linux

• For licensed installations, you will also need the following information that was provided by Progress DataDirect:

• IPE Key (control number) • Serial Number

Requirements and Support

Driver/Client Software Requirements:

• The driver has no client requirements. Supported Data Sources:

• Amazon Redshift For the latest information on supported data sources and requirements, visit the Progress DataDirect Supported Configurations page.

Downloading the Driver

To download the ODBC Amazon Redshift driver:

1. Visit the Progress DataDirect Connectors Download page. 2. Select Amazon Redshift from the list. 3. Select ODBC for the interface. 4. When prompted for your OS and architecture, select the bitness and platform your application runs on. 5. Fill in the registration form with your contact information. 6. Review the End User License Agreement. If you agree, select the corresponding box; then, click Download.

The installer program has been downloaded. See "Installing the ODBC Driver on UNIX/Linux" for instructions on installing the driver.

See also Installing the ODBC Driver on UNIX/Linux on page 4

Installing the ODBC Driver on UNIX/Linux

This section provides instructions for installing your downloaded files from a command-line interface. Depending on your environment, you can also install using GUI or silent installation options. Refer to the Progress DataDirect for ODBC Drivers Installation Guide for complete installation instructions.

1. Download the appropriate product file from the Web site into a temporary directory, for example, /tmp. 2. Switch the temporary directory; then, choose one of the following:

4 enter product name here: Quick Start for UNIX/Linux: Version 8.0.0 Installing the ODBC Driver on UNIX/Linux

3. Extract the contents of the product file. Enter: tar -xvzf product_filename.tgz where product_filename is the name of the tarred product file name. The untarred files appear in the temporary directory.

4. Run the installer program by switching to the temporary directory that contains the untarred installer files and entering: ./installer_filename.bin –i console where:

installer_filename

is the full name of the installer's binary file you untarred in Step 3 on page 5 .

5. The Introduction step appears. Press ENTER. 6. The product license agreement appears. Press SPACEBAR to page to the end of the agreement. At the end, you are asked to accept the agreement:

• Enter Y to accept the license agreement and continue with the installation. • Enter N to abort the installation.

Note: You can exit the installer program at any time by typing quit or return to the previous step by typing previous.

7. You are prompted to enter the absolute path to the installation directory. The default is: For 32-bit installations: opt/Progress/DataDirect/ODBC_nn_32bit For 64-bit installations: opt/Progress/DataDirect/ODBC_nn_64bit If you do not have /opt directory permissions, the installer program installs the drivers to your home directory by default. For example, the directory for 32-bit installation would be: /home_directory/Progress/DataDirect/ODBC_nn_32bit where

nn

is the product version number. For example, this value is 80 for the 8.0 version of the product.

home_directory

is the home directory for the user who is installing the product.

8. You are prompted for the type of installation:

• If you are installing an evaluation copy of the product (expires in 15 days), enter 1. Then, press Enter to confirm the evaluation information. Skip to Step 12 on page 6. • If you are installing a OEM or licensed copy of the product, enter 2. Proceed to the next step.

enter product name here: Quick Start for UNIX/Linux: Version 8.0.0 5 Chapter 1: Quick Start: Progress DataDirect for ODBC for Amazon Redshift Wire Protocol Driver for UNIX/Linux

Note: If you were issued multiple product keys, you can type them sequentially, separating the keys with a space. For example: xxxxkey1 xxxxkey2 xxxxkey3

9. You are prompted to enter the IPE key (control number) that was provided by Progress DataDirect. Type the IPE key (control number), including dashes, and then press ENTER. Proceed to the next step. 10. The DataDirect Installer Customer Experience Improvement Program step appears. By choosing to participate in the program, you permit the installer to gather data about your installation, such as environment information and error details, that will be used to improve our products. Choose one of the following:

• If you would like to participate in the program, enter 1. • If you do not want to participate in the program, enter 2. For more information about data collection, refer to the Progress Privacy Policy.

11. The installer prompts you for product registration information. Enter your name, your company name, and the serial number provided by Progress DataDirect; then, press ENTER. 12. The Pre-Installation Summary step provides the opportunity for you to review the information you have entered, and you are prompted to accept or change the information:

• Press ENTER to accept the information and begin the installation. • To change the information, type back and then press ENTER. You are prompted for the information again. • If you are installing with a licensed OEM IPE key, you are prompted for branding information. Please refer to the Progress DataDirect for ODBC Drivers Distribution Guide.

13. After completion of the installation, a message appears indicating that you have installed the software successfully. Press ENTER to close the installer.

This completes the installation. After installation, you must do the following: • Configure your environment • Configure a data source See "Environment Configuration", "Setting the Library Path Environment Variable" and "Configuring a Data Source" for details.

See also Environment Configuration on page 6 Configuring a Data Source on page 7

Environment Configuration

After installing your driver, your first step in setting up and configuring the driver is to configure your environment variables. The following procedures require that you have the appropriate permissions to modify your environment and to read, write, and execute various files. You must log in as a user with full r/w/x permissions recursively on the entire DataDirect Connect Series for ODBC installation directory. To configure the environment:

6 enter product name here: Quick Start for UNIX/Linux: Version 8.0.0 Configuring a Data Source

1. Check your permissions: You must log in as a user with full r/w/x permissions recursively on the entire product installation directory. 2. From your login shell, determine which shell you are running by executing: echo $SHELL

3. Run one of the following product setup scripts from the installation directory to set variables: odbc.sh or odbc.csh. For Korn, Bourne, and equivalent shells, execute odbc.sh. For a C shell, execute odbc.csh. After running the setup script, execute: env to verify that the installation_directory/lib directory has been added to your shared library path.

4. Set the ODBCINI environment variable. The variable must point to the path from the root directory to the system information file where your data source resides. The system information file can have any name, but the product is installed with a default file called odbc.ini in the product installation directory. For example, if you use an installation directory of /opt/odbc and the default system information file, from the Korn or Bourne shell, you would enter: ODBCINI=/opt/odbc/odbc.ini; export ODBCINI From the C shell, you would enter: setenv ODBCINI /opt/odbc/odbc.ini

Configuring a Data Source

The default odbc.ini file installed in the installation directory is a template in which you create data source definitions. You enter your site-specific database connection information using a text editor. Each data source definition must include the keyword Driver=, which is the full path to the driver. The following examples show the minimum connection string options that must be set to complete a test connection, where xx represents iv for 32-bit or dd for 64-bit drivers, and yy represents the extension. The values for the options are samples and are not necessarily the ones you would use.

[ODBC Data Sources] Amazon Redshift Wire Protocol=DataDirect 8.0 Amazon Redshift Wire Protocol Driver

[Amazon Redshift Wire Protocol] Driver=ODBCHOME/lib/xxrsftyy.zz Database=Redshiftdb1 HostName=RedshiftServer PortNumber=5439

Connection Option Descriptions:

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

• HostName: The endpoint for the Amazon Redshift cluster to which you want to connect. • Port Number: The port number of the server listener. The default is 5439.

enter product name here: Quick Start for UNIX/Linux: Version 8.0.0 7 Chapter 1: Quick Start: Progress DataDirect for ODBC for Amazon Redshift Wire Protocol Driver for UNIX/Linux

Testing the Connection

The driver installation includes an ODBC application called example that can be used to connect to a data source and execute SQL. The application is located in the installation_directory/samples/example directory. To run the program after setting up a data source in the odbc.ini, enter example and follow the prompts to enter your data source name, user name, and password. If successful, a SQL> prompt appears and you can type in SQL statements such as SELECT * FROM table. If example is unable to connect, the appropriate error message is returned.

Tuning for Performance

The connection options described in this section directly affect the performance of your driver. To tune for performance, configure your driver according to the recommended settings and your environment.

ApplicationUsingThreads Purpose: Determines whether the driver works with applications using multiple ODBC threads. Performance Impact: The driver coordinates concurrent database operations (operations from different threads) by acquiring locks. Although locking prevents errors in the driver, it also decreases performance. If your application does not make ODBC calls from different threads, the driver has no reason to coordinate operations. Recommended Settings: If your application is multi-threaded, set to 1 (enabled). If your application is not multi-threaded, set to 0 (disabled) for improved performance.

ConnectionReset Purpose: Determines whether the state of connections that are removed from the connection pool for reuse by the application is reset to the initial configuration of the connection.

Note: The value for this option is ignored when Connection Pooling is disabled (Pooling=0).

Performance Impact: Resetting a re-used connection to the initial configuration settings impacts performance negatively because the connection must issue additional commands to the server. Recommended Settings: Set to 0 (disabled) for improved performance.

EncryptionMethod Purpose:

8 enter product name here: Quick Start for UNIX/Linux: Version 8.0.0 Tuning for Performance

Determines the method the driver uses to encrypt data sent between the driver and the database server. Performance Impact: Data encryption may adversely affect performance because of the additional overhead (mainly CPU usage) that is required to encrypt and decrypt data. Recommended Settings: If data encryption is not required, set to 0 (No Encryption) for improved performance.

FailoverMode Purpose: Specifies the type of failover method the driver uses. Performance Impact: Although high availability that replays queries after a failure provides increased levels of protection, it can adversely affect performance because of increased overhead. Recommended Settings: If your application does not require the ability to recover or restart transactions, set this option to 0 (Connection) for improved performance.

LoadBalanceTimeout Purpose: Specifies the number of seconds to keep inactive connections open in a connection pool.

Note: The value for this option is ignored when Connection Pooling is disabled (Pooling=0).

Performance Impact: By configuring LoadBalanceTimeout to keep inactive connections open, you improve the likelihood that the driver can reuse an existing connection instead of establishing new one when a connection is needed. This improves performance by avoiding the overhead required to establish a new connection. The MinPoolSize option can cause some connections to ignore this value. Recommended Settings: Set to 0 for improved performance. By specifying a value of 0 (the default), inactive connections are kept open.

MaxPoolSize Purpose: The maximum number of connections allowed within a single connection pool. When the maximum number of connections is reached, no additional connections can be created in the connection pool.

Note: The value for this option is ignored when Connection Pooling is disabled (Pooling=0).

Performance Impact: Setting the maximum number of connections that the pool can contain too low might cause delays while waiting for a connection to become available. Setting the number too high wastes memory resources. Recommended Settings:

enter product name here: Quick Start for UNIX/Linux: Version 8.0.0 9 Chapter 1: Quick Start: Progress DataDirect for ODBC for Amazon Redshift Wire Protocol Driver for UNIX/Linux

Tune this setting for your environment. Specify the maximum number of connections your environment requires to have open at a time.

MinPoolSize Purpose: Specifies the minimum number of connections that are opened and placed in a connection pool, in addition to the active connection, when the pool is created. The connection pool retains this number of connections, even when some connections exceed their LoadBalanceTimeout value.

Note: The value for this option is ignored when Connection Pooling is disabled (Pooling=0).

Performance Impact: A connection pool is created when the first connection with a unique connection string connects to the database. The pool is populated with connections up to the minimum pool size, if one has been specified. The connection pool retains this number of connections, even when some connections exceed their LoadBalanceTimeout value. By increasing this number, you improve the likelihood that the driver will be able to reuse a connection; thereby, improving performance. Recommended Settings: Tune this setting for your environment. Specify the average number of connections your environment typically uses at a time.

Pooling Purpose: Specifies whether to use the driver’s connection pooling. Performance Impact: Connection pooling allows you to reuse connections rather than creating a new one every time the driver needs to establish a connection to the underlying database. Using connection pooling can improve performance by avoiding the penalty incurred when establishing a new connection, especially for high-throughput applications. You can further affect the performance by tuning the following connection options that are related to connection pooling: ConnectionReset, MaxPoolSize, MinPoolSize, and LoadBalanceTimeout. Recommended Settings: Set to 1 (enabled) to improve performance.

Troubleshooting Setup/Connection Issues

This section describes common setup/connection issues you may encounter while trying to establish a database connection with the driver as well as some potential reasons for these issues. If you are experiencing a problem not described in this section, comprehensive troubleshooting resources are available in the "Troubleshooting" section of the User's Guide and Reference for your driver. In addition, Progress DataDirect offers a variety of options to meet your technical support needs. See Contacting Technical Support on page 12 for details.

10 enter product name here: Quick Start for UNIX/Linux: Version 8.0.0 Additional Resources

Common Setup/Connection Issues

You are experiencing a setup/connection issue if you are encountering an error or hang while you are trying to make a database connection with the ODBC driver or are trying to configure the ODBC driver. Some common errors that are returned by the ODBC driver if you are experiencing a setup/connection issue include: • Specified driver could not be loaded. • Data source name not found and no default driver specified. • Unable to connect to destination. • Invalid username/password; logon denied.

Troubleshooting the Issue

Some common reasons that setup/connection issues occur are:

• The database and/or listener are not started. • The ODBCINI environment variable is not set correctly for the ODBC drivers on UNIX and Linux. • The ODBC driver’s connection attributes are not set correctly in the system information file on UNIX and Linux. See "Configuring a Data Source" for more information. For example, the host name or port number are not correctly configured.

See also Configuring a Data Source on page 7

Additional Resources

In addition to this quick start, the following resources enable you to take full advantage of the features and support offered for your driver. • Product Documentation Library contains a comprehensive set of product documentation, including the following guides: • Progress DataDirect for ODBC Drivers Installation Guide details requirements and procedures for installing the product. • Progress DataDirect for ODBC for Amazon Redshift Wire Protocol Driver User's Guide and Reference guides you through using and configuring the driver, provides detailed reference information, and explains the tools used to troubleshoot common problems.

• Progress Support Knowledgebase provides answers to questions, access to technical documentation, release notes, product alerts and other support information. • Progress Community allows you to contribute, share, and network with other Progress users and employees. • Technical Support provides technical support services, including maintenance services and opening a support case.

enter product name here: Quick Start for UNIX/Linux: Version 8.0.0 11 Chapter 1: Quick Start: Progress DataDirect for ODBC for Amazon Redshift Wire Protocol Driver for UNIX/Linux

Contacting Technical Support

Progress DataDirect offers a variety of options to meet your support needs. Please visit our Web site for more details and for contact information: https://www.progress.com/support The Progress DataDirect Web site provides the latest support information through our global service network. The SupportLink program provides access to support contact details, tools, patches, and valuable information, including a list of FAQs for each product. In addition, you can search our Knowledgebase for technical bulletins and other information. When you contact us for assistance, please provide the following information:

• Your number or the serial number that corresponds to the product for which you are seeking support, or a case number if you have been provided one for your issue. If you do not have a SupportLink contract, the SupportLink representative assisting you will connect you with our Sales team. • Your name, phone number, email address, and organization. For a first-time call, you may be asked for full information, including location. • The Progress DataDirect product and the version that you are using. • The type and version of the operating system where you have installed your product. • Any database, database version, third-party software, or other environment information required to understand the problem. • A brief description of the problem, including, but not limited to, any error messages you have received, what steps you followed prior to the initial occurrence of the problem, any trace logs capturing the issue, and so on. Depending on the complexity of the problem, you may be asked to submit an example or reproducible application so that the issue can be re-created. • A description of what you have attempted to resolve the issue. If you have researched your issue on Web search engines, our Knowledgebase, or have tested additional configurations, applications, or other vendor products, you will want to carefully note everything you have already attempted. • A simple assessment of how the severity of the issue is impacting your organization.

Copyright

© 2017 Progress Software Corporation and/or one of its subsidiaries or affiliates. All rights reserved.

These materials and all Progress® software products are copyrighted and all rights are reserved by Progress Software Corporation. The information in these materials is subject to change without notice, and Progress Software Corporation assumes no responsibility for any errors that may appear therein. The references in these materials to specific platforms supported are subject to change.

12 enter product name here: Quick Start for UNIX/Linux: Version 8.0.0 Copyright

Corticon, DataDirect (and design), DataDirect Cloud, DataDirect Connect, DataDirect Connect64, DataDirect XML Converters, DataDirect XQuery, Deliver More Than Expected, Icenium, Kendo UI, Making Software Work Together, NativeScript, OpenEdge, Powered by Progress, Progress, Progress Software Developers Network, Rollbase, SequeLink, Sitefinity (and Design), SpeedScript, Stylus Studio, TeamPulse, Telerik, Telerik (and Design), Test Studio, and WebSpeed are registered trademarks of Progress Software Corporation or one of its affiliates or subsidiaries in the U.S. and/or other countries. Analytics360, AppServer, BusinessEdge, DataDirect Spy, SupportLink, DevCraft, Fiddler, JustCode, JustDecompile, JustMock, JustTrace, OpenAccess, ProDataSet, Progress Results, Progress Software, ProVision, PSE Pro, Sitefinity, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, and WebClient are trademarks or service marks of Progress Software Corporation and/or its subsidiaries or affiliates in the U.S. and other countries. Java is a registered trademark of Oracle and/or its affiliates. Any other marks contained herein may be trademarks of their respective owners. Please refer to the readme applicable to the particular Progress product release for any third-party acknowledgments required to be provided in the documentation associated with the Progress product.

enter product name here: Quick Start for UNIX/Linux: Version 8.0.0 13 Chapter 1: Quick Start: Progress DataDirect for ODBC for Amazon Redshift Wire Protocol Driver for UNIX/Linux

14 enter product name here: Quick Start for UNIX/Linux: Version 8.0.0