Ruby Quick Start

WoWSQL Ruby SDK — Get started in minutes

Get your API key: Use the WoWSQL project dashboard to create or copy your API key. The same key works for database, auth, and storage (unified API key).

Installation

Official package: View on RubyGems →

Direct install:

gem install wowsql-sdk

Gemfile:

# Gemfile
gem 'wowsql-sdk', '~> 1.0'

# Then run
bundle install

Initialize Client

require 'wowsql'

# Initialize client with your API key (same key for database, auth, storage)
client = WowSQL::Client.new(
  project_url: 'myproject',
  api_key: 'your_api_key_here'
)

# Or with full URL
client_full = WowSQL::Client.new(
  project_url: 'https://myproject.wowsql.com',
  api_key: 'your_api_key'
)

# Always use select() before get()
users = client.table('users').select('*').get

Query Data

Basic Queries

# Get all records
users = client.table('users').select('*').get

# With filters
adults = client.table('users')
  .select('*')
  .gte('age', 18)
  .get

# Select specific columns
names = client.table('users')
  .select('id', 'name')
  .get

Advanced Queries

# Multiple filters with sorting
active_users = client.table('users')
  .select('*')
  .eq('status', 'active')
  .gt('age', 18)
  .order_by('created_at', desc: true)
  .limit(20)
  .offset(0)
  .get

puts "Found #{active_users['count']} users"
active_users['data'].each { |user| puts user['name'] }

Filter Helper Methods

# Using helper methods
users = client.table('users')
  .eq('status', 'active')
  .gt('age', 18)
  .like('email', '%@gmail.com')
  .is_not_null('email_verified_at')
  .in('role', %w[admin moderator])
  .between('created_at', '2024-01-01', '2024-12-31')
  .get

GROUP BY and Aggregates

Basic GROUP BY

# Group by category with counts
result = client.table('products')
  .select('category', 'COUNT(*) as count', 'AVG(price) as avg_price')
  .group_by('category')
  .get

# Group by date
result2 = client.table('orders')
  .select('DATE(created_at) as date', 'COUNT(*) as orders', 'SUM(total) as revenue')
  .group_by('DATE(created_at)')
  .order_by('date', desc: true)
  .get

HAVING Clause

# Filter aggregated results
result = client.table('products')
  .select('category', 'COUNT(*) as count')
  .group_by('category')
  .having('COUNT(*)', 'gt', 10)
  .get

CRUD Operations

Create Record

result = client.table('users').create(
  name: 'John Doe',
  email: 'john@example.com',
  age: 30
)
puts "Created user with ID: #{result['id']}"

Update Record

client.table('users').update(123, email: 'newemail@example.com')
puts 'User updated successfully'

Delete Record

client.table('users').delete(123)
puts 'User deleted successfully'

Get Single Record by ID

user = client.table('users').get_by_id(123)
puts "User: #{user['name']}"

Get First Record

user = client.table('users')
  .eq('status', 'active')
  .first

puts "First active user: #{user['name']}" if user

Filter Operators

Available operators for filtering data:

Error Handling

begin
  users = client.table('users').select('*').get
  puts "Success: #{users['data'].count} users"
rescue WowSQL::WOWSQLException => e
  puts "Database error (#{e.status_code}): #{e.message}"
rescue WowSQL::StorageException => e
  puts "Storage error: #{e.message}"
end

Rails Integration

Use a global client via Rails credentials:

# config/initializers/wowsql.rb
WOWSQL_CLIENT = WOWSQL::WOWSQLClient.new(
  Rails.application.credentials.wowsql[:project_url],
  Rails.application.credentials.wowsql[:api_key]
)

# app/controllers/users_controller.rb
class UsersController < ApplicationController
  def index
    @users = WOWSQL_CLIENT.table('users')
      .select('id', 'name', 'email')
      .get['data']
  end
end

Authentication

Use the same API key for authentication. One key works for database and auth.

Sign Up & Sign In

auth = WowSQL::Auth.new(project_url: 'myproject', api_key: 'your_api_key')

# Sign up
result = auth.sign_up(
  email: 'user@example.com',
  password: 'SecurePassword123',
  full_name: 'John Doe'
)
puts "Access token: #{result['access_token']}"

# Sign in
login = auth.sign_in(email: 'user@example.com', password: 'SecurePassword123')
puts "User ID: #{login['user']['id']}"

Password Reset

auth.forgot_password(email: 'user@example.com')
auth.reset_password(token: 'reset_token_from_email', new_password: 'NewSecurePassword123')

OTP Authentication

auth.send_otp(email: 'user@example.com', purpose: 'login')
result = auth.verify_otp(
  email: 'user@example.com',
  otp: '123456',
  purpose: 'login'
)
puts "Logged in: #{result[:user][:id]}"

Magic Link & Email Verification

auth.send_magic_link(email: 'user@example.com', purpose: 'login')
auth.verify_email(token: 'verification_token_from_email')
auth.resend_verification(email: 'user@example.com')

OAuth Authentication

result = auth.get_oauth_authorization_url(
  provider: 'github',
  redirect_uri: 'http://localhost:5000/auth/callback'
)
# Redirect user to result[:authorization_url]
auth_result = auth.exchange_oauth_callback(
  provider: 'github',
  code: 'authorization_code_from_callback'
)
puts "OAuth login successful: #{auth_result[:user][:id]}"

Storage Operations

Initialize Storage

storage = WowSQL::Storage.new(
  project_url: 'myproject',
  api_key: 'your_api_key'
)

File Operations

# Upload file
result = storage.upload_from_path('path/to/document.pdf', 'uploads/document.pdf', 'documents')
puts "Uploaded: #{result['file_key']}"

# Get file URL
url_data = storage.get_file_url('uploads/document.pdf', 3600)
puts "Download URL: #{url_data['file_url']}"

# List files
files = storage.list_files('uploads/')
files.each { |file| puts "#{file['key']}: #{ (file['size'].to_f / 1024 / 1024).round(2) } MB" }

# Delete file
storage.delete_file('uploads/document.pdf')

# Check quota
quota = storage.get_quota
puts "Used: #{quota['used_gb']} GB / #{quota['quota_gb']} GB"

Download or View File

Via REST: use GET .../files/{file_key}/download for attachment download, or GET .../files/{file_key}/view to view inline in the browser.