Everything you need to know to build your first app in Retool

Building internal tools usually means choosing between speed and control. Retool gives you both—an enterprise platform where you generate interfaces with AI, edit visually, and drop into code whenever you need custom logic.

Here, we’ll cover everything you need to know to start building in Retool: setting up databases, building interfaces with AI and drag-and-drop components, writing queries, and connecting to the APIs and databases your team already uses.

To build your first app in Retool, you’ll:

Create a PostgreSQL database using Retool DB
Design your UI with AI and drag-and-drop components
Write SQL and JavaScript queries to connect your data to your interface
Integrate external APIs and databases

Let's dive in.

How do Retool apps work?

Retool apps combine UI components, queries, and data resources to create dynamic internal tools.

Components

Components are elements like tables, forms, and buttons that make up your interface. When users interact with components, their state updates. You reference these values throughout your app using {{ searchInput.value }} or {{ accountTable.selectedRow }}.

Queries

Queries do the actual work in your app: fetching data, calling APIs, transforming results, or updating records. Queries reference component values, and components display query results. When a component value changes, any queries that reference it automatically re-run, making both the authoring and end-user experiences naturally dynamic.

Resources

Resources are saved connections to your data sources, such as databases, REST APIs, Salesforce, Slack, and more. Configure resources properly according to security rules once, then safely use them everywhere.

With those building blocks in mind, the first step is to create a database where your app’s data will live.

Step 1: Set up your first database

Retool Database gives you a PostgreSQL database with a spreadsheet-like interface. It’s a fast, secure way to save and edit data used in Retool apps.

How Retool DB works

Retool DB combines spreadsheet ease with database power. Click into cells to edit data directly, but get real database features: typed columns, primary keys, foreign keys, unique constraints, and environment separation (development, staging, production).

What’s the difference between Retool DB and a spreadsheet?

Unlike spreadsheets, Retool DB enforces data types, prevents duplicates with unique constraints, maintains relationships with foreign keys, and provides schema migration tools. You get spreadsheet convenience with database reliability.

Use Retool DB for app-specific data, prototypes, and operational tables. Mix it with external databases—use Retool DB for application state while connecting to your existing PostgreSQL, MySQL, or MongoDB for source-of-truth data.

Start with AI: Generate your schema with a prompt

The quickest and most common way to set up a database is to describe what you need while prompting to build your app. Just mention you need a database in your prompt—"build a support ticket tracker with a tickets table"—and Retool automatically generates the schema, creates the table structure, and even populates it with sample data so you can start building your UI immediately.

You can refine the schema afterward—add columns, adjust data types, or modify constraints—using either the spreadsheet interface or additional prompts.

Creating tables manually or via CSV import

Navigate to Resources > Retool Database > Create new table. Name your table, then add columns with appropriate types:

id (number, primary key, auto-increment)
name (text, required)
email (text, required, unique)
status (text, default: "active")
created_at (timestamp, default: current timestamp)

Mark fields required, set defaults, and add unique constraints early to keep data clean.

How to upload a CSV to Retool

Click Import CSV, drag your file, and map columns. Rename fields, remove unnecessary columns, and fix types (convert "price" to number). Set your primary key, confirm, and Retool creates the table and loads all rows at once.

Tip: Add 5-10 sample rows even if your real data isn't ready. It makes writing queries and building UI much smoother.

Field types, data validation, and foreign keys

Because Retool DB is PostgreSQL, you get proper database features:

Data types: text, number, boolean, date, timestamp, JSON, array
Nullability: Required or optional fields
Unique constraints: Prevent duplicate emails, SKUs, usernames
Default values: Auto-set status to "pending" or created_at to now
Foreign keys: Link tables (orders.customer_id → customers.id)

These constraints prevent bad data from reaching your app at the database level.

Once your database is ready, you can focus on how users will interact with that data: by designing the interface.

Step 2: Build your user interface (UI)

Once your data is ready, you can start building the interface where users interact with it. Retool lets you start with AI, then refine with drag-and-drop or code.

Start from a prompt

The easiest way to create a new app in Retool is by using a prompt to generate one. Describe what you need—"build a customer dashboard with a table, status filters, and a form to create customers using our customer table in @Retool Database"—and Retool generates the complete UI, connected to your data. Drag components to adjust or add new ones from the library.

Drag-and-drop UI components in the Retool IDE

