Calling functions via RPC in Supabase - Deep Dive

Overview - Calling functions via RPC

What is it?

Calling functions via RPC means asking a remote server to run a specific function for you and send back the result. Instead of running code on your own computer, you send a request over the internet to a database or service that executes the function. This is useful when you want to perform complex operations close to your data or share logic across different apps.

Why it matters

Without RPC, every app would have to copy and run the same code separately, which can cause mistakes and slow things down. RPC lets you centralize important logic in one place, making apps faster and easier to maintain. It also helps keep data safe by controlling how functions access it.

Where it fits

Before learning RPC, you should understand basic database queries and how client-server communication works. After mastering RPC, you can explore advanced database features like triggers, stored procedures, and API design.

Mental Model

Core Idea

RPC is like sending a letter to a trusted helper who runs a task for you and sends back the answer.

Think of it like...

Imagine you want to bake a cake but don't have an oven. You write a recipe and send it to a friend who has an oven. They bake the cake and send it back to you. You didn't bake it yourself, but you got the cake you wanted.

┌─────────────┐       request       ┌──────────────┐
│ Your Client │ ────────────────▶ │ Remote Server│
└─────────────┘                   │ (runs func)  │
                                 └──────────────┘
                                       ▲
                                       │
                                response with result

Build-Up - 7 Steps

1

Foundation

Understanding Remote Procedure Calls

Concept: Learn what RPC means and how it differs from local function calls.

A local function call runs code inside your own app. RPC means calling a function that lives somewhere else, like a database server. You send a request with the function name and inputs, and the server runs it and sends back the output.

Result

You understand that RPC lets you run code remotely, not just locally.

Knowing the difference between local and remote calls helps you see why RPC is useful for distributed systems.

2

Foundation

Basics of Supabase Functions

Concept: Supabase allows you to create and call database functions remotely using RPC.

Supabase uses PostgreSQL, which supports stored functions. You can write SQL or JavaScript functions inside the database. These functions can be called remotely via RPC to perform operations like calculations or data updates.

Result

You can identify that Supabase functions live inside the database and can be called remotely.

Understanding that functions live in the database clarifies why calling them remotely is efficient and secure.

3

Intermediate

How to Call RPC Functions in Supabase

🤔Before reading on: do you think calling an RPC function requires writing raw SQL or can it be done with simple client methods? Commit to your answer.

Concept: Learn the syntax and method to call RPC functions using Supabase client libraries.

Supabase client libraries provide a method called rpc() to call remote functions. You specify the function name and pass parameters as an object. For example: supabase.rpc('function_name', {param1: value1}). This sends a request to the database to run the function.

Result

You can call any defined database function remotely with simple code.

Knowing the rpc() method simplifies remote function calls and avoids writing complex queries.

4

Intermediate

Passing Parameters and Receiving Results

🤔Before reading on: do you think RPC functions can return complex data like lists or only simple values? Commit to your answer.

Concept: Understand how to send inputs to RPC functions and handle their outputs.

When calling an RPC function, you pass parameters as a JSON object. The function can return simple values, rows, or complex data types. The client receives the result in a structured format, usually JSON, which you can use directly in your app.

Result

You can send inputs and get back useful data from remote functions.

Understanding parameter passing and result handling is key to integrating RPC functions smoothly.

5

Advanced

Security and Permissions with RPC

🤔Before reading on: do you think any user can call any RPC function by default? Commit to your answer.

Concept: Learn how Supabase controls who can call which RPC functions to protect data.

Supabase uses database roles and policies to restrict RPC function access. You can set permissions so only authorized users or roles can execute certain functions. This prevents unauthorized data access or changes through RPC calls.

Result

You can secure your RPC functions to protect sensitive operations.

Knowing how to secure RPC calls prevents common security risks in remote execution.

6

Advanced

Error Handling and Debugging RPC Calls

🤔Before reading on: do you think errors in RPC functions are automatically shown to the client? Commit to your answer.

Concept: Understand how to detect and handle errors when calling RPC functions.

When an RPC function fails, Supabase returns error information in the response. You should check for errors in your client code and handle them gracefully. Debugging involves checking function logic, permissions, and network issues.

Result

You can build robust apps that handle RPC failures properly.

Proper error handling improves user experience and helps maintain system reliability.

7

Expert

Optimizing RPC Functions for Performance

🤔Before reading on: do you think calling many small RPC functions is always better than one big function? Commit to your answer.

Concept: Learn best practices to write efficient RPC functions and reduce latency.

RPC functions run inside the database, so writing efficient SQL and minimizing data transfer is crucial. Combining related operations into one function reduces network calls. Avoid heavy computations in RPC if they slow down the database. Use indexes and caching where possible.

Result

Your RPC functions run faster and scale better under load.

Understanding performance tradeoffs helps you design scalable remote functions.

