# Create your first database

> Create a Postgres database, branch it and change the branch while the source stays the same

> Nevia is in early access for selected teams. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser.
> Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md).

> For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/get-started/first-database

You will create a Postgres database, add a few rows and branch it. The branch
is a full copy of the data with its own connection string, so you can change
it while the source keeps running.

## Prerequisites

You need:

* The `nevia` CLI, [installed and signed in](https://nevia.cloud/docs/get-started/install-cli.md).
* A selected workspace where you have the **admin** or **editor** role, with
  the names `orders` and `orders-staging` free.
* The `psql` Postgres client.

To install `psql`:

```bash
# macOS
brew install libpq && brew link --force libpq

# Debian / Ubuntu
sudo apt install postgresql-client
```

## 1. Create a database

Version, size and storage take platform defaults, so the command needs only a
name:

```bash
nevia pg new orders
nevia pg ls
```

`orders` should be ready, with no pending transition. If creation is still
running, run `nevia pg ls` again.

## 2. Add a table and some rows

`nevia pg connect orders --uri` prints the `postgres://` URI. Pass it to
`psql` with a table, four rows and a count:

```bash
psql "$(nevia pg connect orders --uri)" <<'SQL'
CREATE TABLE IF NOT EXISTS pings (id serial PRIMARY KEY, note text);
INSERT INTO pings (note) VALUES
  ('csv-note-one'), ('csv-note-two'), ('baseline-a'), ('baseline-b');
SELECT count(*) FROM pings;
SQL
```

The count is 4. The URI reaches the database directly over TLS. If the
connection fails, see [Create and connect to a database](https://nevia.cloud/docs/databases/create.md).

## 3. Branch the database

```bash
nevia pg branch orders -b orders-staging
nevia pg status orders-staging
```

Wait until `orders-staging` is ready, with no pending transition. It starts
with the same four rows and its own password. Change the branch only:

```bash
psql "$(nevia pg connect orders-staging --uri)" <<'SQL'
INSERT INTO pings (note) VALUES ('branch-mutation');
UPDATE pings SET note = 'baseline-a (edited in branch)' WHERE note = 'baseline-a';
SQL
```

`psql` prints `INSERT 0 1` and `UPDATE 1`.

## 4. Compare the two

Run the same query against both databases:

```bash
for db in orders orders-staging; do
  psql "$(nevia pg connect "$db" --uri)" -c \
    "SELECT count(*), array_agg(note ORDER BY id) FROM pings;"
done
```

The source still has 4 rows. The branch has 5, with the new `branch-mutation`
row and `baseline-a` rewritten.

## 5. Clean up

Delete the branch and its data first, then the source:

```bash
nevia pg rm orders-staging --yes
nevia pg rm orders --yes
nevia pg ls
```

Neither database should appear in the list. If deletion is still running, run
`nevia pg ls` again.

## Next steps

* [Create and connect to a database](https://nevia.cloud/docs/databases/create.md) covers connection details and password resets.
* [Branch a database](https://nevia.cloud/docs/databases/branch.md) covers what a branch copies and what it needs.
* [Sleep, wake and delete a database](https://nevia.cloud/docs/databases/lifecycle.md) covers lifecycle actions and protection.
* [Create your first computer](https://nevia.cloud/docs/get-started/first-computer.md) serves a page from a computer and branches it.
