Gen 2 connector configuration and versioning¶

Gen 2 Openflow connectors are File Based Entities (FBEs): Snowflake objects whose configuration is stored as files on an internal versioned stage that Snowflake creates and manages on the connector object. You do not create this stage with CREATE STAGE—it is attached automatically when the connector is created. Configuration files (for example, config.json) and assets (for example, JDBC driver JARs) live under versioned paths on that stage.

This topic explains the version states, UI labels, SQL workflow for editing connector configuration, and how to list, download, and upload files on the connector stage. Other Snowflake object types (for example, dbt projects and Cortex agents) use a similar versioned-stage model with their own snow:// URI schemes; here we cover Openflow connectors only.

Access the connector’s versioned stage¶

Each connector version is an immutable snapshot in the connector’s version history. Versions behave similarly to Git commits: if a new version does not change a file, both versions can reference the same underlying file. Use the snow://openflow_connector/ URI scheme to reference files:

snow://openflow_connector/<database>.<schema>.<connector_name>/versions/<version>/[<file_name>]

version is one of:

• live — writable working copy (see Version states below)
• LAST — alias for the most recently committed (default) version
• VERSION$N — a specific committed version (for example, VERSION$1)
• A user-assigned name — set when you commit; preserved for later reference (for example, production-config)

You can use a user-assigned name or VERSION$N in snow:// paths and SQL when referencing a committed version.

List, download, and upload files with the standard stage commands documented in File staging commands (LIST, GET, and PUT). Pass the URI as a quoted string (for example, GET 'snow://openflow_connector/...').

You can also inspect version metadata with SHOW VERSIONS IN OPENFLOW CONNECTOR and connector properties (including the active version) with DESCRIBE OPENFLOW CONNECTOR. See SHOW VERSIONS IN OPENFLOW CONNECTOR and DESCRIBE OPENFLOW CONNECTOR.

Version states¶

The live version is your working copy. The default version is what runs when the connector starts in the target runtime. In stage paths, versions/LAST points to the default (committed) version. Committing the live version creates a new immutable default and removes the live version.

While a connector is RUNNING, you can still edit the live version. Changes are not applied to the running connector until you COMMIT (UI Apply or SQL COMMIT).

UI labels¶

Configuration workflow¶

New connectors created with CREATE OPENFLOW CONNECTOR ... FROM DEFINITION or the setup wizard start with a live version and no default (Draft).

1. Upload or edit files in the live version (skip ADD LIVE VERSION on a new connector—it already has a live version).

2. Commit to promote live to default:

   Copy code

   ALTER OPENFLOW CONNECTOR my_db.my_schema.my_connector COMMIT;
   

3. To discard uncommitted changes:

   Copy code

   ALTER OPENFLOW CONNECTOR my_db.my_schema.my_connector ABORT;
   

4. To edit a committed connector, create a new live version seeded from the current default:

   Copy code

   ALTER OPENFLOW CONNECTOR my_db.my_schema.my_connector ADD LIVE VERSION FROM LAST;
   

Stage file operations¶

The following examples use the snow://openflow_connector/ URI. Replace my_db.my_schema.my_connector with your connector’s fully qualified name.

List files in the live version:

LS 'snow://openflow_connector/my_db.my_schema.my_connector/versions/live';

Download the last committed config.json (use snow sql or another client that supports GET on stages; Snowsight does not support GET/PUT on stages):

GET 'snow://openflow_connector/my_db.my_schema.my_connector/versions/LAST/config.json'
  file:///path/to/local/;

Upload to the live version:

PUT 'file:///path/to/config.json'
  'snow://openflow_connector/my_db.my_schema.my_connector/versions/live/config.json'
  AUTO_COMPRESS = FALSE
  OVERWRITE = TRUE;

After uploading, commit:

ALTER OPENFLOW CONNECTOR my_db.my_schema.my_connector COMMIT;

SELECT SYSTEM$WAIT_FOR_STABLE_OPENFLOW_CONNECTORS(600, 'my_db.my_schema.my_connector');

Create from a known configuration¶

Use this workflow when you already have a validated connector configuration and want to create another connector with the same settings—for example, standing up a matching connector in a second runtime, or automating repeat deployments with CI/CD.

This is not the path for your first connector. Create and configure a connector once with the setup wizard or CREATE OPENFLOW CONNECTOR ... FROM DEFINITION, then export the configuration.

Definition vs configuration¶

A catalog definition (for example, OPENFLOW_POSTGRES_CDC) and instance configuration (config.json) are separate:

• FROM DEFINITION in CREATE OPENFLOW CONNECTOR selects the catalog connector type. You then edit config.json on the connector’s versioned stage and COMMIT.
• FROM a stage path supplies a complete configuration bundle from any stage reference—a Git repository stage (@my_git_repo/...), another connector’s stage in the same account (snow://openflow_connector/...), or another internal stage. The catalog definition is named inside config.json as connectorDefinitionId—there is no FROM DEFINITION clause in the CREATE command.

When you use FROM with a stage path, Openflow reads connectorDefinitionId from config.json to determine the connector type—you do not use FROM DEFINITION in CREATE. The stage holds only instance configuration: config.json, asset files (such as JDBC drivers), and metadata. Snowflake supplies the catalog connector package at create time; you do not copy it onto the stage.

Before you run CREATE, update connection URLs, secret references, and destination settings for the target runtime.

Initial state difference¶

Workflow¶

1. Create and configure a connector with the wizard or FROM DEFINITION. Commit the configuration when it works in your source environment.

2. Register a Git repository in Snowflake if you do not already have one. See Using a Git repository in Snowflake.

3. Export the connector configuration:

   Copy code

   ALTER OPENFLOW CONNECTOR my_db.my_schema.my_connector PUSH TO
     '@my_git_repo/branches/main/connectors/my_connector'
     USERNAME = 'my-git-username'
     PASSWORD = 'my-git-token'
     NAME = 'My Name'
     EMAIL = 'my.email@example.com'
     COMMENT = 'Export connector config';
   

4. Review and update config.json in the repository for the target environment (secrets, URLs, destination settings).

5. Create the new connector from the stage path:

   Copy code

   CREATE OPENFLOW CONNECTOR my_db.my_schema.my_connector_prod
     IN RUNTIME my_db.my_schema.my_prod_runtime
     FROM '@my_git_repo/branches/main/connectors/my_connector/'
     COMMENT = 'Created from validated stage config';
   

   You can also use a snow://openflow_connector/.../versions/LAST/ URI to clone a connector in the same account without Git—for example, 'snow://openflow_connector/my_db.my_schema.my_connector/versions/LAST/'.

For CREATE, ADD VERSION FROM, PUSH, and PULL syntax, see CREATE OPENFLOW CONNECTOR and ALTER OPENFLOW CONNECTOR.

Secrets in configuration¶

Sensitive values (for example, database passwords) should reference Snowflake secrets rather than plain text in config.json. See Secrets in configuration in Configure a gen 2 connector with SQL.