Skip to main content

Connect to gRPC

You can connect to gRPC services and make them available as a resource in Retool. Once complete, your users can write queries to connect to your gRPC endpoints. Retool only supports unary service methods with gRPC.

Requirements​

All users for Retool organizations on Free or Team plans have global Edit permissions and can add, edit, and remove resources. If your organization manages user permissions for resources, you must be a member of a group with Edit all permissions.

To create a gRPC resource, you need:

  • Your gRPC host and port.
  • The location of your gRPC service definitions.

1. Create a gRPC resource​

Retool can connect to almost any API or database, and has built-in integrations for popular data sources. Sign in to your Retool organization and create a new gRPC resource from the Resources tab.

2. Configure the resource​

Provide the necessary details to configure the resource so Retool can connect to your gRPC endpoints. Not all settings are required but refer to the gRPC documentation to learn what is needed.

General​

These settings configure the name and location of the resource within Retool.

Name​

The name to use for the resource (e.g., gRPC).

Folder​

The folder in which to save the resource.

Description​

A brief description of the resource (e.g., gRPC endpoints).

Credentials​

These settings configure how Retool connects to gRPC.

Host​

The URL or IP address of the gRPC server.

Port​

The port number.

Service definitions​

To specify service definitions, select Import a .proto file from a URL or Connect to gRPC using Server Reflection. On self-hosted Retool, you can also choose Import .proto files from the file system. This setting requires you to mount files to your Retool instance and set an environment variable to point to the volume.

See the gRPC documentation to learn how to use Server Reflection to connect to your endpoints.

After you configure service definitions, the Service name field populates with service names from your definitions.

Import .proto files on self-hosted Retool​

Use the following steps for Docker-based deployments. If you deploy Retool using Helm or Kubernetes, use the respective deployment guides for mounting instructions instead.

  1. On your deployment's host machine, create a protos/ directory and add your .proto files to it.

  2. In your docker-compose.yml file, add the proto folder as a volume in the api, db-connector, and db-ssh-connector containers.

- ./protos:/retool_backend/protos
  1. In docker.env, add the path to your protos directory as an environment variable.
PROTO_DIRECTORY_PATH=/retool_backend/protos

Retool automatically includes the Google proto files and the /retool_backend/protos folder. If your import statements rely on another folder, you can also specify the PROTO_IMPORT_DIRECTORY_PATH environment variable.

PROTO_IMPORT_DIRECTORY_PATH=/retool_backend/proto_dependencies
  1. Restart Retool. You must also restart Retool whenever you update any .proto files.
sudo docker-compose up -d

Authentication​

Choose between Auth0, OAuth, and custom authentication methods to connect to gRPC. See the guide to custom authentication for more detail.

Use SSL/TLS​

Enable this setting to connect over SSL/TLS.

Advanced options​

You can also configure the following advanced settings for gRPC resources.

SettingDescription
Maximum incoming message size (bytes)The maximum size, in bytes, of incoming messages.
Maximum outgoing message size (bytes)The maximum size, in bytes, of outgoing messages.

3. Save the resource​

Click Create resource to complete the setup. You can then click either Create an app to immediately start building a Retool app or Back to resources to return to the list of resources.

Wrap up​

Your gRPC resource is now ready to use. To interact with your gRPC endpoints, select the resource in the query editor. The methods or RPCs for your service are then available in the query. Placeholder JSON is also generated to match the expected request.