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
• Export
• 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 Export Connections

Exports one or more connections to an encrypted archive file for backup or transfer to another system. Passwords and credentials are encrypted using the specified key.

Use this command to:

• Export all stored connections
• Export specific connections
• Export connections from a specific folder (including subfolders)

Syntax

connmgr|cm export {OPTIONS}

Options

Option	Description
Required
-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.
Optional
-folder <folder>	Specifies the folder (including sub folders) from which to export all connections.
-all-connections|-a|-all	Exports all stored connections.
-overwrite|-o	Overwrites an existing export file if it exists.
-preserve-folders|-p	Preserves the current folder hierarchy so connections are exported with the same structure.

Example 1

To export all connections to a file:

SQL> CONNMGR EXPORT -key mykey -all-connections connections.backup

Example 2

To export specific connections:

SQL> CONNMGR EXPORT -key mykey conn1 conn2 conn3 my_connections
  

Example 3

To export all connections from a folder:

SQL> CONNMGR EXPORT -key mykey -folder /prod prod_backup

Example 4

To overwrite an existing export file:

SQL> CONNMGR EXPORT -key mykey -overwrite -all-connections
      connections.backup

11.8.3 Import Connections

Imports one or more connections to the common connection store .

Use this command to import connections from:

• JSON files exported from SQL Developer. These may include encrypted passwords and credentials. If passwords are encrypted, provide the encryption key (stored as a secret) or enter it when prompted. Alternatively, you can strip passwords during import and provide them later when connecting.
• Encrypted archive files exported via CONNMGR EXPORT. The encryption key is required to import.
• Oracle Cloud Infrastructure Database Tools service. Imports a reference to a cloud-based connection; the connection name is stored locally, while credentials, connect string, and other details are retrieved from the Database Tools service as needed.

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.
-list-contents|-l|-list	Lists the connections contained in the archive without importing them.
-folder|-f <folder>	Imports connections into the specified folder instead of the root folder.

Parameters

Parameter	Description
Required
<import-location>	A JSON file (from SQL Developer), an encrypted archive (from CONNMGR EXPORT), or the DisplayName of a DatabaseTools Service connection when used with -oci
Optional
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. Note: This parameter is applicable only when using the -oci option.

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
  

Example 3

To import connections from a legacy JSON file:

Example 4

To import connections from an encrypted archive:

 SQL> CONNMGR IMPORT -KEY mySecret connections.backup

Example 5

To list connections in an archive without importing:

SQL> CONNMGR IMPORT -KEY mySecret -LIST connections.backup

Example 6

To import connections into a specific folder:

SQL> CONNMGR IMPORT -KEY mySecret -FOLDER /imported connections.backup

Example 7

To import connections, renaming duplicates:

SQL> CONNMGR IMPORT -KEY mySecret -DUPLICATES RENAME connections.backup

Example 8

To import with passwords stripped:

SQL> CONNMGR IMPORT -STRIP-PASSWORDS myconns.json

11.8.3.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.4 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.5 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.6 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