Connections commands

Add, edit, remove and list saved connections with the sqlflow CLI, including capture mode, options and secret references.

These commands manage the saved connections of the account you are signed in to: the same records as the Connections page. A saved connection holds connection details and, optionally, a secret reference. It never holds a password. See Saved connections. Set up the CLI first: see Overview and authentication.

Add a connection

sqlflow connection add <name> --engine <engine> --host <host> --port <port> --db <database> --user <user>
                      [--mode <mode>] [--encryption require|prefer] [--opt <key=value> ...]
                      [--secret-ref <env:NAME|file:NAME>]

add fails if a connection with the same engine and name already exists. Use edit to change one.

The capture modes you can give with --mode:

PostgreSQL and MySQL have no capture mode. See Choosing a capture mode.

--password is refused. Pass the password when you create the pipeline, or store a secret reference.

sqlflow connection add orders-sql --engine sqlserver --host sql01.example.com --port 1433 --db Orders --user sqlflow_reader --mode directlog --secret-ref file:orders-pw
sqlflow connection add warehouse-pg --engine postgres --host pg01.example.com --port 5432 --db warehouse --user sqlflow_writer

The command prints saved connection 'orders-sql' [<id>] → sqlserver sqlflow_reader@sql01.example.com:1433/Orders secret=file:orders-pw encryption=require.

Encryption

Every SQL Server, PostgreSQL, MySQL, Oracle and Sybase ASE connection carries an encryption setting, the same Encryption choice the connection form shows:

Use prefer only for a server you trust on a network you trust, for example an on-premises SQL Server with a self-signed certificate. A sqlserver connection to an Azure host name, such as *.database.windows.net, validates the certificate under prefer too. Azure SQL and SQL database in Fabric connections always validate the server certificate and have no setting, so --encryption is refused for them: --encryption is not applicable to Azure SQL connections, which always validate the server certificate. Leave the flag out.

Options

--opt sets the same engine-specific fields the pipeline wizard shows. The ones you are most likely to need are:

The options trustServerCertificate and sslMode are refused as retired. Use --encryption instead.

sqlflow connection add orders-azure --engine azuresql --host myserver.database.windows.net --port 1433 --db Orders --opt authentication=entraManagedIdentity

A value that holds = is split at the first one.

Edit a connection

sqlflow connection edit <name> [--engine <engine>] [--host <host>] [--port <port>] [--db <database>] [--user <user>]
                       [--mode <mode>] [--encryption require|prefer] [--opt <key=value> ...]
                       [--secret-ref <env:NAME|file:NAME>]

edit changes only the fields you give and keeps everything else. A repeated --opt is added to the options already saved, --mode replaces the saved capture mode, and --encryption replaces the saved encryption setting. A --secret-ref replaces the saved reference. The CLI can't remove a saved reference. To drop one, delete the connection and add it again.

A connection is identified by its engine and name, so edit can't change either. When two connections share a name, add --engine to say which. --password is refused, as for add.

sqlflow connection edit orders-sql --host sql02.example.com

If no connection matches, the command fails with No connection '<name>' to edit. Use `connection add` to create it, or `connection list` to see saved connections.

Remove a connection

sqlflow connection remove <name> [--engine <engine>]

Deletes the saved connection. Pipelines created from it are unaffected, because each pipeline keeps its own copy. <name> can also be the connection's ID.

List connections

sqlflow connection list

NAME                         ENGINE     ENDPOINT                                   ID
orders-sql                   sqlserver  sqlflow_reader@sql01.example.com:1433/Orders secret=file:orders-pw encryption=require  <id>

Connections are sorted by engine, then by name. The endpoint shows user@host:port/database, secret=<reference> when the connection names a secret reference, and, for SQL Server, PostgreSQL, MySQL, Oracle and Sybase ASE, encryption=require or encryption=prefer. A reference is a name, not a password, so listing it discloses nothing. encryption=retired option, edit and save means the connection holds a retired encryption option; connection edit removes it.

Errors

See also

• Saved connections
• Database credentials and secret references
• Pipelines commands
• Choosing a capture mode