Database events

The Nexconn Chat SDK reports two distinct database-related events:

1. Database opened — fires inline via the databaseOpenedHandler block when you call connect. Tells you whether the local database opened successfully and whether it was recreated.
2. Database upgrade progress — fires via the NCDatabaseStatusHandler protocol when the SDK upgrades its internal database schema. Register this handler separately before connecting.

---

Database opened callback

The databaseOpenedHandler block is passed directly to connect(params:databaseOpenedHandler:completionHandler:) (Objective-C selector: connectWithParams:databaseOpenedHandler:completionHandler:). It fires before the connection is established, so it is the earliest point at which local data access is safe.

Swift

swift

import NexconnChatSDK

let params = ConnectParams(token: "your-token")
NCEngine.connect(
    params: params,
    databaseOpenedHandler: { isRecreated, error in
        if let error {
            print("Failed to open local database: \(error.localizedDescription)")
            return
        }

        if isRecreated {
            // The local database was recreated; local data has been cleared.
            print("Database recreated. Reload from remote as needed.")
        }
    },
    completionHandler: { userId, error in
        if let error {
            print("Connect failed: \(error.localizedDescription)")
            return
        }
        print("Connected as: \(userId ?? "")")
    }
)

Objective-C

Objective C

NCConnectParams *params = [[NCConnectParams alloc] initWithToken:@"your-token"];

[NCEngine connectWithParams:params
       databaseOpenedHandler:^(BOOL isRecreated, NCError * _Nullable error) {
    if (error == nil) {
        if (isRecreated) {
            // The local database was recreated; local data has been cleared
            NSLog(@"Database recreated. Reload from remote as needed.");
        }
    } else {
        NSLog(@"Failed to open local database: %@", error);
    }
}
        completionHandler:^(NSString *userId, NCError *error) {
    if (error == nil) {
        NSLog(@"Connected as: %@", userId);
    }
}];

Callback parameter	Type	Description
isRecreated	BOOL	YES if the local database was recreated (local data cleared); NO if the existing database was opened normally.
error	NCError *	nil if the database opened successfully; otherwise contains the error details.

---

Database upgrade events

When the SDK needs to upgrade its database schema (for example, after an SDK version update), it fires upgrade lifecycle events. Register an NCDatabaseStatusHandler before connecting to receive these callbacks.

Swift

swift

import NexconnChatSDK

// Register
NCEngine.addDatabaseStatusHandler(identifier: "MyDBHandler", handler: self)

// Remove
NCEngine.removeDatabaseStatusHandler(forIdentifier: "MyDBHandler")

Objective-C

Objective C

// Register
[NCEngine addDatabaseStatusHandlerWithIdentifier:@"MyDBHandler" handler:self];

// Remove
[NCEngine removeDatabaseStatusHandlerForIdentifier:@"MyDBHandler"];

Implement DatabaseStatusHandler (Objective-C protocol name: NCDatabaseStatusHandler):

Swift

swift

import NexconnChatSDK

final class MyAppDelegate: NSObject, DatabaseStatusHandler {
    // The database upgrade is about to begin.
    func onUpgradeWillStart(_ event: DatabaseUpgradeWillStartEvent) {
        // Display a loading indicator or block UI interactions as needed.
        print("Database upgrade starting.")
    }

    // Called repeatedly during upgrade; event.progress is in [0, 100].
    func onUpgrading(_ event: DatabaseUpgradingEvent) {
        print("Database upgrade progress: \(event.progress)%")
    }

    // Called when upgrade finishes; event.error is nil on success.
    func onUpgradeCompleted(_ event: DatabaseUpgradeCompletedEvent) {
        if let error = event.error {
            print("Database upgrade failed: \(error.localizedDescription)")
        } else {
            print("Database upgrade completed successfully.")
        }
    }
}

Objective-C

Objective C

@interface MyAppDelegate () <NCDatabaseStatusHandler>
@end

@implementation MyAppDelegate

// The database upgrade is about to begin
- (void)onUpgradeWillStart:(NCDatabaseUpgradeWillStartEvent *)event {
    // Display a loading indicator or block UI interactions as needed
    NSLog(@"Database upgrade starting.");
}

// Called repeatedly during upgrade; event.progress is in [0, 100]
- (void)onUpgrading:(NCDatabaseUpgradingEvent *)event {
    NSLog(@"Database upgrade progress: %ld%%", (long)event.progress);
}

// Called when upgrade finishes; event.error is nil on success
- (void)onUpgradeCompleted:(NCDatabaseUpgradeCompletedEvent *)event {
    if (event.error == nil) {
        NSLog(@"Database upgrade completed successfully.");
    } else {
        NSLog(@"Database upgrade failed: %@", event.error);
    }
}

@end

NCDatabaseStatusHandler protocol methods

Method	Event type	Description
onUpgradeWillStart:	DatabaseUpgradeWillStartEvent	Called before the database upgrade begins.
onUpgrading:	DatabaseUpgradingEvent	Called repeatedly during the upgrade. Read event.progress (integer in [0, 100]).
onUpgradeCompleted:	DatabaseUpgradeCompletedEvent	Called when the upgrade finishes. Read event.error — nil means success.