You can also build from scratch using Retool's library of 100+ components. The Components tab on the left organizes UI components by category. Drag them onto the canvas, and configure them in the Inspector panel on the right.

Components display demo data by default so you can design layouts before connecting queries.

Layout tips: Containers, tabbed containers, forms

Use Containers to group related elements. Put filters in a container so you can move or hide them as a unit. This keeps your layout organized and makes it easy to adjust the positioning of entire sections at once.

Tabbed containers work well for multi-view apps. Use tabs for "Overview," "Details," "History" instead of separate pages. Users stay in context as they switch between views, without losing their place.

Forms are essential for data entry. Add inputs inside a Form component for built-in validation and clean access to values via {{ registrationForm.data }}. When designing forms, align inputs consistently with uniform widths to create a scannable layout.

Working with containers in Retool: Use the Sidebar frame for navigation, Drawer frame for slide-out details, Modal frame for confirmations, and Header frame for persistent branding.

Start simple with your first app: one table to display data, one form to add or edit records. You can always add charts, filters, and sophistication later once the core workflow is proven.

Now that your interface is in place, it’s time to connect it to real data and logic using queries.

Table, chart, and input components

Tables are the workhorse of internal tools. Bind data to {{ getCustomers.data }}, then configure columns: hide IDs, format currency/dates, make columns editable, add action buttons. You can click the filter icon in the table toolbar to set up filter rules, or you can add a Text Input and set the table's "Search term" to {{ searchInput.value }} for quick search-as-you-type functionality.

Charts answer questions at a glance. Bar charts for categories, line charts for trends, pie charts for proportions.

Input components include Text Input, Number Input, Select/Multiselect, Date/Date Range, Checkbox/Switch, and File Input. Use clear labels and defaults.

Customizing themes and appearance

Apply consistent styling with App theme. Set primary color, fonts, border radius, and spacing. Themes apply to all components automatically. When you generate an app with AI, it respects your organization's theme and custom components.

Now that your interface is ready, it’s time to power it with logic. The next section will focus on queries, which handle most app logic. But for more sophisticated ways to implement and execute logic, Retool also offers workflows and agents.

Step 3: Write queries to power your app

In Retool, queries bring your app to life—they fetch data from databases, call APIs, transform results, and write changes back to your systems. Without queries, your UI components are just empty shells.

Retool supports several types of queries depending on what you're trying to accomplish:

SQL queries for reading and writing to databases (SELECT, INSERT, UPDATE, DELETE)
JavaScript queries for data transformations, business logic, and calculations
API queries for calling REST endpoints, GraphQL APIs, or any HTTP service
Integration queries for prebuilt connectors like Salesforce, Slack, or Stripe (these abstract away API complexity)

You'll often combine multiple query types in a single app—fetching data with SQL, transforming it with JavaScript, then sending results to Slack via an integration query. Let's explore how each type works.

SQL queries: SELECT, INSERT, UPDATE via GUI and code

SQL queries are how you read and write data from databases. Retool makes this accessible, whether you're comfortable writing raw SQL or prefer a visual query builder.

Create a query by clicking Code > + New > Resource query. Select a resource (like Retool Database or your PostgreSQL connection), then choose between SQL mode and GUI mode.

SQL mode gives you full control and is ideal for reading data with complex logic:

SELECT id, customer_name, email, subscription_tier

FROM customers

WHERE subscription_tier = {{ tierFilter.value }}

ORDER BY created_at DESC;

The {{ }} syntax is what makes Retool queries dynamic. Any component value can be referenced this way, and Retool automatically tracks dependencies. When tierFilter changes, this query re-runs automatically if you've enabled "Run query when inputs change" in the query settings. This reactive behavior means you don't need to write event handlers to refresh data—Retool handles it for you.

GUI mode is safer for writes (INSERT, UPDATE, DELETE) because Retool generates the SQL for you, reducing the risk of syntax errors and SQL injection. Select your table and action type, then map fields to component values:

Table: customers
Action: Insert
Fields:
customer_name: {{ customerForm.data.nameInput }}
email: {{ customerForm.data.emailInput }}
subscription_tier: {{ customerForm.data.tierSelect }}

