apache / apache/couchdb

Add per-db _config API

Open
#5,685 3 comments 2 reactions 0 assignees View on GitHub
enhancement
Dominant language
Erlang
Stars
7k
Forks
1.1k
Avg merge
1d 16h
Merged PRs (30d)
9

Description

#5655 introduced a new [database API endpoint](https://github.com/apache/couchdb/pull/5655/files#diff-82d8b792ffdb5c58dcd7d9c3bb2b4582e46d03e416f62104a403242f42e2a234R38): `/{db}/_auto_purge` which is a `/{db}/_security`-like JSON structure with a single key `deleted_document_ttl`.

With [other features on the horizon](https://github.com/apache/couchdb/pull/5583/files#top) that need per-db configuration, I suggest we formalise an extensible API for database config modelled after the server `_config` API and move the `_auto_purge` functionality into that. In addition, this allows us to consolidate a few other things like `_revs_limit` and `_purged_infos_limit` into that API as well.

The general idea is to model the behaviour on how `/_config` works. I’ll skip the `/_node/{name-or_local}` prefix for brevity.

To recap how `/_config` works:

- `GET /_config` -> returns all config in a JSON object, top level keys are config sections, second level keys are config settings and their values are the config value.
- `GET /_config/section` -> returns a JSON response of all config keys and their values for a particular section.
- `GET /_config/section/key` -> returns just the config value for a given section and key.
- `PUT /_config/section/key value` -> updates the value of section/key to the provided value and returns the old value.
- `DELETE /_config/section/key` -> removes a configuration option, this means the source-default is assumed.

I propose `/db/_config` to behave exactly the same:

- `GET /{db}/_config` -> returns all config in a JSON object, top level keys are config sections, second level keys are config settings and their values are the config value.
- `GET /{db}/_config/section` -> returns a JSON response of all config keys and their values for a particular section.
- `GET /{db}/_config/section/key` -> returns just the config value for a given section and key.
- `PUT /{db}/_config/section/key value` -> updates the value of section/key to the provided value and returns the old value.
- `DELETE /{db}/_config/section/key` -> removes a configuration option, this means the source-default is assumed. TBD: behaviour as we do not want to actually remove the key entry, just reset its value

To get started, we should implement the following sections and config options:

- `section` `key` `default value`
- `revs` `limit` `1000`
- `purges` `limit` `1000`
- `auto_purge` `deleted_document_ttl` `TBD` // also TBD about the unit, which is currently seconds and a bit unwieldy. We want to suggest long timeframes, so maybe days or months?
- `compaction` `generations` `0` (for #5583 when it lands)

Optional:

Bob suggested to move the `_security` object here as well, which I don’t object to, but it does not fit the data structure without some awkwardness about the value being a JSON structure where everything else is a scalar. I’m open to other suggestions, but it’d be awkward to invent something that does not behave like server `_changes` already.
- `security` `admins` `{names: [], roles: ["_admin"]}`
- `security` `members` `{names: [], roles: ["_admin"]}`

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the existing /{db}/_auto_purge endpoint and the server /_config API described in the issue. Resolve the proposed sections, defaults, DELETE behavior, TTL units, and whether _security belongs in the model. Done means the per-database configuration API and its behavior are specified consistently, including the listed existing settings.

Written by the indexing model from the issue text.

Assessment

Tech stack
erlang
Domain
api, database
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.