Instant Ruby

A lightweight, idiomatic Ruby client for InstantDB.

This gem provides a clean interface for InstantDB's Admin API, allowing you to query data, run transactions, and manage authentication from your Ruby backend.

Installation

Add this line to your application's Gemfile:

gem 'instant-ruby'

And then execute:

$ bundle install

Quick Start

require 'instant-ruby'

# 1. Configure
Instant::Client.configure do |config|
  config.app_id = ENV['INSTANT_APP_ID']
  config.admin_token = ENV['INSTANT_ADMIN_TOKEN']
end

# 2. Write data (Transaction)
user_id = Instant::Client.id
Instant::Client.transact do |tx|
  tx.users[user_id].update(name: "Alice", email: "alice@example.com")
end

# 3. Query data
users = Instant::Client.query({ users: { where: { email: "alice@example.com" } } })

Configuration

In a Rails application, place this in config/initializers/instant.rb.

Instant::Client.configure do |config|
  config.app_id = Rails.application.credentials.dig(:instant, :app_id)
  config.admin_token = Rails.application.credentials.dig(:instant, :admin_token)
end

Querying

The query syntax mirrors the InstantDB client SDK. The gem automatically handles the $ operator for modifiers (like where, order, limit), so you can write clean Ruby hashes.

Basic Queries

# Fetch all tasks
data = Instant::Client.query({ tasks: {} })

# With modifiers (automatically normalized)
data = Instant::Client.query({
  tasks: {
    where: { completed: false },
    order: { created_at: "desc" },
    limit: 10
  }
})

# Nested relations
data = Instant::Client.query({
  users: {
    posts: {
      comments: { limit: 5 }
    }
  }
})

Helper Methods

Convenience methods are available for common patterns:

# Query all items in a namespace
Instant::Client.query_all(:users)

# Query with a simple where clause
Instant::Client.query_where(:users, { email: "alice@example.com" })

# Query by specific ID
Instant::Client.query_by_id(:users, "user-id-123")

Transactions

Transactions allow you to write, update, and delete data atomically.

Block Syntax (Recommended)

The block syntax allows for readable, chainable operations.

user_id = Instant::Client.id
team_id = "team-123"

Instant::Client.transact do |tx|
  # Create/Update a user and link to a team
  tx.users[user_id].update(
    name: "Alice",
    role: "admin"
  ).link(teams: team_id)

  # Update the team in the same transaction
  tx.teams[team_id].update(active: true)
end

Operations

Available operations on an entity:

update(attrs): Updates fields (merges).
link(relation_name: id): Creates a link.
unlink(relation_name: id): Removes a link.
delete: Deletes the entity.

Array Syntax

For dynamic or programmatic transactions, you can pass an array of steps directly.

steps = []
steps << Instant::Client.tx.users["user-1"].delete
steps << Instant::Client.tx.logs[Instant::Client.id].update(action: "deleted_user")

Instant::Client.transact(steps)

Authentication & Permissions

Managing Tokens

# Create a refresh token for a specific email
token = Instant::Client.create_token("alice@example.com")

# Create a guest user (returns token and user ID)
guest = Instant::Client.create_guest_user

Impersonation

You can run queries or transactions "as" a specific user to test permissions or perform actions on their behalf.

# Fetch data as 'alice@example.com'
Instant::Client.query(
  { secrets: {} },
  as_email: "alice@example.com"
)

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/dqnamo/instant-ruby.

License

The gem is available as open source under the terms of the MIT License.