11.8 CONNMGR

Use the Connection Manager (CONNMGR) command to work with persistent connections and connections stored in the OCI Database Tools Service.

It contains the following subcommands:

• Clone
• Import
• List
• Show
• Test

11.8.1 Clone Connections

Clones an existing connection. By default, the credentials stored with the original connection are used for the new connection. To change the user name, the -user option can be used. If the user changes, a password prompt is displayed unless the -nopwd option is used

Syntax

connmgr|cm clone {OPTIONS} {PARAMETERS}

Options

Option	Description	Default
-original, -o	The name of the source connection being cloned.	Required
-nopwd	Whether to create the connection without a stored password.	-
-user, -u	The user name to store with the connection. If no user name is specified, you may be prompted to provide one when using the connection, depending on the authentication configuration.	-

Parameters

Parameter	Description
<name>	The name of the connection. Connection names are case-sensitive.

Example

To clone an existing connection:

SQL> CONNMGR CLONE -original original_name newname
SQL> CONNMGR CLONE -original original_name -user newuser newname

11.8.2 Import Connections

Imports one or more connections to the common connection store.

Connect files may contain encrypted passwords and other credentials.

When importing connections with encrypted passwords, the encryption key is required to decrypt the passwords. The encryption key may be provided with the import command by first securing it with a secret. For more information about using a secret, see SECRET Command. If no key is provided with the import command, a prompt is displayed to request the key.

The passwords can be removed from imported connections by specifying the -strip_passwords option.

Syntax

connmgr|cm import {OPTIONS} {PARAMETERS}

Options

Option	Description
-duplicates | d | dups	{ignore|rename|replace} Indicates how to handle imported connections whose names match an existing connection. IGNORE: Skips the duplicate connections. RENAME: Renames the duplicate connections by appending a unique number to the end of the name. REPLACE: Replaces the existing connection with the new connection.
-key	The public name of a secret that protects the encryption key used to encrypt passwords in the file. Note: If the encryption key is invalid, the connections are imported with the passwords removed.
-strip_passwords | s | strip	Indicates that encrypted passwords be stripped from imported connections.
-oci	Accesses the Database Tools connections that are available to you within your OCI tenancy.

Parameters

Parameter	Description
path	A single file or directory containing one or more connections to import. If the path is an archive file, the archive is checked for a single connection definition. If the path is a JSON file, it is checked for legacy connection definitions. If the path is a directory, it is checked for more archives containing connection definitions.
<display_name>	The display name of a connection in the OCI Database Tools Service.

Example 1

To create a secret for the encryption key and specify the secret name when importing connections from a file, enter:

SQL> SECRET SET mySecret <encryption key>
  SQL> CONNMGR IMPORT -KEY mySecret myconns.json

Example 2

To import a connection from the OCI Database Tools Service, enter:

SQL> CONNMGR IMPORT -OCI DB23c-Free
  

11.8.2.1 SECRET Command

This command is used to securely store secret values in memory. The Connection Manager (connmgr) commands enable the use of the secret name to identify secure values such as passwords and encryption keys. Using the secret name in this way ensures that secure values are not displayed on the command line and do not persist in command history. Secure values cannot be retrieved with the SECRET command.

Syntax

secret {SUBCOMMAND}

where the subcommands are:

• Set
• List
• Unset

Set

Sets a name for a secret value. The secret name can be used with commands that support secure values.

Syntax

secret set {PARAMETERS}

Parameters

Parameter	Description
secret_name	The public name that can be used to represent a secure value.
secret_value	The protected secret value that is associated with the secret name.

List

Lists the currently stored secret names.

Syntax

secret list

Unset

Removes the secret value for the secret name.

Syntax

 secret unset <secret_name>

where secret_name is the public name used to represent a secret value.

Example

Set a name for a secret value and use it to import connections.

SQL> secret set my_name myEncryptionKey
secret my_name stored
SQL> connmgr import -encryption_key my_name conns.json

11.8.3 List Connections

Lists the names of the connections.

Syntax

cnnmgr|cm list {OPTIONS}

Options

Option	Description
-oci	Accesses the Database Tools connections that are available to you within your OCI tenancy.

Example 1

To list the names of the connections in the local connection store, enter:

SQL> CONNMGR LIST

Example 2

To list the Database Tools connections that are available within your OCI tenancy, enter:

SQL> CONNMGR LIST -OCI

11.8.4 Show Connections

Shows the details for a connection, including the connection URL and the user name (if stored). Additional details are displayed depending on the stored connection description.

Syntax

connmgr|cm show {OPTIONS} {PARAMETERS}

Options

Option	Description
-oci	Accesses the Database Tools connections that are available to you within your OCI tenancy.

Parameters

Parameter	Description
<name>	The name of the connection. Connection names are case-sensitive.
<display_name>	The display name of a connection in the OCI Database Tools Service.

Example 1

To show details for MyConnection, enter:

SQL> CONNMGR SHOW MyConnection

Example 2

To show details for the DB23c-Free connection in the OCI Database Tools Service, enter:

SQL> CONNMGR SHOW -OCI DB23c-Free

11.8.5 Test Connections

Tests a connection definition.

Opens and closes a test connection. This test connection does not affect the current SQLcl connection. The credentials stored with the connection are used for the test. If no password is stored, the user is prompted for the password. If the -user option is used, the provided user is tested instead. A password will need to be provided when prompted.

Syntax

connmgr|cm test {OPTIONS} {PARAMETERS}

Options

Option	Description
-user, -u	Specify a user name instead of using the one stored with the connection definition. Case-sensitive user names are quoted to preserve case.

Parameters

Parameter	Description
<name>	The name of the connection. Connection names are case-sensitive.

Example

To test the connection MyConnection for user name SCOTT:

SQL> CONNMGR TEST MyConnection
SQL> CONNMGR TEST -USER SCOTT MyConnection