Skip to content

Latest commit

 

History

History
126 lines (101 loc) · 7.53 KB

setup.md

File metadata and controls

126 lines (101 loc) · 7.53 KB
Raw

Amazon DocumentDB JDBC Driver Setup

Topics

Prerequisites

DocumentDB Cluster

If you don't already have an Amazon DocumentDB cluster, there are a number of ways to get started.

Note that DocumentDB is a Virtual Private Cloud (VPC) only service. If you will be connecting from a local machine outside the cluster's VPC, you will need to create an SSH connection to an Amazon EC2 instance. In this case, launch your cluster using the instructions in Connect with EC2. See Using an SSH Tunnel to Connect to Amazon DocumentDB for more information on SSH tunneling and when you might need it.

JRE or JDK

Depending on your BI application, you may need to ensure a 64-bit JRE or JDK installation version 8 or later is installed on your computer. You can download the Java SE Runtime Environment 8 here.

DocumentDB JDBC Driver

Download the DocumentDB JDBC driver here. The driver is packaged as a single JAR file (e.g., documentdb-jdbc-1.0.0-all.jar).

Specifying the Amazon RDS Certificate Authority Certificate File

If you are connecting to a TLS-enabled cluster, you may want to specify the Amazon RDS Certificate Authority certificate on your connection string. By default, an Amazon RDS Certificate Authority root certificate has been embedded in the JDBC driver JAR file which should work when connecting to Amazon DocumentDB clusters using SSL/TLS encryption. However, if you want to provide a new Amazon RDS Certificate Authority root certificate, follow the directions below:

  1. Download the root CA certificate

  2. It is recommended to relocate the file to your user's home directory: $HOME for Windows or ~ for MacOS/Linux.

  3. Add the tlsCAFile option to your JDBC connection string. For example:

    jdbc:documentdb://localhost:27017/<database-name>?tlsAllowInvalidHostnames=true&tlsCAFile=global-bundle.pem

To determine whether your cluster is TLS-enabled, you can check the value of your cluster's tls parameter.

Using an SSH Tunnel to Connect to Amazon DocumentDB

Amazon DocumentDB (with MongoDB compatibility) clusters are deployed within an Amazon Virtual Private Cloud (Amazon VPC). They can be accessed directly by Amazon EC2 instances or other AWS services that are deployed in the same Amazon VPC. Additionally, Amazon DocumentDB can be accessed by EC2 instances or other AWS services in different VPCs in the same AWS Region or other Regions via VPC peering.

However, suppose that your use case requires that you (or your application) access your Amazon DocumentDB resources from outside the cluster's VPC. This will be the case for most users not running their application on a VM in the same VPC as the DocumentDB cluster. When connecting from outside the VPC, you can use SSH tunneling (also known as port forwarding) to access your Amazon DocumentDB resources.

There are two options to create an SSH tunnel:

  1. Internally, using the SSH tunnel options (minimally, sshUser, sshHost, and sshPrivateKeyFile).
  2. Externally, using the ssh application. For further information on creating an external SSH tunnel, please refer to the documentation on Connecting from Outside an Amazon VPC

The JDBC Connection String When Using an SSH Tunnel

To create an SSH tunnel, you need an Amazon EC2 instance running in the same Amazon VPC as your Amazon DocumentDB cluster. You can either use an existing EC2 instance in the same VPC as your cluster or create one. Connecting from outside the Amazon VPC using an SSH tunnel will have the following impact on the JDBC connection string:

  1. If your cluster has Transport Layer Security (TLS) enabled, you will need to add the tlsAllowInvalidHostNames=true option.
  2. For external SSH, since the SSH tunnel is running on your local computer, the host name must be set to localhost.
  3. For external SSH, if your local port (-L <local-port>:<cluster-host>:<remote-port>) configured for the SSH tunnel is not the default port (27017) for Amazon DocumentDB, ensure the connection string host setting for your SSH tunnel is properly set in the JDBC connection string.
  4. The replicaSet option is not supported when using an SSH tunnel.

Using an External SSH Tunnel to Connect to Amazon DocumentDB

Start an SSH port-forwarding tunnel to the cluster with the following command:

ssh -i <ssh-key-pair-filename>.pem -N -L <local-port>:<cluster-host>:<remote-port> <ec2-username>@<public-IPv4-DNS-name>
  • The -L flag defines the port forwarded to the remote host and remote port. Adding the -N flag means do not execute a remote command
  • Ensure you have read access permission for the file <ssh-key-pair-filename>.pem. To enable read access permission you can run the following command: chmod 400 <ssh-key-pair-filename>.pem.

This is a prerequisite for connecting to any BI tool running on a client outside your VPC.

Example: Given the following

  • <cluster-host> = sample-cluster.node.us-east-1.docdb.amazonaws.com

  • <public-IPv4-DNS-name> = ec2-34-229-221-164.compute-1.amazonaws.com

  • <local-port> = 27117

  • <remote-port> = 27017

  • <ssh-key-pair-filename>.pem = ~/.ssh/ec2Access.pem

  • <ec2-username> = ubuntu

    The SSH tunnel command would look like:

    ssh -i ~/.ssh/ec2Access.pem -N -L 27117:sample-cluster.node.us-east-1.docdb.amazonaws.com:27017 [email protected]

    The JDBC connection string for connecting to the TLS-enabled Amazon DocumentDB cluster with <database-name> = customer would look like:

    jdbc:documentdb://localhost:27117/customer?tlsAllowedInvalidHostnames=true

For further information on SSH tunneling , please refer to the documentation on Connecting from Outside an Amazon VPC.

Driver Setup in BI Applications

The JDBC driver is compatible with a number of BI tools. Instructions are outlined here for:

  1. Tableau Desktop
  2. Tableau Server
  3. DbVisualizer
  4. SQuirrel SQL Client
  5. DBeaver
  6. MicroStrategy Developer

For other BI tools, please refer to that tool's product documentation.