forge-db (0.1.0)

2025-06-15T11:13:16-05:00

Setup this registry in the Cargo configuration file (for example ~/.cargo/config.toml):

[registry]
default = "gitea"

[registries.gitea]
index = "sparse+" # Sparse index
# index = "" # Git

[net]
git-fetch-with-cli = true

To install the package using Cargo, run the following command:

cargo add forge-db@0.1.0

For more information on the Cargo registry, see the documentation.

Forge In-Memory Database

Forge DB - In-Memory Database Server

A Redis-like in-memory database server with support for various data types and operations. Built with Rust and Tokio for high performance and reliability.

Features

Basic key-value operations - GET, SET, DEL, EXISTS
List operations - LPUSH, RPUSH, LPOP, RPOP
Hash operations - HSET, HGET, HDEL, HGETALL
Counter operations - INCR, DECR, INCRBY, DECRBY
Persistence - Save/load functionality with auto-save support
Concurrent access - Thread-safe design using tokio::sync
Network support - TCP server accessible from any client
Pub/Sub messaging - Channel-based publish/subscribe functionality
Vehicle management - Support for garage system with atomic operations

Quick Start

Running Locally

# Start the server with default settings (localhost:6379)
cargo run

# Or specify a custom address (for production)
DB_SERVER_ADDR="0.0.0.0:6379" cargo run

Using Docker

# Build and start with Docker Compose
cd bin/db
docker-compose up -d

# Check logs
docker-compose logs -f

# Stop service
docker-compose down

Feature Flags

The database server supports feature flags to enable or disable specific functionality:

TCP Support

The tcp feature flag controls whether the database server accepts TCP connections:

[dependencies]
forge-db = { version = "0.1.0", features = ["tcp"] }

When enabled:

The server accepts TCP connections on the configured port
Remote clients can connect to the database
Network-related environment variables are used

When disabled:

The server runs in embedded mode
Only local connections are allowed
Network configuration is ignored

This feature is particularly useful for:

Development environments where TCP is not needed
Embedded deployments where network access is not required
Testing scenarios where direct access is preferred

Supported Commands

Basic Operations

PING - Test server connection, returns PONG
SET <key> <value> - Set key to hold string value
MSET <key1> <value1> [<key2> <value2> ...] - Set multiple keys to their respective values
GET <key> - Get value of key
DEL <key> - Delete key
EXISTS <key> - Check if key exists
KEYS - Get all keys in the database
CLEAR - Clear all keys
SAVE - Save database to disk
LOAD [filename] - Load database from disk (uses latest if no filename provided)

List Operations

LPUSH <key> <value> - Insert at the beginning of the list
RPUSH <key> <value> - Insert at the end of the list
LPOP <key> - Remove and return first element
RPOP <key> - Remove and return last element
LRANGE <key> <start> <stop> - Get a range of elements
LINDEX <key> <index> - Get element by index

Hash Operations

HSET <key> <field> <value> - Set field in hash stored at key
HGET <key> <field> - Get field from hash stored at key
HMSET <key> <field1> <value1> [<field2> <value2> ...] - Set multiple fields in hash stored at key
HDEL <key> <field> - Delete field from hash stored at key
HGETALL <key> - Get all fields and values in hash

Counter Operations

INCR <key> - Increment counter by 1
DECR <key> - Decrement counter by 1
INCRBY <key> <delta> - Increment counter by specified amount
DECRBY <key> <delta> - Decrement counter by specified amount

Auto-save Operations

AUTOSAVE <seconds> - Set auto-save interval in seconds
AUTOSAVE OFF - Disable auto-save

Pub/Sub Operations

PUBLISH <channel> <message> - Publish a message to a channel
SUBSCRIBE <channel> [<channel> ...] - Subscribe to one or more channels
UNSUBSCRIBE [<channel> ...] - Unsubscribe from channels (all if none specified)
PSUBSCRIBE <pattern> [<pattern> ...] - Subscribe using patterns (e.g. 'user:*')
PUNSUBSCRIBE [<pattern> ...] - Unsubscribe from patterns

Environment Variables

Variable	Description	Default
`DB_SERVER_ADDR`	Server binding address	"127.0.0.1:6379"
`RUST_LOG`	Logging level	info

Binding Address Notes

For local development on Windows, use 127.0.0.1:6379
To accept connections from any IP address:
- On Linux/Mac: use 0.0.0.0:6379
- On Windows: use a specific network interface IP (e.g., 192.168.1.5:6379)

Docker Support

The database server can be easily containerized and deployed using Docker:

# Build the Docker image
docker build -t forge-db -f bin/db/Dockerfile .

# Run the container
docker run -d -p 6379:6379 --name forge-db forge-db

# Or use docker-compose
docker-compose -f bin/db/docker-compose.yml up -d

