> 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/collections/edit-schema.md).

# Edit a schema

Change a collection's schema as a draft and publish a new version; change its settings or delete it.

**Where:** Database → Collections → row menu → **Edit schema** · `/projects/<project>/db/schemas/<schemaName>/edit`

## Before you start

* The collection exists — see [Create a schema](/codemash/cloud/database/collections/create-schema.md).
* You need `database:update` on the schema; deleting it needs `database:delete`.
* Records keep working while you edit: changes are a **draft** until you publish a new version, and records always follow the latest *published* version.

## Steps

1. Open **Database → Collections**, open the row menu of the collection and choose **Edit schema**. The builder opens as **Editing authors schema**, with the **Schema id** (`sch_2inwcOhCFWyKgivFGlDIjA`) to copy and the four tabs **Schema**, **List**, **Triggers** and **Settings**.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-823beb8e5b1323c4354f1c834cd7d82bac94f9bc%2Fedit-schema-1.png?alt=media" alt="Editing authors schema: Schema id with a copy button, Schema name authors, the Visual Builder with the tab Author and the fields Name (Required), Country and Born"><figcaption><p>The builder opened on a published schema.</p></figcaption></figure>
2. Change the fields — in **Visual Builder** (drag a field in, the trash icon removes one, the gear icon changes it) or in **JSON** → **Edit JSON**. Example: remove the `website` field of `authors`. Every keyword a field takes is on the [Field type reference](/codemash/cloud/database/schema/field-types.md); a key outside the contract is refused with the key named (`CM-ERRORS-SCHEMA-010` / `012`).
3. Press **Save draft**. The footer now says `Published: v2 · draft pending`: the change is saved, but records still follow version 2.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-0d59a2d7f114406c4d8bd6c66ef2363b3419b9d6%2Fedit-schema-2.png?alt=media" alt="The builder footer: Published: v2 · draft pending, and the buttons Cancel, Save draft and Save &#x26; publish"><figcaption><p>A saved draft on top of the published version.</p></figcaption></figure>
4. Press **Save & publish** to publish the draft as the next version. When the change removes or retypes a field, Cloud first shows **Publishing this version is a breaking change** with the fields that go; records that still use them no longer match the schema. Tick **I understand this is a breaking change and want to publish anyway**, then press **Save & publish** again.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-fb7f2c8cd5b30d179169ce84b4dabb57547c42c2%2Fedit-schema-7.png?alt=media" alt="Warning box Publishing this version is a breaking change: Publishing this version removes the field(s): website. Records that still use these fields will no longer match the schema. The confirmation box is ticked; the footer shows Published: v2 · draft pending"><figcaption><p>The breaking-change warning before the publish.</p></figcaption></figure>

## Result

Cloud goes back to **Database → Collections** and the collection shows the new version, here `Published · v3`. New writes are checked against version 3 at once, in Cloud and through the API.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-4a868ca18ea7765f3aa76228146b4680ab78acaf%2Fedit-schema-3.png?alt=media" alt="Data Collections list: books Published · v1 with the trigger flame, authors Published · v3"><figcaption><p>authors after the publish.</p></figcaption></figure>

If you leave the builder while the JSON is not valid, Cloud asks first (**Data loss warning**). **Cancel** goes back to the list and keeps the last saved draft.

## Change or remove it later

**Collection settings** — the **Settings** tab of the builder. Press **Save settings** after a change; it applies to new requests at once.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-0075e683bd0eae97d191b99504646a9393ff935f%2Fedit-schema-4.png?alt=media" alt="Settings tab of authors: Collection settings with Description Authors of the books we sell, the switches Soft delete and Records have an owner, Save settings, and below it the Embed card"><figcaption><p>The Settings tab.</p></figcaption></figure>

| Field                 | What it does                                                                                                                                                                                                                               | Example                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
| Description           | A short summary of what the collection stores.                                                                                                                                                                                             | `Authors of the books we sell` |
| Soft delete           | A deleted record is marked as deleted instead of removed. Soft-deleted records are hidden from lists and treated as not found by updates.                                                                                                  | off                            |
| Records have an owner | Each record gets a responsible user; end users with own-data rights (for example the **Authenticated** role) read and edit only their own records, and the "my records" API (`findOwn`) is on.                                             | off                            |
| Embed (card below)    | **Embed records** puts the collection's records into the project's AI knowledge; **Fields** picks which fields form the text; **Embedding integration** (or **Project default**). Press **Save embed**. Shown for a published schema only. | on, fields `name`, `country`   |

**Delete the schema** — **Settings** tab → **Delete schema...**. The dialog names the environment and counts the records, for example **All records in PROD will be deleted** · *3 records in PROD will be permanently deleted*. Copy the schema id shown in the dialog and paste it into **Schema id**; only then **Delete** turns on.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-64f00ef2c7b1b77b170af9987a410407e46d9355%2Fedit-schema-5.png?alt=media" alt="Delete schema dialog for archive_2024: All records in PROD will be deleted, 3 records in PROD will be permanently deleted; the schema id to copy and the Schema id field to paste it into; Cancel and Delete"><figcaption><p>The delete dialog asks for the schema id.</p></figcaption></figure>

After **Delete** the message says **Schema deleted. Its records in PROD were deleted too.** and the collection is gone from the list.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-b1533ec4904907185106f827f6dcc3cea5a08e5a%2Fedit-schema-6.png?alt=media" alt="Data Collections list after the delete with the message Schema deleted. Its records in PROD were deleted too."><figcaption><p>After the delete.</p></figcaption></figure>

* Deleting drops the collection with every record and its indexes **in this environment only**; copies in other environments stay. It cannot be undone. A new schema with the same name starts empty.
* A schema that a trigger or a saved aggregate uses is refused, and nothing is deleted: delete the [triggers](/codemash/cloud/database/collections/schema-triggers.md) (`CM-ERRORS-SCHEMA-017`) or change the [aggregates](/codemash/cloud/database/aggregates.md) (`CM-ERRORS-SCHEMA-018`) first.
* Renaming to a name that another schema has in the same environment is refused.

## Do it from code

```ts
dataSchema.properties.country = { type: 'string', maxLength: 100 };
await norbix.hub.database.updateDatabaseSchemaDraft({
  id,
  dataSchema: JSON.stringify(dataSchema),
  visualSchema: JSON.stringify(uiSchema),
});
await norbix.hub.database.publishDatabaseSchema({ id });
const { item } = await norbix.hub.database.getDatabaseSchema({ id });
console.log(item.version); // 2
```

```sh
norbix hub database schema publish --id sch_5QdZnkIC7qMbVLbNXysByI
```

`publishDatabaseSchema` takes `confirmed: true` to publish a breaking change from code. The client setup is on the [Database page](/codemash/cloud/database.md#use-it-from-code). API: [Update Database Schema Draft](/codemash/api-reference/database/schemas/update-database-schema-draft.md) · [Publish Database Schema](/codemash/api-reference/database/schemas/publish-database-schema.md) · [Update Database Schema Settings](/codemash/api-reference/database/schemas/update-database-schema-settings.md) · [Delete Database Schema](/codemash/api-reference/database/schemas/delete-database-schema.md)