> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fibery.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Databases

> Learn how to create and manage Databases using the Fibery API.

A Database is a template for a kind of Entity: Bugs, Teams, Objectives, etc. It consists of metadata and Fields.

<img src="https://mintcdn.com/fibery/lUFkgk4SW9_Hi0iL/images/ad0d48f5-b2ea-43c7-a466-1d9b38f2de9d.gif?s=33bde4cd870c254a74bfd7cf9c7c589a" alt="2024-01-12 12.43.42.gif" width="924" height="1094" data-path="images/ad0d48f5-b2ea-43c7-a466-1d9b38f2de9d.gif" />

<Note>
  The API uses `type` for Database and `app` for Space. See [Terminology](/guides/general/terminology#api-naming).
</Note>

## Database and Field permissions

Imagine you've got a Database `Task` with a Field called `Effort`. Here's how permissions apply depending on `secured?` parameter:

<table class="matrix-table">
  <thead>
    <tr>
      <th />

      <th />

      <th colSpan={2}>**Task `secured?`**</th>
    </tr>

    <tr>
      <th />

      <th />

      <th align="center">❌</th>
      <th align="center">✅</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <th rowSpan={2}>**Effort `secured?`**</th>
      <td align="center">❌</td>
      <td>Everyone has access to all fields</td>
      <td>Everyone has access to Effort, but not to other `secured?` fields</td>
    </tr>

    <tr>
      <td align="center">✅</td>
      <td>Everyone has access to all fields</td>
      <td>Everyone has access to Task's non-secured Fields like Id, but permissions are applied to Effort</td>
    </tr>
  </tbody>
</table>

## Create Database

Every Database is a part of some Space. If the Database's Space does not exist yet, create or install the Space.

To create a fully functional Database, we'll execute two commands:

1. `schema.type/create` to create a Database with at least five mandatory primitive Fields:

* `fibery/id`
* `fibery/public-id`
* `fibery/creation-date`
* `fibery/modification-date`
* `${space}/name`

2. `fibery.app/install-mixins` to be able to prioritize the Database's Entities.

For auxiliary Databases, that are hidden from `Workspace Map` screen, `${space}/name` Field and `rank` Mixin are optional. Just skip these parts when creating a Database.

Auxiliary Databases might be useful as an Entity-based storage — that's how our User's favourite pages and recent items work, for example.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch('https://YOUR_ACCOUNT.fibery.io/api/commands', {
    method: 'POST',
    headers: {
      'Authorization': 'Token YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      command: 'fibery.schema/batch',
      args: {
        commands: [
          {
            command: 'schema.type/create',
            args: {
              'fibery/name': 'Cricket/Player',
              'fibery/meta': {
                'fibery/domain?': true,
                'fibery/secured?': true,
                'ui/color': '#F7D130'
              },
              'fibery/fields': [
                {
                  'fibery/name': 'Cricket/name',
                  'fibery/type': 'fibery/text',
                  'fibery/meta': {
                    'fibery/secured?': false,
                    'ui/title?': true
                  }
                },
                {
                  'fibery/name': 'fibery/id',
                  'fibery/type': 'fibery/uuid',
                  'fibery/meta': {
                    'fibery/secured?': false,
                    'fibery/id?': true,
                    'fibery/readonly?': true
                  }
                },
                {
                  'fibery/name': 'fibery/public-id',
                  'fibery/type': 'fibery/text',
                  'fibery/meta': {
                    'fibery/secured?': false,
                    'fibery/public-id?': true,
                    'fibery/readonly?': true
                  }
                },
                {
                  'fibery/name': 'fibery/creation-date',
                  'fibery/type': 'fibery/date-time',
                  'fibery/meta': {
                    'fibery/secured?': false,
                    'fibery/creation-date?': true,
                    'fibery/readonly?': true,
                    'fibery/default-value': '$now'
                  }
                },
                {
                  'fibery/name': 'fibery/modification-date',
                  'fibery/type': 'fibery/date-time',
                  'fibery/meta': {
                    'fibery/modification-date?': true,
                    'fibery/required?': true,
                    'fibery/readonly?': true,
                    'fibery/default-value': '$now',
                    'fibery/secured?': false
                  }
                },
                {
                  'fibery/name': 'user/salary',
                  'fibery/type': 'fibery/int',
                  'fibery/meta': {
                    'fibery/secured?': true
                  }
                }
              ]
            }
          },
          {
            command: 'fibery.app/install-mixins',
            args: {
              types: {
                'Cricket/Player': ['fibery/rank-mixin']
              }
            }
          }
        ]
      }
    })
  });
  const data = await response.json();
  ```

  ```bash cURL theme={null}
  curl -X POST https://YOUR_ACCOUNT.fibery.io/api/commands \
    -H 'Authorization: Token YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '
    {
      "command": "fibery.schema/batch",
      "args": {
        "commands": [
          {
            "command": "schema.type/create",
            "args": {
              "fibery/name": "Cricket/Player",
              "fibery/meta": {
                "fibery/domain?": true,
                "fibery/secured?": true,
                "ui/color": "#F7D130"
              },
              "fibery/fields": [
                {
                  "fibery/name": "Cricket/name",
                  "fibery/type": "fibery/text",
                  "fibery/meta": {
                    "fibery/secured?": false,
                    "ui/title?": true
                  }
                },
                {
                  "fibery/name": "fibery/id",
                  "fibery/type": "fibery/uuid",
                  "fibery/meta": {
                    "fibery/secured?": false,
                    "fibery/id?": true,
                    "fibery/readonly?": true
                  }
                },
                {
                  "fibery/name": "fibery/public-id",
                  "fibery/type": "fibery/text",
                  "fibery/meta": {
                    "fibery/secured?": false,
                    "fibery/public-id?": true,
                    "fibery/readonly?": true
                  }
                },
                {
                  "fibery/name": "fibery/creation-date",
                  "fibery/type": "fibery/date-time",
                  "fibery/meta": {
                    "fibery/secured?": false,
                    "fibery/creation-date?": true,
                    "fibery/readonly?": true,
                    "fibery/default-value": "$now"
                  }
                },
                {
                  "fibery/name": "fibery/modification-date",
                  "fibery/type": "fibery/date-time",
                  "fibery/meta": {
                    "fibery/modification-date?": true,
                    "fibery/required?": true,
                    "fibery/readonly?": true,
                    "fibery/default-value": "$now",
                    "fibery/secured?": false
                  }
                },
                {
                  "fibery/name": "user/salary",
                  "fibery/type": "fibery/int",
                  "fibery/meta": {
                    "fibery/secured?": true
                  }
                }
              ]
            }
          },
          {
            "command": "fibery.app/install-mixins",
            "args": {
              "types": {
                "Cricket/Player": [
                  "fibery/rank-mixin"
                ]
              }
            }
          }
        ]
      }
    }
    '
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "success": true,
  "result": "ok"
}
```

### Command parameters

| Parameter (required in bold) | Default        | Description                                                                    | Example            |
| ---------------------------- | -------------- | ------------------------------------------------------------------------------ | ------------------ |
| **`fibery/name`**            |                | Database name in `${space}/${name}` format                                     | `CRM/Lead`         |
| `fibery/id`                  | Auto-generated | UUID                                                                           | `fd5d9550-3779...` |
| meta.`fibery/domain?`        | false          | Domain Databases are available as cards on Views                               | true               |
| meta.**`fibery/secured?`**   |                | [Permissions](#database-and-field-permissions) apply to secured Databases only | true               |
| meta.`ui/color?`             | #000000        | HEX color to use in Entity badges                                              | #F7D130            |
| meta.**`fibery/fields`**     |                | Array of [Fields](/guides/http-api/fields) including 5 primitive ones above    |                    |

## Rename Database

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch('https://YOUR_ACCOUNT.fibery.io/api/commands', {
    method: 'POST',
    headers: {
      'Authorization': 'Token YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      command: 'fibery.schema/batch',
      args: {
        commands: [
          {
            command: 'schema.type/rename',
            args: {
              'from-name': 'Cricket/Referee',
              'to-name': 'Cricket/Umpire'
            }
          }
        ]
      }
    })
  });
  const data = await response.json();
  ```

  ```bash cURL theme={null}
  curl -X POST https://YOUR_ACCOUNT.fibery.io/api/commands \
    -H 'Authorization: Token YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '
    {
      "command": "fibery.schema/batch",
      "args": {
        "commands": [
          {
            "command": "schema.type/rename",
            "args": {
              "from-name": "Cricket/Referee",
              "to-name": "Cricket/Umpire"
            }
          }
        ]
      }
    }
    '
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "success": true,
  "result": "ok"
}
```

