README
¶
[Command-Line Tour](doc/cli-tour.md) | [Go SDK Tour](doc/go-tour.md) | [JavaScript SDK Tour](doc/js-tour.md) | [Intro to Noms](doc/intro.md) | [FAQ](doc/faq.md) | [Project Status](#status)
[](http://jenkins.noms.io/job/NomsMasterBuilder) [](https://godoc.org/github.com/attic-labs/noms) [](https://goreportcard.com/report/github.com/attic-labs/noms) [](http://slack.noms.io)
Noms is a decentralized database based on ideas from Git.
This repository contains two reference implementations of the database—one in Go, and one in JavaScript. It also includes a number of tools and sample applications.
About Noms
Noms is different from other databases. It is:
-
Content-addressed. If you have some data you want to put into Noms, you don't have to worry about whether it already exists. Duplicate data is automatically ignored. There is no update, only insert.
-
Append-only. When you commit data to Noms, you aren't overwriting anything. Instead you're adding to a historical record. By default, data is never removed from Noms. You can see the entire history of the database, diff any two commits, or rewind to any previous point in time.
-
Typed. Every value, dataset, and version of a database has a type, which is generated automatically as you add data. You can write code against the type of a Noms database, confident that you've handled all the cases you need to.
-
Decentralized. If I give you a copy of my database, you and I can modify our copies disconnected from each other, and come back together and merge our changes efficiently and correctly days, weeks, or years later.
## Setup
Noms is supported on Mac OS X and Linux. Windows usually works, but isn't officially supported.
git clone https://github.com/attic-labs/noms $GOPATH/src/github.com/attic-labs/noms
go install github.com/attic-labs/noms/cmd/noms
noms log http://demo.noms.io/cli-tour::sf-film-locations
## Explore
Visually explore a demo instance of Noms
## What Noms is Good For
Data Version Control
Noms gives you the entire Git workflow, but for large-scale structured (or unstructured) data. Fork, merge, track history, efficiently synchronize changes, etc.
noms diff and noms log on large datasets
An Application Database with History
A database where every change is automatically and efficiently preserved. Instantly revert to, fork, or work from any historical commit.
Versioning, Diffing, and Syncing with Noms
An Archival Database
Trivially import snapshots from any format or API. Data is automatically versioned and deduplicated. Track the history of each datasource. Search across data sources.
TODO: Sample and video
## Status
Data Format
We are fairly confident in the core data format, and plan to support Noms database version 7 and forward. If you create a database with Noms today, future versions will have migration tools to pull your databases forward.
Completeness
We're just getting started. Some important features are not yet implemented including a query system, concurrency, auto-merging, and GC.
API
The Public API will continue to evolve. Pull requests which represent breaking API changes should be marked with APIChange and sent to the slack channel and mailing list below for advance warning and feedback.
## Talk
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
noms
command
|
|
|
noms-ui
command
|
|
|
util
This is the Command struct used by the noms utility.
|
This is the Command struct used by the noms utility. |
|
go
|
|
|
chunks
Package chunks provides facilities for representing, storing, and fetching content-addressed chunks of Noms data.
|
Package chunks provides facilities for representing, storing, and fetching content-addressed chunks of Noms data. |
|
constants
Package constants collects common constants used in Noms, such as the Noms data format version.
|
Package constants collects common constants used in Noms, such as the Noms data format version. |
|
d
Package d implements several debug, error and assertion functions used throughout Noms.
|
Package d implements several debug, error and assertion functions used throughout Noms. |
|
datas
Package datas defines and implements the database layer used in Noms.
|
Package datas defines and implements the database layer used in Noms. |
|
dataset
Package dataset implements the dataset layer of Noms that sits above the database.
|
Package dataset implements the dataset layer of Noms that sits above the database. |
|
hash
Package hash implements the hash function used throughout Noms.
|
Package hash implements the hash function used throughout Noms. |
|
marshal
Package marshal implements encoding and decoding of Noms values.
|
Package marshal implements encoding and decoding of Noms values. |
|
perf/codec-perf-rig
command
|
|
|
perf/hash-perf-rig
command
|
|
|
perf/suite
Package suite implements a performance test suite for Noms, intended for measuring and reporting long running tests.
|
Package suite implements a performance test suite for Noms, intended for measuring and reporting long running tests. |
|
spec
Package spec provides builders and parsers for spelling Noms databases, datasets and values.
|
Package spec provides builders and parsers for spelling Noms databases, datasets and values. |
|
types
Package types contains most of the data structures available to/from Noms.
|
Package types contains most of the data structures available to/from Noms. |
|
util/progressreader
Package progressreader provides an io.Reader that reports progress to a callback
|
Package progressreader provides an io.Reader that reports progress to a callback |
|
util/status
Package status prints status messages to a console, overwriting previous values.
|
Package status prints status messages to a console, overwriting previous values. |
|
walk
Package walk implements an API for iterating on Noms values.
|
Package walk implements an API for iterating on Noms values. |
|
samples
|
|
|
go/blob-get
command
|
|
|
go/counter
command
|
|
|
go/csv/csv-analyze
command
|
|
|
go/csv/csv-export
command
|
|
|
go/csv/csv-import
command
|
|
|
go/demo-server
command
|
|
|
go/hr
command
|
|
|
go/json-import
command
|
|
|
go/nomdex
command
|
|
|
go/noms-merge
command
|
|
|
go/nomsfs
command
|
|
|
go/poke
command
|
|
|
go/url-fetch
command
|
|
|
go/xml-import
command
|
|
|
loadtest
command
|
|