> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newly.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Backend Systems

> Understanding Liquid Backend and Supabase in Newly

# Backend Systems

Newly supports two backend systems for your app's server-side functionality. This guide helps you understand which one you're using and how each works.

## Which Backend Am I Using?

<Note>
  **Quick Check**: Look at the preview header in your project.

  * **See a "Database" button?** → You're using **Liquid Backend**
  * **No "Database" button?** → You're using **Supabase**
</Note>

<Tip>
  **Liquid Backend will get you further.** It's the recommended backend for most use cases. Supabase is mostly available for users that already have a website set up and are running Supabase there.
</Tip>

***

## Liquid Backend

Liquid Backend is Newly's integrated backend system. It automatically generates APIs and databases from natural language.

### What Liquid Backend Provides

<CardGroup cols={2}>
  <Card title="RESTful APIs" icon="network-wired">
    Automatic API endpoint generation from natural language
  </Card>

  <Card title="PostgreSQL Database" icon="database">
    Fully managed database with automatic schema creation
  </Card>

  <Card title="Authentication" icon="key">
    User registration, login, and session management
  </Card>

  <Card title="File Storage" icon="cloud-arrow-up">
    Upload and serve images and files
  </Card>
</CardGroup>

### When Liquid Backend Is Created

The AI automatically creates backend functionality when you request:

* **User authentication** - Sign up, login, password reset
* **Data persistence** - Saving data across sessions
* **User-specific data** - Data tied to user accounts
* **API integrations** - External services requiring server-side secrets
* **AI features** - ChatGPT or other AI model integrations

### Example Prompts

```text theme={null}
Build me a journaling app, ai integrated with Google and Apple authentication
```

```text theme={null}
Create an AI financial advisor app, where I can chat and ask AI for financial advices on how to spend my money.
```

### Database Viewer

With Liquid Backend, you can view your data directly in Newly:

1. Click the **Database** icon (🗄️) in the preview header
2. Browse tables on the left sidebar
3. View records and their values

This is useful for:

* Verifying data is saving correctly
* Debugging data-related issues
* Understanding the database structure

### Logs Viewer

Liquid Backend includes a **Logs Viewer** in Newly:

1. Click the **Logs** icon in the preview header
2. Switch between "Frontend" and "Backend" tabs
3. View API calls, errors, and debug information

### Environment Variables (Liquid Backend)

For Liquid Backend projects, environment variables are managed through Liquid Backend:

* **Server-side secrets** (API keys, tokens) are stored securely in Liquid Backend
* **Frontend variables** can be added via **More** → **Environment Variables**
* Variables are automatically available to your backend code

<Warning>
  Secret keys (like `OPENAI_API_KEY`) should be stored in Liquid Backend, not exposed to the frontend.
</Warning>

### Production Deployment

When deploying your app with Liquid Backend:

<Steps>
  <Step title="Development">
    During development, you're using a dev environment backend
  </Step>

  <Step title="Push to Production">
    In the Deploy modal, click "Push to Production" for backend
  </Step>

  <Step title="Production URL">
    Your app is automatically configured to use the production API
  </Step>
</Steps>

### Dev and production data

Your project has two separate databases:

* **Dev** — your working sandbox, where you build and test. Test users and sample records you create here live only in dev.
* **Production** — a separate, permanent database that your live app uses.

When you click **Push to Production**, Newly deploys your **code and database structure (schema)** to production. It does **not** copy your dev data across. So a user you registered in dev won't appear in production, and rebuilding or restarting won't change that: the record simply isn't in the production database. This is expected, not a bug.

Production data is permanent. It starts empty and keeps everything created there, including across later deploys. That's by design, so your real users' data stays intact while you keep changing and testing in dev.

To confirm production is saving correctly, sign up or create a record in your **deployed** app, then view it via the **Database** button switched to production.

<Note>
  Deploys move your **code and schema** from dev to production, never your **dev data**. Seed anything your production app needs by creating it in production directly.
</Note>

### After a deploy, your dev database starts empty

