Skip to content

Go to the docs contents

Read another project’s database

An app reads the database of another project in your organization, read only, through its usual driver. The database’s approvers choose what it reads.

Updated November 21, 2026.

View as Markdown

Read another project’s PostgreSQL database read-only: the database under glass, which you can look at but not write to

You, to your AI: Let the dashboard read the sales warehouse database.

What your agent writes

Your agent writes it in while.yaml, at the root of your app:

while.yaml
apiVersion: while/v1
project: my-app
services:
  - name: web
    port: 3000
databases:
  - from: ventes/main
    access: read

What your app receives

Your app receives these environment variables at every deployment:

VariableWhat it holds
DB_VENTES_MAIN_URLThe address of the database being read (here the main database of the ventes project).
DB_VENTES_MAIN_USERYour app’s PostgreSQL role in that database.
DB_VENTES_MAIN_PASSWORDIts password.

When to use it

Use it when a project needs another one’s data, like a warehouse: it reads its database rather than calling an API, in production only.

How it works

An app reads, read-only, the PostgreSQL database of another project of the organization, with its usual driver and DB_<NAME>_URL. The approvers of the source database approve, and choose what it reads.

What to know

The first deployment that declares the read asks the approvers of the source database for approval. Once approved, each reading app has its PostgreSQL role in that database, exactly with its permissions: the whole database, or the schemas, tables and columns the approvers choose. The source project sees who reads it (explain_access tool).

Only production reads: a preview does not read, because its code is not reviewed. Both projects are in the same organization, which reads 10 databases at most (quota). The read happens on the primary instance of the source database, with 5 connections per app, 30 seconds per query and at most 60 seconds of idle time in a transaction. Removing the read cuts the connection; giving it back requires a new deployment of the reading project, with a fresh password.

The network does not yet reserve the source database’s pooler for the reading apps only: it is their PostgreSQL permissions that separate what each one reads.

Your agent’s MCP tools

Your agent handles it with the deploy_app, plan_deploy and explain_access tools.

Give your AI the message, and it takes care of the rest

Give this to your AI

Read while.sh/agents and help me get started with while.

Copy the message

In 3 minutes, with no sign-up, the tool has its own address. To keep it, create your account.

For a company project, write to the while team: hello@while.sh