Skip to content

Commit a5ec5ed

Browse files
iDneproviDneprov
committed
Update quickstart in readme
Add new test with single instance tarantool application Change quickstart section in readme Closes #305
1 parent c0f6f2b commit a5ec5ed

File tree

3 files changed

+120
-82
lines changed

3 files changed

+120
-82
lines changed

Diff for: ‎README.md

+17-82
Original file line numberDiff line numberDiff line change
@@ -16,67 +16,29 @@ with sharding via [vshard](https://github.com/tarantool/vshard).
1616

1717
## Quickstart
1818

19-
1. Set up your [Cartridge cluster](https://tarantool.io/cartridge). Use an existing Cartridge application or create
20-
a new one from the available [examples](https://github.com/tarantool/examples).
21-
22-
2. Add the [tarantool/crud](https://github.com/tarantool/crud) and [tarantool/ddl](https://github.com/tarantool/ddl)
23-
modules to the dependencies in the [`rockspec`](https://www.tarantool.io/en/doc/latest/book/cartridge/cartridge_dev/#creating-a-project)
24-
file of your application.
25-
26-
3. Add the following lines into any [storage role](https://www.tarantool.io/en/doc/latest/book/cartridge/cartridge_dev/#cluster-roles)
27-
enabled on all storage instances in your cluster. The lines go into role API declaration section; in other words, into the returned table
28-
29-
```lua
30-
return {
31-
role_name = 'app.roles.api_storage',
32-
init = init,
33-
...
34-
get_schema = require('ddl').get_schema,
35-
...
36-
dependencies = {
37-
'cartridge.roles.crud-storage'
38-
}
39-
}
40-
```
41-
42-
4. Add the following lines into any [router role](https://www.tarantool.io/en/doc/latest/book/cartridge/cartridge_dev/#cluster-roles)
43-
enabled on all router instances in your cluster to which the driver will be connected to:
44-
45-
```lua
46-
...
19+
Example of single instance Tarantool application and java app connected using cartridge-java.
4720

48-
-- Add the following variables
49-
local cartridge_pool = require('cartridge.pool')
50-
local cartridge_rpc = require('cartridge.rpc')
21+
The easiest way to start experimenting with cartridge-java and single instance tarantool app is to use
22+
[single instance test](/src/test/java/io/tarantool/driver/integration/SingleInstanceExampleTest.java).
23+
You can set breakpoints and run it in debug mode.
24+
Testcontainers will start [single instance tarantool application](src/test/resources/single-instance.lua) for you.
25+
So you will be able to manipulate data in Tarantool in real life through java expressions or Tarantool console.
5126

52-
...
53-
54-
-- Add the following function
55-
local function get_schema()
56-
for _, instance_uri in pairs(cartridge_rpc.get_candidates('app.roles.api_storage', { leader_only = true })) do
57-
return cartridge_rpc.call('app.roles.api_storage', 'get_schema', nil, { uri = instance_uri })
58-
end
59-
end
60-
61-
...
62-
63-
local function init(opts)
64-
...
65-
rawset(_G, 'ddl', { get_schema = get_schema }) -- Add this line
66-
...
67-
end
27+
If you want to start tarantool application manually all you need is to run this file in tarantool
28+
``` bash
29+
tarantool src/test/resources/single-instance.lua
6830
```
6931

70-
5. Check that at least one role enabled on the storage instances depends on the [`crud-storage`](https://github.com/tarantool/crud#api)
71-
role from the `tarantool/crud` module and at least one role enabled on the router instances the driver will be connected
72-
to depends on the [`crud-router`](https://github.com/tarantool/crud#api) role.
32+
Example of TarantoolClient set up
33+
https://github.com/tarantool/cartridge-java/blob/master/src/test/java/io/tarantool/driver/integration/SingleInstanceExampleTest.java#L49-L58
7334

74-
6. Start your Cartridge cluster. You may use [`cartridge start`](https://www.tarantool.io/en/doc/latest/book/cartridge/cartridge_cli/)
75-
for starting it manually or the [Testcontainers for Tarantool](https://github.com/tarantool/cartridge-java-testcontainers)
76-
library for starting it automatically in tests.
35+
Example of client API usage
36+
https://github.com/tarantool/cartridge-java/blob/master/src/test/java/io/tarantool/driver/integration/SingleInstanceExampleTest.java#L62-L74
7737

78-
7. Add the following dependency into your project:
38+
You can read more about Cartridge applications in its [documentation](https://www.tarantool.io/ru/doc/latest/how-to/getting_started_cartridge/).
39+
Also look at available Cartridge application [examples](https://github.com/tarantool/examples).
7940

41+
If you use this code in another project don't forget to add `cartridge-driver` dependency:
8042
```xml
8143
<dependency>
8244
<groupId>io.tarantool</groupId>
@@ -85,33 +47,6 @@ library for starting it automatically in tests.
8547
</dependency>
8648
```
8749

88-
8. Create a new `TarantoolClient` instance:
89-
90-
```java
91-
TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>> setupClient() {
92-
return TarantoolClientFactory.createClient()
93-
// If any addresses or an address provider are not specified, the default host 127.0.0.1 and port 3301 are used
94-
.withAddress("123.123.123.1")
95-
// For connecting to a Cartridge application, use the value of cluster_cookie parameter in the init.lua file
96-
.withCredentials("admin", "secret-cluster-cookie")
97-
// you may also specify more client settings, such as:
98-
// timeouts, number of connections, custom MessagePack entities to Java objects mapping, etc.
99-
.build();
100-
}
101-
```
102-
103-
9. Use the API provided by the Tarantool client, for example:
104-
105-
```java
106-
TarantoolTupleFactory tupleFactory = new DefaultTarantoolTupleFactory(mapperFactory.defaultComplexTypesMapper());
107-
TarantoolSpaceOperations<TarantoolTuple, TarantoolResult<TarantoolTuple>> profileSpace = client.space("profile");
108-
109-
List<Object> values = Arrays.asList(123, null, "Jane Doe", 18, 999);
110-
TarantoolTuple tarantoolTuple = tupleFactory.create(values);
111-
112-
TarantoolResult<TarantoolTuple> insertTuples = profileSpace.insert(tarantoolTuple).get();
113-
```
114-
11550
### Cluster Tarantool client
11651

11752
Connects to multiple Tarantool nodes, usually Tarantool Cartridge routers. Supports multiple connections to one node.
@@ -122,7 +57,7 @@ connections are open to a single host (using the `connections` option in the con
12257
closed, all connections to that host are gracefully closed and re-established.
12358

12459
You may set up automatic retrieving of the list of cluster nodes available for connection (aka discovery). Discovery
125-
provider variants with a HTTP endpoint and a stored function in Tarantool are available out-of-the-box. You may use
60+
provider variants with an HTTP endpoint and a stored function in Tarantool are available out-of-the-box. You may use
12661
these variants or create your own discovery provider implementation. In real environments with high availability
12762
requirements it is recommended to use an external configuration provider (like etcd), DNS or a balancing proxy for
12863
connecting to the Tarantool server.

Diff for: ‎src/test/java/io/tarantool/driver/integration/SingleInstanceExampleTest.java

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
package io.tarantool.driver.integration;
2+
3+
import java.util.Arrays;
4+
5+
import org.junit.jupiter.api.BeforeAll;
6+
import org.junit.jupiter.api.Test;
7+
import static org.junit.jupiter.api.Assertions.assertEquals;
8+
9+
import org.slf4j.Logger;
10+
import org.slf4j.LoggerFactory;
11+
12+
import org.testcontainers.containers.TarantoolContainer;
13+
import org.testcontainers.containers.output.Slf4jLogConsumer;
14+
import org.testcontainers.junit.jupiter.Container;
15+
import org.testcontainers.junit.jupiter.Testcontainers;
16+
17+
import io.tarantool.driver.api.TarantoolClient;
18+
import io.tarantool.driver.api.TarantoolClientFactory;
19+
import io.tarantool.driver.api.TarantoolResult;
20+
import io.tarantool.driver.api.space.TarantoolSpaceOperations;
21+
import io.tarantool.driver.api.conditions.Conditions;
22+
import io.tarantool.driver.api.tuple.TarantoolTuple;
23+
import io.tarantool.driver.api.tuple.TarantoolTupleFactory;
24+
import io.tarantool.driver.api.tuple.DefaultTarantoolTupleFactory;
25+
import io.tarantool.driver.mappers.DefaultMessagePackMapperFactory;
26+
27+
28+
/**
29+
* @author Ivan Dneprov
30+
*/
31+
@Testcontainers
32+
public class SingleInstanceExampleTest {
33+
34+
private static final Logger log = LoggerFactory.getLogger(SingleInstanceExampleTest.class);
35+
36+
@Container
37+
private static final TarantoolContainer container = new TarantoolContainer()
38+
.withScriptFileName("single-instance.lua")
39+
.withLogConsumer(new Slf4jLogConsumer(log));
40+
41+
private static final DefaultMessagePackMapperFactory mapperFactory = DefaultMessagePackMapperFactory.getInstance();
42+
43+
@BeforeAll
44+
public static void prepareCluster() {
45+
container.start();
46+
}
47+
48+
TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>> setupClient() {
49+
return TarantoolClientFactory.createClient()
50+
// If any addresses or an address provider are not specified,
51+
// the default host 127.0.0.1 and port 3301 are used
52+
.withAddress(container.getHost(), container.getPort())
53+
// For connecting to a Cartridge application, use the value of cluster_cookie parameter in the init.lua file
54+
.withCredentials(container.getUsername(), container.getPassword())
55+
// you may also specify more client settings, such as:
56+
// timeouts, number of connections, custom MessagePack entities to Java objects mapping, etc.
57+
.build();
58+
}
59+
60+
@Test
61+
public void simplePutAndGetTest() throws Exception {
62+
try (TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>> client = setupClient()) {
63+
TarantoolTupleFactory tupleFactory =
64+
new DefaultTarantoolTupleFactory(mapperFactory.defaultComplexTypesMapper());
65+
TarantoolSpaceOperations<TarantoolTuple, TarantoolResult<TarantoolTuple>> regionSpace =
66+
client.space("region");
67+
68+
TarantoolTuple tarantoolTuple = tupleFactory.create(Arrays.asList(77, "Moscow"));
69+
TarantoolResult<TarantoolTuple> insertTuples = regionSpace.insert(tarantoolTuple).get();
70+
TarantoolResult<TarantoolTuple> selectTuples =
71+
regionSpace.select(Conditions.equals("id", 77)).get();
72+
73+
TarantoolTuple insertTuple = insertTuples.get(0);
74+
TarantoolTuple selectTuple = selectTuples.get(0);
75+
assertEquals(insertTuple.getInteger("id"), selectTuple.getInteger("id"));
76+
assertEquals(insertTuple.getString("name"), selectTuple.getString("name"));
77+
}
78+
}
79+
}

Diff for: ‎src/test/resources/single-instance.lua

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
box.cfg {
2+
listen = 3301,
3+
memtx_memory = 128 * 1024 * 1024, -- 128 Mb
4+
log_level = 6,
5+
}
6+
7+
-- Create region space
8+
-- Set if_not_exists = true to ignore that region space already exists
9+
-- You need this to have an ability to restart Tarantool app without deleting .xlog .snap files
10+
s = box.schema.space.create('region', { if_not_exists = true })
11+
s:format({
12+
{name = 'id', type = 'unsigned'},
13+
{name = 'name', type = 'string'}
14+
})
15+
s:create_index('id', {
16+
type = 'tree',
17+
parts = {'id'},
18+
if_not_exists = true
19+
})
20+
21+
-- API user will be able to login with this password
22+
box.schema.user.create('api_user', { password = 'secret' })
23+
-- API user will be able to create spaces, add or remove data, execute functions
24+
box.schema.user.grant('api_user', 'read,write,execute', 'universe')

0 commit comments

Comments
 (0)