# How to connect Bubble to an external database

- Tool: Bubble
- Difficulty: Intermediate
- Time required: 20-25 min
- Compatibility: All Bubble plans
- Last updated: March 2026

## TL;DR

Connect Bubble to external databases like MySQL, PostgreSQL, Airtable, or Supabase via the API Connector plugin. Configure REST API calls to perform CRUD operations against the external database's API endpoints. Use external databases when you need advanced SQL queries, larger data volumes, or shared data across multiple applications while keeping Bubble as the frontend.

## Connect to External Databases from Bubble

This tutorial shows how to connect your Bubble app to external databases when Bubble's built-in database is not sufficient — for SQL queries, large datasets, or multi-app data sharing.

## Before you start

- A Bubble account with the API Connector plugin
- An external database with a REST API (Supabase, Airtable, Xano, etc.)
- API credentials for your external database
- Basic understanding of REST APIs

## Step-by-step guide

### 1. Choose Your External Database

Common options: Supabase (PostgreSQL with REST API), Airtable (spreadsheet-like), Xano (no-code backend), or a custom API server. Each provides REST endpoints for CRUD operations. Supabase is popular because it offers a full PostgreSQL database with auto-generated REST API and good free tier.

**Expected result:** You have selected an external database service and have access to its API.

### 2. Configure the API Connector

In Bubble, go to Plugins → API Connector → Add another API. Name it after your database (e.g., 'Supabase API'). Set authentication: for Supabase, use 'Private key in header' with key 'apikey' and your Supabase anon key. Add another header 'Authorization: Bearer [anon_key]'. For Airtable, use 'Private key in header' with 'Authorization: Bearer [api_key]'.

**Expected result:** API Connector is configured with proper authentication.

### 3. Create Read (GET) Calls

Add a GET call named 'Get Records'. URL: your database's REST endpoint (e.g., https://[project].supabase.co/rest/v1/[table]?select=*). Set 'Use as' to Data. Click Initialize with sample data. Bubble maps the JSON response fields. Use this in Repeating Groups as 'Get data from an external API'.

**Expected result:** You can read external database records in Bubble elements.

### 4. Create Write (POST/PATCH/DELETE) Calls

Add POST, PATCH, and DELETE calls for create, update, and delete operations. POST: URL + body with field values. PATCH: URL + record ID + updated fields. DELETE: URL + record ID. Set 'Use as' to Action for all write operations. Use these in workflows triggered by form submissions or button clicks.

**Expected result:** You can create, update, and delete records in the external database from Bubble.

### 5. Handle Pagination and Filtering

External APIs often paginate responses. Add query parameters for pagination (limit, offset) and filtering (where clauses). For Supabase: ?select=*&limit=20&offset=0&name=eq.value. Make these dynamic parameters in the API Connector so Bubble can pass filter values from the UI.

**Expected result:** You can fetch filtered and paginated data from the external database.

## Complete code example

File: `API Connector payload`

```json
{
  "api_name": "Supabase API",
  "authentication": {
    "type": "Private key in header",
    "headers": [
      {"key": "apikey", "value": "YOUR_SUPABASE_ANON_KEY", "private": true},
      {"key": "Authorization", "value": "Bearer YOUR_SUPABASE_ANON_KEY", "private": true}
    ]
  },
  "calls": [
    {
      "name": "Get Products",
      "method": "GET",
      "url": "https://YOUR_PROJECT.supabase.co/rest/v1/products?select=*&order=created_at.desc&limit=[limit]&offset=[offset]",
      "use_as": "Data"
    },
    {
      "name": "Create Product",
      "method": "POST",
      "url": "https://YOUR_PROJECT.supabase.co/rest/v1/products",
      "use_as": "Action",
      "headers": [{"key": "Content-Type", "value": "application/json"}],
      "body": "{\"name\": \"<name>\", \"price\": <price>}"
    },
    {
      "name": "Update Product",
      "method": "PATCH",
      "url": "https://YOUR_PROJECT.supabase.co/rest/v1/products?id=eq.[product_id]",
      "use_as": "Action"
    },
    {
      "name": "Delete Product",
      "method": "DELETE",
      "url": "https://YOUR_PROJECT.supabase.co/rest/v1/products?id=eq.[product_id]",
      "use_as": "Action"
    }
  ]
}
```

## Common mistakes

- **Exposing API keys in client-safe parameters** — API keys grant access to your external database. Client-safe parameters are visible in the browser. Fix: Always mark API keys and auth tokens as 'Private' in the API Connector.
- **Not handling API latency** — External API calls add latency (100-500ms per call). Multiple calls per page load can make the app feel slow. Fix: Minimize API calls per page, cache frequently accessed data in Bubble's database, and use loading indicators.
- **Not handling API errors gracefully** — External APIs can return errors, timeouts, or rate limits that crash workflows. Fix: Enable 'Include errors in response' and add error handling logic in your workflows.

## Best practices

- Mark all API credentials as Private in the API Connector.
- Cache frequently accessed external data in Bubble's database to reduce API calls.
- Handle pagination for large datasets — never assume all data fits in one response.
- Add error handling for API timeouts and rate limits.
- Use the external database for heavy queries and Bubble's database for user-facing data.
- Test all API calls in Postman before configuring in Bubble.

## Frequently asked questions

### When should I use an external database instead of Bubble's built-in one?

Use external databases when you need SQL queries, handle millions of records, share data across multiple apps, need specific database features (full-text search, vector storage), or require more control over performance.

### Does using an external database increase latency?

Yes. Each API call adds 100-500ms of latency compared to Bubble's native database. Cache critical data in Bubble's DB to mitigate this.

### Can I use both Bubble's database and an external one?

Yes. Many apps use a hybrid approach: Bubble's DB for user data and app state, external DB for large datasets or shared data.

### Which external database works best with Bubble?

Supabase and Xano are the most popular choices. Supabase offers PostgreSQL with a generous free tier. Xano provides a no-code backend builder. Both have clean REST APIs.

### How do I handle real-time updates from an external database?

Set up webhooks from your external database to trigger Bubble backend workflows when data changes. This keeps Bubble in sync without polling.

### Is it complex to maintain an external database connection?

It adds complexity compared to Bubble's built-in database. For complex integrations, RapidDev can help architect and maintain external database connections.

---

Source: https://www.rapidevelopers.com/bubble-tutorial/connect-to-a-database-in-bubble
© RapidDev — https://www.rapidevelopers.com/bubble-tutorial/connect-to-a-database-in-bubble