RelationalAI Native App Upgrades#

RelationalAI (RAI) Native Applications receive automatic upgrades with each new RAI release. Subscribe to the release notes to be notified when new versions are available. RAI schemas are automatically upgraded with the application, but additional steps are required to fully upgrade any existing RAI engines.

IMPORTANT

To upgrade the RAI Native App, your Snowflake user must have the app_admin application role.

Step 1: Start Upgrading Engines#

During the upgrade process, CDC streams are temporarily suspended and all existing RAI engines are deleted and recreated. No RAI transactions may be processed while the upgrade is in progress.

Open a Snowflake SQL worksheet and query the app.engines view to see if any engines are running:

#SELECT * FROM relationalai.api.engines;

If the result is empty, you don’t need to upgrade engines and may skip to Step 3. Otherwise, run the following command to start upgrading your engines:

#CALL relationalai.app.upgrade();

Step 2: Finalize Engine Upgrade#

Use the app.upgrade_status view to check the status of the upgrade:

#SELECT * FROM relationalai.app.upgrade_status;

The view has the following columns:

Column Name	Description
`NA_VERSION`	The current version of your RAI Native App.
`ATTEMPT`	The attempt number of the upgrade. `NULL` if no upgrades have been attempted.
`STATE`	The current state of the upgrade. `DONE` when the upgrade is complete.
`ENGINE_COUNT`	The number of engines that have been upgraded.
`STARTED_AT`	The timestamp when the upgrade started.
`LAST_UPDATE`	The timestamp of the last update to the upgrade status.

Once the STATE column shows DONE, call app.finalize_upgrade() to complete the upgrade and resume CDC:

#CALL relationalai.app.finalize_upgrade();

A message indicating the success or failure of the upgrade is returned. If the upgrade fails, repeat Step 1 to attempt the upgrade again. You can view the error message for the failure in the app.upgrade_status_details view’s MESSAGE column:

#SELECT * FROM relationalai.app.upgrade_status_details;

Step 3: Upgrade RAI Libraries (Optional)#

RAI libraries provide the core functionality for RAI engines to execute queries. They are stored in RAI schemas and must be manually updated if the upgrade includes library updates.

To update libraries, query the app.schemas view to get the names of all RAI schemas and then update each of them using the app.update_libraries procedure:

#-- Get the names of all RAI schemas.
SELECT * FROM relationalai.api.schemas;

-- Updating libraries requires an engine.
-- If necessary, you may create a new engine using the following command:
CALL relationalai.app.create_engine('<engine_name>', 'HIGHMEM_X64_S');

-- Run the following command once for each schema to update its libraries:
CALL relationalai.app.update_libraries('<schema_name>', '<engine_name>');

-- After updating all schemas, you may delete the engine if it is no longer needed.
CALL relationalai.app.delete_engine('<engine_name>');

Step 4: Upgrade the RelationalAI Python Package (Optional)#

Users of the relationalai Python package should upgrade the package after RAI Native App upgrades to ensure compatibility and to access new features.

To upgrade the package:

Activate your project’s virtual environment:

## Linux/macOS
source .venv/bin/activate

 # Windows
 .venv\Scripts\activate

Upgrade pip and the relationalai package:

#python -m pip install --upgrade pip
python -m pip install --upgrade relationalai