2025.02.21_engineering_nocoDB.mdc

# Overview REST APIs

Once you've created the schemas, you can manipulate the data or invoke actions using the REST APIs. We provide several types of APIs for different usages. Refer to the following links for more details:

- [Meta APIs](https://meta-apis-v2.nocodb.com/)
- [Data APIs](https://data-apis-v2.nocodb.com/)

You will need an API key and endpoint to use the API. The endpoint URL for hosted instances of NocoDB is in the format `https://app.nocodb.com/api/v2/tables/TABLEID/records` and `https://app.nocodb.com/api/v2/meta/bases/BASEID/info`.

- You can find a TABLEID by going to any table in NocoDB > Details > API Snippets.
- You can find your BASEID by clicking the menu icon next to any database, rest APIs > and seeing the BASEID in the url.

Additional information on the REST APIs is provided below.

## Query params

| Name   | Alias | Use case                       | Default value | Example value                                                                                               |
|--------|-------|--------------------------------|---------------|-------------------------------------------------------------------------------------------------------------|
| where  | w     | Complicated where conditions   |               | `(colName,eq,colValue)~or(colName2,gt,colValue2)`<br>Usage: Comparison operators<br>Usage: Logical operators |
| limit  | l     | Number of rows to get          | 10            | 20                                                                                                          |
| offset | o     | Offset for pagination          | 0             | 20                                                                                                          |
| sort   | s     | Sort by column name            |               | column_name                                                                                                 |
| fields | f     | Required column names in result| *             | column_name1,column_name2                                                                                   |
| shuffle| r     | Shuffle the result for pagination | 0           | 1 (Only allow 0 or 1. Other values would see it as 0)                                                       |

## Comparison Operators

| Operation | Meaning     | Example                       |
|-----------|-------------|-------------------------------|
| eq        | equal       | (colName,eq,colValue)         |
| neq       | not equal   | (colName,neq,colValue)        |
| not       | not equal   | (colName,not,colValue)        |
| gt        | greater than| (colName,gt,colValue)         |
| ge        | greater or equal | (colName,ge,colValue)    |
| lt        | less than   | (colName,lt,colValue)         |
| le        | less or equal | (colName,le,colValue)       |
| is        | is          | (colName,is,true/false/null)  |
| isnot     | is not      | (colName,isnot,true/false/null) |
| in        | in          | (colName,in,val1,val2,val3,val4) |
| btw       | between     | (colName,btw,val1,val2)       |
| nbtw      | not between | (colName,nbtw,val1,val2)      |
| like      | like        | (colName,like,%name)          |
| nlike     | not like    | (colName,nlike,%name)         |
| isWithin  | is Within (Available in `Date` and `DateTime` only) | (colName,isWithin,sub_op) |
| allof     | includes all of | (colName,allof,val1,val2,...) |
| anyof     | includes any of | (colName,anyof,val1,val2,...) |
| nallof    | does not include all of (includes none or some, but not all of) | (colName,nallof,val1,val2,...) |
| nanyof    | does not include any of (includes none of) | (colName,nanyof,val1,val2,...) |

## Comparison Sub-Operators

The following sub-operators are available in the `Date` and `DateTime` columns.

| Operation        | Meaning           | Example                         |
|------------------|-------------------|---------------------------------|
| today            | today             | (colName,eq,today)              |
| tomorrow         | tomorrow          | (colName,eq,tomorrow)           |
| yesterday        | yesterday         | (colName,eq,yesterday)          |
| oneWeekAgo       | one week ago      | (colName,eq,oneWeekAgo)         |
| oneWeekFromNow   | one week from now | (colName,eq,oneWeekFromNow)     |
| oneMonthAgo      | one month ago     | (colName,eq,oneMonthAgo)        |
| oneMonthFromNow  | one month from now| (colName,eq,oneMonthFromNow)    |
| daysAgo          | number of days ago| (colName,eq,daysAgo,10)         |
| daysFromNow      | number of days from now | (colName,eq,daysFromNow,10) |
| exactDate        | exact date        | (colName,eq,exactDate,2022-02-02) |

For `isWithin` in `Date` and `DateTime` columns, the different set of sub-operators are used.

| Operation          | Meaning             | Example                           |
|--------------------|---------------------|-----------------------------------|
| pastWeek           | the past week       | (colName,isWithin,pastWeek)       |
| pastMonth          | the past month      | (colName,isWithin,pastMonth)      |
| pastYear           | the past year       | (colName,isWithin,pastYear)       |
| nextWeek           | the next week       | (colName,isWithin,nextWeek)       |
| nextMonth          | the next month      | (colName,isWithin,nextMonth)      |
| nextYear           | the next year       | (colName,isWithin,nextYear)       |
| nextNumberOfDays   | the next number of days | (colName,isWithin,nextNumberOfDays,10) |
| pastNumberOfDays   | the past number of days | (colName,isWithin,pastNumberOfDays,10) |

## Logical Operators

| Operation | Example                                                                 |
|-----------|-------------------------------------------------------------------------|
| ~or       | (checkNumber,eq,JM555205)~or((amount,gt,200)~and(amount,lt,2000))       |
| ~and      | (checkNumber,eq,JM555205)~and((amount,gt,200)~and(amount,lt,2000))      |
| ~not      | ~not(checkNumber,eq,JM555205)                                           |

# Upload via API

Sample code to upload files via API is listed below. Assumes `http://localhost:8080/` as the base URL for the API calls.
## Upload local file

```
let axios = require("axios").default;
let FormData = require('form-data');
let fs = require('fs');

// Configurations
//
const project_id = '<Project Identifier>';
const table_id = '<Table Identifier>';
const xc_token = '<Auth Token>';
const file_path = '<Local File Path>';


// Insert Image
// @param image_path : local file path
// @return : JSON object to be used in insert record API for attachment field
//
async function insertImage (path) {
    const formData = new FormData();
    formData.append("file", fs.createReadStream(path));
    const data = await axios({
        url: 'http://localhost:8080/api/v2/storage/upload',
        data: formData,
        headers:{
            'Content-Type':`multipart/form-data;`,
            'xc-token': xc_token
        },
        method: 'post',

        // Optional : storage file path
        params: {"path": "somePath"}
    });
    return data;
}

// Insert record with attachment
// Assumes a table with two columns :
//      'Title' of type SingleLineText and
//      'Attachment' of type Attachment
//
async function uploadFileExample() {
    let response = await insertImage(file_path);

    let row = {
        "Title": "2",
        "Attachment": response.data
    };

    await axios({
        method: 'POST',
        url: `http://localhost:8080/api/v2/tables/${table_id}/records`,
        data: row,
        headers: {
            'xc-token': xc_token
        }
    });
}

(async () => {
    await uploadFileExample();
})();
```

## Upload via URL

```
let axios = require("axios").default;
let FormData = require('form-data');
let fs = require('fs');

// Configurations
//
const project_id = '<Project Identifier>';
const table_id = '<Table Identifier>';
const xc_token = '<Auth Token>';

// URL array : URLs of files to be uploaded
const URLs = [{ url: '<URL1>' }, { url: '<URL2>' }];

// Insert Image
// @param URLs : [] containing public URL for files to be uploaded
// @return : JSON object to be used in insert record API for attachment field
//
async function insertImageByURL (URL_array) {
    const data = await axios({
        url: 'http://localhost:8080/api/v2/storage/upload-by-url',
        data: URL_array,
        headers: {
            'xc-token': xc_token
        },
        method: 'post',

        // Optional : storage file path
        params: {"path": "somePath"}
    });
    return data;
}

// Insert record with attachment
// Assumes a table with two columns :
//      'Title' of type SingleLineText and
//      'Attachment' of type Attachment
//
async function uploadByUrlExample() {
    let response = await insertImageByURL(URLs);

    // Update two columns : Title and Attachment
    let row = {
        "Title": "3",
        "Attachment": response.data
    };

    await axios({
        method: 'POST',
        url: `http://localhost:8080/api/v2/tables/${table_id}/records`,
        data: row,
        headers: {
            'xc-token': xc-token
        }
    });
}

