Skip to main content

Relational Database (MySQL)

version tip

Since v5.0.0, this module has been added. Accessed via app.mysql, it provides full management capabilities for TCB-hosted MySQL (Serverless CynosDB) databases.

Initialize​

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

const mysql = app.mysql

createMySQL​

1. API Description​

API feature: Activate the MySQL database for the current environment.

API declaration: app.mysql.createMySQL(options?): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
DbInstanceTypeNoStringDatabase type, fixed value MYSQL
MysqlVersionNoStringMySQL version, such as 5.7
VpcIdNoStringVPC ID
SubnetIdNoStringSubnet ID
LowerCaseTableNamesNoStringTable name case sensitivity: 0 (case-sensitive) / 1 (case-insensitive, default)

3. Return Results​

FieldTypeDescription
RequestIdStringUnique identifier of the request
Data.TaskIdStringAsynchronous provisioning task ID

4. Sample Code​

const { Data } = await mysql.createMySQL({ MysqlVersion: '5.7' })
console.log('Provisioning task ID:', Data.TaskId)

describeCreateResult​

1. API Description​

API feature: Query MySQL provisioning status

API declaration: app.mysql.describeCreateResult(options?): Promise<Object>

2. Return Results​

FieldTypeDescription
Data.StatusStringnotexist (Not activated) / success (Activated)
Data.FailReasonStringFailure reason (present when failed)
Data.FreezeStatusBooleanWhether it is frozen

describeClusterDetail​

1. API Description​

API feature: Query MySQL cluster details (database information, network configuration, etc.)

API declaration: app.mysql.describeClusterDetail(): Promise<Object>

2. Return Results​

FieldTypeDescription
Data.DbClusterIdStringCluster ID
Data.DbInfoObjectDatabase status, version, storage, and other information
Data.NetInfoObjectInternal and external IP addresses, VPC, and other network information

destroyMySQL​

1. API Description​

API feature: Destroy the MySQL instance in the current environment.

API declaration: app.mysql.destroyMySQL(): Promise<Object>

2. Return Results​

FieldTypeDescription
Data.IsSuccessBooleanwhether the operation was successful
Data.TaskIdStringTask ID
Data.TaskNameStringTask Name

describeTaskStatus​

1. API Description​

API feature: Query MySQL asynchronous task status

API declaration: app.mysql.describeTaskStatus(options?): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
TaskIdNoStringTask ID

3. Return Results​

FieldTypeDescription
StatusStringTask status, such as SUCCESS / FAILED
StatusDescStringStatus description

runSql​

1. API Description​

API feature: Directly execute SQL statements (SELECT/INSERT/UPDATE/DELETE, etc.)

API declaration: app.mysql.runSql(options): Promise<IRunSqlResult>

2. Input Parameters​

FieldRequiredTypeDescription
SqlRequiredStringSQL statement to be executed
DbInstanceNoObjectDatabase connector instance information
ReadOnlyNoBooleanRead-only mode (only allows SELECT/WITH/SHOW/DESCRIBE/EXPLAIN statements)

3. Return Results​

FieldTypeDescription
ItemsString[]Query result rows (each row is a JSON string)
InfosString[]Column metadata
RowsAffectedNumberNumber of affected rows
RequestIdStringUnique identifier of the request

4. Sample Code​

const res = await mysql.runSql({
  Sql: 'SELECT * FROM users WHERE id = 1'
})
const rows = res.Items.map(item => JSON.parse(item))
console.log(rows)

openWan / closeWan​

1. API Description​

API feature: Enable/disable public network access for instances.

API Declaration:

  • app.mysql.openWan(options?): Promise<Object>
  • app.mysql.closeWan(options?): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
InstanceIdNoStringInstance ID
InstanceGroupIdNoStringInstance Group ID

3. Return Results​

FieldTypeDescription
FlowIdNumberWorkflow ID
RequestIdStringUnique identifier of the request

describeClusterInstanceGroups​

1. API Description​

API feature: Query cluster instance group list (including network information and instance list of each instance group)

API declaration: app.mysql.describeClusterInstanceGroups(): Promise<Object>

2. Return Results​

FieldTypeDescription
TotalCountNumberTotal count of instance groups
InstanceGroupInfoListArrayList of instance groups, each containing Vip/Vport/InstanceSet, etc.

