Data & Operations

This section details mutations for data management and operational tasks within Blocklet Server, primarily focusing on creating and managing backups, and migrating data structures. These operations are crucial for data integrity, updates, and disaster recovery.

For queries related to backups and logs, please refer to the Data & Operations Queries documentation.

backupBlocklet

Initiates a backup process for a specified blocklet. The backup can be saved to either the local disk or a configured DID Space. This is an asynchronous operation that starts a backup job in the background.

Parameters

input RequestBackupBlockletInput (required) — The input object for the backupBlocklet mutation.
- appDid string (required) — The DID of the blocklet to be backed up.
- to BackupTo (required) — The destination for the backup. Must be one of spaces or disk.

Returns

Returns a GeneralResponse object indicating the status of the request.

backupBlocklet GeneralResponse — The response object from the mutation.
- code StatusCode — Returns ok if the backup job was successfully initiated.

Example

Backup Blocklet to Disk

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createBackup() {
  try {
    const response = await client.backupBlocklet({
      input: {
        appDid: 'z8iZpA6x8CRsBAbg9s33i1WkGHxGTCYxP81G',
        to: 'disk',
      },
    });
    console.log('Backup initiated:', response.code);
  } catch (error) {
    console.error('Error initiating backup:', error);
  }
}

createBackup();

Example Response

{
  "backupBlocklet": {
    "code": "ok"
  }
}

This example shows how to start a backup process for a specific blocklet, saving the backup to the local disk.

abortBlockletBackup

Aborts an in-progress backup operation for a specific blocklet. This is useful for canceling long-running backups.

Parameters

input RequestAbortBlockletBackupInput (required) — The input object for the abortBlockletBackup mutation.
- appPid string (required) — The process ID (which is the blocklet DID) of the blocklet whose backup should be aborted.

Returns

Returns a GeneralResponse object indicating the status of the request.

abortBlockletBackup GeneralResponse — The response object from the mutation.
- code StatusCode — Returns ok if the backup abortion was successfully requested.

Example

Abort Backup

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function cancelBackup(blockletDid) {
  try {
    const response = await client.abortBlockletBackup({
      input: {
        appPid: blockletDid,
      },
    });
    console.log('Backup cancellation requested:', response.code);
  } catch (error) {
    console.error('Error aborting backup:', error);
  }
}

cancelBackup('z8iZpA6x8CRsBAbg9s33i1WkGHxGTCYxP81G');

Example Response

{
  "abortBlockletBackup": {
    "code": "ok"
  }
}

This example demonstrates how to cancel a running backup for a given blocklet.

restoreBlocklet

Restores a blocklet from a backup. The source of the backup can be either the local disk or a DID Space. This operation will overwrite the existing blocklet data if it exists.

Parameters

input RequestRestoreBlockletInput (required) — The input object for the restoreBlocklet mutation.
- appDid string (required) — The DID of the blocklet to restore.
- appPid string (required) — The process ID (DID) of the blocklet being restored.
- from BackupTo (required) — The source of the backup. Must be one of spaces or disk.
- endpoint string — The backup endpoint URL. Required when restoring from spaces.
- delegation string — Optional. Delegation information for accessing the backup.
- password Bytes — Optional. Password for decrypting the backup, if it's encrypted.
- wallet any — Optional. The wallet object for authentication if required.

Returns

Returns a GeneralResponse object indicating the status of the request.

restoreBlocklet GeneralResponse — The response object from the mutation.
- code StatusCode — Returns ok if the restore job was successfully initiated.

Example

Restore from Disk

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function restoreFromBackup() {
  try {
    const response = await client.restoreBlocklet({
      input: {
        appDid: 'z8iZpA6x8CRsBAbg9s33i1WkGHxGTCYxP81G',
        appPid: 'z8iZpA6x8CRsBAbg9s33i1WkGHxGTCYxP81G',
        from: 'disk',
      },
    });
    console.log('Restore initiated:', response.code);
  } catch (error) {
    console.error('Error initiating restore:', error);
  }
}

restoreFromBackup();

Example Response

{
  "restoreBlocklet": {
    "code": "ok"
  }
}

This example shows how to start a restore process for a blocklet from a local disk backup.

migrateApplicationToStructV2

Migrates an application from an older data structure to the V2 structure. This is a one-time operation typically required for older blocklets to support newer features like componentization and enhanced backup/restore capabilities.

Parameters

input RequestMigrateApplicationToStructV2Input (required) — The input object for the migration mutation.
- did string (required) — The DID of the application to migrate.
- appSk string (required) — The secret key of the application.

Returns

Returns a GeneralResponse object indicating the status of the request.

migrateApplicationToStructV2 GeneralResponse — The response object from the mutation.
- code StatusCode — Returns ok if the migration was successful.

Example

Migrate Application

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function migrateApp(appDid, appSecretKey) {
  try {
    const response = await client.migrateApplicationToStructV2({
      input: {
        did: appDid,
        appSk: appSecretKey,
      },
    });
    console.log('Migration successful:', response.code);
  } catch (error) {
    console.error('Error migrating application:', error);
  }
}

migrateApp('z8iZpA6x8CRsBAbg9s33i1WkGHxGTCYxP81G', 'your_app_secret_key');

Example Response

{
  "migrateApplicationToStructV2": {
    "code": "ok"
  }
}

This example shows how to trigger the data structure migration for an older application.