Support/How to connect your content database to BaseBuddy

How to connect your content database to BaseBuddy

Add the Postgres URL and optional Supabase storage credentials BaseBuddy needs before setup checks or mapping content.

BaseBuddy needs one required connection before it can map content: the Postgres database that stores the tables you want to edit.

BaseBuddy setup, users, projects, members, permissions, invites, mappings, and sidebar layout are saved in one app-data backend. The simplest backend is basebuddy-data/basebuddy.config.json. You can also choose Supabase/Postgres app data, where BaseBuddy creates its own basebuddy schema and does not change your content tables.

App data storage options explains when to use the default folder, a separate database, or the same database as your content.

What you need

Collect these values from the database or Supabase project that stores your content:

Value	Required	Where BaseBuddy reads it
Postgres database URL	Yes	`BASEBUDDY_CONTENT_DATABASE_URL`
Supabase project URL	Optional	`BASEBUDDY_SUPABASE_URL`
Supabase publishable key	Optional	`BASEBUDDY_SUPABASE_PUBLISHABLE_KEY`
Supabase server key	Optional	`BASEBUDDY_SUPABASE_SECRET_KEY`

The Postgres URL is required for setup, mapping, reads, and writes. The Supabase values are only needed when you want images or files in BaseBuddy.

Use the browser setup

Start BaseBuddy and open:

texthttp://localhost:8080/onboarding

Set BASEBUDDY_AUTH_SECRET and BASEBUDDY_CONTENT_DATABASE_URL in .env or your production host env. If you selected Supabase/Postgres app data, run the Prepare BaseBuddy data tables commands before creating the owner.

Then enter:

Your owner email, name, and password.
Optional Supabase storage values in env if you want images or files.

When you submit setup, BaseBuddy creates or updates:

textbasebuddy-data/basebuddy.config.json

The file lives inside basebuddy-data/ in the folder where the app runs. For a normal checkout, that is the BaseBuddy repo folder where you run pnpm dev, pnpm build, or pnpm start.

If you selected Supabase/Postgres app data in onboarding, BaseBuddy uses its own basebuddy schema tables instead of writing the local file.

Use the CLI setup

From the BaseBuddy repo root, run:

shpnpm basebuddy setup \
  --owner-email "owner@example.com" \
  --owner-name "Owner" \
  --owner-password "choose-a-strong-password"

For Supabase/Postgres app data, prepare the BaseBuddy app-data tables before setup:

shpnpm basebuddy app-data:migrate
pnpm basebuddy app-data:check

Use pnpm basebuddy app-data:sql if your runtime role cannot create schemas or tables.

Only if you want images or files, set these values too:

shBASEBUDDY_SUPABASE_URL=https://your-project-ref.supabase.co
BASEBUDDY_SUPABASE_PUBLISHABLE_KEY=your-publishable-key
BASEBUDDY_SUPABASE_SECRET_KEY=your-server-key

BaseBuddy does not write those values into app data. The CLI only creates BaseBuddy-owned basebuddy.app_state and basebuddy.audit_events tables when you explicitly choose supabase-same-project or supabase-split-project.

Find the Postgres URL

In Supabase, the database URL is usually in Project Settings -> Database or Connect.

The database URL is not the same as the Supabase project URL. It usually starts with:

textpostgresql://

If Supabase asks you to choose between a direct connection and a pooler connection, use the one that works from the machine or host running BaseBuddy. Local development often works with a direct connection. Hosted apps often work better with a pooler.

If you do not know the database password, use How to find or reset your Supabase database password.

Run checks

After setup, run:

shpnpm basebuddy doctor

You can also run:

shpnpm setup:check

The browser setup check verifies the selected app-data backend and can also test content database reachability.

Confirm mapping can see tables

After setup checks pass:

Sign in.
Open Projects.
Create or open a project.
Open Project Settings -> Content Mapping.
Confirm your schemas, tables, and columns appear.

Your tables stay yours. BaseBuddy reads the saved mapping from app data and writes only the mapped fields you change.

Common fixes

Problem	Likely cause	What to do
App data is missing	Setup has not been submitted from UI or CLI	Run onboarding or `pnpm basebuddy setup`
Database check fails	URL, password, host, or network access is wrong	Recopy the connection string and confirm the host can reach the database
Mapping cannot find tables	The URL points at the wrong database or the user lacks access	Check the database user and schema/table permissions
Storage checks fail	Only part of the optional Supabase storage env is set	Set URL, publishable key, and server key together, or remove all three

Keep BaseBuddy app data private because it contains local users, password hashes, sessions, projects, permissions, and saved mappings. Database URLs and service keys belong in env.