Under the Hood

When you call an RPC function, the client sends a request over the network to the Supabase backend, which forwards it to the PostgreSQL database. The database executes the stored function with the given parameters inside its engine, accessing data directly. The result is serialized into JSON and sent back through the same path to the client.

Why designed this way?

This design keeps logic close to data, reducing data transfer and improving speed. It also centralizes business rules in the database, making maintenance easier. Using PostgreSQL's native function support leverages a mature, reliable system instead of reinventing execution layers.

Client App
   │
   ▼
Supabase Client Library
   │ rpc('func', params)
   ▼
Supabase Backend
   │
   ▼
PostgreSQL Database
   │ execute stored function
   ▼
Result JSON
   ▲
   │
Back to Client

Myth Busters - 4 Common Misconceptions

Quick: Do you think RPC functions run on the client device? Commit to yes or no.

Common Belief: RPC functions run on the user's device just like local functions.

Reality: RPC functions run remotely on the database server, not on the client device.

Why it matters: Thinking they run locally leads to confusion about performance and security, causing wrong design choices.

Quick: Can any user call any RPC function by default? Commit to yes or no.

Common Belief: All RPC functions are open to all users without restrictions.

Reality: RPC function access is controlled by database roles and policies; unauthorized calls are blocked.

Why it matters: Assuming open access risks exposing sensitive data or operations unintentionally.

Quick: Do you think RPC calls always return simple values? Commit to yes or no.

Common Belief: RPC functions can only return single values like numbers or strings.

Reality: RPC functions can return complex data like tables, JSON objects, or arrays.

Why it matters: Underestimating return types limits how you design and use RPC functions effectively.

Quick: Is it always better to split logic into many small RPC functions? Commit to yes or no.

Common Belief: More small RPC functions improve modularity and performance.

Reality: Too many RPC calls increase network overhead and latency; sometimes fewer bigger functions are better.

Why it matters: Misusing RPC granularity can degrade app performance and user experience.

Expert Zone

1

RPC functions can leverage PostgreSQL's advanced features like window functions and JSON operators for powerful data processing inside the database.

2

Supabase allows defining RPC functions in multiple languages (SQL, PL/pgSQL, JavaScript with extensions), enabling flexible logic placement.

3

Understanding how Supabase handles connection pooling and transaction boundaries affects how RPC functions behave under concurrent loads.

When NOT to use

Avoid using RPC for very simple queries that can be done with direct table access, or for operations requiring complex client-side logic. Instead, use direct queries or client-side processing. Also, do not use RPC for long-running tasks better suited for background jobs or serverless functions.

Production Patterns

In production, RPC functions are used to encapsulate business logic like user authentication checks, data aggregation, and complex updates. Teams version control their SQL functions and use migrations to deploy changes. Monitoring RPC call performance and errors is standard practice.

Connections

API Design

RPC functions act like backend API endpoints for database operations.

Understanding RPC helps grasp how APIs expose functionality remotely, bridging frontend and backend.

Client-Server Architecture

RPC is a core pattern in client-server communication where clients request services from servers.

Knowing RPC deepens understanding of how distributed systems coordinate work across machines.

Distributed Systems

RPC is a fundamental mechanism enabling remote execution in distributed computing.

Recognizing RPC's role clarifies challenges like latency, security, and fault tolerance in distributed systems.

Common Pitfalls

#1 Calling RPC functions without checking user permissions.

Wrong approach:

const { data, error } = await supabase.rpc('sensitive_function', { id: 123 });

Correct approach:

Ensure database policies restrict 'sensitive_function' to authorized roles before calling it.

Root cause:

Assuming RPC functions are secure by default without configuring access controls.

#2 Passing parameters with wrong names or types to RPC functions.

Wrong approach:

await supabase.rpc('calculate_discount', { wrongParam: 50 });

Correct approach:

await supabase.rpc('calculate_discount', { price: 50 });

Root cause:

Not matching parameter names and types expected by the database function.

#3 Ignoring errors returned from RPC calls.

Wrong approach:

const { data } = await supabase.rpc('update_user', { id: 1 }); console.log(data);

Correct approach:

const { data, error } = await supabase.rpc('update_user', { id: 1 }); if (error) handleError(error); else useData(data);

Root cause:

Not handling asynchronous errors leads to silent failures and bugs.

Key Takeaways

Calling functions via RPC lets you run code remotely on a database server, centralizing logic and improving efficiency.

Supabase provides a simple rpc() method to call stored functions with parameters and receive structured results.

Security is critical: RPC function access must be controlled with database roles and policies to protect data.

Proper error handling and performance optimization are essential for building reliable and fast applications using RPC.

Understanding RPC deepens your grasp of client-server communication and distributed system design.

Practice

1. What does supabase.rpc() do in a Supabase app?

