# niv databases

`niv databases` reads and changes a Space's databases from the command line, with your own rights. It's how an agent works with them: a free member's agent reads only. An app that speaks MCP can do the same through [niv mcp](/p/docs/niv-mcp).

A database's rows are encrypted in transit and on the server, not end to end like your notes. Notes you link stay end-to-end encrypted: a row holds only a note's id.

## Which Space

`--space <name or id>`, else the Space this folder syncs, else your only one. A database, a column, a choice and a person go by name or id.

## Read

```
niv databases list
niv databases query Finances --limit 50
niv databases query Finances --where '[{"column":"Status","op":"in","values":["Done"]}]'
```

A read returns 100 rows, or up to 200 with `--limit`. Go on with `--after <next>` until `next` is null. Without `--json` it prints `More: --after 200`.

A filter looks through 20,000 rows at a time, so a read can come back empty with `next` set: that isn't the end. `op` is `in`, `has`, `contains`, `range`, `empty` or `notEmpty`. Don't count rows by reading them: `total` is in the first read.

## Change

```
niv databases insert Finances --cells '{"Name":"Rent","Status":"Done"}'
niv databases update Finances <row id> --cells '{"Amount":12}'
```

Give a choice by its label and a person by their name. Sending a value a cell already holds is no change. Several cells are written one by one: if one is refused, those before it have changed, so read the row again.

**Retrying:** pass `--row-id` with your own id, a UUID. The same id sent again is the same row, so a lost answer can't make two.

## Change many rows

```
niv databases insert Finances --rows-file rows.jsonl
niv databases update Finances --rows-file rows.jsonl
```

The file holds one row a line, as `{"id":"<row id>","cells":{"Name":"Rent"}}`. The key opens once, and niv checks every line and every label before the first write. `id` is what `--row-id` is on `insert`, and it's needed on `update`.

If a row is refused partway, niv says how many went in. On `insert`, with ids in the file, sending the same file again is the same rows.

## Make

```
niv databases create "Trips" --title-column Destination
niv databases add-column Trips Stage --type select --choices '["Todo","Done"]'
niv databases add-column Trips Cost --type number
niv databases add-column Trips Twice --type formula --formula "Cost * 2"
```

A new database has one column, called Name unless `--title-column` says otherwise. A type is `text`, `number`, `date`, `select`, `multi_select`, `checkbox`, `url`, `person`, `note` or `formula`. `--id`, a UUID, does for these what `--row-id` does for a row. A formula names columns that are already there.

## What niv refuses first

A flag goes with the actions that read it: `--id` with `create` and `add-column`, `--row-id` with `insert`, and so on. Any other is refused before anything is written. So is an id that isn't a lowercase UUID.

## Who it says did it

Every change shows in the database's Activity as an agent's, for you, through niv, and a person can undo it there. Someone typing `niv databases` counts as an agent too. `--agent "<name>"` is the name it shows. If you delete your account, that name goes from the Activity of other people's Spaces within about an hour, longer if a database is unavailable.

## Limits

Reads have limits per person and database: 60 calls a minute and a million rows an hour. Over one, niv says how long to wait.

## Exit codes

These are the ones this command uses; [Exit codes](/p/docs/exit-codes) explains them all.

| Code | Means                                                                                                                                         |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 0    | Done                                                                                                                                          |
| 2    | Niv refused it itself: no such column, a label that isn't a choice, bad JSON, a flag that doesn't go with the action, an id that isn't a UUID |
| 3    | Sign-in or keys: see [Sign in and keys](/p/docs/sign-in-and-keys)                                                                             |
| 5    | Niv can't reach its server                                                                                                                    |
| 6    | The server refused it, with `code` in `--json`: `planRequired`, `invalidValue`, `invalidFormula`, `agentReadLimit`, `rowNotFound`             |

## With `--json`

- `databases`: `databases`, `access`
- `rows`: `database`, `columns`, `people` with a person column, `rows`, `next`, `scanned`, `total` in a first read
- `row`: `database`, `state`, `row`
- `written`: `database`, `state`, `rows`, the number written
- `database`: `id`, `title`, `tableId`, `notice`
- `column`: `database`, `column`

---

Published with [Niv](https://niv.md/) in the Space Docs.
