# pgweb (/docs/databases-and-storage/pgweb)



[pgweb](https://github.com/sosedoff/pgweb) is a web-based PostgreSQL browser. Rock8Cloud ships it as a one-click application so you can read rows, inspect schemas and run SQL against a database that has no public address.

Databases on Rock8Cloud are network-isolated - they only accept connections from services inside the same project. pgweb runs inside the project, so it can reach the database, and you reach pgweb over its own URL.

## Deploy from the Database [#deploy-from-the-database]

1. Open your PostgreSQL service and select the **Browse** tab
2. Click **Deploy pgweb**

Rock8Cloud creates a pgweb service in the same project, links it to the database and generates a login. Once it is running, pgweb opens right inside the **Browse** tab, already signed in. Rock8Cloud passes the login for you, so there is no password prompt. **New tab** opens the same signed-in pgweb in its own browser tab. Each time pgweb is opened it is recorded in the audit log. Opening pgweb, deploying and redeploying it need a role that can modify resources. Click **Deploy pgweb** again from another tab and you get the same service back, not a second copy - as long as that pgweb's `PGWEB_DATABASE_URL` is still linked to this database. A pgweb whose URL was pasted manually or linked to another database is not recognised, and **Deploy pgweb** then creates a new linked one.

If the pgweb deployment fails or is cancelled, the **Browse** tab shows a **Redeploy** button that deploys it again with the default version.

**Manage service** opens the pgweb service itself, where you change its login, redeploy or delete it. pgweb also keeps its own public URL, which asks for the login from the service's **Environment** tab.

## Create a pgweb Service Manually [#create-a-pgweb-service-manually]

Use this when you want to pick the version or the service name yourself.

1. Click **Add Service** in the project that holds the database
2. Select **Application**
3. Choose **pgweb**
4. Pick a version (0.15.0, 0.16.2, or 0.17.0) and keep replicas at 1
5. Copy the generated login password
6. Link `PGWEB_DATABASE_URL` to your PostgreSQL service's **Connection URL**
7. Click **Deploy pgweb**

pgweb comes up on its own public URL and asks for the generated credentials before it loads.

***

## Environment Variables [#environment-variables]

| Variable             | Description                                      | Default            |
| -------------------- | ------------------------------------------------ | ------------------ |
| `PGWEB_DATABASE_URL` | Connection string for the database pgweb browses | *(linked)*         |
| `PGWEB_AUTH_USER`    | Login user                                       | `admin`            |
| `PGWEB_AUTH_PASS`    | Login password                                   | *(auto-generated)* |

All three are ordinary environment variables. Change the user or password in the service's **Environment** tab and pgweb redeploys with the new login.

### Which connection URL to link [#which-connection-url-to-link]

Link the plain **Connection URL**, not the libpq-compatible variant. The libpq variant appends `uselibpqcompat`, a Go-specific flag that pgweb's driver rejects. Linking to the PostgreSQL service selects the right key for you.

The link is live rather than a copy, so rotating the database password does not require re-pasting anything into pgweb.

***

## What You Can Do [#what-you-can-do]

| Tab                           | What it shows                                   |
| ----------------------------- | ----------------------------------------------- |
| **Rows**                      | Table data, with filtering                      |
| **Structure**                 | Columns, types and defaults                     |
| **Indexes** / **Constraints** | Table indexes and constraints                   |
| **Query**                     | A SQL editor, with **Explain Query** for a plan |
| **History**                   | Statements run in this session                  |
| **Activity**                  | What the database is doing right now            |
| **Connection**                | The connection pgweb is using                   |

Result sets export as JSON, CSV or XML.

***

## Scope and Security [#scope-and-security]

* **Locked to one database** - multiple sessions are disabled and the session is pinned to the linked connection, so a signed-in user cannot point pgweb at another host
* **Full write access** - anyone with the login can modify data, so treat the credentials as production access
* **Public URL** - the login is the only thing in front of the database. Use a strong password and rotate it from the **Environment** tab when someone who had it moves on
* **Stop or delete when idle** - a browser you are not using is access nobody is watching. Adding it back takes a couple of minutes

***

## Troubleshooting [#troubleshooting]

### pgweb fails to start or cannot connect [#pgweb-fails-to-start-or-cannot-connect]

* Confirm `PGWEB_DATABASE_URL` is linked to the plain **Connection URL**, not the libpq-compatible one
* Confirm the database is in the same project as the pgweb service
* Check the **Logs** tab on the pgweb service for the driver error

### The browser does not ask for a login [#the-browser-does-not-ask-for-a-login]

* `PGWEB_AUTH_USER` and `PGWEB_AUTH_PASS` must both be set. If either is missing, redeploy with both present

### Sign-in is rejected [#sign-in-is-rejected]

* Check the current values in the **Environment** tab. The password shown on the add-service screen is only generated once, and editing the variable replaces it

***

## Related [#related]

* [PostgreSQL](/docs/databases-and-storage/postgresql) - provision the database pgweb browses
* [Environment Variables](/docs/guides/environment-variables) - link and rotate service variables
* [Service Configuration](/docs/guides/service-configuration) - the **Resources** tab (replicas, CPU / memory) and deploy history