{"id":13792770,"url":"https://github.com/tarantool/cartridge-springdata","last_synced_at":"2025-04-14T15:10:58.276Z","repository":{"id":39966912,"uuid":"294135187","full_name":"tarantool/cartridge-springdata","owner":"tarantool","description":"Spring Data Tarantool","archived":false,"fork":false,"pushed_at":"2024-01-24T07:27:07.000Z","size":912,"stargazers_count":18,"open_issues_count":29,"forks_count":7,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-28T04:03:27.949Z","etag":null,"topics":["java","spring","tarantool"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tarantool.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-09T14:20:42.000Z","updated_at":"2024-03-14T09:05:54.000Z","dependencies_parsed_at":"2024-08-03T22:07:13.069Z","dependency_job_id":"015959e1-6920-47c7-b07b-61fe2f73b852","html_url":"https://github.com/tarantool/cartridge-springdata","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fcartridge-springdata","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fcartridge-springdata/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fcartridge-springdata/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fcartridge-springdata/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tarantool","download_url":"https://codeload.github.com/tarantool/cartridge-springdata/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248904640,"owners_count":21180835,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","spring","tarantool"],"created_at":"2024-08-03T22:01:15.783Z","updated_at":"2025-04-14T15:10:58.255Z","avatar_url":"https://github.com/tarantool.png","language":"Java","funding_links":[],"categories":["Connectors"],"sub_categories":["Java Ecosystem"],"readme":"# Spring Data Tarantool\n\n[![cartridge-springdata:ubuntu/master Actions Status](https://github.com/tarantool/cartridge-springdata/workflows/ubuntu-master/badge.svg)](https://github.com/tarantool/cartridge-springdata/actions)\n\nThe primary goal of the [Spring Data](https://projects.spring.io/spring-data)\nproject is to make it easier to build Spring-powered applications that\nuse new data access technologies such as non-relational databases,\nmap-reduce frameworks, and cloud based data services.\n\nThe Spring Data Tarantool project provides Spring Data way of working\nwith Tarantool database spaces. The key features are repository support\nand different API layers which are common in Spring Data, as well as\nsupport for asynchronous approaches baked by the underlying asynchronous\nTarantool database driver.\n\n## Spring Boot compatibility\n\n| `spring-data-tarantool` Version | Spring Boot Version |\n|:--------------------------------|:-------------------:|\n| 0.x.x                           |        2.2.x        |\n| 0.3.x                           |        2.3.2        |\n| 0.5.2                           |        2.6.3        |\n| 0.5.3                           |        2.7.5        |\n| 0.6.x                           |        2.7.5        |\n\n## Tarantool compatibility\n\n| `spring-data-tarantool` Version | Tarantool Version |\n|:--------------------------------|:-----------------:|\n| 0.x.x                           |    1.10.x, 2.x    |\n\n## References\n\nThe Tarantool Database documentation is located at\n[tarantool.io](https://www.tarantool.io/en/doc/latest/reference/)\n\nFeel free to join the [Tarantool community chat](https://t.me/tarantool)\nin Telegram (or its counterpart [in Russian](https://t.me/tarantoolru))\nif you have any questions about Tarantool database or Spring Data Tarantool.\n\nDetailed questions can be asked on StackOverflow using the\n[tarantool](https://stackoverflow.com/questions/tagged/tarantool) tag.\n\nDocumentation and StackOverflow links will be added in the nearest future.\n\nIf you are new to Spring as well as to Spring Data, look for information\nabout [Spring projects](https://projects.spring.io/).\n\n## Quick Start\n\n### Demo project\n\nCheck out a traditional [Pet Clinic application](https://github.com/tarantool/spring-petclinic-tarantool) implemented using this module.\n\n### Maven configuration\n\nAdd the Maven dependency:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.tarantool\u003c/groupId\u003e\n    \u003cartifactId\u003espring-data-tarantool\u003c/artifactId\u003e\n    \u003cversion\u003e0.6.1\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### TarantoolTemplate\n\n`TarantoolTemplate` is the central support class for Tarantool database\noperations. It provides:\n\n* Basic POJO mapping support to and from Tarantool tuples\n* Convenience methods to interact with the store (insert object,\nupdate objects, select)\n* Exception translation into Spring's\n[technology agnostic DAO exception hierarchy](https://docs.spring.io/spring/docs/current/spring-framework-reference/html/dao.html#dao-exceptions).\n\n### Spring Data repositories\n\nTo simplify the creation of data repositories Spring Data Tarantool\nprovides a generic repository programming model. It will automatically\ncreate a repository proxy for you that adds implementations of finder\nmethods you specify on an interface.\n\nOnly simple CRUD operations including entity ID are supported at the\nmoment (will be fixed soon).\n\nFor example, given a `Book` class with name and author properties, a\n`BookRepository` interface can be defined for saving and loading the\nentities:\n\n```java\n@Tuple(\"books\")\npublic class Book {\n    @Id\n    private Integer id;\n\n    @Field(name = \"unique_key\")\n    private String uniqueKey;\n\n    @Field(name = \"book_name\")\n    private String name;\n\n    private String author;\n\n    private Integer year;\n}\n```\n\n```java\npublic interface BookRepository extends CrudRepository\u003cBook, Long\u003e {\n}\n```\n\nThe `@Tuple` annotation allows to specify the space name which schema will be used for forming the data tuples to sending\nand for mapping the incoming tuple into an object.\nYou can omit the `@Tuple` annotation, then the connector will take the class name converted to snake_case.\nThe `@Field` annotations provide custom names for the fields. It is necessary to have at least \none field marked with the `@Id` annotation.\n\nExtending `CrudRepository` causes basic CRUD methods being pulled into the\ninterface so that you can easily save and find single entities and\ncollections of them. We can also use Tarantool specific interface `TarantoolRepository`.\n\nLet's assume that you have the [tarantool/crud](https://github.com/tarantool/crud) module installed in yor Cartridge\napplication and there is an active 'crud-router' role on your router. Put the following settings in your application\nproperties:\n\n| Property name      | Example value        | Description                                                          |\n|:-------------------|:---------------------|:---------------------------------------------------------------------|\n| tarantool.host     | localhost            | Cartridge router host                                                |\n| tarantool.port     | 3301                 | Cartridge router port                                                |\n| tarantool.username | admin                | Default username for API access, may be different                    |\n| tarantool.password | myapp-cluster-cookie | Password for API access, see you Cartridge application configuration |\n\nThan you can have Spring automatically create a proxy for the repository interface by using the following JavaConfig:\n\n```java\n@Configuration\n@EnableTarantoolRepositories(basePackageClasses = BookRepository.class)\nclass ApplicationConfig extends AbstractTarantoolDataConfiguration {\n\n    @Value(\"${tarantool.host}\")\n    protected String host;\n    @Value(\"${tarantool.port}\")\n    protected int port;\n    @Value(\"${tarantool.username}\")\n    protected String username;\n    @Value(\"${tarantool.password}\")\n    protected String password;\n\n    @Override\n    protected TarantoolServerAddress tarantoolServerAddress() {\n        return new TarantoolServerAddress(host, port);\n    }\n\n    @Override\n    public TarantoolCredentials tarantoolCredentials() {\n        return new SimpleTarantoolCredentials(username, password);\n    }\n\n    @Override\n    public TarantoolClient tarantoolClient(TarantoolClientConfig tarantoolClientConfig,\n                                           TarantoolClusterAddressProvider tarantoolClusterAddressProvider) {\n        return new ProxyTarantoolTupleClient(super.tarantoolClient(tarantoolClientConfig, tarantoolClusterAddressProvider));\n    }\n}\n```\n\nThis sets up a connection to a local Tarantool instance and enables the\ndetection of Spring Data repositories (through `@EnableTarantoolRepositories`).\n\nThis will find the repository interface and register a proxy object in the container. You can use it as shown below:\n\n```java\n@Service\npublic class MyService {\n\n    private final BookRepository repository;\n\n    @Autowired\n    public MyService(BookRepository repository) {\n        this.repository = repository;\n    }\n\n    public void doWork() {\n        Book book = new Book();\n        book.setName(\"Le Petit Prince\");\n        book.setAuthor(\"Antoine de Saint-Exupéry\");\n        Book savedBook = repository.save(book);\n\n        List\u003cBook\u003e allBooks = repository.findAll();\n    }\n}\n```\n\n#### Proxy Tarantool functions in repositories\n\nConsider we need to write a complex query in Lua, working with sharded data in Tarantool Cartridge. In this case\nwe can expose this query as a public API function and map that function on a repository method via the `@Query`\nannotation by specifying the functionName parameter:\n\n```java\npublic interface BookRepository extends CrudRepository\u003cBook, Long\u003e {\n    @Query(function = \"find_by_complex_query\")\n    List\u003cBook\u003e findByYearGreaterThenProxy(Integer year);\n}\n```\n\nThe corresponding function in on Tarantool Cartridge router may look like (uses the\n[tarantool/crud](https://github.com/tarantool/crud) module):\n\n```lua\n    local crud = require('crud')\n    local fun = require('fun')\n\n    ...\n\n    function find_by_complex_query(year)\n        return crud.pairs('books'):filter(function(b) return b[6] and b[6] \u003e year end):totable()\n    end\n```\n\nSee more examples in the module tests.\n\n##### Specify output\nFor such methods, you can specify the stored function response format so that it will be parsed correctly.\nThe response format can be specified in the `@Query` annotation using the `output` parameter, see the examples below.\n\n```java\npublic interface SampleUserRepository extends TarantoolRepository\u003cSampleUser, String\u003e {\n    @Query(function = \"get_users_with_age_gt\", output = TarantoolSerializationType.TUPLE)\n    List\u003cSampleUser\u003e usersWithAgeGreaterThen(Integer age);\n\n    @Query(function = \"get_predefined_user\", output = TarantoolSerializationType.AUTO)\n    SampleUser predefinedUser();\n}\n```\n\n```lua\nfunction get_users_with_gt_age(age)\n    return crud.select(\"sample_user\", { { \"\u003e\", \"age\", age } })\nend\n\nfunction get_predefined_user()\n    return { name = \"John\", age = 46 }\nend\n```\nThe first function returns users who are older than the specified age.\nIn the Repository, we indicate that we expect `TUPLE`, because `crud.select` returns the result in compressed format, flatten tuples.\nThe keys for mapping the result into a Java object are obtained from the space metadata determined by the class name in the method return type. If this class has a `@Tuple` annotation with a custom space name, this space will be used for getting the metadata.\n\nThe second function returns a ready-made result with keys.\nSo `TUPLE` will not work here, because it's not flatten structure, and we specify `AUTO`.\nMapping happens by keys of table.\n\nOf course, the word `AUTO` means that we can accept any result, and therefore it can be specified in the first request as well.\nBut we specify `TUPLE` because a different stack of converters is used and the conversion is faster.\nFor ease of use and clarity, the **default output parameter** is `TarantoolSerializationType.AUTO`.\n\nWe can also return primitive types if needed:\n```java\n@Query(function = \"get_age_by_name\", output = TarantoolSerializationType.AUTO)\nOptional\u003cInteger\u003e getAgeByName(String name);\n```\n\n```lua\nfunction get_age_by_name(name)\n    local user = crud.get(\"sample_user\", name)\n    if user.rows[1] ~= nil then\n        return user.rows[1][2]\n    end\n    return nil\nend\n```\n\n\n### Composite primary key\n\nYou can create an entity representing a Tarantool tuple with composite primary index. For this you need to use\n@TarantoolIdClass annotation on entity to specify the type of id. Also you may mark all 'id' fields in the entity with\nstandard @Id annotation. @Id annotation on properties is optional but It is recommended to use it to make code more\nclear.\n\nSee the example:\n\n```java\n\npublic class BookTranslationId {\n    private Integer bookId;\n    private String language;\n    private Integer edition;\n}\n\n@Tuple(\"book_translation\")\n@TarantoolIdClass(BookTranslationId.class)\npublic class BookTranslation {\n    @Id\n    @Field(value = \"id\")\n    private Integer bookId;\n    @Id\n    private String language;\n    @Id\n    private Integer edition;\n    private String translator;\n    private String comments;\n}\n\npublic interface BookTranslationRepository\n        extends TarantoolRepository\u003cBookTranslation, BookTranslationId\u003e {\n}\n\n```\n\n## Contributing to Spring Data Tarantool\n\nContributions and issues are welcome, feel free to add them to this project or offer directly in the Tarantool community\nchat or on StackOverflow using the [tarantool](https://stackoverflow.com/questions/tagged/tarantool)\ntag.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Fcartridge-springdata","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftarantool%2Fcartridge-springdata","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Fcartridge-springdata/lists"}