# Use Postgres from your laptop

> Open psql, get a connection URI for any client, and run the environment locally with pier dev

URL: https://pier.run/docs/guides/use-postgres-locally

**Goal.** Connect to `main` from your machine (an interactive shell, a GUI client, or an
application running locally) without storing a password in a file.

### psql

```bash
pier psql main
```

Runs the local `psql` against the instance's default database with a credential minted
for your session; the credential is valid for one hour, after which `pier psql` mints a new
one. `psql` must be on `PATH`; the command reports it if it is not. `--db <name>` selects
another database inside the instance; arguments after `--` are passed to `psql`:

```bash
pier psql main -- -c 'select version()'
```

```text title="output"
→  Connecting as cli_admin_e9187807 (role: pier_admin, expires 15:32 UTC)
                                                          version                                                           
----------------------------------------------------------------------------------------------------------------------------
 PostgreSQL 17.9 (Debian 17.9-1.pgdg11+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit
(1 row)


```

### Any other client

```bash
pier pg credentials main
```

```text title="output"
Host      4b5nx4s2r4a.pg.pier.run
Port      5432
Database  app
Username  app_1b4350c5
Password  …
SSL Mode  require
URI       postgresql://app_1b4350c5:…@4b5nx4s2r4a.pg.pier.run:5432/app?sslmode=require

```

`--uri` prints only the connection string, for piping into a client or an environment
variable:

```bash
export DATABASE_URL="$(pier pg credentials main --uri)"
```

The hostname is the instance's public endpoint, over TLS. The credential is the same
one-hour credential `pier psql` uses.

### Run the environment locally

```bash
pier dev
```

Starts the environment's apps in docker on your machine with the same variables the
platform injects, so `api` reads a `DATABASE_URL` of the same shape it receives in
production. `pier dev logs`, `pier dev stop` and `pier dev reset` manage the local stack.

## Variations

* **Backups** before a risky change: `pier backups create main`, then `pier backups ls main`.
* **Read-only exploration**: the credential carries your workspace role; a `viewer` can
  read, a `developer` can write.

## See also

[Postgres](/docs/resources/postgres) · [`pier psql`](/docs/cli/reference/psql) ·
[`pier pg`](/docs/cli/reference/pg) · [`pier dev`](/docs/cli/reference/dev)