By default, both Retool Cloud and Retool On-Premise instances automatically log key user actions, such as query executions and password resets. These logs include the user’s name, the action taken, and the timestamp. To view these, the audit log page (https://{yourdomain}.retool.com/audit) is accessible to customers on the Business plan and above.
Unfortunately, in standard Retool deployments, the default UI for viewing audit logs currently lacks several important features: you can’t download logs extensively, filter by specific parameters passed to API calls, or define custom filters for advanced querying. Giving your engineering or management teams access to these kinds of features can hugely level up their ability to maintain and monitor Retool usage across larger infrastructures.
That's why, in this Retool for Enterprise guide, we’ll walk you through how to gain access to these audit logs to build a more robust, customizable audit trail directly within your Retool environment. We’ll show you how to connect directly to Retool’s internal Audit Trail Events table so you can build your own application around your instance’s logs and make your audit logging more accessible.
Building an Audit Log Explorer for on-prem Retool deployments
In order to create our Audit Explorer application on Retool, it's important to begin with the correct permissions. To start, we will need the POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD environment variables in our deployment configuration to create this application.
Step 1. Create a Read-only database user
For us to access the audit logs, we will need to query Retool’s internal storage Database. To do so, we require a Postgres read-only user with access to the following tables:
- pages
- users
- audit_trail_events
- resources
- resource_folders
To create a user and set a password, you can use the following commands:
CREATE USER <YOUR_READ_ONLY_USER> WITH PASSWORD <YOUR_PASSWORD>;This creates a new user in your Postgres database with the specified username and password. This user has no permissions by default, you’ll define them explicitly.
To assign the required permissions, connect to the Retool storage database and use the following commands:
GRANT CONNECT ON DATABASE `<POSTGRES_DB>` TO <YOUR_READ_ONLY_USER> ;This allows the user to connect to the specified database, but not to see or do anything yet.
GRANT USAGE ON SCHEMA public TO <YOUR_READ_ONLY_USER>;This gives access to the public schema, which is where the relevant Retool tables live. This is required before you can grant table-specific privileges.
Now, you must:
GRANT SELECT ON pages TO <YOUR_READ_ONLY_USER>;
GRANT SELECT ON users TO <YOUR_READ_ONLY_USER>;
GRANT SELECT ON audit_trail_events TO <YOUR_READ_ONLY_USER>;
GRANT SELECT ON resources to <YOUR_READ_ONLY_USER>;
GRANT SELECT ON resource_folders to <YOUR_READ_ONLY_USER>;These commands grant read-only (SELECT) access to the key Retool metadata tables:
• pages: Your Retool apps
• users: User accounts in your Retool instance
• audit_trail_events: Logged user actions (the audit trail itself)
• resources: Configured data sources/APIs
• resource_folders: Groupings of those resources
Step 2. Retool’s internal storage database as a Retool resource.
Since we will be interacting with these audit logs via a Retool app, we also need to configure a Retool resource to access the data in our application canvas.
Start by navigating to the resources page in your instance and click 'Create a new resource'. Since the Retool Storage DB is Postgres, select Postgresql as the resource type and name it “Retool Audit Log”.
Now we can fill out the information for the Retool storage DB user we just configured. The relevant environment variables are:
- Host: POSTGRES_HOST
- Port: POSTGRES_PORT
- Database name: POSTGRES_DB
- Database username: <read_only_user>
- Database password: <your_password>
Save the resource, and it should be available for you to use inside of your applications.
Step 3. Create your Audit Log Application
Congrats! From here on out you can query the audit_trail_events retool table via SQL inside your Retool applications. You can also connect it to your services outside of Retool. From here, you can use this data to build your own custom audit trail app to monitor your teams' Retool use.
