Listen for database upgrade status

The SDK provides a database upgrade status handler. When an SDK upgrade involves database schema changes, installing the new SDK version triggers a database migration. The connection state may be unstable during migration, so use this handler to display an upgrade progress indicator and reduce user anxiety.

tip

Database upgrades are triggered automatically by the SDK and do not cause data loss. Upgrade time depends on device performance, database version, and database size, and cannot be estimated in advance.

Register and remove the handler

Register a DatabaseStatusHandler via NCEngine.addDatabaseStatusHandler() before connecting, so that upgrade callbacks are not missed.

Kotlin

kotlin

// Register
NCEngine.addDatabaseStatusHandler("DB_HANDLER_ID", object : DatabaseStatusHandler {

    // The database upgrade is about to begin
    override fun onUpgradeWillStart(event: DatabaseUpgradeWillStartEvent) {
        // Show upgrade UI indicator or block UI interactions
        println("Database upgrade starting.")
    }

    // Called repeatedly during upgrade; event.progress is in [0, 100]
    override fun onUpgrading(event: DatabaseUpgradingEvent) {
        println("Database upgrade progress: ${event.progress}%")
    }

    // Called when upgrade finishes; event.error is null on success
    override fun onUpgradeCompleted(event: DatabaseUpgradeCompletedEvent) {
        if (event.error == null) {
            println("Database upgrade completed successfully.")
        } else {
            println("Database upgrade failed: ${event.error.code}")
        }
    }
})

// Remove the handler when no longer needed
NCEngine.removeDatabaseStatusHandler("DB_HANDLER_ID")

Java

Java

// Register
NCEngine.addDatabaseStatusHandler("DB_HANDLER_ID", new DatabaseStatusHandler() {

    @Override
    public void onUpgradeWillStart(@NonNull DatabaseUpgradeWillStartEvent event) {
        // Show upgrade UI indicator
        System.out.println("Database upgrade starting.");
    }

    @Override
    public void onUpgrading(@NonNull DatabaseUpgradingEvent event) {
        System.out.println("Database upgrade progress: " + event.getProgress() + "%");
    }

    @Override
    public void onUpgradeCompleted(@NonNull DatabaseUpgradeCompletedEvent event) {
        if (event.getError() == null) {
            System.out.println("Database upgrade completed successfully.");
        } else {
            System.out.println("Database upgrade failed: " + event.getError().getCode());
        }
    }
});

// Remove the handler when no longer needed
NCEngine.removeDatabaseStatusHandler("DB_HANDLER_ID");

Callback reference

Method	Event type	Description
onUpgradeWillStart	DatabaseUpgradeWillStartEvent	Called before the upgrade begins. Use this to show a progress UI.
onUpgrading	DatabaseUpgradingEvent	Called repeatedly during the upgrade. Read event.progress (integer in [0, 100]).
onUpgradeCompleted	DatabaseUpgradeCompletedEvent	Called when the upgrade finishes. event.error is null on success.