README.md (32d070f) - kvs.git · David Blume's GitList

README.md

# Key Value Store

kvs is an artisanal, hand-crafted online key/value store sourced by a California native.
It is written in Python and yet harkens back to a simpler era before Redis and Riak.

## Dependencies and Guarantees

kvs uses a local file for its backing store. Its ACID properties are as follows:

* **Atomicity**: Either all tuples in a transaction are successfully saved or none are.
* **Consistency**: Only valid states are saved, and saves are atomic. 
* **Isolation**: All transactions are serialized.
* **Durability**: System failure or restart won't break the store. Store writes are atomic.

# Getting the project

You can get a copy of this project by clicking on the
[ZIP](http://git.dlma.com/kvs.git/zipball/master)
or [TAR](http://git.dlma.com/kvs.git/tarball/master) buttons
near the top right of the GitList web page.

If you're me, and you want to contribute to the repo, then you can clone it like so:

git clone ssh://USERNAME@dlma.com/~/git/kvs.git

# Building it

1. Enable Python pages at your web server. See [How to use Python in the web](https://docs.python.org/2/howto/webservers.html#). My configuration is for Apache, hence the .htaccess file.
2. Move auth\_sample.txt to auth.txt, and replace `yourauthorizationhere` with a passcode you choose. chmod 600 the file or deny access to it via .htaccess.
3. Optional: Use secure HTTP. I recommend getting a free SSL certificate from [Let's Encrypt](https://letsencrypt.org/).
4. If you don't have the YAML module, pip install pyyaml.

# Using it

Here is [a live instance that serves an index page](https://kvs.dlma.com/).  You can send a key to get a value like so:

https://kvs.dlma.com/?k=1GM35N000010

Special use case, here's how to get the value for the most-recently updated key of a list of keys. The list could contain any number of keys, but only one value will be returned.

https://kvs.dlma.com/?k=1GM35N000010,1GU44N010910

Here's the recipe for a cURL command to store a new value for a key:

curl --data "key=value&auth={authorization}" https://{url}

Here's [the source code for a Roku channel client of such a service](http://git.dlma.com/roku_ip_tagger.git/).

# Is it any good?

[Yes](https://news.ycombinator.com/item?id=3067434).

# Licence

This software uses the [MIT license](http://git.dlma.com/kvs.git/blob/master/LICENSE.txt).

kvs.git

Trying a little humor in the README.md.