database.build Documentation

database.build is an in-browser Postgres sandbox that provides AI assistance. It allows users to instantly spin up unlimited Postgres databases that run directly in the browser using PGlite, a WASM version of Postgres. Data is persisted in IndexedDB, ensuring changes remain after a page refresh.

Key features include:

• Drag-and-drop CSV import with automatic table generation.
• AI-powered report generation and export.
• AI-powered chart generation.
• Database diagram building.

The application provides an in-browser Postgres sandbox using PGlite. The architecture relies on two distinct database instances stored locally in the browser via IndexedDB:

1. Meta DB: Tracks user databases and message history.
2. User DB: A dedicated instance for each database created by the user, containing their specific tables and data.

To prevent main thread blocking, every PGlite instance runs within a Web Worker. Note that because data is stored in IndexedDB, databases are not persisted to the cloud and are device-specific.

The database.build repository is organized as a monorepo containing the following core projects:

• Web (./apps/web/): The primary Next.js web application.
• Browser proxy (./apps/browser-proxy/): Proxies Postgres TCP connections back to the browser using pg-gateway and Web Sockets.
• Deploy worker (./apps/deploy-worker/): Handles deployment of in-browser databases to external platforms (currently supporting Supabase).

The Certificate function's cron job requires two specific secrets to be stored in Supabase Vault:

1. supabase_url: The Supabase API URL.
2. supabase_functions_certificate_secret: A shared secret used to authorize the trigger of the 'certificate' Supabase Edge Function.

select vault.create_secret('<supabase_url>', 'supabase_url', 'Supabase API URL');
select vault.create_secret(encode(gen_random_bytes(24), 'base64'), 'supabase_functions_certificate_secret', 'Shared secret to trigger the "certificate" Supabase Edge Function');

To start the development environment, run the following command from the monorepo root. This uses turbo to manage dependencies and automatically build required packages in ./packages/* before building the applications in ./apps/*.

Note: If you bypass turbo, you must manually build each package in ./packages/* before the applications in ./apps/* can function.

npm run dev

Authentication is used to prevent LLM abuse by validating users via GitHub. User management and authentication are handled by a Supabase database.

Configuration and migrations for the authentication layer are located in the root ./supabase directory of the monorepo.

The Certificate function manages SSL certificates delivered by Let's Encrypt, which are stored in Supabase Storage under the tls/<domain> directory. It automatically renews certificates when they are within 30 days of expiration.

To set up this function, you must ensure the following PostgreSQL extensions are enabled:

• pg_cron
• pg_net
• vault

To run the Browser Proxy locally, configure your environment variables by copying .env.example to .env. You must set the correct environment variables as specified in the example file.

Once configured, run the dev server from the monorepo root. When running, the proxy will listen on the following ports:

• 5432 (Postgres TCP)
• 443 (Web Sockets)

This setup enables communication between a PGlite instance in the browser and a standard PostgreSQL client.

To set up the deploy-worker for local development:

1. Create a .env file by copying the .env.example file in the package directory.
2. Populate the .env file with the required environment variables.
3. Start the development server from the monorepo root.

The deploy worker listens on port 4000 via HTTP.

To deploy the Browser Proxy, create a new application on Fly.io (e.g., database-build-browser-proxy). Ensure you populate the application's secrets with the environment variables defined in the .env.example file before deploying.

fly deploy --app database-build-browser-proxy

Use pg_cron to schedule a weekly task (e.g., every Sunday at 00:00) that calls the Certificate Edge Function via net.http_post. The request must include the domainName in the JSON body and use the supabase_functions_certificate_secret for Bearer authentication.

select cron.schedule (
  'certificates',
  -- every Sunday at 00:00
  '0 0 * * 0',
  $$
  -- certificate for the browser proxy
  select net.http_post(
    url:=(select supabase_url() || '/functions/v1/certificate'),
    headers:=('{"Content-Type": "application/json", "Authorization": "Bearer ' || (select supabase_functions_certificate_secret()) || '"}')::jsonb,
    body:='{"domainName": "browser.db.build"}'::jsonb
  ) as request_id
  $$
);