Improve /database/create API #1350
Conversation
Codecov Report
@@ Coverage Diff @@
## master #1350 +/- ##
========================================
+ Coverage 70.7% 70.7% +<.1%
========================================
Files 822 822
Lines 70204 70275 +71
========================================
+ Hits 49648 49715 +67
Misses 17325 17325
- Partials 3231 3235 +4
Continue to review full report at Codecov.
|
Codecov Report
@@ Coverage Diff @@
## master #1350 +/- ##
========================================
+ Coverage 70.7% 70.7% +<.1%
========================================
Files 822 822
Lines 70204 70289 +85
========================================
+ Hits 49653 49737 +84
+ Misses 17322 17313 -9
- Partials 3229 3239 +10
Continue to review full report at Codecov.
|
richardartoul
changed the title
docs/how_to/single_node.md
Outdated
| retention: <new_retention> | ||
| resolution: <new_resolution> | ||
| ``` | ||
| Note that the `api/v1/database/create` endpoint is abstraction over two concepts in M3DB called [placements](../operational_guide/placement) and [namespaces](../operational_guide/namespace_configuration). If a placement doesn't exist, it will create one based on the `type` argument, otherwise if the placement already exists, it just creates the specified namespace. For now its enough to just understand that it creates M3DB namespaces (tables), but if you're going to run a clustered M3 setup in production, make sure you familiarize yourself with the links above. |
There was a problem hiding this comment.
Do these links need the .md suffixes?
|
|
||
| ## Namespace Operations | ||
|
|
||
| The operations below include sample CURLs, but you can always review the API documentation by navigating to |
There was a problem hiding this comment.
s/CURL/cURL here and other mentions to cURL.
| CreateURL = handler.RoutePrefixV1 + "/database/create" | ||
|
|
||
| // CreateHTTPMethod is the HTTP method used with this resource. | ||
| // CreateNamespaceURL is the URL for the database namespace create handler. |
There was a problem hiding this comment.
Nit: double space to single space.
|
|
||
| ### Modifying a Namespace | ||
|
|
||
| There is currently no atomic namespace modification endpoint. Instead, you will need to delete a namespace and then add it back again with the same name, but modified settings. Review the individual namespace settings above to determine whether or not a given setting is safe to modify. For example,it is never safe to modify the blockSize of a namespace. |
Codecov Report
@@ Coverage Diff @@
## master #1350 +/- ##
========================================
+ Coverage 70.7% 70.7% +<.1%
========================================
Files 822 822
Lines 70204 70289 +85
========================================
+ Hits 49653 49724 +71
- Misses 17322 17329 +7
- Partials 3229 3236 +7
Continue to review full report at Codecov.
|
| <!-- TODO: link to aggregation documentation (outside of query.md) --> | ||
|
|
||
| ```json | ||
| local: |
There was a problem hiding this comment.
We should probably have this somewhere, no?
There was a problem hiding this comment.
Aggregation is hard to talk about without the Prometheus context, so I added a link in the Prometheus integration section to the Query aggregation docs
| return nil, true, errCantReplaceLocalPlacementWithClustered | ||
| } | ||
|
|
||
| // This is fine because we'll just assume they want to keep the same clustered placement |
There was a problem hiding this comment.
worth logging this so that the user knows?
There was a problem hiding this comment.
the placement comes back in the API response, so I think its ok
This P.R refactors the
/database/createAPI to make it more general purpose, user-friendly, and have better error messages.The API was originally designed to only be used once to create both a placement and a single namespace, and then never used again. Now that many of our users are creating multiple namespaces, compounded with the fact that configuring a reasonable blocksize for most namespaces is confusing, we want to push users to use this API by default for creating all their namespaces.
This P.R modifies the API to allow it to be called multiple times. If a placement does not exist, it will create it, otherwise it will just initialize the namespace. This logic has a lot of specific error handling to make it user-friendly which is documented in code comments in the P.R.
In addition to modifying the API, the documentation is also updated to explain the new API and push people towards using it.