Getting Started Tutorial

Getting Started with IceFireDB #

Introduction #

This tutorial will guide you through setting up and using IceFireDB for the first time. We’ll cover installation, basic operations, and some advanced features.

Prerequisites #

  • Go 1.18+ installed
  • Basic understanding of Redis commands
  • Terminal/shell access

Installation #

Method 1: From Source #

# Clone the repository
git clone https://github.com/IceFireDB/IceFireDB.git
cd IceFireDB

# Build the project
make build

# The binary will be in the bin/ directory
ls bin/

Method 2: Using Docker #

# Pull the Docker image
docker pull icefiredb/icefiredb:latest

# Run the container
docker run -d -p 11001:11001 --name icefiredb icefiredb/icefiredb:latest

Method 3: Pre-built Binaries #

Download the latest release from the GitHub releases page.

Basic Setup #

1. Start IceFireDB with Default Settings #

# Start with default settings (LevelDB backend, port 11001)
./bin/icefiredb-nosql

# Or specify basic options
./bin/icefiredb-nosql -n 11001 -a 0.0.0.0 -j ./data

You should see output like:

[INFO] Starting IceFireDB on :11001
[INFO] Storage driver: leveldb
[INFO] Data directory: ./data

Basic Redis Operations #

Connecting with redis-cli #

# Connect to IceFireDB
redis-cli -p 11001

# Or if using Docker
redis-cli -h localhost -p 11001

Basic Key-Value Operations #

# Set and get values
127.0.0.1:11001> SET mykey "Hello IceFireDB"
OK
127.0.0.1:11001> GET mykey
"Hello IceFireDB"

# Work with numbers
127.0.0.1:11001> SET counter 100
OK
127.0.0.1:11001> INCR counter
(integer) 101
127.0.0.1:11001> INCRBY counter 50
(integer) 151

# Set with expiration
127.0.0.1:11001> SETEX session:user123 3600 "active"
OK
127.0.0.1:11001> TTL session:user123
(integer) 3600

Hash Operations #

# Store user data as hash
127.0.0.1:11001> HSET user:1000 name "Alice" email "[email protected]" age 30
(integer) 3

# Get specific fields
127.0.0.1:11001> HGET user:1000 name
"Alice"
127.0.0.1:11001> HGET user:1000 email
"[email protected]"

# Get all fields
127.0.0.1:11001> HGETALL user:1000
1) "name"
2) "Alice"
3) "email"
4) "[email protected]"
5) "age"
6) "30"

List Operations #

# Push items to list
127.0.0.1:11001> LPUSH tasks "task1"
(integer) 1
127.0.0.1:11001> LPUSH tasks "task2"
(integer) 2
127.0.0.1:11001> RPUSH tasks "task3"
(integer) 3

# Get list range
127.0.0.1:11001> LRANGE tasks 0 -1
1) "task2"
2) "task1"
3) "task3"

# Pop items
127.0.0.1:11001> LPOP tasks
"task2"
127.0.0.1:11001> RPOP tasks
"task3"

Using Different Storage Drivers #

Switching Storage Backends #

# Check current driver
127.0.0.1:11001> DRIVER.INFO
1) "leveldb"
2) "./data"

# Switch to BadgerDB
127.0.0.1:11001> DRIVER.SELECT badger
OK

# Switch to IPFS (decentralized)
127.0.0.1:11001> DRIVER.SELECT ipfs
OK

Using Different Storage Drivers #

Start IceFireDB with different storage backends:

# Use LevelDB (default)
./bin/icefiredb-nosql -storage-backend leveldb -j ./leveldb_data

# Use BadgerDB for better write performance
./bin/icefiredb-nosql -storage-backend badger -j ./badger_data

# Use IPFS for decentralized storage
./bin/icefiredb-nosql -storage-backend ipfs -j ./ipfs_data --p2p-enable

P2P Networking #

Setting Up a Decentralized Cluster #

  1. First Node
./bin/icefiredb-nosql \
  -storage-backend ipfs \
  -n 11001 \
  -j ./node1_data \
  --p2p-enable \
  --discovery-id "my_cluster" \
  --p2p-listen "/ip4/0.0.0.0/tcp/4001"
  1. Second Node
./bin/icefiredb-nosql \
  -storage-backend ipfs \
  -n 11002 \
  -j ./node2_data \
  --p2p-enable \
  --discovery-id "my_cluster" \
  --p2p-listen "/ip4/0.0.0.0/tcp/4002" \
  --bootstrap-peers "/ip4/192.168.1.100/tcp/4001/p2p/QmFirstNodePeerID"
  1. Verify Connection
# On either node
127.0.0.1:11001> P2P.PEERS
1) "/ip4/192.168.1.101/tcp/4002/p2p/QmSecondNodePeerID"

