GitDB Ruby Client

Official Ruby client for GitDB - GitHub-backed NoSQL database.

Installation

Add this line to your application's Gemfile:

gem 'gitdb-client'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install gitdb-client

Quick Start

require 'gitdb_client'

# Create a client instance
client = GitDBClient.new('your-github-token', 'owner', 'repository')

# Check server health
client.health

# Create a collection
client.create_collection('users')

# Insert a document
document = {
  name: 'John Doe',
  email: '[email protected]',
  age: 30
}

id = client.insert('users', document)
puts "Inserted document with ID: #{id}"

# Find documents
query = {
  age: { '$gte' => 25 }
}

documents = client.find('users', query)
puts "Found #{documents.length} documents"

# Update a document
update = { age: 31 }
client.update('users', id, update)

# Delete a document
client.delete('users', id)

Features

  • ✅ Simple Ruby API - Easy to use Ruby interface
  • ✅ Full CRUD operations - Create, Read, Update, Delete documents
  • ✅ Query support - MongoDB-style query operators
  • ✅ Collection management - Create, list, delete collections
  • ✅ Error handling - Comprehensive error handling
  • ✅ HTTP client - Built-in HTTP client with retry logic
  • ✅ JSON handling - Native JSON serialization/deserialization
  • ✅ Ruby 2.6+ support - Modern Ruby compatibility

Configuration

GitHub Token

You'll need a GitHub Personal Access Token with the following permissions:

  • repo - Full control of private repositories
  • workflow - Update GitHub Action workflows

Create a token at: https://github.com/settings/tokens

Client Initialization

require 'gitdb_client'

# Basic initialization
client = GitDBClient.new('token', 'owner', 'repo')

# With custom base URL (for self-hosted instances)
client = GitDBClient.new('token', 'owner', 'repo', 'http://localhost:7896')

API Reference

Client Creation

# Create a new client
client = GitDBClient.new(token, owner, repo)

# Create client with custom URL
client = GitDBClient.new(token, owner, repo, 'http://localhost:7896')

Health Check

# Check if server is healthy
client.health

Collection Management

# Create a collection
client.create_collection('users')

# List all collections
collections = client.list_collections
collections.each do |collection|
  puts "Collection: #{collection['name']} (#{collection['count']} documents)"
end

# Delete a collection
client.delete_collection('users')

Document Operations

Insert

document = {
  name: 'Alice',
  email: '[email protected]',
  age: 25
}

id = client.insert('users', document)
puts "Inserted with ID: #{id}"

Find

# Find all documents
all_users = client.find('users', nil)

# Find with query
query = {
  age: { '$gte' => 30 }
}
older_users = client.find('users', query)

# Find one document
user = client.find_one('users', query)

# Find by ID
user = client.find_by_id('users', 'document-id')

Update

update = {
  age: 26,
  last_updated: '2024-01-01'
}

client.update('users', 'document-id', update)

Delete

# Delete by ID
client.delete('users', 'document-id')

# Delete multiple documents
query = {
  age: { '$lt' => 18 }
}
deleted_count = client.delete_many('users', query)

Batch Operations

# Insert multiple documents
documents = [
  { name: 'Alice', age: 25 },
  { name: 'Bob', age: 30 },
  { name: 'Charlie', age: 35 }
]

documents.each do |doc|
  id = client.insert('users', doc)
end

# Update multiple documents
query = {
  age: { '$gte' => 25 }
}

update = {
  category: 'senior'
}

updated_count = client.update_many('users', query, update)

Query Operators

The Ruby client supports MongoDB-style query operators:

query = {}

# Equal
query[:age] = 30

# Greater than
query[:age] = { '$gt' => 25 }

# Greater than or equal
query[:age] = { '$gte' => 25 }

# Less than
query[:age] = { '$lt' => 50 }

# Less than or equal
query[:age] = { '$lte' => 50 }

# In array
query[:status] = { '$in' => ['active', 'pending'] }

