postgrest/docs/api/writing.md

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.

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

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.

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:

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.

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, 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:

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!

Invitation to Contribute

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