GUN is a realtime, decentralized, embedded, graph database engine.

For the browser, try out this tutorial. This README is for GUN servers.

If you do not have node or npm, read this first. Then in your terminal, run:

npm install gun

Now you can require it in the app you want to build.

var Gun = require('gun');

Once included, initialize a gun instance with a file path or your AWS S3 credentials.

var gun = Gun({
	file: 'data.json',
	s3: { // Optional!
		key: '', // AWS Access Key
		secret: '', // AWS Secret Token
		bucket: '' // The bucket you want to save into
	}
});

These are the default persistence layers, they are modular and can be replaced by others.

Using S3 is recommended for deployment, and using a file is recommended for local development.

The examples included in this repo are online here, you can run them locally by:

npm install gun
cd node_modules/gun
node examples/http.js 8080

Then visit http://localhost:8080 in your browser. If that did not work it is probably because npm installed it to a global directory. To fix that try mkdir node_modules in your desired directory and re-run the above commands. You also might have to add sudo in front of the commands.

The wire protocol was changed between 0.1.x and 0.2.x, meaning if you upgrade gun your old data might not load properly. If you are listening for errors you will get a ''Not a valid graph!' but if you are not listening to errors it will be silent, beware of this. Here is a migration guide if you are having problems.

Version 0.2.0 is currently in alpha. Important changes include .get to .val, .load to .get, and .set to .put. Documentation is our current focus, and .all functionality will be coming soon. The latest documentation can be found at https://github.com/amark/gun/wiki/0.2.0-API-and-How-to. Please report any issues via https://github.com/amark/gun/issues.

GUN is not stable, and therefore should not be trusted in a production environment.

Below is a really basic overview of how the gun API works. For a more detailed explanation with many more examples, check out the wiki.

In gun, it can be helpful to think of everything as field/value pairs. For example, let's say we have a user object that looks like this:

{
  "username": "marknadal",
  "name": "Mark Nadal",
  "email": "[email protected]"
}

Now, we want to save this object to a key called 'usernames/marknadal'. We can do that like this:

gun.put({
  username: "marknadal",
  name: "Mark Nadal",
  email: "[email protected]"
}).key('usernames/marknadal');

We can also pass put a callback that can be used to handle errors:

gun.put({
  username: "marknadal",
  name: "Mark Nadal",
  email: "[email protected]"
}, function(err){
  // Do something to handle the error
}).key('usernames/marknadal');

Once we have some data stored in gun, we need a way to get them out again. Retrieving the data that we just stored would look like this:

gun.get('usernames/marknadal').val(function(user){
  console.log(user.name); // Prints `Mark Nadal` to the console
});

Basically, this tells gun to check 'usernames/marknadal', and then return the object it finds associated with it. For more information, including how to save relational or document based data, check out the wiki.

Being lonely is never any fun, especially when programming. Our goal is for GUN to be the easiest database ever, which means if you ever get stuck on something for longer than 5 minutes, let us know so we can help you. Your input is invaluable, as it enables us where to refine GUN. So drop us a line in the ! Or join the mail list.

Thanks to the following people who have contributed to GUN, via code, issues, or conversation:

agborkowski, alexlafroscia, anubiann00b, bromagosa, coolaj86, d-oliveros, danscan, forrestjt, gedw99, HelloCodeMing, JosePedroDias, onetom, ndarilek, phpnode, riston, rootsical, rrrene, ssr1ram, Xe, zot

This list of contributors was manually compiled, alphabetically sorted. If we missed you, please submit an issue so we can get you added!

Extending GUN or writing modules for it is as simple as:

Gun.on('opt').event(function(gun, opt){ /* Your module here! */ })

We also want our database to be comprehensible, not some magical black box. So often database questions get dismissed with "its complicated hard low level stuff, let the experts handle it". That attitude prevents progress, instead we welcome teaching people and listening to new perspectives. Join along side us in a quest to learn cool things and help others build awesome technology!

We need help on the following roadmap.

• Realtime push to the browser
• Persistence in the browser
• Efficient storage engine
• Authorization callbacks
• Security or ACLs
• Schema Validation
• Point of Entry Encryption
• Graph manipulation
• Server to server communication
• Test more
• WebRTC Transport
• LRU or some Expiry (so RAM doesn't asplode)
• Bug fixes
• Data Structures:
• Sets (Table/Collections, Unordered Lists)
• CRDTs
• OT
• Locking / Strong Consistency (sacrifices Availability)
• Query:
• SQL
• MongoDB Query Documents
• Neo4j Cypher
• LINQ
• Gremlin Query Language