# Not in array
query[:status] = { '$nin' => ['inactive', 'deleted'] }

# Logical AND
query[:'$and'] = [
  { age: { '$gte' => 18 } },
  { status: 'active' }
]

# Logical OR
query[:'$or'] = [
  { status: 'active' },
  { status: 'pending' }
]

Error Handling

The SDK provides comprehensive error handling:

begin
  document = client.find_by_id('users', 'non-existent-id')
rescue GitDBError => e
  puts "GitDB Error: #{e.message}"
  puts "Status Code: #{e.status_code}"
rescue => e
  puts "General Error: #{e.message}"
end

Advanced Usage

Custom HTTP Client

require 'httparty'

# Create custom HTTP client
http_client = HTTParty
http_client.timeout = 30

# Create GitDB client with custom HTTP client
client = GitDBClient.new('token', 'owner', 'repo', http_client: http_client)

Retry Logic

# The client includes built-in retry logic for transient errors
# You can configure retry behavior if needed
client.max_retries = 3
client.retry_delay = 1

Examples

User Management System

require 'gitdb_client'

class User
  attr_accessor :id, :name, :email, :age, :status, :created_at

  def initialize(name, email, age)
    @name = name
    @email = email
    @age = age
    @status = 'active'
    @created_at = Time.now
  end

  def to_hash
    {
      name: @name,
      email: @email,
      age: @age,
      status: @status,
      created_at: @created_at
    }
  end
end

class UserManager
  def initialize(token, owner, repo)
    @client = GitDBClient.new(token, owner, repo)
  end

  def create_user(name, email, age)
    user = User.new(name, email, age)
    @client.insert('users', user.to_hash)
  end

  def find_user_by_email(email)
    query = { email: email }
    @client.find_one('users', query)
  end

  def update_user_status(user_id, status)
    update = { status: status }
    @client.update('users', user_id, update)
  end

  def get_active_users
    query = { status: 'active' }
    @client.find('users', query)
  end

  def delete_inactive_users
    query = { status: 'inactive' }
    @client.delete_many('users', query)
  end
end

# Usage
user_manager = UserManager.new('your-token', 'owner', 'repo')

# Create user
user_id = user_manager.create_user('John Doe', '[email protected]', 30)

# Find user
user = user_manager.find_user_by_email('[email protected]')

# Update status
user_manager.update_user_status(user_id, 'inactive')

# Get active users
active_users = user_manager.get_active_users
puts "Active users: #{active_users.length}"

Testing

require 'rspec'
require 'gitdb_client'

RSpec.describe GitDBClient do
  describe '#new' do
    it 'creates a client instance' do
      client = GitDBClient.new('token', 'owner', 'repo')
      expect(client).to be_a(GitDBClient)
    end
  end

  describe '#insert and #find_by_id' do
    it 'inserts and finds a document' do
      client = GitDBClient.new('token', 'owner', 'repo')

      # Test document
      document = {
        name: 'Test User',
        age: 25
      }

      # Insert
      id = client.insert('test', document)

      # Find by ID
      found = client.find_by_id('test', id)

      expect(found['name']).to eq('Test User')

      # Cleanup
      client.delete('test', id)
    end
  end
end

Troubleshooting

Common Issues

  1. Authentication Error

    • Verify your GitHub token is valid
    • Ensure token has required permissions
    • Check token hasn't expired

  2. Repository Access

    • Verify repository exists
    • Check you have access to the repository
    • Ensure repository is not private (unless using private GitDB)

  3. Network Issues

    • Check internet connection
    • Verify GitHub API is accessible
    • Check firewall settings

  4. Rate Limiting

    • GitHub API has rate limits
    • Implement exponential backoff for retries
    • Consider using authenticated requests

Debug Mode

Enable debug mode to see detailed request/response information:

# Set debug mode (if supported by the client)
client.debug_mode = true

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Changelog

v1.0.0

  • Initial release
  • Full CRUD operations
  • Query support with MongoDB-style operators
  • Error handling
  • Comprehensive documentation