sop

Scalable Objects Persistence

Project maintained by SharedCode Hosted on GitHub Pages — Theme by mattgraham

Getting Started with SOP

Welcome to Scalable Objects Persistence (SOP)! This guide will take you from downloading the software to building your first application.

1. Download & Installation

Step 1: Download the Bundle

(For Python, C#, Java, Rust Developers, or Standalone Server Usage)

Note for Go Developers: You do not need to download this bundle. SOP is a native Go library. You can simply go get the package (see Developing with SOP below) and compile your application.

Go to the Releases Page and download the Platform Bundle for your operating system:

Step 2: Extract & Run

Unzip the downloaded file. You will see a folder structure like this:

AI Usage Note: To use the AI Copilot features, you must supply your own LLM API Key (e.g., from Google AI Studio or OpenAI). The system does not come with a pre-configured trial key. You can enter your key in the “Environment Configuration” after starting the server.

sop-bundle/
├── sop-httpserver       # The Database Server & UI
├── libs/                # Shared libraries (for C/Rust)
├── python/              # Python package (.whl)
├── java/                # Java library (.jar)
└── dotnet/              # C# package (.nupkg)

Start the Server: Open a terminal in this folder and run:

macOS / Linux:

chmod +x sop-httpserver
./sop-httpserver

Windows: Double-click sop-httpserver.exe or run it from PowerShell.

2. First Run & Setup

Once the server is running, open your browser to: http://localhost:8080

Quick Start (Demo)

For a step-by-step walkthrough of the Setup Wizard and features, please see the SOP Demo Walkthrough.

The Setup Wizard

On your first visit, you will see the Setup Wizard.

  1. Database Engine:
    • Standalone: Best for local development. Data is stored in a local folder.
    • Clustered: For distributed environments. Requires a Redis connection string.
  2. Initialize Database:
    • Populate Demo Data: Check this box! It will create a sample E-commerce database (Users, Products, Orders) so you can explore the features immediately.
  3. Click “Initialize Database”.

Explore the Data

3. Developing with SOP

Now that your server is running, you can write code to interact with it. SOP is polyglot, meaning you can access the same data from Go, Python, C#, or Java.

Go (Native)

  1. Install: 
    go get github.com/sharedcode/sop
  2. Code: 
    import (
    "context"
    "github.com/sharedcode/sop"
    "github.com/sharedcode/sop/database"
)

// Open Database (Standalone)
db, _ := database.Open(sop.DatabaseOptions{
    Type: sop.Standalone, 
    StoresFolders: []string{"./data"},
})

// Transaction & Store
tx, _ := db.BeginTransaction(ctx, sop.ForWriting)
store, _ := tx.GetStore("users")

// Add Item
store.Add(ctx, "user_999", "Alice")
tx.Commit(ctx)

Python

  1. Install: 
    pip install python/sop-*.whl
  2. Code: 
    from sop.store import StoreFactory

# Connect to the local server
factory = StoreFactory()
store = factory.get_store("user")

# Add a user
store.add("user_999", {"name": "Alice", "age": 30})
    
# Get a user
user = store.get("user_999")
print(user)

C# / .NET

  1. Install: Add the .nupkg to your project or local feed. 
    dotnet add package Sop --source ./dotnet
  2. Code: 
    using Sop;

var factory = new StoreFactory();
var store = factory.GetStore<string, User>("user");

store.Add("user_999", new User { Name = "Alice", Age = 30 });

Java

  1. Install: Add the .jar to your classpath.
  2. Code: 
    import sop.StoreFactory;
import sop.Store;

StoreFactory factory = new StoreFactory();
Store<String, User> store = factory.getStore("user");

store.add("user_999", new User("Alice", 30));

4. Next Steps