Database
The board writes, reads and sums records in tables in the cloud over its own connection, with no HTTP, no key in the firmware and no second TLS connection. The tables are declared outside the firmware (in the owner account or in the product), and the records stay in the board's owner account. This page says where the tables come from, their format, the board's API and the limits. The whole example is examples/banco (in Portuguese).
Where the tables come from
A table must exist in the owner account before the board uses it (without it, the answer is nao_existe). It comes from one of two places:
- From the account: the owner declares it in the portal, on the account's database screen; it holds for that account only.
- From the product: the maker declares it once in the product, and it reaches every account that owns a board of the product at first use. The owner account does not change a table that came from the product, and the maker never sees the accounts' records.
The product's tables belong to the product, never to the firmware: one board does not change what holds for the whole fleet. There are two ways, which write the same declaration, with a version of its own, apart from the interface's publications:
- in the portal: Desenvolvedor ("Developer") > the product > the Banco de dados ("Database") tab, where tables are created, changed and removed;
with the SDK's CLI, with the same publishing key as
devui publish(CLI reference):python tools/devui.py tables push tabelas.json --project-key pk_... --key-file ~/.devui-chave python tools/devui.py tables get --project-key pk_... --key-file ~/.devui-chave > tabelas.jsonpushchecks the file on your machine, by the cloud's rules, before sending anything (an invalid file exits with code 2, naming the table and the field) and ends inversão N das tabelas do produto("version N of the product's tables").getprints the tables in force, ready for the nextpush(the JSON goes to the standard output, and the count to the standard error).
Keep the file away from the firmware's web/ folder: a tabelas.json beside it makes devui pack (and devui_add_bundle) exit with an error, because the tables no longer go in the interface's manifest. Whoever had the file there sends the same content with devui tables push and moves it away from the web/ folder.
The format
The file is a list of up to 64 tables:
[
{
"table": "creditos",
"fields": {"valor": "number", "maquina": "text", "pago_em": "date", "estornado": "boolean"},
"device": {"device": ["read", "insert"], "account": []}
},
{
"table": "precos",
"fields": {"produto": "text", "valor": "number"},
"device": {"device": [], "account": ["read"]},
"guest": {"device": ["read"], "account": ["read"]}
}
]
table: the name, of[a-z][a-z0-9_]{0,31}, not repeated.fields: 1 to 32 fields, each with the typetext,number,booleanordate. The names follow the table name's rule, andid,ts,deviceandaccountare reserved (the cloud puts them in each record).device(required): what the boards may do, in the two scopes, each with a list ofread,insert,updateanddelete:device.device(required): on their own records (the scopeDEVUI_DB_DEVICE, the ones the board wrote). The list may be empty,[]: the board does not touch its own records. A board never sees another board's records.device.account(optional): on the account's records (the scopeDEVUI_DB_ACCOUNT, the ones shared by the account's boards); without it, onlyread.
guest(optional): what a guest may do, indevice(on the records of the device they were invited to) and inaccount(on the account's records), with the same four words; without it, nothing.
No other field is taken, neither in the table, nor in device, nor in guest.
Give each scope only what the firmware uses. In the example, the board writes credits and sums the month's on its own records: in creditos, insert and read (the sum and the find are reads), and nothing on the account's. In precos, it only reads the account's prices, which the owner writes. A table where the board only writes, without reading back, changing or removing what it wrote (a sensor's readings, which the owner account looks at in the portal, for instance), takes only insert:
{"table": "leituras", "fields": {"valor": "number"}, "device": {"device": ["insert"], "account": []}}
In it, the board's find, sum, change and removal come back DEVUI_DB_FORBIDDEN.
The bare list of before ("device": ["read", "insert"], which held for the account's records) is refused: tables push exits with code 2, with the table and the new form, and the cloud refuses it again. To keep what it did, move the list to device.account and put in device.device what the board does on its own records (the four words, to stay as it was).
On the portal's screen
The Declarar tabela ("Declare table") screen (on the product's Banco de dados ("Database") tab and on the account's database) shows the permissions in a grid of who × scope, with the four actions:
| Who and scope | Read | Insert | Change | Remove |
|---|---|---|---|---|
Board, on its own records (device.device) | ||||
Board, on the account's records (device.account) | ✓ | |||
Guest, on the device of the invitation (guest.device) | ||||
Guest, on the account's records (guest.account) |
That is how a new table starts: the row of the board on its own records comes empty, and whoever declares chooses. When a table is edited, the grid shows what is stored.
The tables declared before
The tables declared before this permission (in the accounts and in the products) got the four actions of the board on its own records, what it could already do: no board in the field starts getting proibido. tables get returns each table already in the new form, with the four lists explicit, ready for the next push; to take from the board what it does not use, change device.device and send it again.
Changing the declaration with boards in the field
- Adding a table or a field: always.
- Removing a field: an old board that still sends it goes on writing: the removed field is dropped when written (from the insert and from the
set), and the rest is written. In a filter, it matches as absent. A field that never existed in the table is stillinvalido. - Changing the type of a field, existing or removed before: never. The cloud refuses the declaration (
tables pushexits with code 5 and the reason); for that, create another table. - Removing a table: it leaves every owner account with its records, for good; after that, the board's request to it is
nao_existe. The product's tab warns first;tables pushdoes not ask, so check the list before sending.
On the board
The board must have an owner (in the limbo, the answer is proibido). The records stay in the cloud in plain text, outside the vault mode's end-to-end encryption.
Each request says its scope: DEVUI_DB_DEVICE (this board's records) or DEVUI_DB_ACCOUNT (the owner account's). In each one, the board only does what the table allows in that scope (device.device or device.account). The SDK builds the request in JSON and puts the scope in it; the app never writes it.
| Function | What it does | The answer (JSON) |
|---|---|---|
devui_db_insert(scope, table, record, cb, ctx) | writes a record (a flat JSON object: {"valor":550}) | {"id":"<24 hex>","ts":"<ISO>"} |
devui_db_update(scope, table, id, set, cb, ctx) | changes the fields of set in the record id (null removes a field) | {"ok":true} |
devui_db_delete(scope, table, id, cb, ctx) | removes the record id | {"ok":true} |
devui_db_find(scope, table, query, cb, ctx) | records by filter, sort, limit (1 to 100; with no query, the first 50 by ts) and cursor | {"records":[...],"cursor":...} |
devui_db_aggregate(scope, table, query, cb, ctx) | sum, average, minimum, maximum and count (calc, up to 8), by group_by (a field, day, week or month) in the zone tz (UTC by default) | {"groups":[...]} |
devui_db_request(scope, op, table, query, cb, ctx) | the generic one, also with update_where and delete_where | the operation's |
The example writes a credit and sums the month's:
static void on_inserted(const devui_db_result_t *r, void *ctx)
{
if (r->status == DEVUI_DB_OK) {
printf("gravado: %.*s\n", (int)r->len, r->answer); /* answer has no NUL at its end */
}
}
devui_db_insert(DEVUI_DB_DEVICE, "creditos", "{\"valor\":550}", on_inserted, NULL);
devui_db_aggregate(DEVUI_DB_DEVICE, "creditos",
"{\"filter\":{\"ts\":{\"gte\":\"2026-11-01\",\"lt\":\"2026-12-01\"}},\"tz\":\"America/Sao_Paulo\","
"\"calc\":{\"total\":{\"sum\":\"valor\"},\"quantidade\":{\"count\":true}}}",
on_sum, NULL);
The callback comes once, on the SDK's task (short, no blocking, as the others), with a devui_db_result_t: the status, the answer in JSON (answer and len, with no NUL at the end, valid during the callback only) and the wait asked for (retry_after_ms).
status | What it means |
|---|---|
DEVUI_DB_OK | done; answer has the answer |
DEVUI_DB_INVALID | the request or the record off the table's schema; the answer says the field |
DEVUI_DB_FORBIDDEN | the board is in the limbo, or the table does not let boards do that in the scope asked for (on their own records or on the account's) |
DEVUI_DB_NOT_FOUND | the table was not declared (neither in the account nor in the product), the product removed it, or the record does not exist |
DEVUI_DB_QUOTA | the plan's quota (records kept or writes of the month) |
DEVUI_DB_LIMIT | too many writes or reads a minute, or 4 requests at once; retry_after_ms says how long to wait |
DEVUI_DB_UNAVAILABLE | the database is out, no answer in 10 s, or the connection dropped first: it may have been done |
DEVUI_DB_TOO_LARGE | a record above 2 KB or 32 fields, or an answer larger than the board takes (ask fewer records per page) |
DEVUI_DB_ERROR | an answer this version does not know, or the cloud refused the frame (error_code) |
The call itself returns ESP_OK (the callback comes), or refuses at once, sending nothing: ESP_ERR_INVALID_ARG (a scope, a table, an id or a JSON the SDK refuses), ESP_ERR_INVALID_SIZE (the request above the ceiling, below), ESP_ERR_INVALID_STATE (no cloud and no queue), DEVUI_ERR_DB_LIMIT (4 requests wait for their answer) or ESP_ERR_NO_MEM (the SDK's send queue is full). The whole list is in the C API reference.
In the Arduino library, the same requests are DevUI.dbInsert, dbUpdate, dbDelete, dbFind, dbAggregate, dbRequest and dbQueue (The Arduino library). The Rust binding does not have them yet.
With no cloud: the queue of inserts
With no cloud, a request is refused at once (ESP_ERR_INVALID_STATE), unless the app turns on the queue of inserts:
devui_db_queue(DEVUI_DB_QUEUE_FLASH, 50, 2048); /* up to 50 records in 2 KB, kept in the NVS too */
With it on, every insert goes through it, cloud or not: it waits with an op_id drawn on the board (16 hex digits) and goes in order, one at a time, when the connection is ready. After limite, indisponivel, 10 s with no answer or a drop, it goes again with the same op_id, and the cloud does not write again an op_id it already wrote in the last 24 h: the record the cloud wrote before the connection dropped, with no answer arriving, shows up once.
DEVUI_DB_QUEUE_RAM: in the RAM; a restart loses what was waiting.DEVUI_DB_QUEUE_FLASH: in the RAM and in the NVS, rewritten at each change; it survives a restart. Up toDEVUI_DB_QUEUE_FLASH_MAX(2,048 B), because the queue shares the SDK's NVS with the key. On the ESP8266, the RAM only.DEVUI_DB_QUEUE_OFF: off (the default); what was waiting ends withDEVUI_DB_UNAVAILABLE.
Only inserts go in the queue: a find, a sum, a change or a removal with no cloud is refused at once. The local mode is not the cloud: the same holds. The queue belongs to the owner: a change of owner, or the way back to the limbo, empties it, and each record ends with DEVUI_DB_FORBIDDEN.
Limits
| Limit | Value | Who sets it |
|---|---|---|
| Writes per board | 60 a minute, with a burst of 10 | the cloud (DEVUI_DB_LIMIT) |
| Reads per board | 120 a minute, with a burst of 20 | the cloud (DEVUI_DB_LIMIT) |
| Requests waiting for their answer at once | 4 | the board (DEVUI_ERR_DB_LIMIT, with nothing on the wire) and the cloud |
| Request, in JSON | up to 4,083 B (1,011 B on the ESP8266); an insert of the queue, up to 4,055 B (983 B), as it gets the op_id | the board (ESP_ERR_INVALID_SIZE) |
| Record | up to 2 KB and 32 fields | the cloud (DEVUI_DB_TOO_LARGE) |
| Wait for the answer | 10 s; then, DEVUI_DB_UNAVAILABLE | the board |
| Queue of inserts in the NVS | up to 2,048 B | the board (DEVUI_DB_QUEUE_FLASH_MAX) |
| The product's tables | up to 64, of 1 to 32 fields each | the cloud and the CLI |
| Records kept and writes of the month | the quota of the owner account's plan | the cloud (DEVUI_DB_QUOTA) |
The connection's other limits are in Limits and measured numbers.
