Couch Slacker project started in 2020. Basic idea and motivation was to create Spring Data support for CouchDB which is awesome and light document database. We felt in love with it because of easy clustering, nice API and good documentation. Spring Data is an awesome tool how to make development faster. So we decided to join it together.

Differently from other projects, Couch Slacker not only Spring Data like library. It is true Spring Data implementation CouchDB which makes Couch Slacker very powerful. You can start you project with Spring on CouchDB with Couch Slacker and switch to MongoDB or other database engine by simple change of dependency (and probably some little changes in entity/POJO classes). No massive refactorings needed. The other reason is that developer does not need to know Couch Slacker well. Knowledge of Spring Data is enough.

Simply said Couch Slacker let you relax on the CouchDB as Spring Data works for you.

Artifacts releases are available on maven central (and on pages indexing central):

• central
• mvnRepository

This README contains only basic information about project. For more or detailed information, visit the wiki

• Provide a basic client for CouchDB
• Provide Spring data implementation for CouchDB

• Management of documents
• Management of indexes

• Spring data repositories for CouchDB
• Query methods
• Native queries triggered by query methods

First of all we have to add Maven dependency

<dependency>
    <groupId>com.groocraft</groupId>
    <artifactId>couch-slacker</artifactId>
  <version>${version}</version>
</dependency>

Both the basic client and repositories works above document POJO classes. Let`s create a POJO class for user. Do you need to map more entities to the same database, or you need to know more information about mapping? Visit this wiki, and this wiki

@Document("user")
public class User {

    @JsonProperty("_id")
    @JsonInclude(Include.NON_NULL)
    private String id;

    @JsonProperty("_rev")
    @JsonInclude(Include.NON_NULL)
    private String revision;

    @JsonProperty("name")
    private String name;
}

It looks pretty talkative does not it? Ok, do not worry, here is way to make it shorter:

@Document("user")
public class User extends DocumentBase {

    @JsonProperty("name")
    private String name;

}

It is much better. In both examples you can notice Jackson is used. (in the case of name, no annotation is really needed, and it is present only as example). If database annotation is missing, lower-cased name of class is used as database name.

We have to start with a configuration of connectivity. URL must contain a port. Scheme can be elided, default value is HTTP. Username and password are mandatory. More information about the configuration you can find here

couchdb:
  client:
    url: http:https://localhost:5984/
    username: user
    password: password

@Configuration
class AppConfig extends CouchSlackerConfiguration {

}

Now we are ready to define Spring Data repository for CouchDB. Please notice, that CouchDB supports only String IDs.

interface UserRepository extends CrudRepository<User, String> {

}

The final step is to use the defined repository in your application.

@SpringBootApplication
@EnableCouchDbRepositories
public class CouchSlackerDemoApplication {

	@Autowired
	UserRepository userRepository;

	public static void main(String[] args) {
		SpringApplication.run(CouchSlackerDemoApplication.class, args);
	}

	@Bean
	public CommandLineRunner runner(){
		return args -> userRepository.save(new User("Majlanky"));
	}

}

The basic repository is very easy to use. Everything is based on CouchDbClient class. First of all lets show the way completely without Spring framework.

CouchDbProperties properties = new CouchDbProperties("http:https://localhost:5984/", "admin", "password");
CouchDbClient client = CouchDbClient.builder().properties(properties).build();

The project is still in its infancy, so there are limitations. There is a list of known limitations:

• Missing API for attachments and views.
• Projections are not tested and probably not working
• Query by example is not tested and probably not working
• Some operations are done very ineffectively (paging for example is done without view and startKey)
• Missing auditing feature
• Not following operations are not implemented for query method
  • Between
  • Near
  • Within

See issues what is known and when it is planned to solve it. If you need something faster than planned, let us know.

Despite the fact you can use Couch Slacker as dependency of your project as it is available on maven central, you can build the project by you own. Couch Slacker is a maven project with prepared maven wrapper. Everything you need to do is call the following command in the root of the project.

$ ./mwnw clean install

the previous command skips integration tests. For build with integration tests use (and check wiki for integration tests information):

$ ./mwnw clean install -P ITs

More information about integration tests of Couch Slacker you can find here

However, every build contains integration (and junit) tests which are executed against CouchDB in Docker. It is reason, why Docker must be installed on the machine. If you do not have Docker and do not want to install it, execute the first command.

Couch Slacker project follows Apache versioning

Couch Slacker project is licensed under the Apache License, Version 2.0