Early Adopters: First 20 receive 20% off with 1 year technical support.
Global Protocol
Schema Management
RogueDB utilizes a Declarative Schema Model. Instead of executing incremental migration scripts, you synchronize the entire state of your data structures with the database.
1. The Subscribe API
Schema changes are managed through a single Subscribe call.
Protobuf
// NOTE: A Response is never sent.
rpc subscribe(Subscribe) returns(Response) {}
message Subscribe {
string api_key = 1; // Requires admin or execute privileges for affected schemas.
repeated string schemas = 2; // The raw string content of all Protobuf files
}2. The Rules of Synchronization
Full State Transfer
Every call must include the raw file content of all Protocol Buffer schemas currently in use.
Implicit Deprecation
Omitted schemas are automatically flagged for deletion along with associated data.
Immutability Guardrails
Field names, indices, and types are immutable if data exists.
Mandatory Indexing
Every message must contain at least one "// index-N" directive. Indexing order is string based.
Automatic Reindexing
Engine detects and handles reindexing based on relative ordering changes.
Atomic Validation
Engine validates all files upfront. If one fails, the entire sync is rejected.
Global Namespace
Message names must be globally unique; package names are ignored.
Protocol Agnostic
Subscribe can be called via native gRPC or the standard REST API.
3. Executing a Schema Change
Code Example
C++
Python
Go
JavaScript
C#
Java
rogue::services::Subscribe subscribe{};
subscribe.set_api_key(API_KEY);
// All proto files. No modifications required.
for(const auto& file : detectFiles("absolute/path/to/protos/directory"))
{
std::ifstream inputFile{ file.native() };
std::stringstream buffer{};
buffer << inputFile.rdbuf();
subscribe.add_schemas(buffer.str());
}
rogue::services::Response response{};
// Any schemas excluded will have associated data deleted.
// Schema change failure results in no changes applied.
// Response contains the Registry proto without the import paths.
roguedb->subscribe(&context, subscribe, &response);
Note: All C# and Java examples are untested and generated with Gemini based on other language examples. Validation planned for Q3 based on bandwidth. Validated contributions welcome at support@roguedb.com.
Schema with Indexing
All schemas in RogueDB must be indexed. Indexing uses strong ordering where each field gets evaluated in the order specified. Search queries support and optimize partial indexing without additional specification.
Protobuf
message Test // auth: PII, SOC2
{
int32 attribute1 = 1; // index-1
int64 attribute2 = 2; // index-3
bool attribute3 = 3; // index-2
string attribute4 = 4;
uint32 attribute5 = 5;
uint64 attribute6 = 6;
}Index ordering uses strings with the prefix "index-". Additional data authorization requirements at the schema level can also be specified with "auth:" followed by a comma delineated list.
Central Registry Paradigm
RogueDB generates a Registry proto from a Subscribe request. This contains all registered schemas that can be accessed directly, requiring only the local import paths.
Protobuf
message Registry
{
// Messages always fully lowercased for field name.
oneof registered {
User user = 1;
Test test = 2;
Foo foo = 17;
FooBar foobar = 19;
// Bar = 18; // Deprecated schemas for backwards compatibility
}
}4. Operational Best Practices
Version Control is your Migration Log
Because RogueDB doesn't use migration scripts, your Git history is your source of truth. There is no concept of incremental builds.
•
Local Validation with Protoc: Run protoc in your CI pipelines and regression tests to catch errors before they hit the database.
•
Built-In Exceptions: RogueDB schemas (ex. User and Test) are immutable and managed by the engine. Do not include them in your sync.
5. Data Integrity & Field Behavior
RogueDB enforces indexed fields and uniqueness for all data.
Native Uniqueness (No Duplicates)
RogueDB treats every message as a unique entity based on its indexed fields. The database does not allow duplicate values. If you attempt to Insert a message that exactly matches an existing record's indexed fields, the operation results in a no-op.
Handling Nulls vs. Defaults (optional)
Protocol Buffers utilize default values for every type (e.g., 0 for integers, false for booleans, "" for strings). RogueDB cannot distinguish between a field that was explicitly set to 0 and a field that was simply missing from the payload. Checks are strictly on the application side.
Protobuf
message Order {
int32 id = 1; // If missing, defaults to 0
optional int32 priority = 2; // Can be checked for "presence" (has_priority)
}Optional Keyword:Use this for any field where "missing data" has a different meaning than "zeroed data" (e.g., a middle name, a discount code, or a sensor reading).
External Reference:
Official Protocol Buffers Documentation →