---
title: Manage DBRP mappings
description: Create and manage database and retention policy (DBRP) mappings to use InfluxQL to query InfluxDB buckets.
url: https://docs.influxdata.com/influxdb/v2/query-data/influxql/dbrp/
estimated_tokens: 5154
product: InfluxDB OSS v2
version: v2
---

# Manage DBRP mappings

This page documents an earlier version of InfluxDB OSS. [InfluxDB 3 Core](/influxdb3/core/) is the latest stable version.

#### API token hashing is enabled by default in InfluxDB OSS 2.9.0

Stronger token security: tokens are stored as hashes on disk, so a copy of the database file doesn’t expose usable tokens. Existing tokens are hashed on first startup and the original strings can’t be recovered afterward — **capture any plaintext tokens you still need before you upgrade**.

For more information, see [Token hashing](/influxdb/v2/admin/tokens/#token-hashing).

InfluxQL requires a database and retention policy (DBRP) combination in order to query data. In InfluxDB 2.9, databases and retention policies have been combined and replaced by InfluxDB [buckets](/influxdb/v2/reference/glossary/#bucket). To query InfluxDB 2.9 with InfluxQL, the specified DBRP combination must be mapped to a bucket.

-   [Automatic DBRP mapping](#automatic-dbrp-mapping)
    
-   [Virtual DBRP mappings](#virtual-dbrp-mappings)
    
-   [Create DBRP mappings](#create-dbrp-mappings)
    
-   [List DBRP mappings](#list-dbrp-mappings)
    
-   [Update a DBRP mapping](#update-a-dbrp-mapping)
    
-   [Delete a DBRP mapping](#delete-a-dbrp-mapping)
    

## Automatic DBRP mapping

InfluxDB 2.9 will automatically create DBRP mappings for you during the following operations:

-   Writing to the [`/write` v1 compatibility endpoint](/influxdb/v2/reference/api/influxdb-1x/write/)
    
-   [Upgrading from InfluxDB 1.x to 2.9](/influxdb/v2/upgrade/v1-to-v2/)
    
-   Creating a bucket ([virtual DBRPs](#virtual-dbrp-mappings))
    

For more information, see [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/).

## Virtual DBRP mappings

InfluxDB 2.9 provides “virtual” DBRP mappings for any bucket that does not have an explicit DBRP mapping associated with it. Virtual DBRP mappings use the bucket name to provide a DBRP mapping that can be used without having to explicitly define a mapping.

Virtual DBRP mappings are read-only. To override a virtual DBRP mapping, [create an explicit mapping](#create-dbrp-mappings).

For information about how virtual DBRP mappings are created, see [Database and retention policy mapping – When creating a bucket](/influxdb/v2/reference/api/influxdb-1x/dbrp/#when-creating-a-bucket).

## Create DBRP mappings

Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2/reference/api/) to create DBRP mappings.

#### A DBRP combination can only be mapped to a single bucket

Each unique DBRP combination can only be mapped to a single bucket. If you map a DBRP combination that is already mapped to another bucket, it will overwrite the existing DBRP mapping.

<!-- Tabbed content: Select one of the following options -->

**influx CLI:**

Use the [`influx v1 dbrp create` command](/influxdb/v2/reference/cli/influx/v1/dbrp/create/) to map an unmapped bucket to a database and retention policy. Include the following:

\* Required

-   \* **org** and **token** to authenticate. We recommend setting your organization and token to your active InfluxDB connection configuration in the influx CLI, so you don’t have to add these parameters to each command. To set up your active InfluxDB configuration, see [`influx config set`](/influxdb/v2/reference/cli/influx/config/set/).
-   \* **database name** to map
-   \* **retention policy** name to map
-   \* [Bucket ID](/influxdb/v2/admin/buckets/view-buckets/#view-buckets-in-the-influxdb-ui) to map to
-   **Default flag** to set the provided retention policy as the default retention policy for the database

```sh
influx v1 dbrp create \
  --db example-db \
  --rp example-rp \
  --bucket-id 00oxo0oXx000x0Xo \
  --default
```

**InfluxDB API:**

Use the [`/api/v2/dbrps` API endpoint](/influxdb/v2/api/dbrps/) to create a new DBRP mapping.

[POST http://localhost:8086/api/v2/dbrps](/influxdb/v2/api/dbrps/)

Include the following:

-   **Request method:** `POST`
-   **Headers:**
    -   **Authorization:** `Token` schema with your InfluxDB [API token](/influxdb/v2/admin/tokens/)
    -   **Content-type:** `application/json`
-   **Request body:** JSON object with the following fields:  
    \* Required
    -   \* **bucketID:** [bucket ID](/influxdb/v2/admin/buckets/view-buckets/)
    -   \* **database:** database name
    -   **default:** set the provided retention policy as the default retention policy for the database
    -   \* **org** or **orgID:** organization name or [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id)
    -   \* **retention\_policy:** retention policy name

```sh
curl --request POST http://localhost:8086/api/v2/dbrps \
  --header "Authorization: Token YourAuthToken" \
  --header 'Content-type: application/json' \
  --data '{
        "bucketID": "00oxo0oXx000x0Xo",
        "database": "example-db",
        "default": true,
        "orgID": "00oxo0oXx000x0Xo",
        "retention_policy": "example-rp"
      }'
```

<!-- End tabbed content -->

## List DBRP mappings

Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2/reference/api/) to list all DBRP mappings and verify the buckets you want to query are mapped to a database and retention policy.

<!-- Tabbed content: Select one of the following options -->

**influx CLI:**

Use the [`influx v1 dbrp list` command](/influxdb/v2/reference/cli/influx/v1/dbrp/list/) to list DBRP mappings.

The examples below assume that your organization and API token are provided by the active [InfluxDB connection configuration](/influxdb/v2/reference/cli/influx/config/) in the `influx` CLI. If not, include your organization (`--org`) and API token (`--token`) with each command.

##### View all DBRP mappings

```sh
influx v1 dbrp list
```

##### Filter DBRP mappings by database

```sh
influx v1 dbrp list --db example-db
```

##### Filter DBRP mappings by bucket ID

```sh
influx v1 dbrp list --bucket-id 00oxo0oXx000x0Xo
```

**InfluxDB API:**

Use the [`/api/v2/dbrps` API endpoint](/influxdb/v2/api/dbrps/) to list DBRP mappings.

[GET http://localhost:8086/api/v2/dbrps](/influxdb/v2/api/dbrps/)

Include the following:

-   **Request method:** `GET`
-   **Headers:**
    -   **Authorization:** `Token` schema with your InfluxDB [API token](/influxdb/v2/admin/tokens/)
-   **Query parameters:**  
    \* Required
    -   \* **orgID:** [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id)
    -   **bucketID:** [bucket ID](/influxdb/v2/admin/buckets/view-buckets/) *(to list DBRP mappings for a specific bucket)*
    -   **database:** database name *(to list DBRP mappings with a specific database name)*
    -   **rp:** retention policy name *(to list DBRP mappings with a specific retention policy name)*
    -   **id:** DBRP mapping ID *(to list a specific DBRP mapping)*

##### View all DBRP mappings

```sh
curl --request GET \
  http://localhost:8086/api/v2/dbrps?orgID=00oxo0oXx000x0Xo \
  --header "Authorization: Token YourAuthToken"
```

##### Filter DBRP mappings by database

```sh
curl --request GET \
  http://localhost:8086/api/v2/dbrps?orgID=00oxo0oXx000x0Xo&db=example-db \
  --header "Authorization: Token YourAuthToken"
```

##### Filter DBRP mappings by bucket ID

```sh
curl --request GET \
  https://cloud2.influxdata.com/api/v2/dbrps?organization_id=00oxo0oXx000x0Xo&bucketID=00oxo0oXx000x0Xo \
  --header "Authorization: Token YourAuthToken"
```

<!-- End tabbed content -->

## Update a DBRP mapping

Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2/reference/api/) to update a DBRP mapping.

Virtual DBRP mappings cannot be updated. To override a virtual DBRP mapping, [create an explicit mapping](#create-dbrp-mappings).

<!-- Tabbed content: Select one of the following options -->

**influx CLI:**

Use the [`influx v1 dbrp update` command](/influxdb/v2/reference/cli/influx/v1/dbrp/update/) to update a DBRP mapping. Include the following:

\* Required

-   \* **org** and **token** to authenticate. We recommend setting your organization and token to your active InfluxDB connection configuration in the influx CLI, so you don’t have to add these parameters to each command. To set up your active InfluxDB configuration, see [`influx config set`](/influxdb/v2/reference/cli/influx/config/set/).
-   \* **DBRP mapping ID** to update
-   **Retention policy** name to update to
-   **Default flag** to set the retention policy as the default retention policy for the database

##### Update the default retention policy

```sh
influx v1 dbrp update \
  --id 00oxo0X0xx0XXoX0
  --rp example-rp \
  --default
```

**InfluxDB API:**

Use the [`/api/v2/dbrps/{dbrpID}` API endpoint](/influxdb/v2/api/dbrps/) to update DBRP mappings.

[PATCH http://localhost:8086/api/v2/dbrps/{dbrpID}](/influxdb/v2/api/dbrps/)

Include the following:

\* Required

-   **Request method:** `PATCH`
-   **Headers:**
    -   \* **Authorization:** `Token` schema with your InfluxDB [API token](/influxdb/v2/admin/tokens/)
-   **Path parameters:**
    -   \* **id:** DBRP mapping ID to update
-   **Query parameters:**
    -   \* **orgID:** [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id)
-   **Request body (JSON):**
    -   **rp:** retention policy name to update to
    -   **default:** set the retention policy as the default retention policy for the database

##### Update the default retention policy

```sh
curl --request PATCH \
  http://localhost:8086/api/v2/dbrps/00oxo0X0xx0XXoX0?orgID=00oxo0oXx000x0Xo \
  --header "Authorization: Token YourAuthToken"
  --data '{
      "rp": "example-rp",
      "default": true
    }'
```

<!-- End tabbed content -->

## Delete a DBRP mapping

Use the [`influx` CLI](/influxdb/v2/reference/cli/influx/) or the [InfluxDB API](/influxdb/v2/reference/api/) to delete a DBRP mapping.

Virtual DBRP mappings cannot be deleted.

<!-- Tabbed content: Select one of the following options -->

**influx CLI:**

Use the [`influx v1 dbrp delete` command](/influxdb/v2/reference/cli/influx/v1/dbrp/delete/) to delete a DBRP mapping. Include the following:

\* Required

-   \* **org** and **token** to authenticate. We recommend setting your organization and token to your active InfluxDB connection configuration in the influx CLI, so you don’t have to add these parameters to each command. To set up your active InfluxDB configuration, see [`influx config set`](/influxdb/v2/reference/cli/influx/config/set/).
-   \* **DBRP mapping ID** to delete

```sh
influx v1 dbrp delete --id 00oxo0X0xx0XXoX0
```

**InfluxDB API:**

Use the [`/api/v2/dbrps/{dbrpID}` API endpoint](/influxdb/v2/api/dbrps/) to delete a DBRP mapping.

[DELETE http://localhost:8086/api/v2/dbrps/{dbrpID}](/influxdb/v2/api/dbrps/)

Include the following:

\* Required

-   **Request method:** `PATCH`
-   **Headers:**
    -   \* **Authorization:** `Token` schema with your InfluxDB [API token](/influxdb/v2/admin/tokens/)
-   **Path parameters:**
    -   \* **id:** DBRP mapping ID to update
-   **Query parameters:**
    -   \* **orgID:** [organization ID](/influxdb/v2/admin/organizations/view-orgs/#view-your-organization-id)

```sh
curl --request DELETE \
  http://localhost:8086/api/v2/dbrps/00oxo0X0xx0XXoX0?orgID=00oxo0oXx000x0Xo \
  --header "Authorization: Token YourAuthToken"
```

<!-- End tabbed content -->

[influxql](/influxdb/v2/tags/influxql/) [dbrp](/influxdb/v2/tags/dbrp/)