# Data will automatically sync between nodes
127.0.0.1:11001> SET shared_key "cluster_value"
OK
127.0.0.1:11002> GET shared_key
"cluster_value"

Advanced Features #

CRDT-based Data Sync #

# Enable CRDT mode
127.0.0.1:11001> DRIVER.SELECT crdt
OK

# Data written in CRDT mode will automatically resolve conflicts
127.0.0.1:11001> SET user:preferences '{"theme": "dark", "language": "en"}'
OK

# Force synchronization
127.0.0.1:11001> CRDT.SYNC
OK

# Check sync status
127.0.0.1:11001> CRDT.STATUS
1) "synced"
2) "2 nodes"
3) "0 conflicts"

Hybrid Storage Mode #

# Start with hybrid storage
./bin/icefiredb-nosql \
  -storage-backend hybriddb \
  --hot-storage badger \
  --cold-storage ipfs \
  --hot-data-dir "./data/hot" \
  --cold-data-dir "./data/cold" \
  --migration-threshold 604800  # 7 days in seconds

# Data automatically moves between hot and cold storage
127.0.0.1:11001> SET recent_data "frequently accessed"
OK
127.0.0.1:11001> SET old_data "rarely accessed"
OK

# After threshold, old_data moves to cold storage

Programming Examples #

Python Example #

import redis

# Connect to IceFireDB
r = redis.Redis(host='localhost', port=11001, decode_responses=True)

# Basic operations
r.set('python_key', 'Hello from Python!')
print(r.get('python_key'))

# Hash operations
r.hset('user:python', 'name', 'Python User', 'language', 'python')
print(r.hgetall('user:python'))

# Use IceFireDB extensions
r.execute_command('DRIVER.SELECT', 'ipfs')

Node.js Example #

const redis = require('redis');

const client = redis.createClient({
  host: 'localhost',
  port: 11001
});

client.on('connect', () => {
  console.log('Connected to IceFireDB');
  
  // Basic operations
  client.set('node_key', 'Hello from Node.js!', redis.print);
  client.get('node_key', (err, reply) => {
    console.log('Value:', reply);
  });
  
  // IceFireDB specific command
  client.send_command('DRIVER.INFO', (err, reply) => {
    console.log('Driver info:', reply);
  });
});

Go Example #

package main

import (
	"context"
	"fmt"
	"github.com/go-redis/redis/v8"
)

func main() {
	ctx := context.Background()
	
	// Connect to IceFireDB
	client := redis.NewClient(&redis.Options{
		Addr:     "localhost:11001",
		Password: "", // no password set
		DB:       0,  // use default DB
	})
	
	// Basic operations
	err := client.Set(ctx, "go_key", "Hello from Go!", 0).Err()
	if err != nil {
		panic(err)
	}
	
	val, err := client.Get(ctx, "go_key").Result()
	if err != nil {
		panic(err)
	}
	fmt.Println("go_key:", val)
	
	// IceFireDB extension
	result, err := client.Do(ctx, "DRIVER.INFO").Result()
	fmt.Println("Driver info:", result)
}

Monitoring and Maintenance #

Checking Server Info #

# Get comprehensive server information
127.0.0.1:11001> INFO
# Server
redis_version:IceFireDB
redis_mode:standalone
os:Linux

# Memory
used_memory:1048576
used_memory_human:1.00M

# Stats
total_connections_received:100
total_commands_processed:500

# Persistence
rdb_last_save_time:1633046400

# Replication
role:master
connected_slaves:0

# CPU
used_cpu_sys:10.50
used_cpu_user:15.25

Performance Monitoring #

# Use redis-benchmark for performance testing
redis-benchmark -h localhost -p 11001 -t set,get -c 50 -n 100000

# Example output:
# SET: 253232.12 requests per second
# GET: 2130875.50 requests per second

Troubleshooting Common Issues #

Connection Issues #

# Check if IceFireDB is running
netstat -tlnp | grep 11001

# Check logs
tail -f icefiredb.log

Storage Issues #

# Check disk space
df -h

# Check data directory
ls -la ./data/

Performance Issues #

# Monitor memory usage
127.0.0.1:11001> INFO memory

# Check slow logs
127.0.0.1:11001> SLOWLOG GET 10

Next Steps #

  1. Explore Advanced Features: Try CRDT mode, IPFS storage, and P2P clustering
  2. Read Architecture Docs: Understand how IceFireDB works internally
  3. Check Configuration Options: Optimize for your specific use case
  4. Join the Community: Contribute and get support on GitHub

Additional Resources #

Support #

If you encounter issues:

  1. Check the GitHub issues
  2. Join the Discussions
  3. Review the documentation

Happy building with IceFireDB! 🚀