Connection configuration

Connection configuration is a wizard step that comes directly after the connector configuration. This step allows the user to specify properties required for establishing a connection with the source system to start ingesting data into Snowflake. The procedure called PUBLIC.SET_CONNECTION_CONFIGURATION(connection_configuration VARIANT) is the entry point responsible for this wizard phase. This procedure can be called by the UI or from the worksheet. When overwriting with custom logic, this procedure needs to be replaced, to specify the custom Java handler.

Calling this procedure requires the user to have the ADMIN application role assigned.

The connection configuration step internally consists of several phases. Some of them are fully customizable and by default, don’t do anything. The phases are as follows:

  1. Status validation

  2. Input validation

  3. Configuration update

  4. Internal callback

  5. Connection validation

  6. Status update


Connection configuration requires at least the following SQL files to be executed during native app installation:

In addition there is a requirement dependent on the SDK user:

  • custom implementation of PUBLIC.TEST_CONNECTION() procedure

Status validation

To perform connection configuration the internal status of the connector needs to be CONFIGURING, with configuration status: CONFIGURED or CONNECTED. The first of the configuration statuses will be set directly after the connector configuration step, the latter one will be present if for some reason Connection Configuration has to be updated during later steps.

This validation cannot be overwritten by using ConnectionConfigurationHandlerBuilder nor by overwriting a stored procedure. However, it is possible to implement a custom handler, which will not have this kind of validation.

Input validation

Input needs to be a variant containing a map of properties, however this might not work for all cases. For that reason the SDK provides an internal stored procedure called: PUBLIC.SET_CONNECTION_CONFIG_VALIDATE(config VARIANT). By default, this procedure just returns 'responseCode': 'OK', overwriting it can update the provided config during validation. This feature enables for custom logic. For example, trimming the input or conversion to upper/lower case. To return config transformed in any way the response needs to contain an additional "config" property in the response Variant, this property should contain the updated config as Variant. The procedure can be customized by overwriting through the SQL or by using ConnectionConfigurationHandlerBuilder and providing custom implementation of the ConnectionConfigurationInputValidator interface.

The following is a valid response from the custom implementation with transformation:

    "response_code" : "OK",
    "config": {
        "key1": "value1",
        "key2": "value2"

Configuration update

Once the validations are passed successfully, configuration will be saved to the internal APP_CONFIG table. The service responsible for this saves the provided Variant under the connection_configuration key. This configuration does not follow any additional requirements when saving, the set of provided properties is up to the user.

Internal callback

Internal callback is another customizable step. By default, it invokes PUBLIC.SET_CONNECTION_CONFIGURATION_INTERNAL(connection_configuration VARIANT), which returns 'response_code': 'OK'. For example, it can be used to alter other procedures by granting them external access integration. It can be overwritten through the SQL script or by using a ConnectionConfigurationHandlerBuilder to provide custom implementation of the ConnectionConfigurationCallback interface.

Connection validation

This step triggers a PUBLIC.TEST_CONNECTION procedure. This procedures tries to query the source system for the data. This procedure is not implemented by default and needs to be provided by the SDK user. Additionally, ConnectionValidator interface implementation can be provided to the ConnectionConfigurationHandlerBuilder to customize this phase, in this case, there is no need to implement a stored procedure. The recommendation is to perform just a minimal connectivity check in this procedure to ensure that external access capabilities of Snowflake were configured correctly and the Connector has all required privileges to use them.

Status update

When all the above phases are completed successfully the internal status of the connector will be updated to:

    "status": "CONFIGURING",
    "configurationStatus": "CONNECTED"

For the whole diagram of state transitions, see Connector flow.

Viewing the configuration

There is a PUBLIC.GET_CONNECTION_CONFIGURATION() procedure available to the ADMIN and VIEWER users that returns current connection configuration from the internal table.


Successful response

If the procedure finishes successfully it will return a response from TEST_CONNECTION procedure. We recommend using the following format:

  "response_code": "OK"

Error response

In case of an error the response will follow the below format:

  "response_code": "<ERROR_CODE>",
  "message": "<error message>"

Possible error codes include:

  • INVALID_CONNECTOR_STATUS - Invalid connector status. Expected status: [CONFIGURING]

  • INVALID_CONNECTOR_CONFIGURATION_STATUS - Invalid connector configuration status. Expected status: CONFIGURED

  • INTERNAL_ERROR - Something went wrong internally, the message should be descriptive

  • PROCEDURE_NOT_FOUND - Procedure which was called does not exist. In this case it’s about TEST_CONNECTION procedure mostly

  • UNKNOWN_SQL_ERROR - This error occurs when something unexpected happen when calling internal procedures

  • INVALID_RESPONSE - This error occurs when response received from internal procedure does not contain response_code or an error response does not contain message, but contains response_code

  • UNKNOWN_ERROR - It means that something unexpected went wrong - message of thrown exception is forwarded

  • Custom error codes received from TEST_CONNECTION() procedure - defined by connector developer

  • Custom error codes received from SET_CONNECTION_CONFIGURATION_INTERNAL() procedure - defined by connector developer