CONMGR

9.8 CONMGR

The sub-commands are:

9.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

9.8.2 Import Connections

Import 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

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.

{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.

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 definitons.

Example

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

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

9.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

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

9.8.3 List Connections

List the names of the connections.

Syntax

cnnmgr|cm list

Example

To list the names of connections, enter:

SQL> CONNMGR LIST

9.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 {PARAMETERS}

Parameters

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

Example

To show the details for MyConnection:

SQL> CONNMGR SHOW MyConnection

9.8.5 Test Connections

A test connection is opened and then closed. 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