SQL vs GUI mode in Retool: Use SQL mode when you need sophisticated joins, subqueries, aggregate functions (like SUM, AVG, COUNT), or custom WHERE clauses with multiple conditions. Use GUI mode for straightforward inserts, updates, and deletes where Retool can safely generate the SQL for you. You can switch between modes anytime—start in GUI mode to get the basics right, then switch to SQL mode if you need advanced logic.

When you use a prompt to build your app, Retool writes SQL queries for you. You will then accept or reject the queries in the Assist tab before Retool continues.

JavaScript queries: transforming and enriching data

When your logic goes beyond what SQL can handle easily, JavaScript queries give you the full power of a programming language. This is where you handle sophisticated data transformations, business logic, and multi-step operations that would be complex or impossible to implement in SQL alone.

Common use cases include:

Transform API responses: Reshape nested JSON into a flat structure that works with table components
Combine multiple data sources: Fetch from two APIs and merge the results based on a common field
Calculate derived fields: Add totals, percentages, formatted display values, or status badges
Implement business logic: Conditional calculations based on multiple factors (e.g., discount tiers, shipping costs, tax rates)

Here's an example that calculates order totals with tax and adds display-friendly fields:

const orders = {{ getOrders.data }};
const taxRate = 0.08;

return orders.map(order => ({
  ...order,
  subtotal: order.quantity * order.unit_price,
  tax: order.quantity * order.unit_price * taxRate,
  total: order.quantity * order.unit_price * (1 + taxRate),
  status_badge: order.status === 'shipped' ? 'success' : 'warning',
  formatted_total: `$${(order.quantity * order.unit_price * (1 + taxRate)).toFixed(2)}`
}));

You can then bind components directly to the query's output: {{ calculateOrderTotals.value }}. The table displays all the original order data, along with your calculated fields, and everything updates automatically when the source data changes.

JavaScript in Retool queries: Retool supports modern JavaScript (ES6+), including arrow functions, destructuring, template literals, spread operators, and async/await for asynchronous operations. Built-in libraries include Lodash (accessible as _) for data manipulation and Moment.js (accessible as moment) for date handling. You can also add external libraries by importing them via CDN URL in your app settings.

Organize queries in Retool: As your app grows beyond a handful of queries, create folders to group related ones. Organize by feature (Orders, Customers, Reports) or by type (API Calls, Transformers, Database Writes). This organization makes queries easier to find and maintain as complexity increases, especially when multiple people work on the same app.

Event handlers: tying UI actions to logic

Event handlers are the glue that connects user interactions to your app's logic. They let you specify what should happen when users click buttons, submit forms, select table rows, or change input values. This is how you make your app interactive, rather than just displaying static data.

Configure event handlers in the Inspector panel when a component is selected. Look for the Events section (or Interaction section in some components) to add handlers for different trigger types.

Common patterns you'll use constantly:

Button click triggers a query:

Component: Button ("Refresh Data")
Event: Click
Action: Control query → getCustomers → Trigger

This pattern works for any action button—refresh, export, submit, delete, etc.

Form submit creates a record:

Component: Form
Event: Submit
Action: Control query → createCustomer → Trigger

Forms have built-in validation that prevents submission until all required fields are filled correctly.

Table row selection loads details:

Component: Table
Event: Row select
Action 1: Control query → getCustomerDetails → Trigger (pass {{ customerData.selectedRow.id }} as a parameter)
Action 2: Control component → drawer1 → Open (show the details in a slide-out panel)

This master-detail pattern is extremely common in internal tools—show a list in a table, let users select a row, then display full details in a drawer or modal.

Success/failure states and notifications

Good internal tools provide users with immediate feedback on whether their actions succeeded or failed. Without this feedback loop, users are left wondering if their button click did anything, if the data saved, or if they need to try again.

Add success and failure handlers to queries—especially write queries—for consistent user feedback. In the query's settings panel, scroll down to find the Event handlers section, where you can configure what happens on success or failure.

On success, show users that everything worked:

Show a success notification with a clear message: "Customer added successfully" or "Order #1234 updated"
Trigger a refresh query to update displayed data with the latest changes
Close a modal or drawer to return users to the main view
Reset a form so it's ready for the next entry
Navigate to a different page (e.g., after creating a record, go to the detail view)

On failure, help users understand what went wrong and how to fix it:

Show an error notification with the actual error message: {{ customerQuery.error }}
Log the error to your monitoring system (Sentry, Datadog, etc.) for debugging
Keep the form open with values intact so users can fix issues and retry
For validation errors, highlight which fields are problematic
For permission errors, show who to contact for access

