> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/database.md).

# Database

Store your app's data in MongoDB collections that follow a schema you design, and get a ready API for every collection.

The Database module stores your app's data — orders, products, bookings — in MongoDB collections. You describe each collection once with a **schema**; Norbix then checks every write against it, builds the record form in Cloud, and serves a create, read, update, delete and query API for the collection. The data lives in MongoDB: your own cluster, or a managed Atlas Flex cluster that Norbix runs for you.

## Enable the module

Open a project and choose **Database** in the left menu. While the module is off, Cloud shows this page; press **ENABLE**. You need a project role that can manage modules (for example **Administrator**).

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-1ab9a7bf5f2b98a5551cfb482e65b27689077665%2Fenable-1.png?alt=media" alt="The Norbix Database enable page: Instant database with: Norbix Database, three benefits (Launch your backend in minutes, Store any kind of data, Keep your data safe and yours), an ENABLE button and a Learn more link"><figcaption><p>Database → enable page, shown while the module is off.</p></figcaption></figure>

After **ENABLE**, Cloud opens **Database → Collections**. A new project already has one database integration, **Primary Database**, so you can create a collection at once. To turn the module off again, see [Settings](/codemash/cloud/settings.md) — no data is deleted.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-ab4b02b97d03d9025f24333f49e984f0530bb5cc%2Fenable-2.png?alt=media" alt="Data Collections list right after ENABLE, with the Database menu on the left: Collections, Taxonomies, Aggregates, Integrations, Settings"><figcaption><p>After ENABLE: the Collections screen and the Database menu.</p></figcaption></figure>

## Module map

| Screen                                                 | What it is for                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Collections](/codemash/cloud/database/collections.md) | Your collections: their [schemas](/codemash/cloud/database/collections/create-schema.md), [records](/codemash/cloud/database/collections/records.md), [triggers](/codemash/cloud/database/collections/schema-triggers.md) and [list columns and index warnings](/codemash/cloud/database/collections/schema-indexes.md). |
| [Schema](/codemash/cloud/database/schema.md)           | The schema contract for hand-written and AI-written schemas: the [field types](/codemash/cloud/database/schema/field-types.md) with every keyword and refusal, [references](/codemash/cloud/database/schema/references.md), [nested forms and arrays](/codemash/cloud/database/schema/nesting.md).                       |
| [Taxonomies](/codemash/cloud/database/taxonomies.md)   | Lists of terms (categories, tags, places) that records can point at, in a tree when needed.                                                                                                                                                                                                                              |
| [Aggregates](/codemash/cloud/database/aggregates.md)   | Saved MongoDB aggregation pipelines that your app runs by id.                                                                                                                                                                                                                                                            |
| [Integrations](/codemash/cloud/integrations.md)        | The MongoDB databases your project stores its collections in.                                                                                                                                                                                                                                                            |
| [Settings](/codemash/cloud/settings.md)                | Turn the module off for the project.                                                                                                                                                                                                                                                                                     |

## Your first collection

1. [Check the integration](/codemash/cloud/integrations.md) — a new project has **Primary Database** as the default; [connect your own MongoDB](/codemash/cloud/integrations/providers/mongodb.md) if you want the data in your cluster.
2. [Create a schema](/codemash/cloud/database/collections/create-schema.md) — for example `authors` with a name, a country and a year of birth; press **Save & publish**.
3. [Add a record](/codemash/cloud/database/collections/add-records.md) — open the collection and press **Add New**.
4. [Read it from code](/codemash/cloud/database/collections/records.md#do-it-from-code) — `find` with the SDK, or `norbix api database find` with the CLI.

## Use it from code

Every **Do it from code** block in the Database pages uses this client. Install `@norbix.ai/ts` (see [SDK install](/codemash/sdks/install.md)) and set `NORBIX_API_KEY` to a project API key.

```ts
import { Norbix } from '@norbix.ai/ts';

const projectId = 'pr_4pTPFS01KwV4asdGqlVrIt';
const norbix = new Norbix({ projectId }); // the key comes from NORBIX_API_KEY

const { list } = await norbix.hub.database.getDatabaseSchemas();
console.log(list.items.map((s) => `${s.schemaName} v${s.latestVersion ?? '-'}`));
// [ 'books v1', 'reviews v-', 'authors v2' ]
```

The CLI lines use the generic `norbix hub …` and `norbix api …` commands of `@norbix.ai/cli` (signed in with `norbix login`, project id in `NORBIX_PROJECT_ID`):

```sh
norbix hub database schemas get
```

{% hint style="info" %}
The client sends the project id with every call (the `norbix-project-id` header), so the requests do not repeat it. The CLI does the same with the project of `norbix login --project …`, `norbix config set projectId …` or `NORBIX_PROJECT_ID`. The short commands work too, for example `norbix db find books` and `norbix db count books`.
{% endhint %}

* The **Hub** (`norbix.hub.database`, `norbix hub database …`) manages the module: schemas, taxonomies, triggers, aggregates and integrations. It can also read and write records.
* The **API** (`norbix.api.database`, `norbix api database …`) is what your app calls: records, terms and saved aggregates. It also accepts a signed-in end user's token.
* Every record call can name a `databaseIntegrationId`; without it the default integration of the request's environment is used.

## Related

[Integrations concept](/codemash/cloud/concepts/integrations.md) · [Triggers concept](/codemash/cloud/concepts/triggers.md) · [SDK](/codemash/sdks/database.md) · [CLI](/codemash/cli/reference/db.md) · [API](/codemash/api-reference/database.md) · [What agents can do](/codemash/ai/developers/what-agents-can-do.md)