Qirava DMS docs

Quick start: boot & first query

From a clean checkout to a working query in about two minutes. Boot the DMS, open it for local development, then run real QQL over plain HTTP — no driver, no SDK, no schema migration step.

1. Build and run#

Build the workspace and start the DMS. It tells you the address it bound and prints a one-time bootstrap custodian (for Studio).

bash

git clone --recursive https://github.com/qirava/qroot
cd qroot/qdms
cargo run --bin qdms

text

  bound:   http://127.0.0.1:7179
  routes:  POST /api/qql   (QQL in body)
           GET  /api/qql?q=...

2. Open it for local development#

By default the API requires a signed key (require_api_key = true) — right for anything real, but it blocks a quick curl. For local development, set it to false in the config and restart so you can talk to /api/qql directly.

text

# ~/.qdms/dms.config  (auto-generated on first run)
addr = 127.0.0.1:7179
require_api_key = false
data_dir = memory          # ephemeral; use a path for a durable WAL

3. Create a table, insert, and query#

Everything is QQL over POST /api/qql, with the statement as the request body. Every response is one uniform envelope: { error, data, root }.

Request

curl -X POST http://127.0.0.1:7179/api/qql \
  --data 'CREATE TABLE users SCHEMALESS'

Response

{"error":null,"data":null,"root":{"count":0}}

Request

curl -X POST http://127.0.0.1:7179/api/qql \
  --data 'INSERT INTO users { email: "ada@example.com", age: 36 }'

Response

{"error":null,
 "data":[{"_id":1,"email":"ada@example.com","age":36}],
 "root":{"count":1}}

Output

The DB assigns the immutable _id and echoes back the stored row.

Request

curl -X POST http://127.0.0.1:7179/api/qql \
  --data 'SELECT email, age FROM users WHERE age >= 18 SORT age DESC LIMIT 10'

Response

{"error":null,
 "data":[
   {"email":"bob@example.com","age":42},
   {"email":"ada@example.com","age":36}
 ],
 "root":{"count":2}}

4. The two HTTP forms#

Writes use POST with the statement in the body. Read-only queries can also use GET /api/qql?q=..., which is handy straight from a browser.

Request

curl 'http://127.0.0.1:7179/api/qql?q=SELECT%20email%20FROM%20users'

Response

{"error":null,"data":[{"email":"ada@example.com"},{"email":"bob@example.com"}],"root":{"count":2}}