(async () => {
    await uploadByUrlExample();
})();
```

# Accessing APIs
## API Tokens[​](https://docs.nocodb.com/developer-resources/rest-APIs/accessing-apis#api-tokens "Direct link to API Tokens")
NocoDB APIs can be authorized by using API Tokens. API tokens allow us to integrate seamlessly with 3rd party apps. See [API Tokens Management](https://docs.nocodb.com/account-settings/api-tokens) for more.
### Create API Token[​](https://docs.nocodb.com/account-settings/api-tokens/#create-api-token "Direct link to Create API Token")

Open Account Settings page from the user menu in the bottom left corner of the sidebar.

1. Click on `User menu` in the bottom left corner of the sidebar,
2. Select `Account Settings` from the dropdown

![profile page](https://docs.nocodb.com/assets/images/account-settings-3f8b281c933be2349ddb19f0fa8660e8.png)

Follow the steps below to create API Token

1. Click on `Tokens` tab in the `Account Settings` page
2. Click on `Add New API Token`
3. Enter the name for the API Token
4. Click on `Save` button to save the changes
5. Copy the API Token by clicking on `Copy` button displayed under `Actions` menu
6. Use the API Token in the services that require it to authenticate as `xc-token` in the headers.

```
{  "headers": {    "xc-token": "Copied API token here under quotes"  }}
```

![Create API Token](https://docs.nocodb.com/assets/images/api-token-1-6806c5ece8a92717e786e0fa4e824081.png)

![Create API Token](https://docs.nocodb.com/assets/images/api-token-2-378e04140d53a68be86d17d3561c8591.png)

info

- Only one token can be created per user
- API Token does not expire, but it can be deleted anytime.

API Token created will get added to the list. Copy API token by clicking on `Copy` button displayed under `Actions` menu

![Create API Token](https://docs.nocodb.com/assets/images/api-token-3-493d6baa74b64ec5d6a00c20d6806fd4.png)

### Delete API Token[​](https://docs.nocodb.com/account-settings/api-tokens/#delete-api-token "Direct link to Delete API Token")

warning

Note that, all the services using the API Token will stop working once the API Token is deleted.

Open Account Settings page from the user menu in the bottom left corner of the sidebar.

1. Click on `User menu` in the bottom left corner of the sidebar,
2. Select `Account Settings` from the dropdown

![profile page](https://docs.nocodb.com/assets/images/account-settings-3f8b281c933be2349ddb19f0fa8660e8.png)

1. Click on `Tokens` tab in the `Account Settings` page
2. From the `Actions` menu, click on `Delete` button associated with the API Token to be deleted

![Delete API Token](https://docs.nocodb.com/assets/images/api-token-4-1a6120f496ccdfca799987a4dc8f9027.png)


## Swagger UI (Actions on base)[​](https://docs.nocodb.com/developer-resources/rest-APIs/accessing-apis#swagger-ui "Direct link to Swagger UI")
You can interact with the API's resources via the Swagger UI. For more details, see [Swagger APIs Doc](https://docs.nocodb.com/bases/actions-on-base#rest-apis)
### Base context menu[​](https://docs.nocodb.com/bases/actions-on-base/#base-context-menu "Direct link to Base context menu")

The base context menu offers a selection of swift actions that can be executed on a base. To access this menu, click on the ellipsis symbol (`...`) located adjacent to the base name within the left sidebar. ![base context menu](https://docs.nocodb.com/assets/images/base-context-menu-8cdc9e3b6c6f450d66cb324e8ea1feea.png)

### Rename base[​](https://docs.nocodb.com/bases/actions-on-base/#rename-base "Direct link to Rename base")

To modify the name of a base, you can easily do so by following these steps:

1. Initiate the base context menu by clicking on the ellipses `...` located next to the base name within the left sidebar.
2. In the dropdown menu that appears, choose the `Rename` option.
3. Input the new name for the base directly within the field provided and then press the `Enter` key to confirm and save the updated name.

![base context menu](https://docs.nocodb.com/assets/images/base-context-menu-8cdc9e3b6c6f450d66cb324e8ea1feea.png)

![base rename](https://docs.nocodb.com/assets/images/base-rename-027fd5fbcdca058a00c8213c263d1836.png)

### Star base[​](https://docs.nocodb.com/bases/actions-on-base/#star-base "Direct link to Star base")

You can star a base by following simple steps below:

1. Initiate the base context menu by clicking on the ellipses `...` located next to the base name within the left sidebar.
2. In the dropdown menu that appears, choose the `Add to Starred` option.
3. Subsequently, the designated base will be placed into the "Starred" section, conveniently positioned within the left sidebar.

![base context menu](https://docs.nocodb.com/assets/images/base-context-menu-8cdc9e3b6c6f450d66cb324e8ea1feea.png)

![base starred](https://docs.nocodb.com/assets/images/base-starred-082719a6b8a527be8b23a2d511867ccd.png)

info

Starred base will appear in the `Starred` section on the left sidebar.

#### Remove a base from starred list[​](https://docs.nocodb.com/bases/actions-on-base/#remove-a-base-from-starred-list "Direct link to Remove a base from starred list")

1. Initiate the base context menu by clicking on the ellipses `...` located next to the base name within the left sidebar.
2. In the dropdown menu that appears, choose the `Remove from Starred` option.
3. Subsequently, the designated base will be removed from the `Starred` section.

![image](https://docs.nocodb.com/assets/images/base-remove-from-starred-a5fc6ed9e9cbc2251844fc0cd8afba24.png)

### Duplicate base[​](https://docs.nocodb.com/bases/actions-on-base/#duplicate-base "Direct link to Duplicate base")

To duplicate a base, you can follow these straightforward steps:

1. Initiate the base context menu by clicking on the ellipses `...` located next to the base name within the left sidebar.
2. In the dropdown menu that appears, choose the `Duplicate` option.
3. Optionally, you can configure the duplication process with the following choices: a) `Include data`: You have the flexibility to choose whether to duplicate the base with or without its data. b) `Include views`: You can decide whether to duplicate the base with or without its views.
4. Click the `Confirm` button in the confirmation modal that pops up.
5. A new base will be created, mirroring the original base's schema and data/views based on the configurations specified in step 3.

![base context menu](https://docs.nocodb.com/assets/images/base-context-menu-8cdc9e3b6c6f450d66cb324e8ea1feea.png)

![image](https://docs.nocodb.com/assets/images/base-duplicate-88ebe6a5fcc9c36b5f7d76b65726d9b5.png)

info

- A duplicate base will be generated within the same workspace as the original base.
- The duplicated base will be suffixed with `Copy` in its name.
- You will be designated as the `base owner` upon the duplication of the base.
- Existing base members will not be transferred to the duplicated base.

### Delete base[​](https://docs.nocodb.com/bases/actions-on-base/#delete-base "Direct link to Delete base")

If you determine that a base is no longer necessary, you have the option to permanently remove it from your workspace. Deleting a base will delete all the tables and data associated with it.

info

**This action cannot be undone.**

info

Only **base owner** can delete a workspace.

To delete a base:

1. Initiate the base context menu by clicking on the ellipses `...` located next to the base name within the left sidebar.
2. In the dropdown menu that appears, choose the `Delete` option.
3. Select `Delete base` button on the confirmation dialog box.

![base context menu](https://docs.nocodb.com/assets/images/base-context-menu-8cdc9e3b6c6f450d66cb324e8ea1feea.png)

![base delete](https://docs.nocodb.com/assets/images/base-delete-15390ff1d15eddee39ea1ea63f72a6af.png)

### Developer features[​](https://docs.nocodb.com/bases/actions-on-base/#developer-features "Direct link to Developer features")

#### Base settings[​](https://docs.nocodb.com/bases/actions-on-base/#base-settings "Direct link to Base settings")

Some general configurations are available for you to modify within the base settings.

1. **Show M2M tables**: Toggle this option to display/hide M2M tables within the left sidebar. Many-to-many relation is supported via a junction table & is hidden by default.
2. **Show NULL in cells**: Toggle this option to display/hide NULL values within the cells of the table. This helps differentiate against cells holding EMPTY string.
3. **Show NULL & Empty in Filters**: Enable 'additional' filters to differentiate fields containing NULL & Empty Strings. Default support for Blank treats both NULL & Empty strings alike.

To configure base settings, you can follow these steps:

1. Initiate the base context menu by clicking on the ellipses `...` located next to the base name within the left sidebar.
2. In the dropdown menu that appears, choose the `Settings` option.

![base context menu](https://docs.nocodb.com/assets/images/base-context-menu-8cdc9e3b6c6f450d66cb324e8ea1feea.png)

![bsae settings](https://docs.nocodb.com/assets/images/base-settings-194c9bb15d79c76f4bfea5746a077125.png)

#### REST APIs[​](https://docs.nocodb.com/bases/actions-on-base/#rest-apis "Direct link to REST APIs")

NocoDB provides a Swagger UI for each base. To access the Swagger UI, follow these steps:

1. Initiate the base context menu by clicking on the ellipses `...` located next to the base name within the left sidebar.
2. In the dropdown menu that appears, choose the `REST APIs` option.

![base context menu](https://docs.nocodb.com/assets/images/base-context-menu-8cdc9e3b6c6f450d66cb324e8ea1feea.png)

![swagger](https://docs.nocodb.com/assets/images/base-swagger-66b41d2cd5d5e0a8f51ff026b6cfab85.png)

#### Relations[​](https://docs.nocodb.com/bases/actions-on-base/#relations "Direct link to Relations")

NocoDB provides a visual representation of the relations between tables within a base. To access the relations diagram, follow these steps:

1. Initiate the base context menu by clicking on the ellipses `...` located next to the base name within the left sidebar.
2. In the dropdown menu that appears, choose the `Relations` option.

![base context menu](https://docs.nocodb.com/assets/images/base-context-menu-8cdc9e3b6c6f450d66cb324e8ea1feea.png)

![base relations](https://docs.nocodb.com/assets/images/base-relations-aaa09c0623353f552c7b90a8aa6beacb.png)


### Related articles[​](https://docs.nocodb.com/bases/actions-on-base/#related-articles "Direct link to Related articles")

- [Base overview](https://docs.nocodb.com/bases/base-overview)
- [Create an empty base](https://docs.nocodb.com/bases/create-base)
- [Import base from Airtable](https://docs.nocodb.com/bases/import-base-from-airtable)
- [Invite team members to work on a base](https://docs.nocodb.com/bases/base-collaboration)
- [Share base publicly](https://docs.nocodb.com/bases/share-base)
- [Rename base](https://docs.nocodb.com/bases/actions-on-base#rename-base)
- [Duplicate base](https://docs.nocodb.com/bases/actions-on-base#duplicate-base)
- [Bookmark base](https://docs.nocodb.com/bases/actions-on-base#star-base)
- [Delete base](https://docs.nocodb.com/bases/actions-on-base#delete-base)


---
# Webhook overview

You can employ webhooks to notify external systems whenever there are additions, updates, or removals of records within NocoDB. This feature allows you to receive instantaneous notifications for any changes made to your database. NocoDB also offers webhooks for bulk endpoints for creating, updating, or deleting multiple records simultaneously.

Note that, Webhooks currently are specific to associated table.

- [Create Webhook](https://docs.nocodb.com/developer-resources/webhook/create-webhook)
- [Disable Webhook](https://docs.nocodb.com/developer-resources/webhook/actions-on-webhook#enabledisable-webhook)
- [Modify Webhook](https://docs.nocodb.com/developer-resources/webhook/actions-on-webhook#edit-webhook)
- [Duplicate Webhook](https://docs.nocodb.com/developer-resources/webhook/actions-on-webhook#duplicate-webhook)
- [Delete Webhook](https://docs.nocodb.com/developer-resources/webhook/actions-on-webhook#delete-webhook)

# Create Webhook[​](https://docs.nocodb.com/developer-resources/webhook/create-webhook/#create-webhook "Direct link to Create Webhook")
## Accessing webhook page[​](https://docs.nocodb.com/developer-resources/webhook/create-webhook/#accessing-webhook-page "Direct link to Accessing webhook page")

1. Click on table for which webhook needs to be configured on the left sidebar
2. Open `Details` tab in topbar,
3. Click on `Webhooks` tab
4. Click `Add New Webhook`

![Accessing webhook](https://docs.nocodb.com/assets/images/create-webhook-1-be523f2a91b6829cd8d82915d07e92e4.png)

## Configuring webhook[​](https://docs.nocodb.com/developer-resources/webhook/create-webhook/#configuring-webhook "Direct link to Configuring webhook")

1. Name of the webhook
2. Select the event for which webhook needs to be triggered

|Trigger|Details|
|---|---|
|After Insert|After a single record is inserted|
|After Update|After a single record is updated|
|After Delete|After a single record is deleted|
|After Bulk Insert|After bulk records are inserted|
|After Bulk Update|After bulk records are updated|
|After Bulk Delete|After bulk records are deleted|

1. Method & URL: Configure the endpoint to which webhook needs to be triggered. Supported methods are GET, POST, DELETE, PUT, HEAD, PATCH
2. Headers & Parameters: Configure Request headers & parameters (optional)
3. Condition: Only records meeting the configured criteria will trigger webhook (optional)
4. Test webhook (with sample payload) to verify if parameter are configured appropriately (optional)
5. Save the webhook

![Configuring webhook](https://docs.nocodb.com/assets/images/create-webhook-2-bfee41aaeb94b884024cd5e874f290c1.png)

## Webhook with conditions[​](https://docs.nocodb.com/developer-resources/webhook/create-webhook/#webhook-with-conditions "Direct link to Webhook with conditions")

In case of webhook with conditions, only records meeting the configured criteria will trigger webhook. For example, trigger webhook only when `Status` is `Complete`. You can also configure multiple conditions using `AND` or `OR` operators. For example, trigger webhook only when `Status` is `Complete` and `Priority` is `High`.

The webhook will be triggered only when the configured condition wasn't met before the record was updated. For example, if you have configured webhook with condition `Status` `is` `Complete` and `Priority` `is` `High` and you update the record with `Status` `Complete` and `Priority` `Low` to `High`, webhook will be triggered. However, if you update any other fields of the record with `Status` `Complete` and `Priority` `High`, webhook won't be triggered.

In summary, the webhook will be triggered only when `Condition(old-record) = false` and `Condition(new-record) = true`.

## Webhook response sample[​](https://docs.nocodb.com/developer-resources/webhook/create-webhook/#webhook-response-sample "Direct link to Webhook response sample")

- After Insert
```
{
  "type": "records.after.insert",
  "id": "9dac1c54-b3be-49a1-a676-af388145fa8c",
  "data": {
    "table_id": "md_xzru7dcqrecc60",
    "table_name": "Film",
    "view_id": "vw_736wrpoas7tr0c",
    "view_name": "Film",
    "records": [
      {
        "FilmId": 1011,
        "Title": "FOO",
        "Language": {
          "LanguageId": 1,
          "Name": "English"
        },
      }
    ]
  }
}
```

- After Update
```
{
  "type": "records.after.update",
  "id": "6a6ebfe4-b0b5-434e-b5d6-5212adbf82fa",
  "data": {
    "table_id": "md_xzru7dcqrecc60",
    "table_name": "Film",
    "view_id": "vw_736wrpoas7tr0c",
    "view_name": "Film",
    "previous_records": [
      {
        "FilmId": 1,
        "Title": "ACADEMY DINOSAUR",
        "Description": "A Epic Drama of a Feminist in The Canadian Rockies",
        "Actor List": [
          {
            "ActorId": 10,
            "FirstName": "CHRISTIAN"
          }
        ],
      }
    ],
    "records": [
      {
        "FilmId": 1,
        "Title": "ACADEMY DINOSAUR (Edited)",
        "Actor List": [
          {
            "ActorId": 10,
            "FirstName": "CHRISTIAN"
          }
        ],
      }
    ]
  }
}
```

- After Delete
```
{
  "type": "records.after.delete",
  "id": "e593079f-70e5-4965-8944-5ff7aeed005c",
  "data": {
    "table_id": "md_xzru7dcqrecc60",
    "table_name": "Film",
    "view_id": "vw_736wrpoas7tr0c",
    "view_name": "Film",
    "records": [
      {
        "FilmId": 1010,
        "Title": "ALL-EDITED",
        "Language": {
          "LanguageId": 1,
          "Name": "English"
        },
      }
    ]
  }
}
```

- After Bulk Insert
```
{
  "type": "records.after.bulkInsert",
  "id": "f8397b06-a399-4a3a-b6b0-6d1c0c2f7578",
  "data": {
    "table_id": "md_xzru7dcqrecc60",
    "table_name": "Film",
    "view_id": "vw_3fq2e9q8drkblw",
    "view_name": "GridView",
    "records_inserted": 2
  }
}
```

- After Bulk Update
```
{
  "type": "records.after.bulkUpdate",
  "id": "e983cea5-8e38-438e-96a0-048751f6830b",
  "data": {
    "table_id": "md_xzru7dcqrecc60",
    "table_name": "Film",
    "view_id": "vw_3fq2e9q8drkblw",
    "view_name": "Sheet-1",
    "previous_records": [
      [
        {
          "FilmId": 1005,
          "Title": "Q",
          "Language": {
            "LanguageId": 1,
            "Name": "English"
          },
        },
        {
          "FilmId": 1004,
          "Title": "P",
          "Language": {
            "LanguageId": 1,
            "Name": "English"
          }
        }
      ]
    ],
    "records": [
      [
        {
          "FilmId": 1005,
          "Title": "Q-EDITED",
          "Language": {
            "LanguageId": 1,
            "Name": "English"
          }
        },
        {
          "FilmId": 1004,
          "Title": "P-EDITED",
          "Language": {
            "LanguageId": 1,
            "Name": "English"
          },
        }
      ]
    ]
  }
}
```

- After Bulk Delete
```
{
  "type": "records.after.bulkDelete",
  "id": "e7f1f4e5-7052-4ca2-9355-241ceb836f43",
  "data": {
    "table_id": "md_xzru7dcqrecc60",
    "table_name": "Film",
    "view_id": "vw_3fq2e9q8drkblw",
    "view_name": "Sheet-1",
    "records": [
      [
        {
          "FilmId": 1022,
          "Title": "x",
          "Language": {
            "LanguageId": 1,
            "Name": "English"
          },
        },
        {
          "FilmId": 1023,
          "Title": "x",
          "Language": {
            "LanguageId": 1,
            "Name": "English"
          },
        }
      ]
    ]
  }
}
```

## Webhook with custom payload ☁[​](https://docs.nocodb.com/developer-resources/webhook/create-webhook/#webhook-with-custom-payload- "Direct link to Webhook with custom payload ☁")

In the enterprise edition, you can set up a personalized payload for your webhook. Just head to the `Body` tab to make the necessary configurations. Users can utilize [handlebar syntax](https://handlebarsjs.com/guide/#simple-expressions), which allows them to access and manipulate the data easily.

Use `{{ json event }}` to access the event data. Sample response is as follows

```
{
  "type": "records.after.insert",
  "id": "0698517a-d83a-4e72-bf7a-75f46b704ad1",
  "data": {
    "table_id": "m969t01blwprpef",
    "table_name": "Table-2",
    "view_id": "vwib3bvfxdqgymun",
    "view_name": "Table-2",
    "rows": [
      {
        "Id": 1,
        "Tags": "Sample Text",
        "CreatedAt": "2024-04-11T10:40:20.998Z",
        "UpdatedAt": "2024-04-11T10:40:20.998Z"
      }
    ]
  }
}
```

info

**Note:** The custom payload feature is only available in the enterprise edition.

#### Discord Webhook[​](https://docs.nocodb.com/developer-resources/webhook/create-webhook/#discord-webhook "Direct link to Discord Webhook")

Discord webhook can be configured to send messages to a Discord channel. Discord request body should contain content, embeds or attachments, otherwise request will fail. Below is an example of Discord webhook payload. More details can be found [here](https://birdie0.github.io/discord-webhooks-guide/discord_webhook.html)

```
{
  "content": "Hello, this is a webhook message",
  "embeds": [
    {
      "title": "Webhook",
      "description": "This is a webhook message",
      "color": 16711680
    }
  ]
}
```

To send complete event data to Discord, use below payload

```
{
  "content" : {{ json ( json event ) }}
}
```

One can also customize the payload as per the requirement. For example, to send only the `Title` field to Discord, use below payload. Note that, the value of `content` is what that will get displayed in the Discord channel.

```
{
   "content": "{{ event.data.rows.[0].Title }}"
}
```

## Environment Variables[​](https://docs.nocodb.com/developer-resources/webhook/create-webhook/#environment-variables "Direct link to Environment Variables")

In self-hosted version, you can configure the following environment variables to customize the webhook behavior.

- NC_ALLOW_LOCAL_HOOKS: Allow localhost based links to be triggered. Default: false

Find more about environment variables [here](https://docs.nocodb.com/getting-started/self-hosted/environment-variables)
# Actions on webhook

### Enable/disable Webhook[​](https://docs.nocodb.com/developer-resources/webhook/actions-on-webhook#enabledisable-webhook "Direct link to Enable/disable Webhook")

To disable a Webhook +

- Open `Webhook` tab to find list of webhooks created

- Toggle `Activate` button to enable/disable

![Webhook List](https://docs.nocodb.com/assets/images/webhook-list-2-55f2996a38422fa4f3f37faf733328d1.png)

### Edit Webhook[​](https://docs.nocodb.com/developer-resources/webhook/actions-on-webhook#edit-webhook "Direct link to Edit Webhook")

To edit a Webhook

- Open `Webhook` tab to find list of webhooks created
- Click on webhook to be edited
- This will open up the webhook configuration page, which is similar to the page used for [creating webhook](https://docs.nocodb.com/automation/webhook/create-webhook). Reconfigure the webhook as required
- Click on `Save` button to save the changes

### Duplicate Webhook[​](https://docs.nocodb.com/developer-resources/webhook/actions-on-webhook#duplicate-webhook "Direct link to Duplicate Webhook")

To duplicate a Webhook

- Open `Webhook` tab to find list of webhooks created
- Click on `...` actions button associated with the webhook to be duplicate
- Select `Duplicate`

![Webhook context menu](https://docs.nocodb.com/assets/images/webhook-list-3-fa64f61ec97eeb2ed3e08a7183608323.png)

A copy of the webhook will be created (disabled by default) with a suffix `- Copy`

### Delete Webhook[​](https://docs.nocodb.com/developer-resources/webhook/actions-on-webhook#delete-webhook "Direct link to Delete Webhook")

To delete a Webhook

- Open the `Webhook` tab to find the list of webhooks created
- Click on the `...` actions button associated with the webhook to be deleted
- Select `Delete`

![Webhook context menu](https://docs.nocodb.com/assets/images/webhook-list-3-fa64f61ec97eeb2ed3e08a7183608323.png)

---

# Architecture overview

By default, if `NC_DB` is not specified, then SQLite will be used to store your metadata. We suggest users to separate the metadata and user data in different databases.

![image](https://docs.nocodb.com/assets/images/architecture-0ae1ed245ed474936af018fb5fa06792.png)

| Project Type                           | Metadata stored in | Data stored in    |
| -------------------------------------- | ------------------ | ----------------- |
| Create new base                        | NC_DB              | NC_DB             |
| Create new base with External Database | NC_DB              | External Database |
| Create new base from Excel             | NC_DB              | NC_DB             |
# Repository structure

We use `Lerna` to manage multi-packages. We have the following [packages](https://github.com/nocodb/nocodb/tree/master/packages).

- `packages/nc-cli` : A CLI to create NocoDB app.
- `packages/nocodb-sdk`: API client sdk of nocodb.
- `packages/nc-gui`: NocoDB Frontend.
- `packages/nc-lib-gui`: The build version of `nc-gui` which will be used in `packages/nocodb`.
- `packages/noco-blog`: NocoDB Blog which will be auto-released to [nocodb/noco-blog](https://github.com/nocodb/noco-blog).
- `packages/noco-docs`: NocoDB Documentation which will be auto-released to [nocodb/noco-docs](https://github.com/nocodb/noco-docs).
- `packages/nocodb`: NocoDB Backend, hosted in [NPM](https://www.npmjs.com/package/nocodb).

# Development Setup

## Clone the repo[​](https://docs.nocodb.com/engineering/development-setup#clone-the-repo "Direct link to Clone the repo")

```
git clone https://github.com/nocodb/nocodb# change directory to the project rootcd nocodb
```

## Install dependencies[​](https://docs.nocodb.com/engineering/development-setup#install-dependencies "Direct link to Install dependencies")

```
# run from the project root# this command will install the dependencies including sdk buildpnpm bootstrap
```

## Start Frontend[​](https://docs.nocodb.com/engineering/development-setup#start-frontend "Direct link to Start Frontend")

```
# run from the project rootpnpm start:frontend# runs on port 3000
```

## Start Backend[​](https://docs.nocodb.com/engineering/development-setup#start-backend "Direct link to Start Backend")

```
# run from the project rootpnpm start:backend# runs on port 8080
```

Any changes made to frontend and backend will be automatically reflected in the browser.

## Enabling CI-CD for Draft PR[​](https://docs.nocodb.com/engineering/development-setup#enabling-ci-cd-for-draft-pr "Direct link to Enabling CI-CD for Draft PR")

CI-CD will be triggered on moving a PR from draft state to `Ready for review` state & on pushing changes to `Develop`. To verify CI-CD before requesting for review, add label `trigger-CI` on Draft PR.

## Accessing CI-CD Failure Screenshots[​](https://docs.nocodb.com/engineering/development-setup#accessing-ci-cd-failure-screenshots "Direct link to Accessing CI-CD Failure Screenshots")

For Playwright tests, screenshots are captured on the tests. These will provide vital clues for debugging possible issues observed in CI-CD. To access screenshots, Open link associated with CI-CD run & click on `Artifacts`

![Screenshot 2022-09-29 at 12 43 37 PM](https://user-images.githubusercontent.com/86527202/192965070-dc04b952-70fb-4197-b4bd-ca7eda066e60.png)

# Writing unit tests

## Unit Tests[​](https://docs.nocodb.com/engineering/unit-testing#unit-tests "Direct link to Unit Tests")

- All individual unit tests are independent of each other. We don't use any shared state between tests.
- Test environment includes `sakila` sample database and any change to it by a test is reverted before running other tests.
- While running unit tests, it tries to connect to mysql server running on `localhost:3306` with username `root` and password `password` (which can be configured) and if not found, it will use `sqlite` as a fallback, hence no requirement of any sql server to run tests.

### Pre-requisites[​](https://docs.nocodb.com/engineering/unit-testing#pre-requisites "Direct link to Pre-requisites")

- MySQL is preferred - however tests can fallback on SQLite too

### Setup[​](https://docs.nocodb.com/engineering/unit-testing#setup "Direct link to Setup")

```
pnpm --filter=-nocodb install

