Supabase for databases

Use Supabase with Bolt to add a database, authentication, or edge functions to your app as an alternative to Bolt Database.

Projects with Supabase databases published prior to September 30, 2025

Before September 30, 2025, Bolt projects required you to use your own Supabase account for databases. New projects created with Claude Agent after September 30, 2025 use Bolt databases by default. Bolt does not support switching existing projects from Supabase to Bolt Database.

If you have an existing project using Supabase databases:

• Keep using Supabase for your databases.
• You can’t convert a Supabase database into a Bolt database.
• You can switch from v1 Agent (legacy) to Claude Agent at any time. Your Supabase databases will still work. The only change you may notice is that your chat history resets when you switch.

If you are starting a new project:

• Claude Agent creates a Bolt database by default, unless you choose to start your project with Supabase.
• You can migrate a Bolt database to Supabase later if you want.
• Projects created with v1 Agent (legacy) only support Supabase databases. These must be added after the initial build. The v1 Agent (legacy) cannot create Bolt databases.
  The v1 agent is being retired. Starting April 13, 2026, you won’t be able to select v1 Agent (legacy) when starting a project. After August 3, 2026, you won’t be able to access projects that use the v1 agent at all. Make sure to switch to Claude Agent before that date.

New to databases and related terminology?

Databases and their features, such as server functions and authentication, are among the more technical parts of Bolt. If you are just getting started and want a simple introduction to the key concepts, see Introduction to databases.

Overview

By default, new projects created with Claude Agent use Bolt databases, though you also have the option to set Supabase as your default project database from the start.

Projects created before September 30, 2025, used Supabase by default, as explained in the section above.

You can choose to claim Bolt databases created with Claude Agent in Supabase if you want to work there, or continue using Supabase directly to create and manage databases for projects that use Bolt’s v1 Agent (legacy).

If you already know you want to use Supabase, choose it during project creation. Switching from a Bolt database to Supabase later requires extra steps.

Supabase provides:

• A hosted SQL database, which you can connect your application to. You don’t need to worry about managing your database.
• Authentication services, for adding user login and user management to your application.
• Edge functions: Bolt uses these if your application needs to include an API. They’re also used for communicating with other applications, such as Stripe for payment handling.

Explore Supabase’s website and documentation for full details of Supabase’s features.

Supabase connections are available with Vite projects. Next.js projects are not supported at this time.

Connect Bolt to Supabase

To start working with Supabase, you’ll first need to connect Bolt to Supabase. You can do this in your Personal Settings, under Applications.

1. Log in to Bolt and open any project.
2. Click the gear icon in the top center of your screen, then click All project settings.
3. Under Personal Settings, click Applications.
4. In the Supabase row, click Connect.
5. Log in with your Supabase credentials.
6. Follow the steps to authorize Bolt.

Start a project using Supabase

When you create a new project from the Bolt homepage, you can select Supabase as your database during setup.

This feature is available on all paid plans and requires a Supabase application connection. If Supabase is not yet connected to your Bolt account, selecting this option will guide you through the connection process.

For most projects, Bolt database offers the simplest and smoothest experience. It works out of the box, requires no additional setup, and supports most use cases. However, if you already have a Supabase account connected and need more advanced database features or tighter control over your data, choosing Supabase during project creation may be a better fit.

Follow the steps below to get started:

1. Log in and open the Bolt homepage.
2. Click the plus icon.
3. Hover over Database, then click Supabase.

View Supabase data in your Bolt settings

When managing a project with Supabase in Bolt, your Supabase data appears in the database-related Bolt Project Settings.

Click the database icon at the top center of your screen to view general database information. To access settings like Authentication, Server Functions, or Secrets, use the gear icon and select from the menu.

Version history and database restores

Bolt’s Version History feature currently does not support Supabase database restores.

Restoring to an earlier project version will not change your current Supabase databases.

Connect a Supabase database

If you already have a Supabase database you want to use in your Bolt project, or want to create a new one, follow the steps below to connect it.

If your project already has a Bolt database, connecting a Supabase database will replace the connection, which may cause data loss. To keep your existing data, you can claim your current Bolt database in Supabase instead.