### **Command parameters**

| Parameter (required in bold) | Description                                        | Example           |
| ---------------------------- | -------------------------------------------------- | ----------------- |
| **`from-name`**              | Current Database name in `${space}/${name}` format | `Cricket/Referee` |
| **`to-name`**                | New Database name in `${space}/${name}` format     | `Cricket/Umpire`  |

## **Delete Database**

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch('https://YOUR_ACCOUNT.fibery.io/api/commands', {
    method: 'POST',
    headers: {
      'Authorization': 'Token YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      command: 'fibery.schema/batch',
      args: {
        commands: [
          {
            command: 'schema.type/delete',
            args: {
              name: 'Cricket/Umpire',
              'delete-entities?': true,
              'delete-related-fields?': true
            }
          }
        ]
      }
    })
  });
  const data = await response.json();
  ```

  ```bash cURL theme={null}
  curl -X POST https://YOUR_ACCOUNT.fibery.io/api/commands \
    -H 'Authorization: Token YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '
    {
      "command": "fibery.schema/batch",
      "args": {
        "commands": [
          {
            "command": "schema.type/delete",
            "args": {
              "name": "Cricket/Umpire",
              "delete-entities?": true,
              "delete-related-fields?": true
            }
          }
        ]
      }
    }
    '
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "success": true,
  "result": "ok"
}
```

### Command parameters

| Parameter (required in bold) | Default | Description                                                                                                        | Example          |
| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | ---------------- |
| **`name`**                   |         | Database name in `${space}/${name}` format                                                                         | `Cricket/Umpire` |
| `delete-entities?`           | false   | Delete all Entities of this Database? See the behavior in the table below.                                         | true             |
| `delete-related-fields?`     | false   | Delete all related Fields like `Criket/Favourite Umpire` in `Cricket/Player`? See the behavior in the table below. | true             |

### `delete?` parameter behavior

<table class="matrix-table">
  <thead>
    <tr>
      <th />

      <th />

      <th colSpan={2}>**`delete?` parameter**</th>
    </tr>

    <tr>
      <th />

      <th />

      <th>**false**</th>
      <th>**true**</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <th rowSpan={2}>**Entities (or related Fields)**</th>
      <td>**don't exist**</td>
      <td>Database is deleted</td>
      <td>Database is deleted</td>
    </tr>

    <tr>
      <td>**exist**</td>
      <td>Error is thrown</td>
      <td>Database and Entities (or related Fields) are deleted</td>
    </tr>
  </tbody>
</table>

Related single-select `enum` Databases are not deleted even with `delete-related-fields?` enabled. Delete these Databases separately the same way you delete the original Database.