# Introduction
Bitsy is a small, fast, embeddable, durable in-memory [graph database] that implements [Apache Tinkerpop].
## Features
* Support for [Apache Tinkerpop] aka Tinkerpop3
* [ACID] guarantees on transactions
* Designed for multi-threaded OLTP applications
* Implements optimistic concurrency control
* Data stored in readable text files
* Serialization using the [Jackson JSON processor]
* Recovers cleanly from power failures and crashes provided the underlying file system supports metadata journaling, like NTFS, ext3, ext4, XFS and JFS (not FAT32 or ext2)
* High read and write throughputs in multi-threaded environments
* Supports online backups through a JMX interface
## Getting started
### Embedding Bitsy
#### Maven
You can add Bitsy and its dependencies to your project by adding this dependency:
```
com.lambdazen.bitsy
bitsy
3.6.2
```
### Using Bitsy
The following code snippet shows how Bitsy can be launched and stopped:
```java
import java.nio.file.Path;
import com.lambdazen.bitsy.BitsyGraph;
public class Test {
public static void main(String[] args) {
Path dbPath = Paths.get("...path to a directory...");
// Open the database
BitsyGraph myGraph = new BitsyGraph(dbPath);
... use myGraph in any number of threads
// Close the database
myGraph.shutdown();
}
}
```
You can use the BitsyAutoReloadingGraph instead of BitsyGraph for a more permissive Tinkerpop3 implementation that automatically reloads vertices and edges when accessed outside the scope of a transaction.
**Note**: The above example uses the simple constructor for BitsyGraph. Refer to [Tuning Bitsy](TuningBitsy.md) for other constructors, including a memory-only (non-durable) database constructor.
### Using Bitsy in Gremlin Console (embedded)
You can run Bitsy in embedded mode from your Gremlin Console as follows:
- Create a new `bitsy` folder under `/ext`
- Download the following JARs into the `ext/bitsy/plugin` folder:
- https://repo1.maven.org/maven2/com/lambdazen/bitsy/bitsy/3.6.2/bitsy-3.6.2.jar
- https://repo1.maven.org/maven2/com/fasterxml/jackson/core/jackson-core/2.13.1/jackson-core-2.13.1.jar
- https://repo1.maven.org/maven2/com/fasterxml/jackson/core/jackson-annotations/2.13.1/jackson-annotations-2.13.1.jar
- https://repo1.maven.org/maven2/com/fasterxml/jackson/core/jackson-databind/2.13.1/jackson-databind-2.13.1.jar
- https://repo1.maven.org/maven2/com/nesscomputing/components/ness-core/1.9.1/ness-core-1.9.1.jar [DEPRECATED after version 3.4.1]
- Launch the Gremlin Console and run these commands:
```
import java.nio.file.Paths
import com.lambdazen.bitsy.BitsyGraph
graph = new BitsyGraph(Paths.get(""))
g = graph.traversal()
```
Now you can use `g` for Gremlin traversals and `graph` for graph modification operations like `addVertex`.
### Using Bitsy in Gremlin Console with Gremlin server
You can run Bitsy in the Gremlin Server as follows:
- Create a new `bitsy` folder under `/ext`
- Download the following JARs into the `ext/bitsy/plugin` folder:
- https://repo1.maven.org/maven2/com/lambdazen/bitsy/bitsy/3.5.1/bitsy-3.5.1.jar
- https://repo1.maven.org/maven2/com/fasterxml/jackson/core/jackson-core/2.10.3/jackson-core-2.10.3.jar
- https://repo1.maven.org/maven2/com/fasterxml/jackson/core/jackson-annotations/2.10.3/jackson-annotations-2.10.3.jar
- https://repo1.maven.org/maven2/com/fasterxml/jackson/core/jackson-databind/2.10.3/jackson-databind-2.10.3.jar
- https://repo1.maven.org/maven2/com/nesscomputing/components/ness-core/1.9.1/ness-core-1.9.1.jar [DEPRECATED after version 3.4.1]
- Download the two Gremlin server configuration files from https://github.com/lambdazen/bitsy/tree/master/src/test/resources/gremlin-server to the `/conf` directory
- Edit the `bitsy.properties` file to point the correct database path
- Launch Gremlin server with server configuration:
```
(Windows) bin\gremlin-server.bat conf\gremlin-server-bitsy.yaml
(Unix) bin/gremlin-server.sh conf/gremlin-server-bitsy.yaml
```
Now you can launch the Gremlin Console (no changes necessary) and run
```
:remote connect tinkerpop.server conf/remote.yaml
```
to connect to the Gremlin server and execute commands on the `graph` and `g` objects.
## Deep dive
[This presentation](http://www.slideshare.net/lambdazen/bitsy-graphdatabase) provides an overview of Bitsy's original design principles and features. Improvements in version 1.5 are summarized [in this presentation](http://www.slideshare.net/lambdazen/bitsy15). Bitsy 3.x is now compatible with Tinkerpop v3.
The following Wiki pages go into a little more detail:
* [Design Principles](DesignPrinciples.md): _No Seek_, _No Socket_ and _No SQL_
* [Optimistic concurrency](OptimisticConcurrency.md): Covers the concurrency control and best practices to retry transactions
* [Write algorithms](WriteAlgorithms.md): Details the different write algorithms along with the threads, buffers and logs used
* [Serialization format](SerializationFormat.md): Specifies the JSON format for the various records in the database files
* [Benchmarks](Benchmarks.md): Illustrates the read and write throughputs in a multi-threaded OLTP setting
* [Tuning Bitsy](TuningBitsy.md): Covers the different BitsyGraph settings and how they can be changed
* [Monitoring and Management](MonitoringAndManagement.md): Covers JMX and SLF4J integration
* [Backup and Restore](BackupAndRestore.md): Discusses offline/online backup and restore procedures
* [Large Objects](LargeObjects.md): Handling large objects outside of Bitsy
* [Fancy Indexes](FancyIndexes.md): Maintaining Lucene and Lucene-like indexes outside of Bitsy
## Licensing
Bitsy is available under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0).
[Apache Tinkerpop]: http://tinkerpop.apache.org/
[graph database]: http://en.wikipedia.org/wiki/Graph_database
[ACID]: http://en.wikipedia.org/wiki/ACID
[OLTP]: https://en.wikipedia.org/wiki/Online_transaction_processing
[Jackson JSON processor]: https://github.com/FasterXML/jackson