RPC Calls

Call custom functions (Stored Procedures / Functions) in a PostgreSQL database via the JS SDK.

💡 Tip: RPC calls are based on the PostgREST protocol and can invoke any custom function created in PostgreSQL.

Initialize SDK

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

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

const db = app.rdb();

Basic Syntax

db.rpc(functionName, params, options);

Parameters

Parameter	Type	Required	Description
functionName	string	Yes	Name of the database function to call
params	object	No	Parameters to pass to the function as key-value pairs
options	object	No	Options configuration

options Parameter Details

Parameter	Type	Required	Description
head	boolean	No	If true, data is not returned, only the count value (must be used with the count option)
count	string	No	Count algorithm, options are "exact", "planned", or "estimated"
get	boolean	No	If true, uses HTTP GET to call the function (only for IMMUTABLE or STABLE read-only functions)

Create Functions

Before calling RPC, you need to create functions in the PostgreSQL database. You can execute SQL to create functions through the DMC database management tool.

-- Create a simple addition function
CREATE OR REPLACE FUNCTION add_numbers(a integer, b integer)
RETURNS integer AS $$
  SELECT a + b;
$$ LANGUAGE sql;

-- Create a function to search articles
CREATE OR REPLACE FUNCTION search_articles(keyword text)
RETURNS SETOF articles AS $$
  SELECT * FROM articles WHERE title ILIKE '%' || keyword || '%';
$$ LANGUAGE sql;

-- Create a statistics function
CREATE OR REPLACE FUNCTION get_article_stats()
RETURNS json AS $$
  SELECT json_build_object(
    'total', COUNT(*),
    'latest', MAX(published_at)
  ) FROM articles;
$$ LANGUAGE sql;

Code Examples

Call with Parameters

// Call the addition function
const { data, error } = await db.rpc("add_numbers", { a: 1, b: 2 });
console.log(data); // 3

Call without Parameters

// Call the statistics function
const { data, error } = await db.rpc("get_article_stats");
console.log(data);
// { total: 15, latest: "2026-04-01T00:00:00Z" }

Call Functions that Return Table Data

When a function returns SETOF <table>, the return value is in array format and supports chaining filters and modifiers.

// Search articles containing a keyword
const { data, error } = await db.rpc("search_articles", {
  keyword: "CloudBase",
});

Filter and Sort Return Results

When a function returns table data, you can use filters and modifiers just like regular queries.

// Search articles, sort by publication time in descending order, limit to 5 results
const { data, error } = await db
  .rpc("search_articles", { keyword: "CloudBase" })
  .select("title, published_at")
  .order("published_at", { ascending: false })
  .limit(5);

Return a Single Record

// Get a single record
const { data, error } = await db
  .rpc("search_articles", { keyword: "CloudBase" })
  .limit(1)
  .single();

Use Filters

// Apply filter conditions to RPC-returned table data
const { data, error } = await db
  .rpc("search_articles", { keyword: "CloudBase" })
  .eq("status", "published")
  .gte("published_at", "2026-01-01");

Use GET Request for Read-Only Functions

For functions marked as IMMUTABLE or STABLE, you can use GET requests for better caching.

// Use GET request to call a read-only function
const { data, error } = await db.rpc(
  "add_numbers",
  { a: 1, b: 2 },
  { get: true }
);

Get Row Count Statistics

// Only get row count, without returning data
const { count, error } = await db.rpc(
  "search_articles",
  { keyword: "CloudBase" },
  { count: "exact", head: true }
);
console.log(count); // Returns the number of matching records

Function Parameter Types

PostgREST supports various PostgreSQL function parameter types:

Parameter Type	Description	JS SDK Example
integer	Integer	{ id: 1 }
text / varchar	Text	{ name: "test" }
boolean	Boolean	{ active: true }
json / jsonb	JSON Object	{ data: { key: "value" } }
integer[]	Integer Array	{ ids: [1, 2, 3] }
text[]	Text Array	{ names: ["a", "b"] }