Storine v0.3.0

Get started

Quick start

Start a server, open the console, and read and write documents from your language, in about five minutes.

This guide assumes you have installed the Storine programs.

1. Start a server#

storage-server ./data 127.0.0.1:7878

The first argument is the data directory, created if it does not exist. The second is the address to listen on. The server prints one line once it is listening, and keeps running until you stop it with Ctrl C.

Without tokens the server only accepts a loopback address such as 127.0.0.1. To listen on the network, give it tokens first: see security.

2. Open the console#

In another terminal:

storine-console storine://127.0.0.1:7878

It prints a link with a key made for this run. Open it in your browser to see the server's health, browse collections, and edit documents. More in the web console.

3. Get a client#

Pick your language. The clients are installed from the repository, and need nothing but their language's standard library.

pip install "git+https://github.com/Twilight-Techy/storine#subdirectory=sdks/python"

4. Write and read documents#

This program creates two accounts, moves money between them in one atomic transaction, and queries them. The balance is an exact decimal, and min=0 makes the server refuse any change that would take it below zero.

from decimal import Decimal
import storine
from storine import add, eq, gt

db = storine.connect("storine://127.0.0.1:7878")
accounts = db.collection("accounts")

accounts.insert("alice", {"owner": "Alice", "balance": Decimal("100.00")})
accounts.insert("bob", {"owner": "Bob", "balance": Decimal("0.00")})

# Atomic, exact, server-side: no lost updates, no overdraft.
accounts.update("alice", add("balance", Decimal("-25.00"), min=0))

# Several writes, all or nothing.
with db.transaction() as tx:
    tx.update("accounts", "alice", add("balance", Decimal("-10.00"), min=0))
    tx.update("accounts", "bob", add("balance", Decimal("10.00")))

doc = accounts.get("alice")
print(doc["balance"], doc.version)      # 65.00 and the document's version

accounts.create_index("owner")
rich = accounts.find(gt("balance", Decimal("50")), order_by="-balance", limit=10)
print(accounts.count(eq("owner", "Bob")))

Run it twice and the second run fails on the first insert, because insert only creates. Use put to create or replace.

Now try an overdraft: change -25.00 to -500.00. The update fails with an invalid-request error, and Alice's balance is unchanged.

5. See it in the console#

Reload the console. The accounts collection is there with both documents, the owner index, and each document's version. Open alice to edit it: saving checks the version you opened, so you never overwrite someone else's change.

Next steps#