tina4-ultipa 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 78beafa9836b0d709d9a02d788ca1bd25bed6e75a8d72b59c28fd07f777ea566
+  data.tar.gz: f367219bedd06967311975326649f6507bace52a439147866bb4144eb96289e1
+SHA512:
+  metadata.gz: 07db5593de9c6a3e6ece49e205263f962ddbafb00b07831a592999c81e5873057b13f8a7b927c60b166138ad326e412cf84239bda016b7876b1d8d56de7bc850
+  data.tar.gz: 22ef4d3cf031368ec8524c082178eb178614cd218b43773938df54f34efa9e25955177bccdd7d7712dcf8563ca8349ba2bc0afebb289b8cf06f8b4ed61b59ea9

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tina4 Stack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,197 @@
+<p align="center">
+  <img src="https://tina4.com/logo.svg" alt="Tina4" height="88">
+  &nbsp;&nbsp;<span>&times;</span>&nbsp;&nbsp;
+  <img src="https://www.ultipa.com/assets/ultipa-logo.svg" alt="Ultipa" height="40">
+</p>
+
+<h1 align="center">tina4-ultipa</h1>
+<h3 align="center">The Ultipa graph driver for Ruby</h3>
+
+<p align="center">
+  A full-fidelity gRPC client for the <a href="https://www.ultipa.com">Ultipa</a>
+  graph database — every GQL type decoded, no Tina4 lock-in.
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/tina4-ultipa"><img src="https://img.shields.io/gem/v/tina4-ultipa?color=ed5034&label=gem" alt="RubyGems"></a>
+  <img src="https://img.shields.io/badge/tests-live%20%C2%B7%20no%20mocks-2f9e44" alt="Tests">
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT">
+  <a href="https://www.ultipa.com"><img src="https://img.shields.io/badge/for-Ultipa%20gqldb-ed5034" alt="Ultipa"></a>
+  <a href="https://tina4.com"><img src="https://img.shields.io/badge/part%20of-Tina4-ed5034" alt="Tina4"></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> &bull;
+  <a href="#type-support">Type Support</a> &bull;
+  <a href="https://www.ultipa.com/docs">Ultipa Docs</a> &bull;
+  <a href="PROTOCOL.md">Protocol</a> &bull;
+  <a href="https://tina4.com">tina4.com</a>
+</p>
+
+---
+
+A thin, standalone **gRPC driver for the [Ultipa](https://www.ultipa.com) graph
+database** (`ultipa-gqldb`). It is the Ultipa driver behind
+[Tina4](https://tina4.com)'s graph data layer — but has **no Tina4 dependency** and
+is perfectly usable on its own. Tina4's core stays zero-dependency; this driver is
+an *optional* gem loaded only for `ultipa://` connections, speaking gRPC directly
+(`grpc` + `google-protobuf`).
+
+> **Ultipa** is a high-performance graph database with a GQL (ISO/IEC 39075) query
+> surface. Learn more at **[ultipa.com](https://www.ultipa.com)** · docs at
+> **[ultipa.com/docs](https://www.ultipa.com/docs)**.
+
+## Why this driver
+
+- **Complete value decoding.** Every gqldb `PropertyType` is decoded to a natural
+  Ruby value — including the composites and temporals most thin clients skip
+  (see [Type support](#type-support)).
+- **Real gRPC, vendored stubs.** Generated protobuf stubs ship inside the gem
+  (`lib/tina4_ultipa/gen/`), so there is no reflection round-trip and no codegen
+  step at install time.
+- **Fails loud.** A bad statement raises; it never returns a falsy value you might
+  miss. An unreachable host raises within your `connect_timeout`.
+- **Cross-language parity.** The same driver exists for
+  [Python](https://github.com/tina4stack/ultipa-python),
+  [Node.js](https://github.com/tina4stack/ultipa-node),
+  [Ruby](https://github.com/tina4stack/ultipa-ruby) and
+  [PHP](https://github.com/tina4stack/ultipa-php), decoding byte-for-byte identically.
+
+## Install
+
+```bash
+gem install tina4-ultipa
+```
+
+or in a `Gemfile`:
+
+```ruby
+gem "tina4-ultipa"
+```
+
+## Quick start
+
+```ruby
+require "tina4_ultipa"
+
+# from a URL...
+db = Tina4Ultipa::Client.from_url("ultipa://admin:password@localhost:60061/mygraph").connect
+# ...or explicitly
+db = Tina4Ultipa::Client.new(
+  host: "localhost", port: 60061,
+  username: "admin", password: "password", graph: "mygraph"
+).connect
+
+# read — GQL text + optional named params
+db.query("MATCH (n:Person) WHERE n.age > $min RETURN n.name AS name",
+         params: { min: 21 }).each do |row|
+  puts row["name"]
+end
+
+# write — dml stats on success, raises on a bad statement
+r = db.execute("INSERT (:Person {name: 'Alice', age: 30})")
+puts r.dml_stats[:inserted_nodes]   # 1
+
+db.close
+```
+
+`query` runs a read, `execute` a write — both take GQL and optional `params`
+and return a `Tina4Ultipa::Result`:
+
+| Member | Meaning |
+|---|---|
+| `#columns` | column names |
+| `#rows` | decoded rows (arrays of Ruby values) |
+| `#to_h_rows` / `#dicts` | rows as hashes keyed by column |
+| `#scalar` | first cell of the first row |
+| `#rows_affected`, `#dml_stats`, `#warnings` | write metadata |
+
+`Result` is `Enumerable` and yields each row as a hash, so `each`, `map` and
+`select` work directly on a result.
+
+Errors: a bad statement raises `Tina4Ultipa::Error`; an unreachable host raises
+`Tina4Ultipa::ConnectError` within `connect_timeout`, naming host, port and elapsed time.
+
+## Type support
+
+Every gqldb `PropertyType` decodes to a natural Ruby value:
+
+| Category | Types | Decodes to |
+|---|---|---|
+| Numeric | int32/uint32/int64/uint64, float, double | `Integer` / `Float` |
+| Text | string, text | `String` |
+| Boolean / null | bool, null, unset | `true`/`false` / `nil` |
+| Binary | **blob** | binary `String` (e.g. an image, round-trips intact) |
+| Decimal | decimal | `String` (precision-preserving) |
+| Temporal | date, local/zoned time, local/zoned datetime, timestamp | ISO-8601 `String` |
+| Interval | year-to-month, day-to-second | `{"months" => …}` / `{"seconds" => …, "nanoseconds" => …}` |
+| Spatial | point, point3d | `{"x", "y"[, "z"], "srid"}` `Hash` |
+| Vector | vector | `Array` of `Float` |
+| Graph | **node**, **edge**, **path** | `Hash` (`_kind` node/edge/path; nodes/edges carry `id`, `labels`/`type`, `properties`, internal `uuid`) |
+| Tabular | list, set, map, record, table | `Array` / `Hash` |
+| Error | error | `{"code", "message"}` |
+
+Node/edge hashes include the 8-byte internal-id (`uuid`) trailer emitted by
+gqldb 6.1.147+.
+
+## Protocol
+
+`ultipa-gqldb` speaks gRPC (default port `60061`, protobuf package `gqldb`). The
+driver authenticates with `SessionService.Login`, passes the returned `session_id`
+on every call as the **`session-id`** metadata header (as an unsigned decimal), then
+runs `QueryService.Gql`. Each value is a `TypedValue{type, bytes}`; all multi-byte
+integers are little-endian. The full byte-level encoding is documented in
+**[PROTOCOL.md](PROTOCOL.md)** — grounded in Ultipa's official gqldb SDK and proto,
+and verified live against gqldb-grpc 6.2.130 CE.
+
+## Sample data pack
+
+Get a real graph into your community-edition instance in seconds - 10 people (with
+photos), 3 companies, 3 projects, 5 skills and 62 relationships:
+
+```bash
+ruby examples/seed.rb ultipa://admin:PASSWORD@HOST:60061
+# graph defaults to "default"; override with TINA4_ULTIPA_GRAPH
+```
+
+Then explore it:
+
+```sql
+MATCH (n:Person)-[e]->(m) RETURN n, e, m LIMIT 100
+RETURN db.overview()
+```
+
+The pack lives in [`examples/`](examples/) - `people.json` describes the graph and
+`sample_data/faces/*.jpg` are 64px portraits of **AI-generated, non-existent people**
+([thispersondoesnotexist.com](https://thispersondoesnotexist.com)) stored as **BLOB**
+properties, so it also demonstrates binary round-tripping through gqldb. Re-running is
+safe - it clears the demo labels (Person/Company/Project/Skill) first.
+
+## Testing
+
+Real, no-mock tests run against a live server:
+
+```bash
+TINA4_TEST_ULTIPA_URL=ultipa://admin:password@host:60061 ruby test/test_driver.rb
+```
+
+They cover scalars, node/edge/list/map decoding, the full temporal/spatial/interval
+set, path decoding, and a BLOB image round-trip.
+
+## Links
+
+- **Ultipa** — website [ultipa.com](https://www.ultipa.com) · docs [ultipa.com/docs](https://www.ultipa.com/docs) · GQL query language reference in the docs
+- **Tina4** — [tina4.com](https://tina4.com) · the framework this driver powers
+- **This driver** — [github.com/tina4stack/ultipa-ruby](https://github.com/tina4stack/ultipa-ruby) · sibling drivers for [Python](https://github.com/tina4stack/ultipa-python), [Node.js](https://github.com/tina4stack/ultipa-node), [PHP](https://github.com/tina4stack/ultipa-php)
+
+## License
+
+MIT. Note: the Ultipa community-edition server is licensed by Ultipa for personal /
+non-commercial use — review [Ultipa's terms](https://www.ultipa.com) before you
+deploy it. This driver is an independent client and may not be officially supported
+by Ultipa.
+
+---
+
+Sponsored by [Code Infinity](https://codeinfinity.co.za) · part of the
+[Tina4](https://tina4.com) stack.

data/lib/tina4_ultipa/client.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+# Thin gRPC client for the Ultipa `ultipa-gqldb` server.
+#
+# Auth: SessionService.Login(username, password[, default_graph]) -> session_id,
+# then that id rides every call as the gRPC metadata header `session-id`.
+# Query: QueryService.Gql(GqlRequest) -> GqlResponse. This is the whole surface the
+# Tina4 graph adapter needs; node/edge/traverse are built in GQL on top of query.
+
+require "uri"
+require "grpc"
+
+# The generated stubs `require 'gqldb_pb'` / `require 'gqldb_services_pb'` by bare
+# name, so put their directory on the load path before requiring them.
+_gen_dir = File.expand_path("gen", __dir__)
+$LOAD_PATH.unshift(_gen_dir) unless $LOAD_PATH.include?(_gen_dir)
+require "gqldb_pb"
+require "gqldb_services_pb"
+
+require_relative "codec"
+require_relative "errors"
+
+module Tina4Ultipa
+  DEFAULT_PORT = 60_061
+
+  # A gqldb result set - columns + rows, shaped like Tina4's DatabaseResult.
+  class Result
+    attr_reader :columns, :rows, :row_count, :rows_affected, :warnings,
+                :current_graph, :dml_stats
+
+    include Enumerable
+
+    def initialize(resp)
+      @columns = resp.columns.to_a
+      @rows = resp.rows.map { |row| row.values.map { |v| Codec.decode(v) } }
+      @row_count = resp.row_count
+      @rows_affected = resp.rows_affected
+      @warnings = resp.warnings.to_a
+      @current_graph = resp.current_graph
+      d = resp.dml_stats
+      @dml_stats = if d
+                     { inserted_nodes: d.inserted_nodes, inserted_edges: d.inserted_edges,
+                       deleted_nodes: d.deleted_nodes, deleted_edges: d.deleted_edges,
+                       set_nodes: d.set_nodes, set_edges: d.set_edges }
+                   else
+                     { inserted_nodes: 0, inserted_edges: 0, deleted_nodes: 0,
+                       deleted_edges: 0, set_nodes: 0, set_edges: 0 }
+                   end
+    end
+
+    # Rows as hashes keyed by column name.
+    def to_h_rows
+      @rows.map { |row| @columns.zip(row).to_h }
+    end
+    alias dicts to_h_rows
+
+    # The first cell of the first row, or nil.
+    def scalar
+      first = @rows[0]
+      first && !first.empty? ? first[0] : nil
+    end
+
+    def each(&block)
+      to_h_rows.each(&block)
+    end
+
+    def length
+      @rows.length
+    end
+    alias size length
+  end
+
+  class Client
+    attr_reader :host, :port, :username, :graph, :connect_timeout, :use_tls,
+                :server_version
+    attr_writer :graph
+
+    def initialize(host:, port: DEFAULT_PORT, username: nil, password: nil,
+                   graph: nil, connect_timeout: 10, use_tls: false)
+      @host = host
+      @port = port.to_i
+      @username = username
+      @password = password
+      @graph = graph || ""
+      @connect_timeout = connect_timeout.to_f
+      @use_tls = use_tls
+      @channel = nil
+      @session = nil
+      @query = nil
+      @session_id = nil
+      @server_version = nil
+    end
+
+    # ultipa://user:pass@host:port/graph?connect_timeout=5&tls=1
+    def self.from_url(url, **kw)
+      u = URI.parse(url)
+      q = URI.decode_www_form(u.query || "").to_h
+      path_graph = (u.path || "").sub(%r{\A/}, "")
+      new(
+        host: u.host,
+        port: (u.port || DEFAULT_PORT),
+        username: (u.user || q["user"] || kw[:username]),
+        password: (u.password || q["password"] || kw[:password]),
+        graph: (path_graph.empty? ? kw[:graph] : path_graph),
+        connect_timeout: (q["connect_timeout"] || kw[:connect_timeout] || 10).to_f,
+        use_tls: (%w[1 true].include?(q["tls"]) || url.start_with?("ultipas://") ||
+                  kw[:use_tls] || false),
+      )
+    end
+
+    # -- connection ---------------------------------------------------------
+    def connect
+      return self unless @session_id.nil?
+
+      target = "#{@host}:#{@port}"
+      creds = @use_tls ? GRPC::Core::ChannelCredentials.new : :this_channel_is_insecure
+      @channel = GRPC::Core::Channel.new(target, nil, creds)
+      started = monotonic
+      wait_for_ready(@channel, started)
+
+      @session = Gqldb::SessionService::Stub.new(target, creds, channel_override: @channel)
+      @query = Gqldb::QueryService::Stub.new(target, creds, channel_override: @channel)
+      begin
+        resp = @session.login(
+          Gqldb::LoginRequest.new(
+            username: @username || "", password: @password || "", default_graph: @graph,
+          ),
+          deadline: Time.now + @connect_timeout,
+        )
+      rescue GRPC::BadStatus => e
+        close
+        raise wrap(e, "login failed")
+      end
+      @session_id = resp.session_id
+      @server_version = resp.server_version
+      self
+    end
+
+    # -- queries ------------------------------------------------------------
+
+    # Run a GQL statement and return a Result. Raises on error.
+    def query(gql, params: nil, graph: nil, read_only: true, timeout: nil)
+      connect
+      req = Gqldb::GqlRequest.new(
+        gql: gql,
+        graph_name: graph.nil? ? @graph : graph,
+        parameters: (params || {}).map do |k, v|
+          Gqldb::Parameter.new(name: k.to_s, value: Codec.encode(v))
+        end,
+        session_id: @session_id || 0,
+        read_only: read_only,
+        timeout: timeout ? timeout.to_i : 0,
+      )
+      begin
+        resp = @query.gql(req, metadata: { "session-id" => @session_id.to_s })
+      rescue GRPC::BadStatus => e
+        raise wrap(e, "gql failed")
+      end
+      Result.new(resp)
+    end
+
+    # Run a writing GQL statement (read_only = false).
+    def execute(gql, params: nil, graph: nil, timeout: nil)
+      query(gql, params: params, graph: graph, read_only: false, timeout: timeout)
+    end
+
+    def close
+      @channel.close if @channel.respond_to?(:close)
+    rescue StandardError
+      # best effort - the channel is being torn down regardless
+    ensure
+      @channel = @session = @query = @session_id = nil
+    end
+
+    private
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def wait_for_ready(channel, started)
+      states = GRPC::Core::ConnectivityStates
+      deadline = Time.now + @connect_timeout
+      state = channel.connectivity_state(true)
+      until state == states::READY
+        break if Time.now >= deadline
+
+        channel.watch_connectivity_state(state, deadline)
+        state = channel.connectivity_state(true)
+      end
+      return if state == states::READY
+
+      elapsed = monotonic - started
+      close
+      raise ConnectError.new(@host, @port, elapsed)
+    end
+
+    def wrap(rpc_error, prefix)
+      detail = rpc_error.respond_to?(:details) ? rpc_error.details : nil
+      detail = rpc_error.message if detail.nil? || detail.to_s.empty?
+      code = rpc_error.class.name.to_s.split("::").last
+      Error.new("#{prefix}: #{detail}", code: code, cause: rpc_error)
+    end
+  end
+end

data/lib/tina4_ultipa/codec.rb

@@ -0,0 +1,391 @@
+# frozen_string_literal: true
+
+require "json"
+
+# Encode/decode gqldb TypedValue <-> Ruby values.
+#
+# Grounded against the official gqldb-nodejs SDK decoder and verified live against
+# gqldb-grpc 6.2.130 CE. All multi-byte integers are little-endian. Mirrors the
+# Python reference `_codec.py`, which passes all live tests.
+#
+# Inside composites (node/edge/map/list/table props) each value is a
+# **TypedValueEntry**: `type:u8 · isNull:u8 · dataLen:u32 · data` - a 1-byte type
+# plus a 1-byte is-null (NOT a u16 type); a set is-null yields nil regardless of data.
+
+module Tina4Ultipa
+  module Codec
+    module_function
+
+    # PropertyType (as the enum symbol google-protobuf hands back) -> pack/unpack
+    # directive for the fixed-width little-endian numeric types.
+    NUMERIC = {
+      PROPERTY_TYPE_INT32:  "l<",
+      PROPERTY_TYPE_UINT32: "L<",
+      PROPERTY_TYPE_INT64:  "q<",
+      PROPERTY_TYPE_UINT64: "Q<",
+      PROPERTY_TYPE_FLOAT:  "e",
+      PROPERTY_TYPE_DOUBLE: "E",
+    }.freeze
+
+    STRINGY = %i[PROPERTY_TYPE_STRING PROPERTY_TYPE_TEXT].freeze
+    NULLISH = %i[PROPERTY_TYPE_NULL PROPERTY_TYPE_UNSET].freeze
+    LISTY = %i[PROPERTY_TYPE_LIST PROPERTY_TYPE_SET].freeze
+    MAPPY = %i[PROPERTY_TYPE_MAP PROPERTY_TYPE_RECORD].freeze
+    LOCAL_DT = %i[PROPERTY_TYPE_DATETIME PROPERTY_TYPE_LOCAL_DATETIME].freeze
+
+    # A google-protobuf enum field usually reads back as a Symbol, but falls back
+    # to the raw Integer for values it does not know. Normalise to the symbol.
+    INT_TO_SYM = {
+      0 => :PROPERTY_TYPE_UNSET, 1 => :PROPERTY_TYPE_INT32, 2 => :PROPERTY_TYPE_UINT32,
+      3 => :PROPERTY_TYPE_INT64, 4 => :PROPERTY_TYPE_UINT64, 5 => :PROPERTY_TYPE_FLOAT,
+      6 => :PROPERTY_TYPE_DOUBLE, 7 => :PROPERTY_TYPE_STRING,
+      8 => :PROPERTY_TYPE_DATETIME, 9 => :PROPERTY_TYPE_TIMESTAMP, 10 => :PROPERTY_TYPE_TEXT,
+      11 => :PROPERTY_TYPE_BLOB, 12 => :PROPERTY_TYPE_POINT, 13 => :PROPERTY_TYPE_DECIMAL,
+      14 => :PROPERTY_TYPE_LIST, 15 => :PROPERTY_TYPE_SET, 16 => :PROPERTY_TYPE_MAP,
+      17 => :PROPERTY_TYPE_NULL, 18 => :PROPERTY_TYPE_BOOL,
+      19 => :PROPERTY_TYPE_LOCAL_DATETIME, 20 => :PROPERTY_TYPE_ZONED_DATETIME,
+      21 => :PROPERTY_TYPE_DATE, 22 => :PROPERTY_TYPE_ZONED_TIME,
+      23 => :PROPERTY_TYPE_LOCAL_TIME, 24 => :PROPERTY_TYPE_YEAR_TO_MONTH,
+      25 => :PROPERTY_TYPE_DAY_TO_SECOND, 26 => :PROPERTY_TYPE_RECORD,
+      27 => :PROPERTY_TYPE_POINT3D, 28 => :PROPERTY_TYPE_VECTOR,
+      29 => :PROPERTY_TYPE_TABLE, 30 => :PROPERTY_TYPE_PATH, 31 => :PROPERTY_TYPE_ERROR,
+      32 => :PROPERTY_TYPE_NODE, 33 => :PROPERTY_TYPE_EDGE
+    }.freeze
+
+    # ── temporal / spatial helpers ──────────────────────────────────────
+
+    def date(data)
+      return nil if data.nil? || data.bytesize < 4
+
+      y = data.byteslice(0, 2).unpack1("s<") # signed year (BCE round-trips)
+      format("%04d-%02d-%02d", y, data.getbyte(2), data.getbyte(3))
+    end
+
+    def time_str(hour, minute, sec, nanos)
+      base = format("%02d:%02d:%02d", hour, minute, sec)
+      return base if nanos.nil? || nanos.zero?
+
+      base + format(".%09d", nanos).sub(/0+\z/, "").sub(/\.\z/, "")
+    end
+
+    def local_time(data)
+      return nil if data.nil? || data.bytesize < 8
+
+      nanos = data.unpack1("@4 L<")
+      time_str(data.getbyte(0), data.getbyte(1), data.getbyte(2), nanos)
+    end
+
+    def zoned_time(data)
+      return nil if data.nil? || data.bytesize < 10
+
+      nanos = data.unpack1("@4 L<")
+      off = data.unpack1("@8 s<")
+      time_str(data.getbyte(0), data.getbyte(1), data.getbyte(2), nanos) + offset(off)
+    end
+
+    def offset(minutes)
+      sign = minutes >= 0 ? "+" : "-"
+      m = minutes.abs
+      format("%s%02d:%02d", sign, m / 60, m % 60)
+    end
+
+    def datetime_frac(base, nanos)
+      return base if nanos.nil? || nanos.zero?
+
+      base + format(".%09d", nanos).sub(/0+\z/, "").sub(/\.\z/, "")
+    end
+
+    def local_datetime(data)
+      if !data.nil? && data.bytesize >= 11
+        y = data.unpack1("s<")
+        nanos = data.unpack1("@7 L<")
+        base = format("%04d-%02d-%02d %02d:%02d:%02d", y, data.getbyte(2), data.getbyte(3),
+                      data.getbyte(4), data.getbyte(5), data.getbyte(6))
+        return datetime_frac(base, nanos)
+      end
+      unix(data) # legacy 8-byte unix fallback
+    end
+
+    def zoned_datetime(data)
+      if !data.nil? && data.bytesize >= 13
+        y = data.unpack1("s<")
+        nanos = data.unpack1("@7 L<")
+        off = data.unpack1("@11 s<")
+        base = format("%04d-%02d-%02d %02d:%02d:%02d", y, data.getbyte(2), data.getbyte(3),
+                      data.getbyte(4), data.getbyte(5), data.getbyte(6))
+        return datetime_frac(base, nanos) + offset(off)
+      end
+      unix(data)
+    end
+
+    def timestamp(data)
+      if !data.nil? && data.bytesize >= 12
+        secs = data.unpack1("q<")
+        nanos = data.unpack1("@8 L<")
+        begin
+          base = Time.at(secs).utc.strftime("%Y-%m-%d %H:%M:%S")
+          return datetime_frac(base, nanos)
+        rescue StandardError, RangeError
+          return secs
+        end
+      end
+      unix(data)
+    end
+
+    # Legacy 8-byte unix time (seconds/ms/us) -> 'YYYY-MM-DD HH:MM:SS' (UTC).
+    def unix(data)
+      return nil if data.nil? || data.bytesize < 8
+
+      v = data.byteslice(0, 8).unpack1("Q<")
+      secs = v > 1e14 ? v / 1e6 : (v > 1e11 ? v / 1e3 : v)
+      begin
+        Time.at(secs).utc.strftime("%Y-%m-%d %H:%M:%S")
+      rescue StandardError, RangeError
+        v
+      end
+    end
+
+    def point(data)
+      return nil if data.nil? || data.bytesize < 16
+
+      x = data.unpack1("E")
+      y = data.unpack1("@8 E")
+      srid = data.bytesize >= 20 ? data.unpack1("@16 L<") : 7203
+      { "_kind" => "point", "x" => x, "y" => y, "srid" => srid }
+    end
+
+    def point3d(data)
+      return nil if data.nil? || data.bytesize < 24
+
+      x = data.unpack1("E")
+      y = data.unpack1("@8 E")
+      z = data.unpack1("@16 E")
+      srid = data.bytesize >= 28 ? data.unpack1("@24 L<") : 9757
+      { "_kind" => "point3d", "x" => x, "y" => y, "z" => z, "srid" => srid }
+    end
+
+    def vector(data)
+      return [] if data.nil? || data.bytesize < 4
+
+      dim = data.unpack1("L<")
+      return [] if data.bytesize < 4 + dim * 4
+
+      Array.new(dim) { |i| data.unpack1("@#{4 + i * 4} e") }
+    end
+
+    def year_to_month(data)
+      return { "months" => 0 } if data.nil? || data.bytesize < 4
+
+      { "months" => data.unpack1("l<") }
+    end
+
+    def day_to_second(data)
+      return { "seconds" => 0, "nanoseconds" => 0 } if data.nil? || data.bytesize < 12
+
+      { "seconds" => data.unpack1("q<"), "nanoseconds" => data.unpack1("@8 L<") }
+    end
+
+    def error(data)
+      s = (data || "".b).dup.force_encoding("UTF-8")
+      obj = JSON.parse(s)
+      { "_kind" => "error", "code" => (obj["code"] || 0), "message" => (obj["message"] || "") }
+    rescue StandardError
+      { "_kind" => "error", "code" => 0, "message" => s }
+    end
+
+    # Walks a self-describing binary blob, reading little-endian fixed-width ints,
+    # length-prefixed strings, and TypedValueEntry composites. Mirrors Python _Reader.
+    class Reader
+      attr_accessor :d, :p
+
+      def initialize(data)
+        @d = (data || "".b).dup.force_encoding("BINARY")
+        @p = 0
+      end
+
+      def u8
+        v = @d.getbyte(@p)
+        @p += 1
+        v
+      end
+
+      def u16
+        v = @d.byteslice(@p, 2).unpack1("S<")
+        @p += 2
+        v
+      end
+
+      def u32
+        v = @d.byteslice(@p, 4).unpack1("L<")
+        @p += 4
+        v
+      end
+
+      def u64
+        v = @d.byteslice(@p, 8).unpack1("Q<")
+        @p += 8
+        v
+      end
+
+      # uint16 length prefix + that many UTF-8 bytes.
+      def str
+        n = u16
+        v = @d.byteslice(@p, n).dup.force_encoding("UTF-8")
+        @p += n
+        v
+      end
+
+      # A TypedValueEntry: type u8, isNull u8, len u32, data -> decoded value (nil if null).
+      def tve
+        t = u8
+        is_null = u8
+        n = u32
+        data = @d.byteslice(@p, n)
+        @p += n
+        is_null.zero? ? Codec.scalar(t, data) : nil
+      end
+
+      # uint16 count of (uint16 keyLen + key + TypedValueEntry) property pairs.
+      def props
+        out = {}
+        u16.times do
+          key = str
+          out[key] = tve
+        end
+        out
+      end
+    end
+
+    # ── composites ──────────────────────────────────────────────────────
+
+    def list(data)
+      r = Reader.new(data)
+      Array.new(r.u16) { r.tve }
+    end
+
+    def table(data)
+      r = Reader.new(data)
+      cols = Array.new(r.u16) { r.str }
+      rows = Array.new(r.u16) { Array.new(r.u16) { r.tve } }
+      { "_kind" => "table", "columns" => cols, "rows" => rows }
+    end
+
+    # Optional 8-byte little-endian uint64 internal-id trailer (gqldb 6.1.147+).
+    def trailer(reader)
+      reader.p + 8 <= reader.d.bytesize ? reader.u64.to_s : ""
+    end
+
+    def node(data)
+      r = Reader.new(data)
+      nid = r.str
+      labels = Array.new(r.u16) { r.str }
+      props = r.props
+      { "_kind" => "node", "id" => nid, "labels" => labels, "properties" => props,
+        "uuid" => trailer(r) }
+    end
+
+    def edge(data)
+      r = Reader.new(data)
+      eid = r.str
+      etype = r.str
+      src = r.str
+      dst = r.str
+      props = r.props
+      { "_kind" => "edge", "id" => eid, "type" => etype, "from" => src, "to" => dst,
+        "properties" => props, "uuid" => trailer(r) }
+    end
+
+    def path(data)
+      r = Reader.new(data)
+      nodes = Array.new(r.u16) do
+        n = r.u32
+        v = node(r.d.byteslice(r.p, n))
+        r.p += n
+        v
+      end
+      edges = Array.new(r.u16) do
+        n = r.u32
+        v = edge(r.d.byteslice(r.p, n))
+        r.p += n
+        v
+      end
+      { "_kind" => "path", "nodes" => nodes, "edges" => edges }
+    end
+
+    # ── dispatch ────────────────────────────────────────────────────────
+
+    # Decode a raw property/value payload of a given PropertyType. Used both for the
+    # top-level TypedValue and for each value inside a composite.
+    def scalar(ptype, data)
+      t = ptype
+      t = INT_TO_SYM[t] || t if t.is_a?(Integer)
+      return nil if NULLISH.include?(t)
+
+      fmt = NUMERIC[t]
+      unless fmt.nil?
+        return nil if data.nil? || data.empty?
+
+        return data.unpack1(fmt)
+      end
+      return data.dup.force_encoding("UTF-8") if STRINGY.include?(t)
+      return !(data.nil? || data.empty? || data.getbyte(0).zero?) if t == :PROPERTY_TYPE_BOOL
+      # BLOB: raw bytes as a binary string.
+      return (data || "".b).dup.force_encoding("BINARY") if t == :PROPERTY_TYPE_BLOB
+      # DECIMAL is a precision-preserving UTF-8 string: return it verbatim, never to_f.
+      return data.dup.force_encoding("UTF-8") if t == :PROPERTY_TYPE_DECIMAL
+      return date(data) if t == :PROPERTY_TYPE_DATE
+      return local_datetime(data) if LOCAL_DT.include?(t)
+      return zoned_datetime(data) if t == :PROPERTY_TYPE_ZONED_DATETIME
+      return timestamp(data) if t == :PROPERTY_TYPE_TIMESTAMP
+      return local_time(data) if t == :PROPERTY_TYPE_LOCAL_TIME
+      return zoned_time(data) if t == :PROPERTY_TYPE_ZONED_TIME
+      return year_to_month(data) if t == :PROPERTY_TYPE_YEAR_TO_MONTH
+      return day_to_second(data) if t == :PROPERTY_TYPE_DAY_TO_SECOND
+      return point(data) if t == :PROPERTY_TYPE_POINT
+      return point3d(data) if t == :PROPERTY_TYPE_POINT3D
+      return vector(data) if t == :PROPERTY_TYPE_VECTOR
+      return list(data) if LISTY.include?(t)
+      return Reader.new(data).props if MAPPY.include?(t)
+      return table(data) if t == :PROPERTY_TYPE_TABLE
+      return node(data) if t == :PROPERTY_TYPE_NODE
+      return edge(data) if t == :PROPERTY_TYPE_EDGE
+      return path(data) if t == :PROPERTY_TYPE_PATH
+      return error(data) if t == :PROPERTY_TYPE_ERROR
+
+      # Unmapped/future types: hand back the raw bytes rather than lose or guess.
+      data
+    end
+
+    # gqldb.TypedValue -> a Ruby value (nil for null; Hash for node/edge/...).
+    def decode(tv)
+      return nil if tv.is_null
+
+      scalar(tv.type, tv.data)
+    end
+
+    # A Ruby value -> gqldb.TypedValue, for query parameters.
+    def encode(value)
+      case value
+      when nil
+        Gqldb::TypedValue.new(type: :PROPERTY_TYPE_NULL, is_null: true)
+      when true, false
+        Gqldb::TypedValue.new(type: :PROPERTY_TYPE_BOOL, data: (value ? "\x01" : "\x00").b)
+      when Integer
+        Gqldb::TypedValue.new(type: :PROPERTY_TYPE_INT64, data: [value].pack("q<"))
+      when Float
+        Gqldb::TypedValue.new(type: :PROPERTY_TYPE_DOUBLE, data: [value].pack("E"))
+      when String
+        # A binary (ASCII-8BIT) String is the Ruby analogue of Python `bytes`:
+        # send it as a BLOB so raw bytes round-trip intact. UTF-8/other -> STRING.
+        if value.encoding == Encoding::ASCII_8BIT
+          Gqldb::TypedValue.new(type: :PROPERTY_TYPE_BLOB, data: value)
+        else
+          Gqldb::TypedValue.new(type: :PROPERTY_TYPE_STRING, data: value.b)
+        end
+      else
+        # Anything else -> UTF-8 bytes.
+        Gqldb::TypedValue.new(type: :PROPERTY_TYPE_STRING, data: value.to_s.b)
+      end
+    end
+  end
+end

data/lib/tina4_ultipa/errors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Tina4Ultipa
+  # A gqldb server or protocol error. Writes and bad statements fail LOUD (raise),
+  # never a falsy return - the framework's graph layer relies on this.
+  # `code` is the gRPC status name when known.
+  class Error < StandardError
+    attr_reader :code
+
+    def initialize(message, code: nil, cause: nil)
+      super(message)
+      @code = code
+      @cause_error = cause
+    end
+
+    # The wrapped lower-level exception (gRPC error), when there is one.
+    attr_reader :cause_error
+  end
+
+  # Could not connect within the timeout. Names host, port and elapsed seconds.
+  class ConnectError < Error
+    attr_reader :host, :port, :elapsed
+
+    def initialize(host, port, elapsed, cause: nil)
+      super(
+        "could not connect to ultipa at #{host}:#{port} within #{format('%.2f', elapsed)}s",
+        code: "UNAVAILABLE",
+        cause: cause,
+      )
+      @host = host
+      @port = port
+      @elapsed = elapsed
+    end
+  end
+end

data/lib/tina4_ultipa/gen/gqldb_pb.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: gqldb.proto
+
+require 'google/protobuf'
+
+
+descriptor_data = "\n\x0bgqldb.proto\x12\x05gqldb\"N\n\nTypedValue\x12!\n\x04type\x18\x01 \x01(\x0e\x32\x13.gqldb.PropertyType\x12\x0c\n\x04\x64\x61ta\x18\x02 \x01(\x0c\x12\x0f\n\x07is_null\x18\x03 \x01(\x08\";\n\tParameter\x12\x0c\n\x04name\x18\x01 \x01(\t\x12 \n\x05value\x18\x02 \x01(\x0b\x32\x11.gqldb.TypedValue\"(\n\x03Row\x12!\n\x06values\x18\x01 \x03(\x0b\x32\x11.gqldb.TypedValue\"\x8e\x01\n\x08\x44mlStats\x12\x16\n\x0einserted_nodes\x18\x01 \x01(\x03\x12\x16\n\x0einserted_edges\x18\x02 \x01(\x03\x12\x15\n\rdeleted_nodes\x18\x03 \x01(\x03\x12\x15\n\rdeleted_edges\x18\x04 \x01(\x03\x12\x11\n\tset_nodes\x18\x05 \x01(\x03\x12\x11\n\tset_edges\x18\x06 \x01(\x03\"I\n\x0cLoginRequest\x12\x10\n\x08username\x18\x01 \x01(\t\x12\x10\n\x08password\x18\x02 \x01(\t\x12\x15\n\rdefault_graph\x18\x03 \x01(\t\"\xfd\x01\n\rLoginResponse\x12\x12\n\nsession_id\x18\x01 \x01(\x04\x12\x16\n\x0eserver_version\x18\x02 \x01(\t\x12\r\n\x05roles\x18\x03 \x03(\t\x12\x12\n\nis_cluster\x18\n \x01(\x08\x12\x12\n\ncluster_id\x18\x0b \x01(\t\x12\x17\n\x0fpartition_count\x18\x0c \x01(\x05\x12\x14\n\x0c\x63\x61pabilities\x18\x14 \x03(\t\x12\x15\n\rcurrent_graph\x18\x15 \x01(\t\x12\x14\n\x0ctime_cost_ns\x18\x16 \x01(\x03\x12\x14\n\x0c\x64isk_cost_ns\x18\x17 \x01(\x03\x12\x17\n\x0f\x63ompute_cost_ns\x18\x18 \x01(\x03\"\xbd\x01\n\nGqlRequest\x12\x0b\n\x03gql\x18\x01 \x01(\t\x12\x12\n\ngraph_name\x18\x02 \x01(\t\x12$\n\nparameters\x18\x03 \x03(\x0b\x32\x10.gqldb.Parameter\x12\x12\n\nsession_id\x18\x04 \x01(\x04\x12\x16\n\x0etransaction_id\x18\x05 \x01(\x04\x12\x0f\n\x07timeout\x18\x06 \x01(\x05\x12\x11\n\tread_only\x18\x07 \x01(\x08\x12\x18\n\x10max_path_results\x18\x08 \x01(\x03\"\x86\x02\n\x0bGqlResponse\x12\x0f\n\x07\x63olumns\x18\x01 \x03(\t\x12\x18\n\x04rows\x18\x02 \x03(\x0b\x32\n.gqldb.Row\x12\x11\n\trow_count\x18\x03 \x01(\x03\x12\x10\n\x08has_more\x18\x04 \x01(\x08\x12\x10\n\x08warnings\x18\x05 \x03(\t\x12\x15\n\rrows_affected\x18\x06 \x01(\x03\x12\x15\n\rcurrent_graph\x18\x07 \x01(\t\x12\x14\n\x0ctime_cost_ns\x18\x08 \x01(\x03\x12\x14\n\x0c\x64isk_cost_ns\x18\t \x01(\x03\x12\x17\n\x0f\x63ompute_cost_ns\x18\n \x01(\x03\x12\"\n\tdml_stats\x18\x0b \x01(\x0b\x32\x0f.gqldb.DmlStats*\x90\x07\n\x0cPropertyType\x12\x17\n\x13PROPERTY_TYPE_UNSET\x10\x00\x12\x17\n\x13PROPERTY_TYPE_INT32\x10\x01\x12\x18\n\x14PROPERTY_TYPE_UINT32\x10\x02\x12\x17\n\x13PROPERTY_TYPE_INT64\x10\x03\x12\x18\n\x14PROPERTY_TYPE_UINT64\x10\x04\x12\x17\n\x13PROPERTY_TYPE_FLOAT\x10\x05\x12\x18\n\x14PROPERTY_TYPE_DOUBLE\x10\x06\x12\x18\n\x14PROPERTY_TYPE_STRING\x10\x07\x12\x1a\n\x16PROPERTY_TYPE_DATETIME\x10\x08\x12\x1b\n\x17PROPERTY_TYPE_TIMESTAMP\x10\t\x12\x16\n\x12PROPERTY_TYPE_TEXT\x10\n\x12\x16\n\x12PROPERTY_TYPE_BLOB\x10\x0b\x12\x17\n\x13PROPERTY_TYPE_POINT\x10\x0c\x12\x19\n\x15PROPERTY_TYPE_DECIMAL\x10\r\x12\x16\n\x12PROPERTY_TYPE_LIST\x10\x0e\x12\x15\n\x11PROPERTY_TYPE_SET\x10\x0f\x12\x15\n\x11PROPERTY_TYPE_MAP\x10\x10\x12\x16\n\x12PROPERTY_TYPE_NULL\x10\x11\x12\x16\n\x12PROPERTY_TYPE_BOOL\x10\x12\x12 \n\x1cPROPERTY_TYPE_LOCAL_DATETIME\x10\x13\x12 \n\x1cPROPERTY_TYPE_ZONED_DATETIME\x10\x14\x12\x16\n\x12PROPERTY_TYPE_DATE\x10\x15\x12\x1c\n\x18PROPERTY_TYPE_ZONED_TIME\x10\x16\x12\x1c\n\x18PROPERTY_TYPE_LOCAL_TIME\x10\x17\x12\x1f\n\x1bPROPERTY_TYPE_YEAR_TO_MONTH\x10\x18\x12\x1f\n\x1bPROPERTY_TYPE_DAY_TO_SECOND\x10\x19\x12\x18\n\x14PROPERTY_TYPE_RECORD\x10\x1a\x12\x19\n\x15PROPERTY_TYPE_POINT3D\x10\x1b\x12\x18\n\x14PROPERTY_TYPE_VECTOR\x10\x1c\x12\x17\n\x13PROPERTY_TYPE_TABLE\x10\x1d\x12\x16\n\x12PROPERTY_TYPE_PATH\x10\x1e\x12\x17\n\x13PROPERTY_TYPE_ERROR\x10\x1f\x12\x16\n\x12PROPERTY_TYPE_NODE\x10 \x12\x16\n\x12PROPERTY_TYPE_EDGE\x10!2D\n\x0eSessionService\x12\x32\n\x05Login\x12\x13.gqldb.LoginRequest\x1a\x14.gqldb.LoginResponse2<\n\x0cQueryService\x12,\n\x03Gql\x12\x11.gqldb.GqlRequest\x1a\x12.gqldb.GqlResponseb\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Gqldb
+  TypedValue = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gqldb.TypedValue").msgclass
+  Parameter = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gqldb.Parameter").msgclass
+  Row = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gqldb.Row").msgclass
+  DmlStats = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gqldb.DmlStats").msgclass
+  LoginRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gqldb.LoginRequest").msgclass
+  LoginResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gqldb.LoginResponse").msgclass
+  GqlRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gqldb.GqlRequest").msgclass
+  GqlResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gqldb.GqlResponse").msgclass
+  PropertyType = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gqldb.PropertyType").enummodule
+end

data/lib/tina4_ultipa/gen/gqldb_services_pb.rb

@@ -0,0 +1,36 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# Source: gqldb.proto for package 'gqldb'
+
+require 'grpc'
+require 'gqldb_pb'
+
+module Gqldb
+  module SessionService
+    class Service
+
+      include ::GRPC::GenericService
+
+      self.marshal_class_method = :encode
+      self.unmarshal_class_method = :decode
+      self.service_name = 'gqldb.SessionService'
+
+      rpc :Login, ::Gqldb::LoginRequest, ::Gqldb::LoginResponse
+    end
+
+    Stub = Service.rpc_stub_class
+  end
+  module QueryService
+    class Service
+
+      include ::GRPC::GenericService
+
+      self.marshal_class_method = :encode
+      self.unmarshal_class_method = :decode
+      self.service_name = 'gqldb.QueryService'
+
+      rpc :Gql, ::Gqldb::GqlRequest, ::Gqldb::GqlResponse
+    end
+
+    Stub = Service.rpc_stub_class
+  end
+end

data/lib/tina4_ultipa/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tina4Ultipa
+  VERSION = "0.1.0"
+end

data/lib/tina4_ultipa.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# tina4-ultipa - a thin gRPC client for the Ultipa (gqldb) graph database.
+#
+# Used by Tina4's graph data layer, and usable standalone:
+#
+#     require "tina4_ultipa"
+#     db = Tina4Ultipa::Client.from_url("ultipa://admin:pass@host:60061/mygraph")
+#     db.query("MATCH (n) RETURN n LIMIT 10").each { |row| puts row }
+
+require_relative "tina4_ultipa/version"
+require_relative "tina4_ultipa/errors"
+require_relative "tina4_ultipa/client"
+
+module Tina4Ultipa
+end

data/proto/gqldb.proto

@@ -0,0 +1,122 @@
+syntax = "proto3";
+
+// Minimal subset of the Ultipa `ultipa-gqldb` gRPC surface that this driver
+// uses: authenticate (SessionService.Login) and run GQL (QueryService.Gql).
+// Field numbers/types match the server exactly (grounded via reflection against
+// the community edition, 2026-08-20). proto3 ignores unknown fields, so the
+// server's extra methods/fields we don't list here are harmless.
+package gqldb;
+
+enum PropertyType {
+  PROPERTY_TYPE_UNSET = 0;
+  PROPERTY_TYPE_INT32 = 1;
+  PROPERTY_TYPE_UINT32 = 2;
+  PROPERTY_TYPE_INT64 = 3;
+  PROPERTY_TYPE_UINT64 = 4;
+  PROPERTY_TYPE_FLOAT = 5;
+  PROPERTY_TYPE_DOUBLE = 6;
+  PROPERTY_TYPE_STRING = 7;
+  PROPERTY_TYPE_DATETIME = 8;
+  PROPERTY_TYPE_TIMESTAMP = 9;
+  PROPERTY_TYPE_TEXT = 10;
+  PROPERTY_TYPE_BLOB = 11;
+  PROPERTY_TYPE_POINT = 12;
+  PROPERTY_TYPE_DECIMAL = 13;
+  PROPERTY_TYPE_LIST = 14;
+  PROPERTY_TYPE_SET = 15;
+  PROPERTY_TYPE_MAP = 16;
+  PROPERTY_TYPE_NULL = 17;
+  PROPERTY_TYPE_BOOL = 18;
+  PROPERTY_TYPE_LOCAL_DATETIME = 19;
+  PROPERTY_TYPE_ZONED_DATETIME = 20;
+  PROPERTY_TYPE_DATE = 21;
+  PROPERTY_TYPE_ZONED_TIME = 22;
+  PROPERTY_TYPE_LOCAL_TIME = 23;
+  PROPERTY_TYPE_YEAR_TO_MONTH = 24;
+  PROPERTY_TYPE_DAY_TO_SECOND = 25;
+  PROPERTY_TYPE_RECORD = 26;
+  PROPERTY_TYPE_POINT3D = 27;
+  PROPERTY_TYPE_VECTOR = 28;
+  PROPERTY_TYPE_TABLE = 29;
+  PROPERTY_TYPE_PATH = 30;
+  PROPERTY_TYPE_ERROR = 31;
+  PROPERTY_TYPE_NODE = 32;
+  PROPERTY_TYPE_EDGE = 33;
+}
+
+message TypedValue {
+  PropertyType type = 1;
+  bytes data = 2;
+  bool is_null = 3;
+}
+
+message Parameter {
+  string name = 1;
+  TypedValue value = 2;
+}
+
+message Row {
+  repeated TypedValue values = 1;
+}
+
+message DmlStats {
+  int64 inserted_nodes = 1;
+  int64 inserted_edges = 2;
+  int64 deleted_nodes = 3;
+  int64 deleted_edges = 4;
+  int64 set_nodes = 5;
+  int64 set_edges = 6;
+}
+
+message LoginRequest {
+  string username = 1;
+  string password = 2;
+  string default_graph = 3;
+}
+
+message LoginResponse {
+  uint64 session_id = 1;
+  string server_version = 2;
+  repeated string roles = 3;
+  bool is_cluster = 10;
+  string cluster_id = 11;
+  int32 partition_count = 12;
+  repeated string capabilities = 20;
+  string current_graph = 21;
+  int64 time_cost_ns = 22;
+  int64 disk_cost_ns = 23;
+  int64 compute_cost_ns = 24;
+}
+
+message GqlRequest {
+  string gql = 1;
+  string graph_name = 2;
+  repeated Parameter parameters = 3;
+  uint64 session_id = 4;
+  uint64 transaction_id = 5;
+  int32 timeout = 6;
+  bool read_only = 7;
+  int64 max_path_results = 8;
+}
+
+message GqlResponse {
+  repeated string columns = 1;
+  repeated Row rows = 2;
+  int64 row_count = 3;
+  bool has_more = 4;
+  repeated string warnings = 5;
+  int64 rows_affected = 6;
+  string current_graph = 7;
+  int64 time_cost_ns = 8;
+  int64 disk_cost_ns = 9;
+  int64 compute_cost_ns = 10;
+  DmlStats dml_stats = 11;
+}
+
+service SessionService {
+  rpc Login (LoginRequest) returns (LoginResponse);
+}
+
+service QueryService {
+  rpc Gql (GqlRequest) returns (GqlResponse);
+}

data/tina4-ultipa.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "lib/tina4_ultipa/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "tina4-ultipa"
+  spec.version = Tina4Ultipa::VERSION
+  spec.authors = ["Tina4 Stack"]
+  spec.email = ["info@tina4.com"]
+
+  spec.summary = "Thin gRPC client for the Ultipa graph database (ultipa-gqldb)"
+  spec.description = "A thin, standalone gRPC client for the Ultipa graph database " \
+                     "(ultipa-gqldb) - the Ultipa driver behind Tina4's graph layer, " \
+                     "usable on its own."
+  spec.homepage = "https://github.com/tina4stack/ultipa-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "proto/*.proto",
+    "README.md",
+    "LICENSE",
+    "tina4-ultipa.gemspec",
+  ]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "google-protobuf", ">= 3.25"
+  spec.add_dependency "grpc", ">= 1.60"
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: tina4-ultipa
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tina4 Stack
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: google-protobuf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.25'
+- !ruby/object:Gem::Dependency
+  name: grpc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.60'
+description: A thin, standalone gRPC client for the Ultipa graph database (ultipa-gqldb)
+  - the Ultipa driver behind Tina4's graph layer, usable on its own.
+email:
+- info@tina4.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/tina4_ultipa.rb
+- lib/tina4_ultipa/client.rb
+- lib/tina4_ultipa/codec.rb
+- lib/tina4_ultipa/errors.rb
+- lib/tina4_ultipa/gen/gqldb_pb.rb
+- lib/tina4_ultipa/gen/gqldb_services_pb.rb
+- lib/tina4_ultipa/version.rb
+- proto/gqldb.proto
+- tina4-ultipa.gemspec
+homepage: https://github.com/tina4stack/ultipa-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tina4stack/ultipa-ruby
+  source_code_uri: https://github.com/tina4stack/ultipa-ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Thin gRPC client for the Ultipa graph database (ultipa-gqldb)
+test_files: []