Skip to content

Latest commit

 

History

History
102 lines (82 loc) · 9.39 KB

connection-string.md

File metadata and controls

102 lines (82 loc) · 9.39 KB
Raw

Connection String Syntax and Options

DRIVER={Amazon DocumentDB};HOSTNAME=<host>:<port>;DATABASE=<database>;USER=<user>;PASSWORD=<password>;<option>=<value>;

Driver

Driver: Required: the driver for this ODBC driver.

Parameters

Property Description Default
DATABASE (required) The name of the database the ODBC driver will connect to. NONE
HOSTNAME (required) The hostname or IP address of the DocumentDB server or cluster. NONE
PORT (optional) The port number the DocumentDB server or cluster is listening on. 27017
USER (optional) The username of the authorized user. While the username is optional on the connection string, it is still required either via the connection string, or the properties. NONE
PASSWORD (optional) The password of the authorized user. While the password is optional on the connection string, it is still required either via the connection string, or the properties. NONE
OPTION (optional) One of the connection string options listed below. NONE
VALUE (optional) The associated value for the option. NONE

Options

Option Description Default
APP_NAME (string) Sets the logical name of the application. Amazon DocumentDB ODBC Driver {version}
LOGIN_TIMEOUT_SEC (int) How long a connection can take to be opened before timing out (in seconds). Alias for connectTimeoutMS but using seconds. NONE
LOG_LEVEL Log level for driver logging. Possible values:
{OFF, ERROR, INFO, DEBUG}		 ERROR
LOG_PATH Folder to store the log file Windows: %USERPROFILE%, or if not available, %HOMEDRIVE%%HOMEPATH%
macOS/Linux: getpwuid(), or if not available, $HOME
READ_PREFERENCE (enum/string) The read preference for this connection. Allowed values: primary, primaryPreferred, secondary, secondaryPreferred or nearest. primary
REPLICA_SET (string) Name of replica set to connect to. For now, passing a name other than rs0 will log a warning. NONE
RETRY_READS (true/false) If true, the driver will retry supported read operations if they fail due to a network error. true
TLS (true/false) If true, use TLS encryption when communicating with the DocumentDB server. true
TLS_ALLOW_INVALID_HOSTNAMES (true/false) If true, invalid host names for the TLS certificate are allowed. This is useful when using an internal SSH tunnel to a DocumentDB server. false
TLS_CA_FILE (string) The path to the trusted Certificate Authority (CA) .pem file. If the path starts with the tilde character (~), it will be replaced with the user's home directory. Ensure to use only forward slash characters (/) in the path or URL encode the path. Providing the trusted Certificate Authority (CA) .pem file is optional as the current Amazon RDS root CA is used by default when the tls option is set to true. This embedded certificate is set to expire on 2024-08-22. For example, to provide a new trusted Certificate Authority (CA) .pem file that is located in the current user's Downloads subdirectory of their home directory, use the following: TLS_CA_FILE=~/Downloads/rds-ca-2019-root.pem. NONE
SSH_USER (string) The username for the internal SSH tunnel. If provided, options sshHost and sshPrivateKeyFile must also be provided, otherwise this option is ignored. NONE
SSH_HOST (string) The host name for the internal SSH tunnel. Optionally the SSH tunnel port number can be provided using the syntax <ssh-host>:<port>. The default port is 22. If provided, options SSH_USER and sshPrivateKeyFile must also be provided, otherwise this option is ignored. NONE
SSH_PRIVATE_KEY_FILE (string) The path to the private key file for the internal SSH tunnel. If the path starts with the tilde character (~), it will be replaced with the user's home directory. If the path is relative, the absolute path will try to be resolved by searching in the user's home directory (~), the .documentdb folder under the user's home directory or in the same directory as the driver JAR file. If the file cannot be found, a connection error will occur. If provided, options SSH_USER and SSH_HOST must also be provided, otherwise this option is ignored. NONE
SSH_PRIVATE_KEY_PASSPHRASE (string) If the SSH tunnel private key file, SSH_PRIVATE_KEY_FILE, is passphrase protected, provide the passphrase using this option. If provided, options SSH_USER, SSH_HOST and SSH_PRIVATE_KEY_FILE must also be provided, otherwise this option is ignored. NONE
SSH_STRICT_HOST_KEY_CHECKING (true/false) If true, the 'known_hosts' file is checked to ensure the target host is trusted when creating the internal SSH tunnel. If false, the target host is not checked. Disabling this option is less secure as it can lead to a "man-in-the-middle" attack. If provided, options sshUser, sshHost and SSH_PRIVATE_KEYFILE must also be provided, otherwise this option is ignored. true
SSH_KNOWN_HOSTS_FILE (string) The path to the 'known_hosts' file used for checking the target host for the SSH tunnel when option SSH_STRICT_HOST_KEY_CHECKING is true. The known_hosts file can be populated using the ssh-keyscan tool. If provided, options SSH_USER, SSH_HOST and SSH_PRIVATE_KEY_FILE must also be provided, otherwise this option is ignored. ~/.ssh/known_hosts
SCAN_METHOD (enum/string) The scanning (sampling) method to use when discovering collection metadata for determining table schema. Possible values include the following: 1) RANDOM - the sample documents are returned in random order, 2) ID_FORWARD - the sample documents are returned in order of id, 3) ID_REVERSE - the sample documents are returned in reverse order of id or 4) ALL - sample all the documents in the collection. RANDOM
SCAN_LIMIT (int) The number of documents to sample. The value must be a positive integer. If SCAN_METHOD is set to all, this option is ignored. 1000
SCHEMA_NAME (string) The name of the SQL mapping schema for the database. _default.
DEFAULT_FETCH_SIZE (int) The default fetch size (in records) when retrieving results from Amazon DocumentDB. It is the number of records to retrieve in a single batch. The maximum number of records retrieved in a single batch may also be limited by the overall memory size of the result. 2000
REFERESH_SCHEMA (true/false) If true, generates (refreshes) the SQL schema with each connection. It creates a new version, leaving any existing versions in place. Caution: use only when necessary to update schema as it can adversely affect performance. false

