Callbacks¶

Synchronous callbacks¶

Synchronous callbacks are called as part of the triggering SQL command. Synchronous callbacks block the calling SQL command. If the callback returns an error, the command will return an error, and the callback’s error message is returned as part of the SQL error message of the command.

Synchronous callbacks run in a warehouse, so the calling procedure must have a session warehouse set.

Asynchronous callbacks¶

Asynchronous callbacks run in the background, after the calling SQL command completes. Asynchronous callbacks do not block the calling SQL command, and errors in asynchronous callbacks are not returned by the calling command.

To ensure that an asynchronous callback has the most current information, the callback signature doesn’t provide state or status information. Instead, the callback should retrieve the most current information using the appropriate SQL commands, such as SHOW CONFIGURATIONS or SHOW SPECIFICATIONS. See the description for each asynchronous callback for more information.

The return value from asynchronous callbacks is ignored.

Permissions¶

The callback procedures listed in this topic are not required to be granted to any application role. The procedure can be internal to the app, and does not need to be runnable by the consumer. The Snowflake Native App Framework triggers the callback.

Specification vs. connection callbacks¶

Both after_specification_change and after_server_connection_change are run when a specification is approved or refused. The differences between the two callbacks are as follows:

• after_specification_change is part of the application specification framework. It is only triggered when the consumer approves or refuses a specification request.

• after_server_connection_change is part of the inter-app communication framework. It is triggered by any operation that directly or indirectly impacts the connection state of application specification, including the following:

  • Approving a specification

  • Refusing an approved specification

  • Dropping an approved specification

  • Dropping the server app

Use after_server_connection_change when your app needs to respond to changes in the connection itself, such as a connection being established, lost, or the server app being deleted. This callback provides better connection tracking because it covers a broader range of events than specification approval alone.

Use after_specification_change when your app only needs to respond to the approval or refusal of a specification request, or when handling application specification types other than CONNECTION.

Configuration callbacks¶

These callbacks are triggered when a configuration changes.

• validate_configuration_change

• before_configuration_change

• after_configuration_change

validate_configuration_change(configuration_name, configuration_value)

{
  "type": "SUCCESS | ERROR",
  "payload":{
      "error_message": "Error message indicating the validation failure"
  }
}

before_configuration_change(configuration_name, configuration_value)

after_configuration_change(configuration_name)

session.sql(f"""
  SHOW CONFIGURATIONS ->>
      SELECT "status", "value"
      FROM $1
      WHERE "name" = '{configuration_name}';
  """);

Connection callbacks¶

These callbacks are triggered when a connection’s status changes.

• after_server_connection_change

• after_client_connection_change

• after_server_version_change

after_server_connection_change(server_name)

session.sql(f"""
  SHOW SPECIFICATIONS ->>
  SELECT "status"
  FROM $1
  WHERE PARSE_JSON("definition"):"SERVER_APPLICATION"::STRING = '{server_name}';
  """);

after_client_connection_change(client_name)

session.sql(f"""
  SHOW GRANTS TO APPLICATION {client_name} ->>
  SELECT "name"
  FROM $1
  WHERE "granted_on" = 'APPLICATION_ROLE'
      AND STARTSWITH("name", CURRENT_DATABASE())
  """);

after_server_version_change(server_name)

session.sql(f"""
  SHOW APPLICATIONS ->>
  SELECT "version", "patch"
  FROM $1
  WHERE "name" = {server_name}
  """);

Specification callbacks¶

The callback is triggered when a specification of any type has a status change

• after_specification_change

after_specification_change(spec_name)

session.sql(f"""
  SHOW SPECIFICATIONS ->>
      SELECT "status"
      FROM $1
      WHERE "name" = '{spec_name}';
  """);