@ -23,7 +23,7 @@ bower install nedb // For the browser versions, which will be in browser-versi
```
```
## API
## API
It's a subset of MongoDB's API (the most used operations).
It's a subset of MongoDB's API (the most used operations).
* <ahref="#creatingloading-a-database">Creating/loading a database</a>
* <ahref="#creatingloading-a-database">Creating/loading a database</a>
* <ahref="#persistence">Persistence</a>
* <ahref="#persistence">Persistence</a>
@ -42,7 +42,7 @@ It's a subset of MongoDB's API (the most used operations).
* <ahref="#browser-version">Browser version</a>
* <ahref="#browser-version">Browser version</a>
### Creating/loading a database
### Creating/loading a database
You can use NeDB as an in-memory only datastore or as a persistent datastore. One datastore is the equivalent of a MongoDB collection. The constructor is used as follows `new Datastore(options)` where `options` is an object with the following fields:
You can use NeDB as an in-memory only datastore or as a persistent datastore. One datastore is the equivalent of a MongoDB collection. The constructor is used as follows `new Datastore(options)` where `options` is an object with the following fields:
* `filename` (optional): path to the file where the data is persisted. If left blank, the datastore is automatically considered in-memory only. It cannot end with a `~` which is used in the temporary files NeDB uses to perform crash-safe writes
* `filename` (optional): path to the file where the data is persisted. If left blank, the datastore is automatically considered in-memory only. It cannot end with a `~` which is used in the temporary files NeDB uses to perform crash-safe writes
* `inMemoryOnly` (optional, defaults to false): as the name implies.
* `inMemoryOnly` (optional, defaults to false): as the name implies.
@ -110,13 +110,13 @@ You can also set automatic compaction at regular intervals with `yourDatabase.pe
Keep in mind that compaction takes a bit of time (not too much: 130ms for 50k records on a typical development machine) and no other operation can happen when it does, so most projects actually don't need to use it.
Keep in mind that compaction takes a bit of time (not too much: 130ms for 50k records on a typical development machine) and no other operation can happen when it does, so most projects actually don't need to use it.
<!--Phyisical persistence works similarly to major databases: compaction forces the OS to physically flush data to disk, while appends to the data file let the OS handle this. That guarantees that a server crash can never cause complete data loss, at most one or two documents, while preserving performance.-->
Durability works similarly to major databases: compaction forces the OS to physically flush data to disk, while appends to the data file do not (the OS is responsible for flushing the data). That guarantees that a server crash can never cause complete data loss, while preserving performance. The worst that can happen is a crash between two syncs, causing a loss of all data between the two syncs. Usually syncs are 30 seconds appart so that's at most 30 seconds of data. <ahref="http://oldblog.antirez.com/post/redis-persistence-demystified.html"target="_blank">This post by Antirez on Redis persistence</a> explains this in more details, NeDB being very close to Redis AOF persistence with `appendfsync` option set to `no`.
### Inserting documents
### Inserting documents
The native types are `String`, `Number`, `Boolean`, `Date` and `null`. You can also use
The native types are `String`, `Number`, `Boolean`, `Date` and `null`. You can also use
arrays and subdocuments (objects). If a field is `undefined`, it will not be saved (this is different from
arrays and subdocuments (objects). If a field is `undefined`, it will not be saved (this is different from
MongoDB which transforms `undefined` in `null`, something I find counter-intuitive).
MongoDB which transforms `undefined` in `null`, something I find counter-intuitive).
If the document does not contain an `_id` field, NeDB will automatically generated one for you (a 16-characters alphanumerical string). The `_id` of a document, once set, cannot be modified.
If the document does not contain an `_id` field, NeDB will automatically generated one for you (a 16-characters alphanumerical string). The `_id` of a document, once set, cannot be modified.