Examples

Connecting to an Amazon DocumentDB Cluster

DRIVER={Amazon DocumentDB};HOSTNAME=localhost;DATABASE=customer;TLSALLOWINVALIDHOSTNAMES=true;

Notes:

  1. An external SSH tunnel is being used where the local port is 27017 (27017 is default).
  2. The Amazon DocumentDB database name is customer.
  3. The Amazon DocumentDB is TLS-enabled (tls=true is default)
  4. User and password values are passed to the ODBC driver using Properties.

Connecting to an Amazon DocumentDB Cluster on Non-Default Port

DRIVER={Amazon DocumentDB};HOSTNAME=localhost:27017;DATABASE=customer;TLS_ALLOW_INVALID_HOSTNAMES=true;

Notes:

  1. An external SSH tunnel is being used where the local port is 27117.
  2. The Amazon DocumentDB database name is customer.
  3. The Amazon DocumentDB is TLS-enabled (tls=true is default).
  4. User and password values are passed to the ODBC driver using Properties.

Connecting to an Amazon DocumentDB Cluster using an Internal SSH tunnel

DRIVER={Amazon DocumentDB};HOSTNAME=localhost:27017;DATABASE=customer;TLS_ALLOW_INVALID_HOSTNAMES=true;SSH_USER=ec2-user;SSH_HOST=ec2-254-254-254-254.compute.amazonaws.com;SSH_PRIVATE_KEY_FILE=~/.ssh/ec2-privkey.pem

Notes:

  1. DocumentDB cluster host is docdb-production.docdb.amazonaws.com (using default port 27017).
  2. The Amazon DocumentDB database name is customer.
  3. The Amazon DocumentDB is TLS-enabled (tls=true is default).
  4. An internal SSH tunnel will be created using the user ec2-user, host ec2-254-254-254-254.compute.amazonaws.com, and private key file ~/.ssh/ec2-privkey.pem.
  5. User and password values are passed to the ODBC driver using Properties.

Change the Scanning Method when Connecting to an Amazon DocumentDB Cluster

DRIVER={Amazon DocumentDB};HOSTNAME=localhost:27017;DATABASE=customer;TLS_ALLOW_INVALID_HOSTNAMES=true;SCAN_METHOD=ID_FORWARD;SCAN_LIMIT=5000

Notes:

  1. An external SSH tunnel is being used where the local port is 27017 (27017 is default).
  2. The Amazon DocumentDB database name is customer.
  3. The Amazon DocumentDB is TLS-enabled (tls=true is default).
  4. User and password values are passed to the ODBC driver using Properties.
  5. The scan method ID_FORWARD will order the result using the _id column in the collection.
  6. The scan limit 5000 will limit the number of scanned documents to 5000.