> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://notion.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://notion.ferndocs.com/_mcp/server.

# Update a database

PATCH https://api.notion.com/v1/databases/{database_id}/
Content-Type: application/json

This page describes the API for versions up to and including `2022-06-28`. In the new `2025-09-03` version, the concepts of databases and data sources were split up, as described in [Upgrading to 2025-09-03](/docs/upgrade-guide-2025-09-03).

Refer to the new APIs instead:

* [Update a database](/reference/database-update)
* [Update a data source](/reference/update-a-data-source)

Updates the database object — the title, description, or properties — of a specified database.

Returns the updated [database object](https://developers.notion.com/reference/database).

Database properties represent the columns (or schema) of a database. To update the properties of a database, use the `properties` [body param](https://developers.notion.com/reference/update-property-schema-object) with this endpoint. Learn more about database properties in the [database properties](https://developers.notion.com/reference/property-object) and [Update database properties](https://developers.notion.com/reference/update-property-schema-object) docs.

To update a `relation` database property, share the related database with the integration. Learn more about relations in the [database properties](https://developers.notion.com/reference/property-object#relation) page.

For an overview of how to use the REST API with databases, refer to the [Working with databases](https://developers.notion.com/docs/working-with-databases) guide.

### How database property type changes work

All properties in pages are stored as rich text. Notion will convert that rich text based on the types defined in a database's schema. When a type is changed using the API, the data will continue to be available, it is just presented differently.

For example, a multi select property value is represented as a comma-separated list of strings (eg. "1, 2, 3") and a people property value is represented as a comma-separated list of IDs. These are compatible and the type can be converted.

Note: Not all type changes work. In some cases data will no longer be returned, such as people type → file type.

### Interacting with database rows

This endpoint cannot be used to update database rows.

To update the properties of a database row — rather than a column — use the [Update page properties](https://developers.notion.com/reference/patch-page) endpoint. To add a new row to a database, use the [Create a page](https://developers.notion.com/reference/post-page) endpoint.

### Recommended database schema size limit

Developers are encouraged to keep their database schema size to a maximum of **50KB**. To stay within this schema size limit, the number of properties (or columns) added to a database should be managed.

Database schema updates that are too large will be blocked by the REST API to help developers keep their database queries performant.

### Errors

Each Public API endpoint can return several possible error codes. See the [Error codes section](https://developers.notion.com/reference/status-codes#error-codes) of the Status codes documentation for more information.

* `formula`
* `select`
* `status`
* [Synced content](https://www.notion.so/help/guides/synced-databases-bridge-different-tools)
* A `multi_select` database property's options values. An option can be removed, but not updated.

To update a database [relation](https://www.notion.so/help/relations-and-rollups#what-is-a-database-relation) property, the related database must also be shared with your integration.

Reference: https://notion.ferndocs.com/reference/update-a-database

## Request

### Path parameters

- `database_id` (string, required) — identifier for a Notion database

### Headers

- `Notion-Version` (string, required) — The [API version](/reference/versioning) to use for this request. The latest version is `<<latestNotionVersion>>`.

### Body (application/json)

This endpoint expects an object.

- `title` (list of any, optional) — An array of [rich text objects](https://developers.notion.com/reference/rich-text) that represents the title of the database that is displayed in the Notion UI. If omitted, then the database title remains unchanged.
- `description` (list of any, optional) — An array of [rich text objects](https://developers.notion.com/reference/rich-text) that represents the description of the database that is displayed in the Notion UI. If omitted, then the database description remains unchanged.
- `properties` (string, optional) — The properties of a database to be changed in the request, in the form of a JSON object. If updating an existing property, then the keys are the names or IDs of the properties as they appear in Notion, and the values are [property schema objects](ref:property-schema-object). If adding a new property, then the key is the name of the new database property and the value is a [property schema object](ref:property-schema-object).

## Response

### 200

200

## Errors

### 400 Bad Request Error

400

- `Update-a-databaseRequestBadRequestError`

### 404 Not Found Error

404

- `object` (string, optional)
- `status` (integer, optional, default: 0)
- `code` (string, optional)
- `message` (string, optional)

### 429 Too Many Requests Error

429

- `object` (string, optional)
- `status` (integer, optional, default: 0)
- `code` (string, optional)
- `message` (string, optional)

## Types

### UpdateADatabaseRequestBadRequestError0

- `object` (string, optional)
- `status` (integer, optional, default: 0)
- `code` (string, optional)
- `message` (string, optional)

### UpdateADatabaseRequestBadRequestError1

- `object` (string, optional)
- `status` (integer, optional, default: 0)
- `code` (string, optional)
- `message` (string, optional)

## Examples

**Request**

```json
{}
```

**Response**

```json
{}
```

**SDK Code**

```python
import requests

url = "https://api.notion.com/v1/databases/database_id/"

payload = {}
headers = {
    "Notion-Version": "Notion-Version",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.notion.com/v1/databases/database_id/';
const options = {
  method: 'PATCH',
  headers: {'Notion-Version': 'Notion-Version', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.notion.com/v1/databases/database_id/"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Notion-Version", "Notion-Version")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.notion.com/v1/databases/database_id/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Notion-Version"] = 'Notion-Version'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.notion.com/v1/databases/database_id/")
  .header("Notion-Version", "Notion-Version")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.notion.com/v1/databases/database_id/', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
    'Notion-Version' => 'Notion-Version',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.notion.com/v1/databases/database_id/");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Notion-Version", "Notion-Version");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Notion-Version": "Notion-Version",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.notion.com/v1/databases/database_id/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```