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.

You, to your agent: 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

databases:
  - from: ventes/main
    access: read

What your app receives

Your app receives these environment variables at every deployment:

Variable	What it holds
`DB_VENTES_MAIN_URL`	The address of the database being read (here the main database of the ventes project).
`DB_VENTES_MAIN_USER`	Your app’s PostgreSQL role in that database.
`DB_VENTES_MAIN_PASSWORD`	Its 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.

Read another project’s database