Your first database

Build the standalone server, initialize a database and submit your first transaction.

On this page

Build the server

Use an authorized Qirava source checkout and the pinned toolchain (Rust 1.96.0). Source access and package publication are separate from this public documentation. A production release is not claimed.

bash

cd db
cargo build --locked -p qirava-server
./target/debug/qiravad init --data ./local-data
./target/debug/qiravad serve --data ./local-data --listen 127.0.0.1:7179

Choose storage protection

New databases default to encryption at rest disabled. Records, pages, checkpoints and object parts retain authenticated integrity checks. Add --encryption-at-rest on during initialization when you need encrypted payloads. Custody and recovery-key wrapping apply in both modes.

Opening an existing database preserves its protection mode. Physical rewrites and backups preserve that selection; changing an instance configuration flag is not a supported conversion. Studio displays the current mode on the Database page.

bash

./target/debug/qiravad init --data ./encrypted-data --encryption-at-rest on

Authenticate and unlock

Initialization privately asks for a recovery passphrase and writes the owner credential to local-data/bootstrap.token. They serve different purposes: the credential grants access; the configured recovery authority unlocks the storage key. The instance starts locked after restart.

Serve the built Studio directory with --studio ../studio/build. Open http://127.0.0.1:7179, connect with the owner credential, then unlock with the recovery passphrase. Keep the credential out of a public website or browser bundle.

bash

# From the integration root
cd studio
bun install --frozen-lockfile
bun run build
cd ..
./db/target/debug/qiravad serve --data ./db/local-data --studio studio/build

Create a collection and a record

After unlocking, send this body to POST /api/v1/execute with the owner Bearer token from a trusted local client. The same JSON is accepted by the TS/JS client. Reuse this exact request if the outcome is uncertain.

json

{
  "requestId": "quickstart-projects-v1",
  "operations": [
    {
      "op": "create_collection",
      "name": "projects",
      "unique": []
    },
    {
      "op": "insert",
      "collection": "projects",
      "key": "first-project",
      "value": {
        "title": "Build with Qirava",
        "status": "active",
        "workspace": "local"
      }
    }
  ]
}

Read what you wrote

The result contains a stored record with key, revision and value. Read-only transactions do not store mutation receipts. For a consistent group of reads, put the related operations in one transaction.

json

{
  "requestId": "read-first-project",
  "operations": [
    {
      "op": "get",
      "collection": "projects",
      "key": "first-project"
    }
  ]
}

Use the TypeScript / JavaScript driver →

Explore QQL →