describeInstances​

1. API Description​

API feature: Query the instance list, supporting multi-dimensional filtering

API declaration: app.mysql.describeInstances(options?): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
LimitNoNumberNumber of returned items, default 20, value range (0,100]
OffsetNoNumberOffset, default 0
OrderByNoStringSorting field: CREATETIME / PERIODENDTIME
OrderByTypeNoStringSort order: ASC / DESC
FiltersNoIQueryFilter[]Filter conditions with an AND relationship between them
StatusNoStringInstance status: creating / running / isolating / isolated, etc.
InstanceIdsNoString[]Filter by instance ID list

3. Return Results​

FieldTypeDescription
TotalCountNumberTotal count of instances
InstanceSetArrayList of instance details

describeInstanceDetail​

1. API Description​

API feature: Querying the full details of a single instance

API declaration: app.mysql.describeInstanceDetail(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
InstanceIdYesStringInstance ID

3. Return Results​

Returns a Detail object containing full details of the instance, such as CPU/memory/storage, network, status, version, etc. (see ICynosdbInstanceFullDetail).

restartInstance​

1. API Description​

API feature: Restarting the specified instance

API declaration: app.mysql.restartInstance(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
InstanceIdYesStringInstance ID

3. Return Results​

FieldTypeDescription
FlowIdNumberAsynchronous Workflow ID
RequestIdStringUnique identifier of the request

upgradeInstance​

1. API Description​

API feature: Modify instance specifications (CPU / Memory)

API declaration: app.mysql.upgradeInstance(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
InstanceIdYesStringInstance ID
CpuYesNumberTarget CPU core count
MemoryYesNumberTarget memory (GB)
UpgradeTypeYesStringUpgrade timing: upgradeImmediate (immediate) / upgradeInMaintain (maintenance window)
UpgradeModeNoStringUpgrade mode: NormalUpgrade (normal) / FastUpgrade (fast)

3. Return Results​

FieldTypeDescription
TranIdStringFreeze transaction ID
BigDealIdsString[]big order IDs
DealNamesString[]order IDs

describeInstanceSlowQueries​

1. API Description​

API feature: Querying the slow query logs of an instance

API declaration: app.mysql.describeInstanceSlowQueries(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
InstanceIdYesStringInstance ID
StartTimeNoStringStart Time
EndTimeNoStringEnd Time
LimitOptionalNumberReturned quantity
OffsetNoNumberoffset
UsernameOptionalStringFilter by username
HostOptionalStringFilter by client Host
DatabaseOptionalStringFilter by database name
OrderByNoStringSorting field: QueryTime / LockTime / RowsExamined / RowsSent
OrderByTypeNoStringSort order: asc / desc
SqlTextOptionalStringFilter SQL statements by keywords

3. Return Results​

FieldTypeDescription
TotalCountNumberTotal count
SlowQueriesArrayList of slow query records (including SQL statements, execution time, rows scanned, etc.)

describeInstanceErrorLogs​

1. API Description​

API feature: Querying the error logs of an instance

API declaration: app.mysql.describeInstanceErrorLogs(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
InstanceIdRequiredStringInstance ID
StartTimeNoStringStart Time
EndTimeNoStringEnd Time
LimitOptionalNumberReturned quantity
OffsetNoNumberoffset
OrderByOptionalStringSorting field, supporting Timestamp
OrderByTypeNoStringSort order: ASC / DESC
LogLevelsOptionalString[]Log Level: error / warning / note
KeyWordsOptionalString[]Keywords filtering (fuzzy search)

3. Return Results​

FieldTypeDescription
TotalCountNumberTotal count
ErrorLogsArrayError logs list (containing Content/Level/Timestamp)

describeClusterDatabases​

1. API Description​

API feature: Query database list in the cluster

API declaration: app.mysql.describeClusterDatabases(options?): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
OffsetNoNumberoffset
LimitOptionalNumberReturned quantity

3. Return Results​

FieldTypeDescription
TotalCountNumberTotal count
DatabasesString[]Database name list

describeClusterDatabaseTables​

1. API Description​

API feature: Query table list in the specified database

API declaration: app.mysql.describeClusterDatabaseTables(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
DbYesStringDatabase name
OffsetNoNumberoffset
LimitOptionalNumberNumber of returned items
TableTypeNoStringTable type: view (view) / base_table (base table) / all (all, default)

3. Return Results​

FieldTypeDescription
TotalCountNumberTotal count
TablesString[]List of table names

4. Sample Code​

const { Databases } = await mysql.describeClusterDatabases()
for (const db of Databases) {
  const { Tables } = await mysql.describeClusterDatabaseTables({ Db: db })
  console.log(`${db}: ${Tables.join(', ')}`)
}

createAccounts​

1. API Description​

API feature: Batch create database accounts.

API declaration: app.mysql.createAccounts(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
AccountsRequiredINewAccount[]New account list

INewAccount

FieldRequiredTypeDescription
AccountNameRequiredStringAccount name
AccountPasswordRequiredStringPassword (8-64 characters, including uppercase letters, lowercase letters, digits, and symbols)
HostRequiredStringAllowed host (IP or %)
DescriptionNoStringAccount description
MaxUserConnectionsNoNumberMaximum connection limit

deleteAccounts​

1. API Description​

API feature: Batch delete database accounts

API declaration: app.mysql.deleteAccounts(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
AccountsOptionalIInputAccount[]List of accounts to be deleted ({ AccountName, Host? })

describeAccounts​

1. API Description​

API feature: Query database account list

API declaration: app.mysql.describeAccounts(options?): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
AccountNamesOptionalString[]Filter by account name
HostsOptionalString[]Filter by Host
LimitOptionalNumberReturned quantity
OffsetOptionalNumberOffset
AccountRegularOptionalStringFuzzy match keywords (supports regular expressions)

3. Return Results​

FieldTypeDescription
TotalCountNumberTotal count of accounts
AccountSetArrayAccount information list (including AccountName/Host/CreateTime, etc.)

describeAccountPrivileges​

1. API Description​

API feature: Query account permissions on specified databases/tables

API declaration: app.mysql.describeAccountPrivileges(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
AccountNameRequiredStringAccount name
HostRequiredStringHost
DbRequiredStringDatabase name, * indicates global privileges
TypeRequiredStringObject type: table (table level) / * (database/global level)
TableNameNoStringTable name (Required when Type='table')

3. Return Results​

FieldTypeDescription
PrivilegesString[]Permission list

describeAccountAllGrantPrivileges​

1. API Description​

API feature: Query all granted permissions for the account (global, database, table)

API declaration: app.mysql.describeAccountAllGrantPrivileges(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
AccountRequiredIInputAccount{ AccountName, Host? }

3. Return Results​

FieldTypeDescription
PrivilegeStatementsString[]Privilege statements
GlobalPrivilegesString[]Global privileges list
DatabasePrivilegesArrayDatabase privileges
TablePrivilegesArrayTable privileges

modifyAccountPrivileges​

1. API Description​

API feature: Modify account permissions

API declaration: app.mysql.modifyAccountPrivileges(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
AccountRequiredIInputAccountAccount information
GlobalPrivilegesOptionalString[]Global privileges list
DatabasePrivilegesOptionalArrayDatabase-level privileges
TablePrivilegesOptionalArrayTable-level privileges

modifyAccountDescription​

API declaration: app.mysql.modifyAccountDescription(options): Promise<Object>

Modify account description information. Parameters: AccountName (Required), Description (Required), Host (Optional).

modifyAccountHost​

API declaration: app.mysql.modifyAccountHost(options): Promise<Object>

Modify the Host allowed for account access. Parameters: Account (IInputAccount, Required), NewHost (New Host, Required).

modifyAccountParams​

API declaration: app.mysql.modifyAccountParams(options): Promise<Object>

Modify account configuration parameters. Parameters: Account (Required), AccountParams (IAccountParamItem[], Required, each item contains ParamName and ParamValue).

resetAccountPassword​

1. API Description​

API feature: Reset account password

API declaration: app.mysql.resetAccountPassword(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
AccountNameRequiredStringAccount name
AccountPasswordRequiredStringNew password
HostOptionalStringHost, default %

createBackup​

1. API Description​

API feature: Manually create database backups.

API declaration: app.mysql.createBackup(options?): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
BackupTypeOptionalStringBackup type: logic (logical) / snapshot (physical, default)
BackupDatabasesOptionalString[]Databases to back up (only valid for logic type)
BackupTablesOptionalArrayTables to back up (only valid for logic type)
BackupNameOptionalStringBackup remark name

3. Return Results​

FieldTypeDescription
FlowIdNumberBackup Workflow ID

deleteBackup​

1. API Description​

API feature: Delete backup files

API declaration: app.mysql.deleteBackup(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
BackupIdsOptionalNumber[]Backup ID list (recommended)
SnapshotIdListOptionalNumber[]Snapshot ID list (legacy, not recommended)

modifyBackupConfig​

1. API Description​

API feature: Modify backup policy configuration (backup time window, retention period, backup frequency)

API declaration: app.mysql.modifyBackupConfig(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
BackupTimeBegNoNumberFull backup start time (seconds, e.g. 0=0:00, 3600=1:00)
BackupTimeEndOptionalNumberFull backup end time
ReserveDurationOptionalNumberBackup retention period (in seconds, e.g., seven days=604800)
BackupFreqOptionalString[]Array of length 7, corresponding to Monday to Sunday, full/increment
BackupTypeOptionalStringBackup type

describeBackupList​

1. API Description​

API feature: Query backup list

API declaration: app.mysql.describeBackupList(options?): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
LimitOptionalNumberNumber of returned items, value range (0,100]
OffsetOptionalNumberOffset
BackupTypeOptionalStringsnapshot (snapshot) / logic (logical)
BackupMethodOptionalStringauto (automatic) / manual (manual)
StartTimeOptionalStringFilter by backup start time
EndTimeOptionalStringFilter by backup end time
BackupNamesOptionalString[]Filter by remark name (fuzzy)

3. Return Results​

FieldTypeDescription
TotalCountNumberTotal count
BackupListArrayList of backup files (including BackupId/BackupType/BackupStatus/StartTime/FinishTime etc.)

describeBackupDownloadUrl​

1. API Description​

API feature: Obtain the download address of backup files

API declaration: app.mysql.describeBackupDownloadUrl(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
BackupIdRequiredNumberBackup ID

3. Return Results​

FieldTypeDescription
DownloadUrlStringBackup download URL

4. Sample Code​

const { BackupList } = await mysql.describeBackupList({ Limit: 5 })
const latest = BackupList[0]
const { DownloadUrl } = await mysql.describeBackupDownloadUrl({ BackupId: latest.BackupId })
console.log('Download URL:', DownloadUrl)

rollBackCluster​

1. API Description​

API feature: Restore the cluster to a specified time point or backup file.

API declaration: app.mysql.rollBackCluster(options): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
RollbackStrategyRequiredStringRollback policy: timeRollback (by point in time) / snapRollback (by backup file)
RollbackIdNoNumberBackup file ID (required when snapRollback)
ExpectTimeNoStringExpected time point (Required when timeRollback)
RollbackDatabasesOptionalArrayList of rollback databases (including OldDatabase / NewDatabase)
RollbackTablesOptionalArrayRollback table list (including Database and Tables)
RollbackModeOptionalStringPoint-in-time rollback mode: full (normal) / db (fast) / table (extreme-speed)

3. Return Results​

FieldTypeDescription
FlowIdNumberRollback Workflow ID
RequestIdStringUnique identifier of the request

4. Sample Code​

// Roll back to a point in time (roll back the users table to a new table users_restore)
const { FlowId } = await mysql.rollBackCluster({
  RollbackStrategy: 'timeRollback',
  ExpectTime: '2025-01-01 12:00:00',
  RollbackTables: [{
    Database: 'mydb',
    Tables: [{ OldTable: 'users', NewTable: 'users_restore' }]
  }],
  RollbackMode: 'table'
})
console.log('Rollback workflow ID:', FlowId)

describeTasks​

1. API Description​

API feature: List MySQL asynchronous tasks

API declaration: app.mysql.describeTasks(options?): Promise<Object>

2. Input Parameters​

FieldRequiredTypeDescription
StartTimeBeginNoStringLower bound of task start time
StartTimeEndNoStringUpper bound of task start time
FiltersNoIQueryFilter[]Filter conditions
LimitOptionalNumberReturned quantity
OffsetNoNumberoffset

3. Return Results​

FieldTypeDescription
TotalCountNumberTotal count
TaskListArrayTask list (including ID/Status/TaskType/StartTime, etc.)