---
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: 2724
product: InfluxDB OSS v2
version: v2
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb/v2/query-data/influxql/dbrp/
date: '2025-04-02T15:54:32-06:00'
lastmod: '2025-04-02T15:54:32-06:00'
---

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.

#### 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
```

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

```
POST http://localhost:8086/api/v2/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"
      }'
```

## 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.

#### influx CLI ####

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

> [!Note]
> 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
```

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

```
GET http://localhost:8086/api/v2/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"
```

## 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.

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

#### 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
```

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

```
PATCH http://localhost:8086/api/v2/dbrps/{dbrpID}
```

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
    }'
```

## 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.

> [!Note]
> Virtual DBRP mappings cannot be deleted.

#### 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
```

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}
```

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"
```

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