# add a .env file
cp tests/unit/.env.sample tests/unit/.env

# open .env file
open tests/unit/.env
```

Configure the following variables

> DB_HOST : host DB_PORT : port DB_USER : username DB_PASSWORD : password

### Run Tests[​](https://docs.nocodb.com/engineering/unit-testing#run-tests "Direct link to Run Tests")

```
pnpm run test:unit
```

### Folder Structure[​](https://docs.nocodb.com/engineering/unit-testing#folder-structure "Direct link to Folder Structure")

The root folder for unit tests is `packages/nocodb/tests/unit`

- `rest` folder contains all the test suites for rest apis.
- `model` folder contains all the test suites for models.
- `factory` folder contains all the helper functions to create test data.
- `init` folder contains helper functions to configure test environment.
- `index.test.ts` is the root test suite file which imports all the test suites.
- `TestDbMngr.ts` is a helper class to manage test databases (i.e. creating, dropping, etc.).

### Factory Pattern[​](https://docs.nocodb.com/engineering/unit-testing#factory-pattern "Direct link to Factory Pattern")

- Use factories for create/update/delete data. No data should be directly create/updated/deleted in the test.
- While writing a factory make sure that it can be used with as less parameters as possible and use default values for other parameters.
- Use named parameters for factories.

```
createUser({ email, password})
```

- Use one file per factory.

### Walk through of writing a Unit Test[​](https://docs.nocodb.com/engineering/unit-testing#walk-through-of-writing-a-unit-test "Direct link to Walk through of writing a Unit Test")

We will create an `Table` test suite as an example.

#### Configure test[​](https://docs.nocodb.com/engineering/unit-testing#configure-test "Direct link to Configure test")

We will configure `beforeEach` which is called before each test is executed. We will use `init` function from `nocodb/packages/nocodb/tests/unit/init/index.ts`, which is a helper function which configures the test environment(i.e resetting state, etc.).

`init` does the following things -

- It initializes a `Noco` instance(reused in all tests).
- Restores `meta` and `sakila` database to its initial state.
- Creates the root user.
- Returns `context` which has `auth token` for the created user, node server instance(`app`), and `dbConfig`.

We will use `createProject` and `createProject` factories to create a project and a table.

```
let context;