A production deploy does two things: it promotes your code and schema to production, and it hands you a **brand-new dev environment** to keep working in. That new dev database has your latest schema and no rows in it.

Nothing was wiped. Your old dev database isn't reset — you're moved onto a fresh one. That's why a test user you registered in dev before a deploy can't log in afterwards: the account lives in the previous dev database, not the new one.

<Note>
  Dev data is disposable by design. Treat anything you create in dev as test data that a deploy will leave behind, and never as something to keep.
</Note>

### Keeping test data across deploys

Rather than re-creating test users by hand after each deploy, have the AI build the sample data into your backend. Ask for it in chat:

> Add a seed script to my backend that inserts sample data into the database — a test user and a few example records. Make it safe to run more than once, run it automatically when the backend starts in development, and also expose it as a dev-only endpoint I can trigger by hand.

A seed script that checks whether a row already exists before inserting it is safe to leave in place permanently: every fresh dev database fills itself the first time your backend boots, so your test login survives every deploy.

<Warning>
  Ask for the seed to run in **development only**. A seed that also runs in production will put fake users and sample records in your live database.
</Warning>

### Why a deploy can look like it started on its own

A production deploy only ever starts when you click **Deploy backend to production** (or run a deploy from the CLI). Two things make it look otherwise:

* **The deploy survives a page refresh.** A merge takes up to about six minutes. While it runs, the button is disabled and reads *Deploying backend…* — so opening the Deploy screen partway through a deploy you started earlier looks like a deploy that began by itself.
* **The new dev environment is provisioned for you.** Once the deploy finishes, Newly creates your replacement dev branch automatically in the background. You may see backend activity for a short while after the deploy itself is done.

If the Deploy screen shows a deploy in flight and you're sure nobody triggered one, contact support with your project link rather than clicking Deploy again.

***

## Comparison Table

| Feature                      | Liquid Backend            | Supabase                                         |
| ---------------------------- | ------------------------- | ------------------------------------------------ |
| **Database Viewer in Newly** | ✅ Yes                     | ⚠️ Project details only (use Dashboard for data) |
| **Backend Logs in Newly**    | ✅ Yes                     | ❌ No (use Dashboard)                             |
| **API Generation**           | Automatic from prompts    | Manual or via AI                                 |
| **Environment Variables**    | Managed in Liquid Backend | OAuth + manual                                   |
| **Authentication**           | Built-in                  | Supabase Auth                                    |
| **Database Access**          | Via generated REST APIs   | Direct client SDK                                |
| **Schema Management**        | AI-generated              | Supabase Dashboard                               |
| **Production Deploy**        | One-click in Newly        | Automatic (Supabase hosted)                      |
| **Realtime**                 | Websockets out of the box | Supabase Realtime                                |

***

## Supabase

Supabase is an open-source Firebase alternative that provides database, authentication, and storage. Some projects use Supabase for specific requirements.

### How Supabase Works

Unlike Liquid Backend which generates APIs automatically, Supabase provides:

1. **Direct Database Access** - Your app connects directly to PostgreSQL
2. **Supabase Client SDK** - Uses `@supabase/supabase-js` for queries
3. **Row Level Security (RLS)** - Security rules defined in Supabase Dashboard
4. **OAuth Integration** - Newly connects to your Supabase project via secure OAuth

### Connecting Supabase

Newly uses OAuth to securely connect to your Supabase project:

<Steps>
  <Step title="Open Supabase Settings">
    Click **More** → **Supabase** in the project menu
  </Step>

  <Step title="Connect via OAuth">
    Click "Connect Supabase" and sign in to your Supabase account
  </Step>

  <Step title="Authorize Access">
    Grant Newly permission to access your Supabase projects
  </Step>

  <Step title="Select Project">
    Choose your Supabase project from the list
  </Step>
</Steps>

<Tip>
  The OAuth connection handles all authentication automatically. No manual API key configuration required.
</Tip>

### Managing Your Supabase Database

The **Database** tab in Newly is relabeled **Supabase** for these projects and shows project details, secrets, and a link to the Supabase Dashboard rather than a table browser. To browse or edit your data, use:

