Skip to content
Pulsabase

Mutations

Pulsabase SDKs offer a comprehensive set of mutation methods, ranging from standard inserts to complex relational graphs and Go-style safe execution.

Insert

Section titled “Insert”

Insert one or multiple records. An array of objects will trigger a batch insert.

await pb.from(User).insert({
  name: 'Jane Doe',
  email: 'jane@example.com',
});

Safe Insert / Safe Update

Section titled “Safe Insert / Safe Update”

Pulsabase provides safeInsert and safeUpdate methods that eliminate the need for try/catch blocks. Similar to Go’s error handling, they return a structured result object. This is especially useful for capturing model validation errors cleanly to display in a UI form.

const result = await pb.from(User).safeInsert({
  name: 'Jane Doe',
  email: 'invalid-email-format' // Will fail built-in validation
});


if (!result.ok) {
  console.log('Validation errors:', result.errors);
  // [{ field: 'email', message: 'Must be a valid email' }]
} else {
  console.log('Success:', result.data);
}

Update

Section titled “Update”

Update records that match the current .where() clause.

await pb.from(User).where('id', '=', userId).update({ name: 'Jane Smith' });

Delete

Section titled “Delete”

Delete records that match the current .where() clause.

await pb.from(User).where('id', '=', userId).delete();

Upsert

Section titled “Upsert”

Insert a record, or automatically update it if a conflict occurs on specific columns (PostgreSQL ON CONFLICT DO UPDATE).

await pb.from(User).upsert(
  { email: 'jane@example.com', name: 'Jane', login_count: 1 },
  { target: ['email'], action: 'update' }
);

Insert With Relations (Graph Insert)

Section titled “Insert With Relations (Graph Insert)”

Atomic insertion of a parent record and its deeply nested children relationships in a single operation. Pulsabase automatically maps the inserted parent’s ID to the children’s foreign keys.

await pb.from(Topic).insertWith(
  { title: 'New Topic Discussion', user_id: 1 }, // Parent payload
  [
    {
      comments: [ // Key must match the related table name
        { content: 'First!', user_id: 2 },
        { content: 'Second!', user_id: 3 }
      ]
    }
  ]
);

Bulk Update

Section titled “Bulk Update”

Update multiple individual records efficiently using varied queries and data objects in a single database request.

await pb.from(User).bulkUpdate([
  { query: { id: 1 }, data: { status: 'active' } },
  { query: { id: 2 }, data: { status: 'inactive' } },
]);

Bulk Delete

Section titled “Bulk Delete”

Delete multiple records efficiently using varied queries in a single database request.

await pb.from(User).bulkDelete([
  { query: { id: 1 } },
  { query: { id: 2 } },
  { query: { email: { $like: '%@spam.com' } } }
]);