132 lines
3.7 KiB
Markdown
132 lines
3.7 KiB
Markdown
## Updating Data
|
|
|
|
### Record Creation
|
|
|
|
* ❌ Cannot be cached or prefetched
|
|
* ❌ Not idempotent
|
|
|
|
To create a row in a database table post a JSON object whose keys
|
|
are the names of the columns you would like to create. Missing keys
|
|
will be set to default values when applicable.
|
|
|
|
```HTTP
|
|
POST /table_name
|
|
{ "col1": "value1", "col2": "value2" }
|
|
```
|
|
|
|
The response will include a `Location` header describing where to
|
|
find the new object. If you would like to get the full object back
|
|
in the response to your request, include the header `Prefer:
|
|
return=representation`. That way you won't have to make another
|
|
HTTP call to discover properties that may have been filled in on
|
|
the server side.
|
|
|
|
### Bulk Insertion
|
|
|
|
* ❌ Cannot be cached or prefetched
|
|
* ❌ Not idempotent
|
|
|
|
While regular insertion uses JSON to encode the value, bulk insertion
|
|
uses CSV. Simply post to a table route with `Content-Type: text/csv`
|
|
and include the names of the columns as the first row. For instance
|
|
|
|
```HTTP
|
|
POST /people
|
|
name,age,height
|
|
J Doe,62,70
|
|
Jonas,10,55
|
|
```
|
|
|
|
An empty field (`,,`) is coerced to an empty string and the reserved
|
|
word `NULL` is mapped to the SQL null value. Note that there should
|
|
be no spaces between the column names and commas.
|
|
|
|
The server sends a multipart response for bulk insertions. Each part
|
|
contains a Location header with URL of each created resource.
|
|
|
|
```HTTP
|
|
Content-Type: application/json
|
|
Location: /festival?name=eq.Venice%20Film%20Festival
|
|
|
|
|
|
--postgrest_boundary
|
|
Content-Type: application/json
|
|
Location: /festival?name=eq.Cannes%20Film%20Festival
|
|
```
|
|
|
|
### Upsertion
|
|
|
|
* ❌ Cannot be cached or prefetched
|
|
* ✅ Idempotent
|
|
|
|
To insert or update a single row use the `PUT` verb on a properly
|
|
filtered table url:
|
|
|
|
```HTTP
|
|
PUT /table_name?primary_key=eq.foo
|
|
{ "col1": "value1", "col2": "value2" }
|
|
```
|
|
|
|
The request must satisfy two things. First all columns must be
|
|
specified (because a default value might be a changing value which
|
|
would violate idempotence). Second the URL must match the URL you
|
|
would use to get the value of the resource. This means that all
|
|
primary key columns must be included in the filter (there are more
|
|
than one when the primary key is compound).
|
|
|
|
If you would like to get the full object back in the response to
|
|
your request, include the header `Prefer: return=representation`.
|
|
It will of match exactly the object you sent though.
|
|
|
|
### Bulk Updates
|
|
|
|
* ❌ Cannot be cached or prefetched
|
|
* ❌ Not idempotent
|
|
|
|
To change parts of a resource or resources use the `PATCH` verb.
|
|
For instance, here is how to mark all young people as children.
|
|
|
|
```HTTP
|
|
PATCH /people?age=lt.13
|
|
{
|
|
"person_type": "child"
|
|
}
|
|
```
|
|
|
|
This affects any rows matched by the url param filters, overwrites
|
|
any fields specified in in the payload JSON and leaves the other
|
|
fields unaffected. Note that although the payload is not in the
|
|
JSON patch format specified by
|
|
[RFC6902](https://tools.ietf.org/html/rfc6902), HTTP does not specify
|
|
which patch format to use. Our format is more pleasant, meant for
|
|
basic field replacements, and not at all "incorrect."
|
|
|
|
### Deletion
|
|
|
|
* ❌ Cannot be cached or prefetched
|
|
* ✅ Idempotent
|
|
|
|
Simply use the `DELETE` verb. All recors that match your filter
|
|
will be removed. For instance deleting inactive users:
|
|
|
|
```HTTP
|
|
DELETE /user?active=eq.false
|
|
```
|
|
|
|
### Protecting Dangerous Actions
|
|
|
|
Notice that it is very easy to delete or update many records at
|
|
once. In fact forgetting a filter will affect an entire table!
|
|
|
|
|
|
<div class="admonition warning">
|
|
<p class="admonition-title">Invitation to Contribute</p>
|
|
|
|
<p>We would like to investigate nginx rules to guard dangerous
|
|
actions, perhaps requiring a confirmation header or query param
|
|
to perform the action.</p>
|
|
|
|
<p>You're invited to research this option and contribute to
|
|
this documentation.</p>
|
|
</div>
|