easy

A. Creates a new table in the database

B. Uploads files to storage

C. Fetches user authentication details

D. Calls a custom database function remotely

Solution

1. Step 1: Understand the purpose of supabase.rpc()

   This method is designed to call remote procedure calls (RPC), which are custom functions defined in the database.

2. Step 2: Identify what supabase.rpc() does in the app context

   It runs these custom functions securely from the app, allowing logic to stay in the database.

3. Final Answer:

   Calls a custom database function remotely -> Option D

4. Quick Check:

   RPC calls = custom database functions [OK]

Hint: RPC means running database functions remotely [OK]

Common Mistakes:

• Confusing RPC with file uploads
• Thinking it creates tables
• Assuming it handles user login

2. Which is the correct way to call a function named get_user_data with parameter { user_id: 5 } using Supabase RPC?

easy

A. supabase.rpc('get_user_data', { user_id: 5 })

B. supabase.call('get_user_data', 5)

C. supabase.function('get_user_data', { id: 5 })

D. supabase.execute('get_user_data', user_id=5)

Solution

1. Step 1: Recall the syntax of supabase.rpc()

   The method takes the function name as a string and an object with parameters.

2. Step 2: Match the correct syntax with the options

   supabase.rpc('get_user_data', { user_id: 5 }) correctly uses supabase.rpc('function_name', { params }) format.

3. Final Answer:

   supabase.rpc('get_user_data', { user_id: 5 }) -> Option A

4. Quick Check:

   Correct RPC call syntax = supabase.rpc('get_user_data', { user_id: 5 }) [OK]

Hint: Use rpc('function', {params}) format [OK]

Common Mistakes:

• Using wrong method names like call or execute
• Passing parameters as separate arguments
• Using incorrect parameter keys

3. Given this code snippet:

const { data, error } = await supabase.rpc('multiply', { a: 3, b: 4 });
console.log(data);

What will be printed if the multiply function returns the product of a and b?

medium

A. 7

B. 12

C. undefined

D. Error

Solution

1. Step 1: Understand the function call and parameters

   The function multiply is called with a=3 and b=4.

2. Step 2: Calculate the expected return value

   Since the function returns the product, 3 * 4 = 12.

3. Final Answer:

   12 -> Option B

4. Quick Check:

   3 times 4 = 12 [OK]

Hint: Multiply parameters to find output [OK]

Common Mistakes:

• Adding instead of multiplying
• Assuming no return value
• Confusing data with error

4. You wrote this code:

const { data, error } = await supabase.rpc('get_user', { user_id: 10 });
console.log(data);

But you get an error saying the function does not exist. What is the likely cause?

medium

A. Parameters must be passed as an array, not an object

B. You forgot to import supabase client

C. The function name is misspelled or missing in the database

D. RPC calls do not support parameters

Solution

1. Step 1: Analyze the error message

   The error says the function does not exist, indicating a problem with the function name or its presence in the database.

2. Step 2: Check common causes for missing function errors

   Usually, the function is either misspelled or not created in the database schema.

3. Final Answer:

   The function name is misspelled or missing in the database -> Option C

4. Quick Check:

   Function missing error = wrong or absent function [OK]

Hint: Check function spelling and existence in DB [OK]

Common Mistakes:

• Passing parameters incorrectly
• Assuming import errors cause this
• Thinking RPC disallows parameters

5. You want to create a Supabase RPC call to get the total sales for a given store_id. The database function is named total_sales and takes store_id as input. Which code snippet correctly calls this function and handles errors?

hard

A. const { data, error } = await supabase.rpc('total_sales', { store_id }); if (error) console.error(error); else console.log(data);

B. const result = supabase.call('total_sales', store_id); console.log(result);

C. const { data } = await supabase.rpc('total_sales', store_id); console.log(data);

D. const { data, error } = supabase.rpc('total_sales', { store: store_id }); if (error) throw error; else console.log(data);

Solution

1. Step 1: Identify correct RPC call syntax with parameters

   The function name is 'total_sales' and parameters must be passed as an object with key matching the function input, here { store_id }.

2. Step 2: Check error handling and async usage

   const { data, error } = await supabase.rpc('total_sales', { store_id }); if (error) console.error(error); else console.log(data); uses await, destructures data and error, and handles error properly with console.error.

3. Final Answer:

   const { data, error } = await supabase.rpc('total_sales', { store_id }); if (error) console.error(error); else console.log(data); -> Option A

4. Quick Check:

   Correct RPC call with error check = const { data, error } = await supabase.rpc('total_sales', { store_id }); if (error) console.error(error); else console.log(data); [OK]

Hint: Use await, pass params as object, check error [OK]

Common Mistakes:

• Passing parameters incorrectly (not as object)
• Ignoring error handling
• Using wrong method names like call