Retool RPC tutorialBeta
A built-in solution to connect your codebase and call server-side functions in Retool apps.
Retool currently supports JavaScript and Python SDKs.
Reach out to your Retool account manager to access Retool RPC on self-hosted Retool 3.38 Edge versions and earlier.
Retool RPC (Remote Procedure Call) is a fast, secure solution for connecting your own codebase to Retool. You define functions in your backend and then call them from Retool apps using a Retool RPC resource.
Prerequisites
The prerequisites for Retool RPC depend on whether your organization is cloud-hosted or uses a self-hosted deployment.
- Cloud-hosted organizations
- Self-hosted organizations
You must set up a Redis server and connect it to your self-hosted instance before you can set up Retool RPC. The Redis server functions as the messaging queue for handling requests and responses between the instance and agent.
Redis server requirements
Your Redis server must:
- Be accessible by hostname and password.
- Have at least 10GiB memory.
- Be reachable from your Retool instance.
Run redis-cli
on your Retool instance to verify it can connect to the Redis server.
Configure eviction policy
Use redis-cli
and the following command to set the eviction policy to noeviction
.
CONFIG SET maxmemory-policy noeviction
Retool automatically clears data after a short period of time.
Configure environment variables
You must restart your Retool instance whenever you modify environment variables.
Edit docker.env
on your Retool instance and update the following environment variables so it can connect to the Redis server.
Variable | Description |
---|---|
RETOOL_RPC_REDIS_HOST | The Redis server hostname or IP address (e.g., retool.example.com ). |
RETOOL_RPC_REDIS_PORT | The Redis server port (e.g., 6379 ). |
RETOOL_RPC_REDIS_PASSWORD | The password with which to authenticate. |
RETOOL_RPC_REDIS_DB | The database number (e.g., 0 ). |
RETOOL_RPC_REDIS_TLS | Whether TLS should be used (e.g., false ). |
To start using Retool RPC, you need to:
- Create an RPC resource on Retool so Retool apps can communicate with your server.
- Generate an access token to authorize your server so it can communicate with Retool.
- Register a server with Retool's SDK to expose server-side functions to Retool and to handle function calls.
1. Set up Retool RPC
You can register a server with the Retool CLI or set it up yourself with an existing project and the Retool SDK. The CLI option is recommended for initial testing.
- Retool CLI
- Existing project
Node.js is required to use the CLI.
The CLI is the easiest way to get started with Retool RPC. It automatically generates a resource and RPC server for you. You can use it to quickly test out Retool RPC and then migrate to a more permanent solution.
To setup Retool RPC with the CLI, run the following commands in your terminal.
# Log into your Retool organization
npx retool-cli login
# Follow the step by step instructions to create a resource and register a server
npx retool-cli rpc
If you already have a project, you can register a server with Retool's SDK. This is the recommended way to set up Retool RPC for production.
Create an RPC resource
Sign in to your Retool organization and create a Retool RPC resource.
After creating the resource, Retool provides instructions and a code snippet. In the code snippet, resourceId
is already populated for you.
Generate an access token
Create an access token with the RPC scope by navigating to your access tokens page. Save this token somewhere safe since you'll need it to register your server.
Register a server
Copy the code snippet from the resource form instructions into a file that can access your codebase. Be sure to populate all fields (e.g., replace the apiToken
with the token you generated in the previous step) and install relevant dependencies.
If you're a cloud customer and your server is running in a private network, you may need to allow outbound traffic to Retool IP addresses.
Run the file to register your server with Retool. This file serves as the entry point to your codebase and must be running for Retool to communicate with your code.
2. Define server-side functions
After registering your server with Retool, you can interact with your codebase. You need to define functions through your registered server, fill in the implementation, and then call the function from Retool apps.
Be sure to restart your server to pick up any changes to your registered functions.
Retool RPC allows you to customize functions with any number of arguments. Currently supported argument types are: string
, number
, boolean
, json
, and array
. You can also specify whether an argument is required or optional.
// server.js
rpc.register({
name: "randomFunction",
arguments: {
stringInput: {
type: "string",
description: "A required string input",
required: true,
},
numberInput: {
type: "number",
description: "A required number input",
required: true,
},
booleanInput: { type: "boolean", description: "An optional boolean input" },
jsonInput: { type: "json", description: "An optional json input" },
stringArrayInput: {
type: "string",
array: true,
description: "An optional string array input",
},
jsonArrayInput: {
type: "json",
array: true,
description: "An optional json array input",
},
},
implementation: async (args, context) => {
console.log(args.stringInput);
console.log(context.userEmail);
// Use parts of your codebase here
},
});
The args
parameter contains the arguments passed in from Retool, and the context
parameter contains information about the user that called the function. Fill in the implementation of the function. Since this server connects to your codebase, you can use your existing infrastructure (ORM frameworks, helper functions, logging, testing, CI/CD, etc.) to enhance the developer experience.
3. Call server-side functions from Retool
After registering server-side functions, you can call them from Retool apps like any other resource. Search for the RPC resource you created and select the function you want to call. Retool automatically generates a form for you to fill in the arguments.
Enter the arguments and click Run to execute the function. Retool automatically checks the argument passed and displays an error if the types don't match or required fields are missing.
4. Configure function permissions
You can configure permissions to control access to exposed functions within your organization. Unlike private APIs that require you to build your own authentication middleware, Retool RPC makes it easy to enforce user or group-level access to functions.
rpc.register({
name: "randomFunctionWithPermissions",
arguments: {
stringInput: { type: "string", description: "A string input" },
},
permissions: {
userEmails: ["hello@world.com"],
groupNames: ["Hello world group"],
},
implementation: async (args, context) => {
return "Hello world!";
},
});
By default, all functions are accessible to all users. If a userEmails
or groupNames
field is specified, only users with the specified email or in the specified group can call the function. If both are provided, users only need to satisfy one condition.
5. Configure schema versioning
Retool RPC supports schema versioning to ensure exposed functions are always up-to-date. If you check Require explicit version
on the resource form, you must increment the version on every server change. This is to ensure non-conflicting changes if multiple people are testing different schemas with the same resource.
const rpc = new RetoolRPC({
apiToken: 'API_TOKEN',
host: 'HOST',
resourceId: 'RESOURCE_ID',
version: '0.0.1', // Increment this on every server change e.g., 0.0.1 -> 0.0.2 -> 0.0.3
})
If left unchecked, Retool uses the last registered server's schema. This is useful for early development where you want to quickly iterate on your functions.
Retool prompts users to refresh their schema if they are running queries against an outdated schema. This can be done by clicking the refresh button on the Schema tab or by refreshing the page.