**Supabase Dashboard** - [supabase.com/dashboard](https://supabase.com/dashboard)

* Table Editor for viewing/editing data
* SQL Editor for running queries
* Schema management

### Logs for Supabase

<Warning>
  Supabase backend logs are **not available** in Newly. You must use the Supabase Dashboard.
</Warning>

To view Supabase logs:

1. Go to [supabase.com/dashboard](https://supabase.com/dashboard)
2. Select your project
3. Navigate to **Logs** in the sidebar
4. Choose the log type:
   * **API Logs** - REST API requests
   * **Postgres Logs** - Database queries
   * **Auth Logs** - Authentication events
   * **Edge Function Logs** - Serverless function logs

<Tip>
  For frontend console logs, use the Logs icon in Newly's preview header - these are still available for all projects.
</Tip>

### Environment Variables (Supabase)

Supabase connection is handled automatically via OAuth. The OAuth integration manages your connection securely without requiring manual API key configuration.

For additional environment variables needed by your app, use **More** → **Environment Variables**.

### Supabase Features

| Feature            | How to Use                          |
| ------------------ | ----------------------------------- |
| **Database**       | Supabase Dashboard Table Editor     |
| **Authentication** | Supabase Auth (email, OAuth, phone) |
| **Storage**        | Supabase Storage buckets            |
| **Edge Functions** | Deploy via Supabase CLI             |
| **Realtime**       | Subscribe to database changes       |
| **RLS Policies**   | Define in Supabase Dashboard        |

***

## Migration

<Warning>
  **Migration from Supabase to Liquid Backend is not possible.**
</Warning>

If you need to switch backend systems, you can only migrate **from Liquid Backend to Supabase**, not the other way around.

### When to Consider Migration

In most cases, **Liquid Backend will get you further**. Consider migrating to Supabase only if you specifically need:

* PostgreSQL functions and triggers
* Supabase-specific features (Realtime subscriptions, Edge Functions)
* Integration with existing Supabase infrastructure
* Direct SQL access for complex queries

### Migration from Liquid Backend to Supabase

If you must migrate:

<Steps>
  <Step title="Export Your Data">
    Use the Database Viewer in Newly to review your data, then contact support to assist with data export
  </Step>

  <Step title="Create Supabase Project">
    Set up a new project at supabase.com
  </Step>

  <Step title="Recreate Schema">
    Create your tables in Supabase Dashboard
  </Step>

  <Step title="Import Data">
    Import your data using Supabase's import tools or SQL
  </Step>

  <Step title="Connect via OAuth">
    Follow the OAuth connection steps in Newly
  </Step>

  <Step title="Update App">
    Ask the AI to update your app to use Supabase
  </Step>
</Steps>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="A user I created in dev isn't in production (or 'nothing saves to prod')">
    Dev and production are separate databases. Push to Production deploys your code and schema, not your dev data, so test records created in dev won't appear in production, and rebuilding won't bring them over. Create the record in your deployed (production) app and it will persist. See [Dev and production data](#dev-and-production-data).
  </Accordion>

  <Accordion title="I don't see the Database button">
    Your project uses Supabase, so that tab is labeled **Supabase** instead. Manage your actual data at [supabase.com/dashboard](https://supabase.com/dashboard).
  </Accordion>

  <Accordion title="Backend logs not showing">
    * **Liquid Backend**: Click the Logs icon and select "Backend" tab
    * **Supabase**: Logs are only available in the Supabase Dashboard
  </Accordion>

  <Accordion title="Environment variables not working">
    * **Liquid Backend**: Check Liquid Backend configuration
    * **Supabase**: Connection is managed via OAuth; additional vars in **More** → **Environment Variables**
  </Accordion>

  <Accordion title="API calls failing">
    * **Liquid Backend**: Check backend logs in Newly
    * **Supabase**: Check API logs in Supabase Dashboard
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Supabase Details" icon="database" href="/integrations/supabase">
    Deep dive into Supabase integration
  </Card>

  <Card title="Deployment Guide" icon="rocket" href="/features/deployment">
    Deploy your app to production
  </Card>
</CardGroup>