beforeEach(async function () {
  context = await init();

  project = await createProject(context);
  table = await createTable(context, project);
});
```

#### Test case[​](https://docs.nocodb.com/engineering/unit-testing#test-case "Direct link to Test case")

We will use `it` function to create a test case. We will use `supertest` to make a request to the server. We use `expect`(`chai`) to assert the response.

```
it('Get table list', async function () {
  const response = await request(context.app)
    .get(`/api/v1/db/meta/projects/${project.id}/tables`)
    .set('xc-auth', context.token)
    .send({})
    .expect(200);

  expect(response.body.list).to.be.an('array').not.empty;
});
```

info

We can also run individual test by using `.only` in `describe` or `it` function and the running the test command.

```
it.only('Get table list', async () => {
```

#### Integrating the New Test Suite[​](https://docs.nocodb.com/engineering/unit-testing#integrating-the-new-test-suite "Direct link to Integrating the New Test Suite")

We create a new file `table.test.ts` in `packages/nocodb/tests/unit/rest/tests` directory.

```
import 'mocha';
import request from 'supertest';
import init from '../../init';
import { createTable, getAllTables } from '../../factory/table';
import { createProject } from '../../factory/project';
import { defaultColumns } from '../../factory/column';
import Model from '../../../../src/lib/models/Model';
import { expect } from 'chai';

function tableTest() {
  let context;
  let project;
  let table;

  beforeEach(async function () {
    context = await init();

    project = await createProject(context);
    table = await createTable(context, project);
  });

  it('Get table list', async function () {
    const response = await request(context.app)
      .get(`/api/v1/db/meta/projects/${project.id}/tables`)
      .set('xc-auth', context.token)
      .send({})
      .expect(200);

    expect(response.body.list).to.be.an('array').not.empty;
  });
}

export default function () {
  describe('Table', tableTests);
}
```

We can then import the `Table` test suite to `Rest` test suite in `packages/nocodb/tests/unit/rest/index.test.ts` file(`Rest` test suite is imported in the root test suite file which is `packages/nocodb/tests/unit/index.test.ts`).

### Seeding Sample DB (Sakila)[​](https://docs.nocodb.com/engineering/unit-testing#seeding-sample-db-sakila "Direct link to Seeding Sample DB (Sakila)")

```

function tableTest() {
  let context;
  let sakilaProject: Project;
  let customerTable: Model;

  beforeEach(async function () {
    context = await init();
    
    /******* Start : Seeding sample database **********/
    sakilaProject = await createSakilaProject(context);
    /******* End : Seeding sample database **********/
    
    customerTable = await getTable({project: sakilaProject, name: 'customer'})
  });

  it('Get table data list', async function () {
    const response = await request(context.app)
      .get(`/api/v1/db/data/noco/${sakilaProject.id}/${customerTable.id}`)
      .set('xc-auth', context.token)
      .send({})
      .expect(200);

    expect(response.body.list[0]['FirstName']).to.equal('MARY');
  });
}
```

# Playwright E2E testing

## How to run tests[​](https://docs.nocodb.com/engineering/playwright#how-to-run-tests "Direct link to How to run tests")

All the tests reside in `tests/playwright` folder.

Make sure to install the dependencies (in the playwright folder):

```
pnpm --filter=playwright install
pnpm exec playwright install --with-deps chromium
```

### Run Test Server[​](https://docs.nocodb.com/engineering/playwright#run-test-server "Direct link to Run Test Server")

Start the backend test server (in `packages/nocodb` folder):

```
pnpm run watch:run:playwright
```

Start the frontend test server (in `packages/nc-gui` folder):

```
NUXT_PAGE_TRANSITION_DISABLE=true pnpm run dev
```

### Running all tests[​](https://docs.nocodb.com/engineering/playwright#running-all-tests "Direct link to Running all tests")

For selecting db type, rename `.env.example` to `.env` and set `E2E_DEV_DB_TYPE` to `sqlite`(default), `mysql` or `pg`.

headless mode(without opening browser):

```
pnpm run test
```

with browser:

```
pnpm run test:debug
```

For setting up mysql(sakila):

```
docker-compose -f ./tests/playwright/scripts/docker-compose-mysql-playwright.yml  up -d
```

For setting up postgres(sakila):

```
docker-compose -f ./tests/playwright/scripts/docker-compose-playwright-pg.yml 
```

### Running individual tests[​](https://docs.nocodb.com/engineering/playwright#running-individual-tests "Direct link to Running individual tests")

Add `.only` to the test you want to run:

```
test.only('should login', async ({ page }) => {
  // ...
})
```

```
pnpm run test
```

## Concepts[​](https://docs.nocodb.com/engineering/playwright#concepts "Direct link to Concepts")

### Independent tests[​](https://docs.nocodb.com/engineering/playwright#independent-tests "Direct link to Independent tests")

- All tests are independent of each other.
- Each test starts with a fresh project with a fresh sakila database(option to not use sakila db is also there).
- Each test creates a new user(email as `user@nocodb.com`) and logs in with that user to the dashboard.

Caveats:

- Some stuffs are shared i.e, users, plugins etc. So be catious while writing tests touching that. A fix for this is in the works.
- In test, we prefix email and project with the test id, which will be deleted after the test is done.

### What to test[​](https://docs.nocodb.com/engineering/playwright#what-to-test "Direct link to What to test")

- UI verification. This includes verifying the state of the UI element, i.e if the element is visible, if the element has a particular text etc.
- Test should verify all user flow. A test has a default timeout of 60 seconds. If a test is taking more than 60 seconds, it is a sign that the test should be broken down into smaller tests.
- Test should also verify all the side effects the feature(i.e. On adding a new field type, should verify field deletion as well) will have, and also error cases.
- Test name should be descriptive. It should be easy to understand what the test is doing by just reading the test name.

### Playwright[​](https://docs.nocodb.com/engineering/playwright#playwright "Direct link to Playwright")

- Playwright is a nodejs library for automating chromium, firefox and webkit.
- For each test, a new browser context is created. This means that each test runs in a new incognito window.
- For assertion always use `expect` from `@playwright/test` library. This library provides a lot of useful assertions, which also has retry logic built in.

## Page Objects[​](https://docs.nocodb.com/engineering/playwright#page-objects "Direct link to Page Objects")

- Page objects are used to abstract over the components/page. This makes the tests more readable and maintainable.
- All page objects are in `tests/playwright/pages` folder.
- All the test related code should be in page objects.
- Methods should be as thin as possible and its better to have multiple methods than one big method, which improves reusability.

The methods of a page object can be classified into 2 categories:

- Actions: Performs an UI actions like click, type, select etc. Is also responsible for waiting for the element to be ready and the action to be performed. This included waiting for API calls to complete.
- Assertions: Asserts the state of the UI element, i.e if the element is visible, if the element has a particular text etc. Use `expect` from `@playwright/test` and if not use `expect.poll` to wait for the assertion to pass.

## Writing a test[​](https://docs.nocodb.com/engineering/playwright#writing-a-test "Direct link to Writing a test")

Let's write a test for testing filter functionality.

For simplicity, we will have `DashboardPage` implemented, which will have all the methods related to dashboard page and also its child components like Grid, etc.

### Create a test suite[​](https://docs.nocodb.com/engineering/playwright#create-a-test-suite "Direct link to Create a test suite")

Create a new file `filter.spec.ts` in `tests/playwright/tests` folder and use `setup` method to create a new project and user.

```
import { test, expect } from '@playwright/test';
import setup, { NcContext } from '../setup';

test.describe('Filter', () => {
  let context: NcContext;

  test.beforeEach(async ({ page }) => {
    context = await setup({ page });
  })

  test('should filter', async ({ page }) => {
    // ...
  });
});
```

### Create a page object[​](https://docs.nocodb.com/engineering/playwright#create-a-page-object "Direct link to Create a page object")

Since filter is UI wise scoped to a `Toolbar` , we will add filter page object to `ToolbarPage` page object.

```
export class ToolbarPage extends BasePage {
  readonly parent: GridPage | GalleryPage | FormPage | KanbanPage;
  readonly filter: ToolbarFilterPage;

  constructor(parent: GridPage | GalleryPage | FormPage | KanbanPage) {
    super(parent.rootPage);
    this.parent = parent;
    this.filter = new ToolbarFilterPage(this);
  }
}
```

We will create `ToolbarFilterPage` page object, which will have all the methods related to filter.

```
export class ToolbarFilterPage extends BasePage {
  readonly toolbar: ToolbarPage;

  constructor(toolbar: ToolbarPage) {
    super(toolbar.rootPage);
    this.toolbar = toolbar;
  }
}
```

Here `BasePage` is an abstract class, which used to enforce structure for all page objects. Thus all page object _should_ inherit `BasePage`.

- Helper methods like `waitForResponse` and `getClipboardText` (this can be access on any page object, with `this.waitForResponse`)
- Provides structure for page objects, enforces all Page objects to have `rootPage` property, which is the page object created in the test setup.
- Enforces all pages to have a `get` method which will return the locator of the main container of that page, hence we can have focused dom selection, i.e.

```
// This will only select the button inside the container of the concerned page
await this.get().querySelector('button').count();
```

### Writing an action method[​](https://docs.nocodb.com/engineering/playwright#writing-an-action-method "Direct link to Writing an action method")

This a method which will reset/clear all the filters. Since this is an action method, it will also wait for the `delete` filter API to return. Ignoring this API call will cause flakiness in the test, down the line.

```
async resetFilter() {
  await this.waitForResponse({
    uiAction: async () => await this.get().locator('.nc-filter-item-remove-btn').click(),
    httpMethodsToMatch: ['DELETE'],
    requestUrlPathToMatch: '/api/v1/db/meta/filters/',
  });
}
```

### Writing an assertion/verification method[​](https://docs.nocodb.com/engineering/playwright#writing-an-assertionverification-method "Direct link to Writing an assertion/verification method")

Here we use `expect` from `@playwright/test` library, which has retry logic built in.

```
import { expect } from '@playwright/test';

async verifyFilter({ title }: { title: string }) {
  await expect(
    this.get().locator(`[data-testid="nc-fields-menu-${title}"]`).locator('input[type="checkbox"]')
  ).toBeChecked();
}
```

## Tips to avoid flakiness[​](https://docs.nocodb.com/engineering/playwright#tips-to-avoid-flakiness "Direct link to Tips to avoid flakiness")

- If an UI action, causes an API call or the UI state change, then wait for that API call to complete or the UI state to change.
- What to wait out can be situation specific, but in general, is best to wait for the final state to be reached, i.e. in the case of creating filter, while it seems like waiting for the filter API to complete is enough, but after its return the table records are reloaded and the UI state changes, so its better to wait for the table records to be reloaded.

## Accessing playwright report in the CI[​](https://docs.nocodb.com/engineering/playwright#accessing-playwright-report-in-the-ci "Direct link to Accessing playwright report in the CI")

- Open `Summary` tab in the CI workflow in github actions.
- Scroll down to `Artifacts` section.
- Access reports which suffixed with the db type and shard number(corresponding to the CI workerflow name). i.e `playwright-report-mysql-2` is for `playwright-mysql-2` workflow.
- Download it and run `pnpm install -D @playwright/test && npx playwright show-report ./` inside the downloaded folder.

# Releases & builds

## Builds of NocoDB[​](https://docs.nocodb.com/engineering/builds-and-releases#builds-of-nocodb "Direct link to Builds of NocoDB")

There are 3 kinds of docker builds in NocoDB

- Release builds [nocodb/nocodb](https://hub.docker.com/r/nocodb/nocodb) : built during NocoDB release.
- Daily builds [nocodb/nocodb-daily](https://hub.docker.com/r/nocodb/nocodb-daily) : built every 6 hours from Develop branch.
- Timely builds [nocodb/nocodb-timely](https://hub.docker.com/r/nocodb/nocodb-timely): built for every PR and manually triggered PRs.

Below is an overview of how to make these builds and what happens behind the scenes.

## Release builds[​](https://docs.nocodb.com/engineering/builds-and-releases#release-builds "Direct link to Release builds")

### How to make a release build ?[​](https://docs.nocodb.com/engineering/builds-and-releases#how-to-make-a-release-build-- "Direct link to How to make a release build  ?")

- Click [NocoDB release action](https://github.com/nocodb/nocodb/actions/workflows/release-nocodb.yml)
    
- You should see the below screen
    
    ![image](https://user-images.githubusercontent.com/35857179/167240353-a02f690f-c865-4ade-8645-64382405c9ea.png)
    
- Change `Use workflow from` to `Branch: master`. If you choose the wrong branch, the workflow will be ended.
    
    ![image](https://user-images.githubusercontent.com/35857179/167240383-dda05f76-8323-4f4a-b3e7-9db886dbd68d.png)
    
- Then there would be two cases - you can either leave target tag and pervious tag blank or manually input some values
    
- Target Tag means the target deployment version, while Previous Tag means the latest version as of now. Previous Tag is used for Release Note only - showing the file / commit differences between two tags.
    

### Tagging[​](https://docs.nocodb.com/engineering/builds-and-releases#tagging "Direct link to Tagging")

The naming convention would be following given the actual release tag is `0.100.0`

- `0.100.0-beta.0` (first version of pre-release)
- `0.100.0-beta.1` (include bug fix changes on top of the previous version)
- `0.100.0-beta.2`(include bug fix changes on top of the previous version)
- and so on ...
- `0.100.0` (actual release)
- `0.100.1` (minor bug fix release)
- `0.100.2` (minor bug fix release)

### Case 1: Leaving inputs blank[​](https://docs.nocodb.com/engineering/builds-and-releases#case-1-leaving-inputs-blank "Direct link to Case 1: Leaving inputs blank")

- If Previous Tag is blank, then the value will be fetched from [latest](https://github.com/nocodb/nocodb/releases/latest)
- If Target Tag is blank, then the value will be Previous Tag plus one. Example: 0.90.11 (Previous Tag) + 0.0.1 = 0.90.12 (Target Tag)

### Case 2: Manually Input[​](https://docs.nocodb.com/engineering/builds-and-releases#case-2-manually-input "Direct link to Case 2: Manually Input")

Why? Sometimes we may mess up in NPM deployment. As NPM doesn't allow us to redeploy to the same tag again, in this case we cannot just use the previous tag + 1. Therefore, we need to use previous tag + 2 instead and we manually configure it.

- After that, click `Run workflow` to start
- You can see Summary for the overall job status.
- Once `release-draft-note` and `release-executables` is finished, then go to [releases](https://github.com/nocodb/nocodb/releases), edit the draft note and save as draft for time being.
    - Example: Adding header, update content if necessary, and click `Auto-generate release notes` to include more info.
- Once `release-docker` is finished, then test it locally first. You'll be expected to see `Upgrade Available` notification in UI as we haven't published the release note. (the version is retrieved from there)
- Once everything is finished, then publish the release note and the deployment is considered as DONE.

### How does release action work ?[​](https://docs.nocodb.com/engineering/builds-and-releases#how-does-release-action-work- "Direct link to How does release action work ?")

#### validate-branch[​](https://docs.nocodb.com/engineering/builds-and-releases#validate-branch "Direct link to validate-branch")

To check if `github.ref` is master. Otherwise, other branches will be not accepted.

#### process-input[​](https://docs.nocodb.com/engineering/builds-and-releases#process-input "Direct link to process-input")

To enrich target tag or previous tag if necessary.

#### pr-to-master[​](https://docs.nocodb.com/engineering/builds-and-releases#pr-to-master "Direct link to pr-to-master")

Automate a PR from develop to master branch so that we know the actual differences between the previous tag and the current tag. We choose master branch for a deployment base.

#### release-npm[​](https://docs.nocodb.com/engineering/builds-and-releases#release-npm "Direct link to release-npm")

Build frontend and backend and release them to NPM. The changes during built such as version bumping will be committed and pushed to a temporary branch and an automated PR will be created and merged to master branch.

Note that once you publish with a certain tag, you cannot publish with the same tag again.

#### release-draft-note[​](https://docs.nocodb.com/engineering/builds-and-releases#release-draft-note "Direct link to release-draft-note")

Generate a draft release note. Some actions need to be done after this step.

#### release-docker[​](https://docs.nocodb.com/engineering/builds-and-releases#release-docker "Direct link to release-docker")

Build docker image and publish it to Docker Hub. It may take around 15 - 30 mins.

#### close-issues[​](https://docs.nocodb.com/engineering/builds-and-releases#close-issues "Direct link to close-issues")

Open issues marked with label `Status: Fixed` and `Status: Resolved` will be closed by bot automatically with comment mentioning the fix is included in which version.

Example:

![image](https://user-images.githubusercontent.com/35857179/167241574-f8f7061f-c689-444a-b761-0a727974c53f.png)

#### publish-docs[​](https://docs.nocodb.com/engineering/builds-and-releases#publish-docs "Direct link to publish-docs")

Publish Documentations

#### update-sdk-path[​](https://docs.nocodb.com/engineering/builds-and-releases#update-sdk-path "Direct link to update-sdk-path")

`nocodb-sdk` is used in frontend and backend. However, in develop branch, the value would be `file:../nocodb-sdk` for development purpose (so that the changes done in nocodb-sdk in develop will be included in frontend and backend). During the deployment, the value will be changed to the target tag. This job is to update them back.

#### sync-to-develop[​](https://docs.nocodb.com/engineering/builds-and-releases#sync-to-develop "Direct link to sync-to-develop")

Once the deployment is finished, there would be some new changes being pushed to master branch. This job is to sync the changes back to develop so that both branch won't have any difference.

## Daily builds[​](https://docs.nocodb.com/engineering/builds-and-releases#daily-builds "Direct link to Daily builds")

### What are daily builds ?[​](https://docs.nocodb.com/engineering/builds-and-releases#what-are-daily-builds- "Direct link to What are daily builds ?")

- NocoDB creates every 6 hours from develop branches and publishes as nocodb/nocodb-daily
- This is so that we can easily try what is in the develop branch easily.

### Docker images[​](https://docs.nocodb.com/engineering/builds-and-releases#docker-images "Direct link to Docker images")

- The docker images will be built and pushed to Docker Hub (See [nocodb/nocodb-daily](https://hub.docker.com/r/nocodb/nocodb-daily/tags) for the full list).

## Timely builds[​](https://docs.nocodb.com/engineering/builds-and-releases#timely-builds "Direct link to Timely builds")

### What are timely builds ?[​](https://docs.nocodb.com/engineering/builds-and-releases#what-are-timely-builds- "Direct link to What are timely builds ?")

NocoDB has github actions which creates docker and binaries for each PR! And these can be found as a **comment on the last commit** of the PR.

Example shown below

- Go to a PR and click on the comment.

![Screenshot 2023-01-23 at 15 46 36](https://user-images.githubusercontent.com/5435402/214083736-80062398-3712-430f-9865-86b110090c91.png)

- Click on the link to copy the docker image and run it locally.

![Screenshot 2023-01-23 at 15 46 55](https://user-images.githubusercontent.com/5435402/214083755-945d9485-2b9e-4739-8408-068bdf4a84b7.png)

This is to

- reduce pull request cycle time
- allow issue reporters / reviewers to verify the fix without setting up their local machines

### Docker images[​](https://docs.nocodb.com/engineering/builds-and-releases#docker-images-1 "Direct link to Docker images")

When a non-draft Pull Request is created, reopened or synchronized, a timely build for Docker would be triggered for the changes only included in the following paths.

- `packages/nocodb-sdk/**`
- `packages/nc-gui/**`
- `packages/nocodb/**`

The docker images will be built and pushed to Docker Hub (See [nocodb/nocodb-timely](https://hub.docker.com/r/nocodb/nocodb-timely/tags) for the full list). Once the image is ready, GitHub bot will add a comment with the command in the pull request. The tag would be `<NOCODB_CURRENT_VERSION>-pr-<PR_NUMBER>-<YYYYMMDD>-<HHMM>`.

![image](https://user-images.githubusercontent.com/35857179/175012097-240dab05-da93-4c4e-87c1-1c36fb1350bd.png)

## Executables or Binaries[​](https://docs.nocodb.com/engineering/builds-and-releases#executables-or-binaries "Direct link to Executables or Binaries")

Similarly, we provide a timely build for executables for non-docker users. The source code will be built, packaged as binary files, and pushed to GitHub (See [nocodb/nocodb-timely](https://github.com/nocodb/nocodb-timely/releases) for the full list).

Currently, we only support the following targets:

- `node16-linux-arm64`
- `node16-macos-arm64`
- `node16-win-arm64`
- `node16-linux-x64`
- `node16-macos-x64`
- `node16-win-x64`

Once the executables are ready, GitHub bot will add a comment with the commands in the pull request.

![image](https://user-images.githubusercontent.com/35857179/175012070-f5f3e7b8-6dc5-4d1c-9f7e-654bc5039521.png)

NocoDB creates Docker and Binaries for each PR.

This is to

- reduce pull request cycle time
- allow issue reporters / reviewers to verify the fix without setting up their local machines

# i18n translation

- NocoDB supports 30+ foreign languages & community contributions are now simplified via [Crowdin](https://crowdin.com/).

## How to add / edit translations ?[​](https://docs.nocodb.com/engineering/translation#how-to-add--edit-translations- "Direct link to How to add / edit translations ?")

### Using GitHub[​](https://docs.nocodb.com/engineering/translation#using-github "Direct link to Using GitHub")

- For English, make changes directly to [en.json](https://github.com/nocodb/nocodb/blob/develop/packages/nc-gui/lang/en.json) & commit to `develop`
- For any other language, use `crowdin` option.

### Using Crowdin[​](https://docs.nocodb.com/engineering/translation#using-crowdin "Direct link to Using Crowdin")

- Setup [Crowdin](https://crowdin.com/) account
- Join [NocoDB](https://crowdin.com/project/nocodb) project

![Screenshot 2022-09-08 at 10 26 23 PM](https://user-images.githubusercontent.com/86527202/189181511-51b8671e-bee8-45d5-8216-a4a031bc6309.png)

- Click the language that you wish to contribute

![Screenshot 2022-09-08 at 10 29 56 PM](https://user-images.githubusercontent.com/86527202/189182132-0eed7d5a-eaa1-43e1-929d-688f375763c1.png)

- Click the `Translate` button; this opens up `Crowdin Online Editor`

![Screenshot 2022-09-08 at 10 32 17 PM](https://user-images.githubusercontent.com/86527202/189182450-999124e8-566c-40af-9d3c-731a11c1b6aa.png)

- Select string in `English` on the left-hand menu bar [1]
- Propose changes [2]
- Save [3] Note: Crowdin provides translation recommendation's as in [4]. Click directly if it's apt

![Screenshot 2022-09-08 at 10 37 38 PM](https://user-images.githubusercontent.com/86527202/189184278-69d688ed-4e5a-4d5a-b629-9f6d10d79346.png)

A GitHub Pull Request will be automatically triggered (periodicity- 6 hours). We will follow up on remaining integration work items.

#### Reference[​](https://docs.nocodb.com/engineering/translation#reference "Direct link to Reference")

Refer following articles to get additional details about Crowdin Portal usage

- [Translator Introduction](https://support.crowdin.com/crowdin-intro/)
- [Volunteer Translation Introduction](https://support.crowdin.com/for-volunteer-translators/)
- [Online Editor](https://support.crowdin.com/online-editor/)

## How to add a new language ?[​](https://docs.nocodb.com/engineering/translation#how-to-add-a-new-language- "Direct link to How to add a new language ?")

#### GitHub changes[​](https://docs.nocodb.com/engineering/translation#github-changes "Direct link to GitHub changes")

- Update enumeration in `enums.ts` [packages/nc-gui/lib/enums.ts]
- Map JSON path in `a.i18n.ts` [packages/nc-gui/plugins/a.i18n.ts]

#### Crowdin changes [admin only][​](https://docs.nocodb.com/engineering/translation#crowdin-changes-admin-only "Direct link to Crowdin changes [admin only]")

- Open `NocoDB` project
- Click on `Language` on the home tab
- Select target language, `Update`
- Update array in `tests/playwright/tests/language.spec.ts`

![Screenshot 2022-09-08 at 10 52 59 PM](https://user-images.githubusercontent.com/86527202/189186570-5c1c7cad-6d3f-4937-ab4d-fa7ebe022cb1.png)

![Screenshot 2022-09-08 at 10 54 04 PM](https://user-images.githubusercontent.com/86527202/189186632-0b9f5f55-0550-4d8f-a8ae-7e9b9076774e.png)

## String Categories[​](https://docs.nocodb.com/engineering/translation#string-categories "Direct link to String Categories")

- **General**: simple & common tokens (save, cancel, submit, open, close, home, and such)
- **Objects**: objects from NocoDB POV (project, table, field, view, page, and such)
- **Title**: screen headers (compact) (menu headers, modal headers)
- **Lables**: text box/ radio/ field headers (few words) (Labels over textbox, radio buttons, and such)
- **Activity**/ actions: work items (few words) (Create Project, Delete Table, Add Record, and such)
- **Tooltip**: additional information associated with work items (usually lengthy) (Additional information provided for activity)
- **Placeholder**: placeholders associated with various textboxes (Text placeholders)
- **Msg**
    - Info: general/success category for everything
    - Error: warnings & errors
    - Toast: pop-up toast messages

> Note: string name should be in camelCase. Use above list as priority order in case of ambiguity.


# Writing docs

This article discusses some of the protocol and conventions to be followed while writing docs.

## Folder Structure[​](https://docs.nocodb.com/engineering/writing-docs#folder-structure "Direct link to Folder Structure")

- Docs follow object-oriented approach. Each folder represents an object and each file represents procedures associated with that object.
- Each folder contains an `_category_.json` file which contains the metadata for that object.

```
{
  "label": "Engineering",
  "collapsible": true,
  "collapsed": true
}
```

## File Structure[​](https://docs.nocodb.com/engineering/writing-docs#file-structure "Direct link to File Structure")

- Add following metadata to the top of each file.

```
---
title: "Writing docs"
description: "Overview to writing docs"
tags: ['Engineering']
keywords: ['Engineering', Writing docs', 'Docs conventions']
---
```

- `title` is the title of the article that appears on the sidebar and on the top of the article.
- `description` is the description of the article that appears in search results.
- `tags` are the tags associated with the article. Tags are used to group articles together. For example, all articles with the tag `Workspaces` will be grouped together.
- `keywords` are the keywords associated with the article. Keywords are used to improve search results. For example, if the user searches for `Create workspace`, then the article with the keyword `Create workspace` will be displayed in the search results.

## Nomenclature[​](https://docs.nocodb.com/engineering/writing-docs#nomenclature "Direct link to Nomenclature")

- Folder names & file name are
    - in kebab-case.
    - prefix with a number that represents the order in which the folder/file should be displayed in the sidebar.
    - prefix number is always a 3-digit number.
    - For example, `010.account-settings`.
- Only first letter of the folder/file name is capitalized. Second letter onwards, first letter is capitalized only if it is a proper noun.

## Tags[​](https://docs.nocodb.com/engineering/writing-docs#tags "Direct link to Tags")

- First letter of each tag is capitalized.
- Tags usually are Objects or Actions. Add a tag only if we are sure that the tag will be used in multiple places. Example: 'Create' - we can have `Create project`, `Create user`, `Create API token` etc.

### Active Tags[​](https://docs.nocodb.com/engineering/writing-docs#active-tags "Direct link to Active Tags")

Tags that are currently being used in the docs are listed below. See if you can reuse any of these tags before adding a new tag.

## Description[​](https://docs.nocodb.com/engineering/writing-docs#description "Direct link to Description")

- Description should be crisp and to the point. Preferably one line.
- Refer to the description associated with the tag to get an idea of how the description should be.
- Descriptions appear in the search results (when searched by tags). So, it should be descriptive enough to give the user an idea of what the article is about.

![Search by tags](https://docs.nocodb.com/assets/images/engineering-search-by-tags-9453d5cf2d1534c2f812c7aee697fe43.png)

## Images[​](https://docs.nocodb.com/engineering/writing-docs#images "Direct link to Images")

- Annotated images should be placed in `img/v2` folder.
- For every annotated image, there should be a corresponding unannotated image in the `img/v2-unannotated` folder.
- Images are kept in the same folder structure as the docs.
- Use `Skitch` for annotations.

## Before you commit[​](https://docs.nocodb.com/engineering/writing-docs#before-you-commit "Direct link to Before you commit")

- Use `npm run build` to build the docs.
- Ensure that the build is successful & there are no errors/warnings related to missing links, images, etc.