ArangoDB v3.11 reached End of Life (EOL) and is no longer supported.

This documentation is outdated. Please see the most recent stable version.

Spring Data ArangoDB

The Spring Data ArangoDB integration is a library for accessing data stored in ArangoDB from Spring-based Java application

Spring Data provides a consistent interface for accessing various types of data sources. Spring Data ArangoDB implements this for ArangoDB and provides mapping of Java objects to ArangoDB documents (ODM).

Supported versions

Spring Data ArangoDB is compatible with:

all the still supported Spring Boot 3.x versions and related Spring Framework versions
all the still supported ArangoDB versions

all the still supported Spring Boot 2.x versions and related Spring Framework versions
all the still supported ArangoDB versions

Get started

This tutorial is about how to configure Spring Data ArangoDB without using Spring Boot Starter ArangoDB.

For a more extensive tutorial about the features of Spring Data ArangoDB and Spring Boot support, see the Spring Boot Starter documentation.

Build a project with Maven

Set up a project and add every needed dependency. This demo uses Maven and Spring Boot.

Create a Maven pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <relativePath/>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>x.y.z</version>
    </parent>

    <groupId>com.arangodb</groupId>
    <artifactId>spring-data-arangodb-tutorial</artifactId>
    <version>1.0.0</version>

    <name>spring-data-arangodb-tutorial</name>
    <description>ArangoDB Spring Data Tutorial</description>

    <properties>
        <java.version>21</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>com.arangodb</groupId>
            <artifactId>arangodb-spring-data</artifactId>
            <version>x.y.z</version>
        </dependency>
    </dependencies>

</project>

Substitute x.y.z with the latest available versions that are compatible. See the Supported versions for details. You may also adjust the Java version.

Entity classes

For this tutorial we will model our entity with a Java record class:

@Document("characters")
public record Character(
        @Id
        String id,
        String name,
        String surname
) {
}

Create a repository

Now that we have our data model, we want to store data. For this, we create a repository interface which extends ArangoRepository. This gives us access to CRUD operations, paging, and query by example mechanics.

public interface CharacterRepository extends ArangoRepository<Character, String> {
}

Create a Configuration class

We need a configuration class to set up everything to connect to our ArangoDB instance and to declare that all needed Spring Beans are processed by the Spring container.

@EnableArangoRepositories: Defines where Spring can find your repositories
arango(): Method to configure the connection to the ArangoDB instance
database(): Method to define the database name
returnOriginalEntities(): Method to configures the behavior of repository save methods to either return the
original entities (updated where possible) or new ones. Set to false to use java records.

@Configuration
@EnableArangoRepositories(basePackages = {"com.arangodb.spring.demo"})
public class AdbConfig implements ArangoConfiguration {

    @Override
    public ArangoDB.Builder arango() {
        return new ArangoDB.Builder()
                .host("localhost", 8529)
                .user("root")
                .password("test");
    }

    @Override
    public String database() {
        return "spring-demo";
    }

    @Override
    public boolean returnOriginalEntities() {
        return false;
    }
}

Note that, in case the driver is configured to use a protocol with VPACK content type (i.e. HTTP_VPACK or HTTP2_VPACK), then the ArangoConfiguration#contentType() method must be overridden to return ContentType.VPACK as shown in the following example:

@Override
public ArangoDB.Builder arango() {
  new ArangoDB.Builder()
      // ...    
      .protocol(Protocol.HTTP2_VPACK);
}

@Override
public ContentType contentType() {
  return ContentType.VPACK;
}

You can use Java to configure your Spring Data environment as show below. Setting up the underlying driver (ArangoDB.Builder) with default configuration automatically loads a properties file arangodb.properties, if it exists in the classpath.

@Configuration
@EnableArangoRepositories(basePackages = { "com.company.mypackage" })
public class MyConfiguration implements ArangoConfiguration {

  @Override
  public ArangoDB.Builder arango() {
    return new ArangoDB.Builder();
  }

  @Override
  public String database() {
    // Name of the database to be used
    return "example-database";
  }

}

The driver is configured with some default values:

property-key	description	default value
arangodb.host	ArangoDB host	127.0.0.1
arangodb.port	ArangoDB port	8529
arangodb.timeout	socket connect timeout(millisecond)	0
arangodb.user	Basic Authentication User
arangodb.password	Basic Authentication Password
arangodb.useSsl	use SSL connection	false

To customize the configuration, the parameters can be changed in the Java code.

@Override
public ArangoDB.Builder arango() {
  ArangoDB.Builder arango = new ArangoDB.Builder()
    .host("127.0.0.1")
    .port(8529)
    .user("root");
  return arango;
}

In addition you can use the arangodb.properties or a custom properties file to supply credentials to the driver.

Properties file

arangodb.hosts=127.0.0.1:8529
arangodb.user=root
arangodb.password=

Custom properties file

@Override
public ArangoDB.Builder arango() {
  InputStream in = MyClass.class.getResourceAsStream("my.properties");
  ArangoDB.Builder arango = new ArangoDB.Builder()
    .loadProperties(in);
  return arango;
}

Create a CommandLineRunner

To run our demo as command line application, we have to create a class implementing CommandLineRunner:

@ComponentScan("com.arangodb.spring.demo")
public class CrudRunner implements CommandLineRunner {

    @Autowired
    private ArangoOperations operations;

    @Autowired
    private CharacterRepository repository;

    @Override
    public void run(String... args) {
        // first drop the database so that we can run this multiple times with the same dataset
        operations.dropDatabase();

        System.out.println("# CRUD operations");

        // save a single entity in the database
        // there is no need of creating the collection first. This happen automatically
        Character nedStark = new Character(null, "Ned", "Stark");
        Character saved = repository.save(nedStark);
        System.out.println("Ned Stark saved in the database: " + saved);
    }
}

Run the application

Finally, we create a main class:

@SpringBootApplication
public class DemoApplication {
  public static void main(final String... args) {
    System.exit(SpringApplication.exit(
            SpringApplication.run(CrudRunner.class, args)
    ));
  }
}

And run it with:

mvn spring-boot:run

This should produce a console output similar to:

Ned Stark saved in the database: Character[id=2029, name=Ned, surname=Stark]

Using the underlying Java Driver

The underlying Java driver can be obtained via ArangoOperations.driver(). This driver instance is configured by default to use ArangoConverter bean to serialize and deserialize user data, therefore keeping the same Spring Data ArangoDB serialization behavior.

Limitations

GraalVM Native Image (available with Spring Boot 3) is not supported (DE-677)
Spring Data REST is not supported (DE-43)
Spring Data Reactive is not supported (DE-678)

Java Record classes and Kotlin Data classes are not supported (DE-539)
Spring Data REST is not supported (DE-43)
Spring Data Reactive is not supported (DE-678)