---
title: "Read another project's PostgreSQL database: the while.sh docs"
url: https://while.sh/en/docs/building-blocks/read-another-database/
updated: 2026-11-09
---

# 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.

> 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:

```yaml titre="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.