ONQL Ruby Driver

Official Ruby client for the ONQL database server.

Installation

From RubyGems

gem install onql-client

Or in your Gemfile:

gem 'onql-client'

From GitHub (latest main)

gem 'onql-client', git: 'https://github.com/ONQL/onqlclient-ruby'

Pinned to a release tag

gem 'onql-client',
    git: 'https://github.com/ONQL/onqlclient-ruby',
    tag: 'v0.1.0'

Quick Start

require 'onql'

client = ONQL::Client.connect('localhost', 5656)

client.insert('mydb', 'users', { id: 'u1', name: 'John', age: 30 })

rows = client.onql('mydb.users[age>18]')
puts rows.inspect

client.update('mydb', 'users', { age: 31 },
              client.build('mydb.users[id=$1].id', 'u1'))

client.delete('mydb', 'users', '', ids: ['u1'])
client.close

API Reference

ONQL::Client.connect(host, port, timeout:)

Creates and returns a connected client instance.

client.send_request(keyword, payload, timeout: nil)

Sends a raw request frame and waits for a response.

client.close

Closes the connection.

Direct ORM-style API

On top of raw send_request, the client exposes convenience methods for the common insert / update / delete / onql operations. Each one builds the standard payload envelope for you and unwraps the {error, data} response — raising RuntimeError on non-empty error, returning the decoded data field on success.

db is passed explicitly to insert / update / delete. onql takes a fully-qualified ONQL expression.

query arguments are ONQL expression strings, e.g. 'mydb.users[id="u1"].id'.

client.insert(db, table, data)

Insert a single record.

client.insert('mydb', 'users', { id: 'u1', name: 'John', age: 30 })

client.update(db, table, data, query = "", protopass: "default", ids: [])

Update records matching query (or explicit ids).

client.update('mydb', 'users', { age: 31 },
              client.build('mydb.users[id=$1].id', 'u1'))

client.update('mydb', 'users', { age: 31 }, '', ids: ['u1'])

client.delete(db, table, query = "", protopass: "default", ids: [])

Delete records matching query (or ids).

client.delete('mydb', 'users',
              client.build('mydb.users[id=$1].id', 'u1'))

client.delete('mydb', 'users', '', ids: ['u1'])

client.onql(query, protopass: "default", ctxkey: "", ctxvalues: [])

Run a raw ONQL query.

rows = client.onql('mydb.users[age>18]')

client.build(query, *values)

Replace $1, $2, … placeholders with values.

q = client.build('mydb.users[name=$1 and age>$2]', "John", 18)
rows = client.onql(q)

ONQL::Client.process_result(raw)

Class-level helper that parses the {error, data} envelope.

Protocol

<request_id>\x1E<keyword>\x1E<payload>\x04

• \x1E — field delimiter
• \x04 — end-of-message marker

License

MIT