With your queries and event handlers defined, you can now extend your app to pull from the external systems your team already uses.

Step 4: Connect to your external data sources

Most internal tools need to work with data that already exists in your organization—customer records in Salesforce, tasks in Asana, user data in PostgreSQL, or files in Amazon S3.

Resources are how you Retool accesses that data. They’re reusable connections to databases, APIs, and services you configure once and use across apps.

Navigating the Resources tab

Click Resources to view connections. In most setups, admins create resources. If you can't access Resources, ask your admin.

When prompting, simply @ mention or add them to the Resource access list via the database icon.

Connecting to APIs and databases (e.g., PostgreSQL, Databricks, Snowflake)

Retool's real power comes from connecting to the systems your team already uses. Instead of building yet another data silo, you can pull from existing databases, query APIs, and interact with third-party services—all from a single interface.

Click Create new > Resource to see Retool's full integration library, organized by category:

Databases: PostgreSQL, MySQL, MongoDB, Microsoft SQL Server, Snowflake, BigQuery, Databricks, Amazon Redshift

APIs: REST API (for any HTTP endpoint), GraphQL, OpenAPI (import from Swagger specs)

Retool integrations (prebuilt connectors): Asana, Jira, Notion, Slack, Microsoft Teams, Salesforce, HubSpot, GitHub, Stripe, SendGrid, Google Analytics, Datadog, and dozens more

These prebuilt integrations do the heavy lifting for you—they handle authentication, rate limiting, and API-specific quirks so you can focus on building your app instead of debugging OAuth flows. They act as a clean, trusted guardrail for proper access to enterprise data.

Once a resource is configured, you can use it across every app in your organization. Build a customer support dashboard that pulls from Salesforce, sends Slack notifications from approval workflows, and syncs data to Notion—all without reconfiguring credentials each time.

OAuth vs API Key authentication

Different services use different authentication methods, and understanding when to use each helps you set up resources correctly the first time.

OAuth (used by Salesforce, Google, Microsoft, Slack):

More secure for user-specific actions since tokens are scoped to individual users
Handles token refresh automatically—no manual intervention when tokens expire
Requires a one-time consent flow where you authorize Retool to access the service on your behalf
Tokens are encrypted and stored securely by Retool, never exposed to end users
Best for services where different users need different permissions (e.g., accessing a user's personal Google Drive vs. a shared company Drive)

API Keys (used by many REST APIs, Notion, Stripe):

Simpler to set up—just paste your key into the resource settings, and you're done
Often included in request headers (like Authorization: Bearer sk_live_abc123) or query parameters
Requires manual rotation if keys expire or are compromised
Good for service accounts where all users share the same access level
Less secure than OAuth if keys are long-lived and broadly scoped

Basic Auth (username/password):

Common for older APIs and some database connections
Credentials are encrypted and sent with each request
Simple but less secure than modern alternatives

When setting up a new resource, follow each service's recommended authentication method—it's usually OAuth for SaaS products and API keys for developer-focused APIs. When possible, use OAuth for better security and automatic token management. Also, scope permissions narrowly: if you only need read access to Salesforce Accounts, don't request write permissions to Opportunities. This principle of least privilege reduces risk if credentials are ever compromised.

Using Transformers to clean API data

APIs often return nested objects or unnecessary fields. Use Transformers (JavaScript queries) to reshape data:

const response = {{ getUsersAPI.data }};

return response.data.users.map(user => ({

id: user.id,

name: user.attributes.name,

email: user.attributes.profile.email

}));

Bind tables to the transformer: {{ cleanUserData.value }}. Transformers are useful for filtering, joining data, adding display fields, and handling missing values.

Prompt to clean API responses: "fetch Asana tasks and show only name, assignee, due date."

At this point, you’ve built a complete app: data, interface, logic, and integrations working together. Here’s how to keep going and level up.

What comes next?

Now that you understand the core concepts for building internal tools with Retool, here’s how to continue building your skills and creating more sophisticated apps.

Build your first complete app. The best way to learn is by building something real. Pick a problem your team actually faces and build a tool to solve it.
Exploring templates, community apps, and Retool University. Learn from and be inspired by other Retool builders.
Create a workflow. Automate background tasks like nightly data syncs, scheduled reports, or webhook processing.