Update or create data

Initialize SDK

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
env: "your-env-id", // Replace this value with your environment ID
});

const db = app.rdb();

// Or specify an instance and a database
// const db = app.rdb({
//   instance: "<instance>",
//   database: "<database>"
// });

Update or create data

Use the upsert() method to perform an update or insert operation. Insert if the record does not exist, update if it exists.

db.from(tableName).upsert(values, options)

• tableName: Table Name
• values: Data to upsert
• options: upsert option configuration

Parameter description

Parameter	Type	Required	Description
values	object | Array	Yes	Values to upsert. Transmit an object to upsert a single row, or transmit an array to upsert multi-row.
options	object	No	upsert option configuration

options parameter description

Parameter	Type	Required	Description
count	string	No	Algorithm used to calculate the upserted row count: "exact" - the underlying layer executes COUNT(*)
ignoreDuplicates	boolean	No	If true, skip duplicate rows. If false, merge duplicate rows with existing rows
onConflict	string	No	Comma-separated unique index column used to specify how to confirm duplicate rows. When all specified columns are equal, two rows are deemed as duplicates. In MySQL, this normally corresponds to a unique index or primary key

Sample Code

Upsert Data

// If the articles table contains a record with id 1, update the title to "MySQL tutorial"; if not found, insert a new record
const { data, error } = await db
  .from("articles")
.upsert({ id: 1, title: "MySQL tutorial" });

console.log('Upsert result:', data);

Batch Upsert Data

Batch upsert multiple records: set the title of the record with id 1 to "MySQL tutorial" and set the title of the record with id 2 to "Redis guide".
const { data, error } = await db.from("articles").upsert([
{ id: 1, title: "MySQL tutorial" },
{ id: 2, title: "Redis guide" },
]);

console.log('Batch Upsert result:', data);

Specify conflict columns

// Check for conflict based on the title field. If a record with the title "unique title" exists, update it. Otherwise, insert a new record with id 42.
const { data, error } = await db
  .from("articles")
  .upsert(
{ id: 42, title: "unique title", content: "article content" },
    { onConflict: "title" }
  );

console.log('Specify conflict column Upsert result:', data);

Returned result

{
    data: [
        {
            id: 1,
title: "MySQL Tutorial"
content: "Article content"
        }
    ],
    error: null
}

💡 Note: The upsert() operation must contain a primary key column to correctly determine whether to insert a new row or update an existing one. In MySQL, upsert is usually implemented using the ON DUPLICATE KEY UPDATE syntax. When the inserted data conflicts with an existing primary key or unique index, an update is performed. The onConflict parameter is used to specify the column for conflict detection, corresponding to the unique index column in MySQL.