Manage the Semarchy xDM Native App

This page provides SQL commands for monitoring, operating, and maintaining the Semarchy Native App on Snowflake.

The Native App supports two repository modes:

Embedded repository (PostgreSQL container managed within Snowflake)
External repository (existing PostgreSQL database)

Repository-related commands on this page apply only to the embedded repository mode.

For more information on repository modes, see Install:snowflake/deploy-in-snowflake.adoc#select_the_repository_mode.

The README file available in the Native App settings provides usage examples for each procedure.

Initial setup and verification

Install the Native App

To install the Native App from the Snowflake Marketplace, run:

CREATE APPLICATION <native_app_name> FROM APPLICATION PACKAGE <app_package_name>;

Verify installation status

To verify that the Native App services are running, run:

CALL <native_app_name>.xdm_public.service_status();

In embedded repository mode, both the xDM application container and the repository container should report a READY status.

Configure parameters

To update Native App configuration parameters, run:

CALL <native_app_name>.xdm_public.reload_app(<params>);

The <params> argument is a JSON object (VARIANT) containing configuration keys used to update the Native App configuration. These keys are grouped into two categories:

Application configuration parameters, which control how the Native App runs.
Repository connection parameters, which define how the Native App connects to the repository in external repository mode.

Application configuration parameters

Key

Description

vol_size^*

The size (in GB) of the block storage volume for the repository container (default: 5).

vol_iops^*

The maximum input/output operations per second (IOPS) supported for the repository storage (default: 3000).

vol_throu^*

The peak throughput (in MiB/s) supported for the repository storage (default: 125).

catalina_opts

Additional JVM options for the Semarchy application container.

cors_allow_origin

The allowed origins for the UI endpoint. Required to enable CORS.

cors_allow_methods

The allowed HTTP methods for CORS.

cors_allow_headers

The allowed request headers for CORS.

cors_expose_headers

The response headers exposed to the browser.

^* Storage-related parameters apply only to the embedded repository mode and are ignored when using an external repository.

Repository connection parameters

Key

Description

repository_url

The JDBC URL of the external repository. If null is provided, the previously saved value is retained. Cannot be cleared once set.

repository_username

The PostgreSQL user for the repository. Stored as a Snowflake Secret. If not provided, the previously saved value is retained. Can be cleared by passing null.

repository_password

The password for the repository user. Stored as a Snowflake Secret. If not provided, the previously saved value is retained. Can be cleared by passing null.

repository_ro_username

The PostgreSQL read-only user. Stored as a Snowflake Secret. If not provided, the previously saved value is retained. Can be cleared by passing null.

repository_ro_password

The password for the read-only user. Stored as a Snowflake Secret. If not provided, the previously saved value is retained. Can be cleared by passing null.

Parameter behavior

For each key in <params>:

If the key is not provided, the previously saved value is retained.
If the key is provided with a value, the value is updated and saved.
If the key is provided with null, the value is cleared and reset to its default or inactive state.
When constructing the JSON object, OBJECT_CONSTRUCT_KEEP_NULL ensures that keys set to null are preserved and their corresponding values are cleared.

Monitor the Native App

Check service status

To check the status of the Native App services, run:

CALL <native_app_name>.xdm_public.service_status();

View application logs

To display logs from the xDM application container:

CALL <native_app_name>.xdm_public.xdm_server_logs([<number_of_lines>]);

View repository logs

To display logs from the repository container (embedded repository mode only):

CALL <native_app_name>.xdm_public.xdm_repo_logs([<number_of_lines>]);

In external repository mode, repository logs are not available through Native App procedures. Logs must be accessed through the database platform hosting the external repository.

Backup and restore

Repository backup and restore operations are available only in embedded repository mode.

When using an external repository, backup and recovery must be managed using the capabilities of the database platform hosting the repository.

Create a backup

To create a backup of the embedded repository, run:

CALL <native_app_name>.xdm_public.xdm_repo_backup(<backup_name>);

To ensure the backup operation succeeds, the backup name must follow Snowflake identifier naming rules. It must start with a letter and may contain only letters, numbers, and underscores; spaces, hyphens, and other special characters are not allowed.

For more information, see the official Snowflake documentation.

Restore a backup

To restore a backup of the embedded repository, run:

CALL <native_app_name>.xdm_public.xdm_repo_restore(<backup_name>);

Restoring a backup interrupts the service. The application container is suspended, the volume is restored, and the service is resumed.

Application lifecycle management

Suspend

To temporarily suspend all containers of the Native App, run:

CALL <native_app_name>.xdm_public.suspend_app();

Resume

To resume the Native App containers, run:

CALL <native_app_name>.xdm_public.resume_app();

Resuming the Native App may upgrade the Native App containers to the latest available version.

Reload

To restart the Native App and apply updated configuration parameters, run:

CALL <native_app_name>.xdm_public.reload_app(<params>);

The <params> argument is a JSON object (VARIANT) containing configuration keys. For a list of supported parameters and their behavior, see Configure parameters.

When using reload_app, only the provided parameters are updated; all others retain their previously saved values.

Stop

To stop the Native App and destroy all associated containers and volumes, run:

CALL <native_app_name>.xdm_public.stop_app();

In embedded repository mode, this operation permanently deletes all repository data.
In external repository mode, the external database is not affected.

Native App upgrade

Patch upgrades of the Native App are handled automatically. Configuration parameters are preserved and reapplied during upgrades.

Manual reload

To manually trigger a reload of the Native App (for example, to apply new configuration parameters), run:

CALL <native_app_name>.xdm_public.reload_app(<params>);

For more information about the supported parameters, see Configure parameters.