Bulk Writes

Bulk Writes allow you to write multiple records in a single request

The Bulk API allows multiple updates or queries to be executed in a single request. Both non-parameterized and parameterized requests are supported by the Bulk API. However the API does not support mixing the parameterized and non-parameterized form in a single request.

A bulk update is contained within a single Raft log entry, so round-trips between nodes are at a minimum. This should result in much better throughput, if it is possible to use this kind of update. You can also ask rqlite to do the batching for you automatically, through the use of Queued Writes. This relieves the client of doing any batching before transmitting a request to rqlite.

Updates

Bulk updates are supported. To execute multiple statements in one HTTP call, simply include the statements in the JSON array:

Non-parameterized example:

  1. curl -XPOST 'localhost:4001/db/execute?pretty&timings' -H "Content-Type: application/json" -d "[
  2.     \"INSERT INTO foo(name) VALUES('fiona')\",
  3.     \"INSERT INTO foo(name) VALUES('sinead')\"
  4. ]"

Parameterized example:

  1. curl -XPOST 'localhost:4001/db/execute?pretty&timings' -H "Content-Type: application/json" -d '[
  2.     ["INSERT INTO foo(name) VALUES(?)", "fiona"],
  3.     ["INSERT INTO foo(name) VALUES(?)", "sinead"]
  4. ]'

The response is of the form:

  1. {
  2.     "results": [
  3.         {
  4.             "last_insert_id": 1,
  5.             "rows_affected": 1,
  6.             "time": 0.00759015
  7.         },
  8.         {
  9.             "last_insert_id": 2,
  10.             "rows_affected": 1,
  11.             "time": 0.00669015
  12.         }
  13.     ],
  14.     "time": 0.869015
  15. }

Atomicity

Because a bulk operation is contained within a single Raft log entry, and only one Raft log entry is ever processed at one time, a bulk operation will never be interleaved with other requests.

Transaction support

You may still wish to set the transaction flag when issuing a bulk update. This ensures that if any error occurs while processing the bulk update, all changes will be rolled back.

Queries

If you want to execute more than one query per HTTP request then perform a POST, and place the queries in the body of the request as a JSON array. For example:

  1. curl -XPOST 'localhost:4001/db/query?pretty' -H "Content-Type: application/json" -d '[
  2.     "SELECT * FROM foo",
  3.     "SELECT * FROM bar"
  4. ]'

Parameterized statements are also supported.

Last modified January 17, 2023: Fix typo (65eeaf1)