1. Make sure you’ve connected Bolt to your Supabase account.
2. Log in to Bolt and open the project with the database you want to claim.
3. Click the Database icon in the top center of your screen.
4. Click the Advanced tab.
5. Click Connect.
6. Select an existing Supabase project or create a new one.
7. Click Connect project.

Claim your Bolt Database in Supabase

Claiming your database lets you migrate an existing Bolt database to Supabase. If you already have a Supabase database and want to connect it to your Bolt project, see Connect a Supabase database instead.

The main reason you may want to claim a Bolt database in Supabase is to access advanced Supabase features. For most use cases, using a Bolt database is simpler and gives you unlimited free databases. However, if you need external management tools, SQL editing, or advanced monitoring, you may need to use Supabase.

To claim your database in Supabase, you must be a Supabase org owner. These permissions are controlled through your Supabase account, not through Bolt. If you’re not the org owner, ask the org owner to claim the database or adjust your permissions.

To migrate your Bolt database and start using Supabase in your project:

1. Make sure you’ve already connected Bolt to your Supabase account.
2. Log in to Bolt and open the project with the database you want to claim.
3. In the top center of your screen, click the Database icon.
4. Click the Advanced tab.
5. Click Claim.
6. Complete additional steps in Supabase.

You should now see your claimed database appear as a Supabase project. If you don’t see the connected database, refresh the Supabase Projects page in your browser.

Use Supabase in a v1 Agent (legacy) Bolt project

Use this section only if your project doesn’t yet have a Bolt database and is working with the v1 Agent (legacy). If your project does have a Bolt database, you must claim the database in Supabase.

To use Supabase in a Bolt project using the v1 Agent (legacy) that does not yet have a database set up, follow the steps below:

1. Make sure you’ve connected Bolt to your Supabase account.
2. Click the gear icon in the top center of your screen, then click Supabase.
3. Choose an existing Supabase project to connect to, or create a new one.
4. Refresh your Bolt project in your browser.

Bolt now uses your connected Supabase project for database operations.

Disconnect Supabase

1. Log in to any project.
2. Click the gear icon in the top center of your screen, then click All project settings.
3. Click Applications under Personal Settings.
4. In the Supabase row, click Disconnect.
5. In Supabase, remove Bolt from your authorized applications:
   1. In the Supabase dashboard, make sure you’re in the organization that you connected to Bolt.
   2. In the left menu, click Organization settings.
   3. Go to the OAuth Apps tab.
   4. Next to Bolt, click Delete.

Using authentication

If you tell Bolt to add authentication with Supabase, users will be able to sign up for your application and log in using Supabase’s user management service.

To use authentication:

1. Make sure you’ve connected your Supabase account.
2. Prompt Bolt to add authentication with Supabase, including adding a signup and login screen to your application.

After your app is working, you can confirm users are being added correctly in Supabase:

1. In your app, go through the signup process.
2. Supabase should send you an email to confirm your email address.
3. In Supabase, open your project.
4. In the left navigation menu, select Authentication.
5. Check the Users list to confirm that the user you just created was added there.

Using edge functions

Edge functions in Bolt rely on databases. Before you begin, make sure you’ve connected your Supabase account.

To get started, prompt Bolt to create the edge function you are interested in. For example: Create an edge function to handle a conversation with an AI Bot (OpenAI). From here, Bolt generates the edge function.

Edge functions can be complex, as they connect up services and involve authentication steps. For help with common errors, see Integrations issues | Supabase edge functions.

FAQs and troubleshooting

My database isn't showing in the Select your database dialog

If a claimed database doesn’t appear in the Select your database dialog when you click Connect, try disconnecting and reconnecting Supabase in Settings > Applications. This should restore the project list.

Bolt doesn't connect to my Supabase database when I prompt it to

The most common reasons Bolt cannot connect to Supabase are that your Bolt account is not connected to Supabase or that your Bolt database has not been claimed in Supabase.

Can I switch from Supabase to Bolt database?

There’s currently no supported flow for migrating Supabase databases to Bolt databases.