BaseBuddy needs a Postgres database URL so it can run setup checks, inspect tables for mapping, read content, and save edits.

That URL includes a database password. This is not your Supabase login password, and it is not an API key. It is the password for the Postgres database user inside your connection string.

Treat the full database URL as a secret. Security explains what to redact before sharing setup output, screenshots, or logs.

Where the password goes

Supabase connection strings usually look like this:

txtpostgresql://USER:PASSWORD@HOST:PORT/postgres

The database password is the part after the username and before @.

txtpostgresql://postgres:PASSWORD@db.your-project-ref.supabase.co:5432/postgres

The finished URL is saved in .env for local testing or your production host env:

shBASEBUDDY_CONTENT_DATABASE_URL=postgresql://...

If you are still collecting all Supabase values, start with How to connect your Supabase database to BaseBuddy.

Open the Supabase connection dialog

In Supabase, open your project and use the Connect button. Choose the connection mode you want to use, then copy the Postgres connection string.

Supabase often shows [YOUR-PASSWORD] inside the connection string. That is only a placeholder. Replace it with your real database password before pasting the URL into BaseBuddy.

Choose direct or pooler connection

Use the connection string Supabase gives you for your hosting environment.

Do not mix pieces from different connection modes. If you switch from direct to pooler, copy the whole pooler string again because the username, host, and port may change.

If you already know the password

Replace the password placeholder in the copied connection string.

If the password has special characters, URL-encode it before putting it in the URL.

For example:

txtmy@db:password

becomes:

txtmy%40db%3Apassword

If you do not know the password

Supabase usually does not show the existing database password after the project is created. If you do not have it saved, reset it from Database -> Settings.

Before resetting, check what else uses the same password:

• Other apps connected to this Supabase database.
• Background jobs and workers.
• Local .env files.
• Deployment platform env values.
• Data tools such as TablePlus, DBeaver, psql, analytics jobs, or ETL tools.

After you reset the password, every old connection string that used the previous password must be updated. Anything still using the old password can stop connecting.

Update BaseBuddy

Save the finished Postgres URL in env:

shBASEBUDDY_CONTENT_DATABASE_URL=postgresql://...

The database URL is a secret because it contains the password. Do not commit it, paste it into public issues, or include it in screenshots.

Restart BaseBuddy

Rerun checks after changing setup.

For local development:

shpnpm basebuddy doctor

If the database URL is valid and reachable from the machine running BaseBuddy, the database-related setup checks should be ready.

If this check fails, fix the database URL before changing mapping or permissions. A wrong password can make later parts of the app look broken even when they are fine.

Test one mapped table

After setup checks pass, confirm BaseBuddy can use the connection for real work.

1. Open BaseBuddy.
2. Open or create a project.
3. Go to Project Settings -> Content Mapping.
4. Confirm your schemas and tables appear.
5. Open one safe content item.
6. Save one harmless text field.
7. Check the database row and confirm only that field changed.

If setup checks pass but mapping cannot see tables, the password is probably correct, but the database user may not have enough schema or table access. Use How to create a database user on Supabase to review grants.

Common problems

Once the database URL works, continue with First-run setup and BaseBuddy sign-in setup.

Related pages

• Configuration
• First-run setup
• How to set up BaseBuddy from UI or CLI
• How to fix failed setup checks