Skip to main content
Percher is still being built and account creation is paused — get notified when it opens.
Percher

Connect an external database

Keep Supabase, Convex, or another compatible provider

Ask your agent
Connect this Percher app to my existing database provider. Check the connection method, configure the environment variables without exposing secrets to the browser, and verify reads, writes, and user access rules after publishing.Read the guide at percher.app/docs/external-databases
How it works, with exact details

Keep your existing database, or choose a provider for features your app needs. Percher hosts the app; your provider manages the database, backups, and billing. Setting a data mode does not create a database, move records, or change your app's code.

Starting fresh? PocketBase combines records, sign-in, and files. A static site may not need a database.

Choose your provider

Supabase

Create or select a project in Supabase. Add its URL and public anon key to percher.toml:

[data]
mode = "supabase"

[data.supabase]
url = "https://your-project.supabase.co"
anon_key = "YOUR_PUBLIC_ANON_KEY"

Percher supplies SUPABASE_URL, SUPABASE_ANON_KEY, VITE_SUPABASE_URL, and VITE_SUPABASE_ANON_KEY. Make sure your app reads those names. For Next.js browser code, set your own NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY in Percher's environment editor.

Use only a public client key here, never a service-role or secret key. Configure row-level security and sign-in in Supabase. Keep Supabase or migrate to PocketBase.

Convex

Create or select a Convex deployment. Deploy your Convex functions with Convex's tools, then add the deployment URL to percher.toml:

[data]
mode = "convex"

[data.convex]
deployment_url = "https://your-project.convex.cloud"

Percher supplies CONVEX_URL and VITE_CONVEX_URL. Set NEXT_PUBLIC_CONVEX_URL yourself if your Next.js client expects it. Configure authentication and redirects for your app's final public URL. Publishing to Percher does not deploy the functions in convex/.

Keep Convex or migrate to PocketBase.

Other providers

Choose a provider with a compatible HTTPS API, install its SDK in your app, and set:

[data]
mode = "external"

In the app's Settings, add the URL and keys under Environment variables using the names your code reads. Keep secret keys server-side. Or import a private, gitignored file:

bunx percher env set --from-env-file .env.database

mode = "none" also leaves connections under your control. Neither mode provisions a database or injects a connection URL.

Check the connection method

Server-side traffic uses Percher's HTTPS proxy on port 443. A normal Postgres connection on port 5432 or MySQL connection on 3306 will not work through it. Use your provider's HTTPS data API or a compatible driver. Browser requests go directly to the provider. See environment variables and outbound connections.

Publish and verify

bunx percher env list
bunx percher publish
  • Public-prefixed variables such as VITE_* and NEXT_PUBLIC_* are visible to visitors. Never use them for secrets. Custom Dockerfiles need matching ARG declarations for build-time values.
  • Publish again after changing environment variables. Test a write and read from the deployed app.
  • Verify private data is inaccessible when signed out and to a different user. Check authentication redirects use the final app URL.
  • Use a separate provider project for preview data where needed. Percher's PocketBase browser and backups do not manage external records.