eeCLOUD 3.3.2

eeCLOUD

eeCLOUD is a .NET library that provides a high-performance logical storage engine, inspired by the concept of a virtual EEPROM. It is designed to manage large volumes of data in a simple, fast, and scalable way.

eeCLOUD is not a traditional ORM and not a simple key-value store. It introduces an address-based persistence model, built for real-world performance and modern workloads.

🚀 Core Concepts

Memory

A Memory is the logical equivalent of a table. It represents an addressable storage space rather than a rigid schema.

Memory = Virtual EEPROM

MemoryArea

A MemoryArea represents a record inside a Memory. It contains the actual data, stored in JSON format (schema-less).

Address

• Type: long
• Primary Key
• Unique and monotonic
• Simulates a physical memory address

The address is the true physical identifier of the data.

Index

• Type: string (commonly a GUID)
• Unique logical identifier
• Used for semantic lookups and integrations

ID

• Type: string
• Not unique
• Indexed
• Useful for grouping and NoSQL-style queries

Reference

• Type: long
• Direct reference to the address of another Memory
• Enables instant relationships without joins

Date vs Create

• date: logical or business date of the data (event time)
• create: actual persistence timestamp

date is indexed and commonly used for range queries.

🧩 Cluster Storage

eeCLOUD supports clustered storage to improve scalability and performance.

Cluster Creation (Write)

Clusters are created only during write operations by explicitly enabling clustering:

clusterized: true

When clusterized is enabled:

• The main Memory table stores only indexes and addresses
• The actual data is written into a cluster table
• Cluster tables are created automatically when needed

Example:

orders          -> index-only table
orders§c_0      -> data cluster
orders§c_1      -> data cluster
orders§c_2      -> data cluster

The target cluster is calculated mathematically from the generated address.

Automatic Cluster Resolution (Read)

During read operations, no cluster flag is required.

The read process is fully automatic:

• eeCLOUD automatically resolves the correct cluster table
• Data is transparently loaded from the corresponding cluster

This makes clustered storage completely transparent for consumers.

⚙️ Configuration

var config = new Config
{
    server = "192.168.1.10",
    username = "dbuser",
    password = "dbpassword",
    type = ServerType.PostgreSQL,
    clusterSize = 100000
};

server

• Format: IP or IP:PORT
• If port is omitted, the default port for the selected engine is used

username / password

Credentials used to connect to the selected backend engine.

• The user must exist on the backend
• The user must have privileges to create databases and tables

Security notes:

• Credentials are used only locally
• They are never sent to external services
• eeCLOUD does not connect to proprietary services

clusterSize

Defines the maximum number of records per cluster. Used to calculate the target cluster table from the address.

🗄️ eeCACHE (Important)

eeCACHE is an optional persistent cache engine for eeCLOUD. It is disabled by default.

To enable caching, an implementation of IeeCACHE must be explicitly injected when creating the Application instance.

var cache = new eeCACHE();
var app = new Application(config, cache);

Architecture

eeCACHE uses a dual-layer architecture:

• In-memory layer

  • Extremely fast
  • Valid only while the process is running
  • Supports expiration (TTL)

• Persistent layer

  • Stored locally using memory-mapped files
  • Automatically restored on process restart
  • Shared across multiple processes on the same machine

Usage Modes

eeCACHE as primary backend

config.type = ServerType.eeCACHE;

• eeCACHE acts as the main storage engine
• No external database is required

eeCACHE with SQL backend

• The database is the source of truth
• eeCACHE acts as a read/write accelerator
• Cache is synchronized from the database on restart

Security

• No network access
• No external services
• No telemetry
• All data is stored locally

📚 When to Use eeCLOUD

Recommended for:

• IoT platforms
• Event logging
• Session storage
• Semi-structured data
• High-throughput systems

Not intended for:

• Complex SQL joins
• Traditional relational modeling
• Heavy analytical reporting

🔧 Supported Backends

• PostgreSQL
• MySQL
• SQL Server
• eeCACHE
• FTP (binary storage)

🔗 Links

• Website: https://eecloud.io
• API reference: https://eecloud.io/docs

Made with ❤️ by Giovanni Petruzzellis