Docker Compose Configuration

The included docker-compose.yml provides:

Volume mounting for data persistence
Health checks to ensure service availability
Network configuration for service discovery
Environment variable configuration

Architecture

The server is built with:

Tokio - Async runtime for non-blocking I/O
Arc<Mutex<>> - Thread-safe shared state
Modular command processing system - Extensible command handling
Layered architecture:
- Server layer - Handles network connections
- Command processor layer - Parses and routes commands
- Database operations layer - Implements data storage and manipulation
- Storage layer - Handles persistence
- Feature layer - Controls optional functionality

Development

Project Structure

bin/db/
├── src/                  # Source code
│   ├── main.rs           # Entry point
│   ├── server.rs         # TCP server implementation
│   ├── client.rs         # Client implementation
│   ├── commands/         # Command handlers
│   ├── operations/       # Database operations
│   ├── types.rs          # Data type definitions
│   ├── error.rs          # Error handling
│   └── features/         # Feature flag implementations
├── Dockerfile            # Docker configuration
├── docker-compose.yml    # Docker Compose configuration
└── README.md             # Documentation

Building from Source

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

# Build the project
cargo build --bin forge-db

# Run tests
cargo test --bin forge-db

# Run the server
cargo run --bin forge-db

Examples

Basic Key-Value Operations

> SET user:1 "John Doe"
OK
> GET user:1
"John Doe"
> MSET user:2 "Jane Doe" user:3 "Bob Smith"
OK
> GET user:2
"Jane Doe"
> EXISTS user:1
1
> DEL user:1
1

List Operations

> LPUSH mylist "first"
1
> RPUSH mylist "last"
2
> LPUSH mylist "very first"
3
> LRANGE mylist 0 -1
1) "very first"
2) "first"
3) "last"
> LPOP mylist
"very first"

Hash Operations

> HSET user:2 name "Jane Doe"
1
> HSET user:2 email "jane@example.com"
1
> HMSET user:3 name "Bob Smith" email "bob@example.com" age "42"
OK
> HGET user:2 name
"Jane Doe"
> HGETALL user:3
1) "name"
2) "Bob Smith"
3) "email"
4) "bob@example.com"
5) "age"
6) "42"

Counter Operations

> SET counter 10
OK
> INCR counter
11
> INCR counter
12
> DECR counter
11
> INCRBY counter 5
16
> DECRBY counter 8
8

Auto-save Configuration

> AUTOSAVE 60
OK - Auto-save set to 60 seconds
> AUTOSAVE OFF
OK - Auto-save disabled

Pub/Sub Messaging

# In Terminal 1
> SUBSCRIBE game:events
Subscribed to: game:events

# In Terminal 2
> PUBLISH game:events "Player joined: PlayerA"
1

# Terminal 1 receives:
MESSAGE game:events Player joined: PlayerA

# In Terminal 3
> PSUBSCRIBE player:*
Subscribed to patterns: player:*

# In Terminal 2
> PUBLISH player:123:update "Position changed"
1

# Terminal 3 receives:
MESSAGE player:123:update Position changed

# In Terminal 1
> SUBSCRIBE chat:room:1
Subscribed to: game:events, chat:room:1

# In Terminal 2
> PUBLISH chat:room:1 "Hello everyone!"
1

# Terminal 1 receives:
MESSAGE chat:room:1 Hello everyone!

# In Terminal 1
> UNSUBSCRIBE game:events
Unsubscribed from: game:events
Still subscribed to: chat:room:1

# In Terminal 3
> PUNSUBSCRIBE player:*
Unsubscribed from pattern: player:*
No active pattern subscriptions

ID	Version
async-trait	^0.1.88
bincode	^2.0.1
chrono	^0.4.41
forge-shared	^0.1.0
regex	^1.11.1
serde	^1.0.219
serde_json	^1.0.140
thiserror	^2.0.12
tokio	^1.45.0
uuid	^1.17.0

Details

Cargo

2025-06-15 11:13:16 -05:00

3

Innovative Dev Solutions

MIT

24 KiB

Assets (1)

forge-db-0.1.0.crate 24 KiB

Versions (2) View all

0.1.1

2025-06-15

0.1.0

2025-06-15

forge-db (0.1.0)

Installation

About this package

Forge DB - In-Memory Database Server

Table of Contents

Features

Quick Start

Running Locally

Using Docker

Feature Flags

TCP Support

Supported Commands

Basic Operations

List Operations

Hash Operations

Counter Operations

Auto-save Operations

Pub/Sub Operations

Environment Variables

Binding Address Notes

Docker Support

Docker Compose Configuration

Architecture

Development

Project Structure

Building from Source

Examples

Basic Key-Value Operations

List Operations

Hash Operations

Counter Operations

Auto-save Configuration

Pub/Sub Messaging

Dependencies