Skip to content

Commit 9658944

Browse files
ostafenostafen
authored
Add documentation section for v1.9.6 (#522)
Add documentation section for v1.9.6
1 parent 825763d commit 9658944

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+10143
-10
lines changed

‎.github/workflows/build-and-deploy.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ jobs:
2929

3030
# cache node_modules
3131
- name: Cache dependencies
32-
uses: actions/cache@v2
32+
uses: actions/cache@v3
3333
id: node-modules-cache
3434
with:
3535
path: |

‎.github/workflows/quality-checks.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ jobs:
1818

1919
# cache node_modules
2020
- name: Cache dependencies
21-
uses: actions/cache@v2
21+
uses: actions/cache@v3
2222
id: node-modules-cache
2323
with:
2424
path: |

‎src/.vuepress/theme/util/index.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -259,6 +259,7 @@ export const versions = [
259259
'1.9.3',
260260
'1.9.4',
261261
'1.9.5',
262+
'1.9.6',
262263
'master'
263264
]
264265

‎src/1.9.6/README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Welcome
2+
3+
<WrappedSection>
4+
5+
<img align="right" src="/logos/immudb-mascot.svg" width="256px"/>
6+
7+
Welcome to the immudb documentation. Great to see you here!
8+
9+
immudb is a database written in Go, but unlike other databases, it is immutable: history is preserved and can't be changed without clients noticing.
10+
11+
immudb can operate as a key-value, relational (SQL) or document database, making it a truly no-SQL database.
12+
13+
immudb can be run as full database server with replicas or easily embedded as a lightweight database into application.
14+
15+
</WrappedSection>
16+
17+
<WrappedSection>
18+
19+
### Help and Support
20+
Join our [Discord community](https://discord.gg/ThSJxNEHhZ)
21+
22+
<CnSocialButton social="discord" href="https://discord.gg/ThSJxNEHhZ" target="_blank" rel="external" bottom-offset="15"></CnSocialbutton>
23+
24+
<CnSocialButton social="twitter" target="_blank" rel="external" href="https://twitter.com/intent/tweet?text=immudb:%20lightweight,%20high-speed%20immutable%20database!&url=https://github.com/codenotary/immudb"></CnSocialButton>
25+
26+
</WrappedSection>

‎src/1.9.6/connecting/authentication.md‎

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
# Authentication
2+
3+
<WrappedSection>
4+
5+
## With credentials
6+
7+
The immudb server runs on port 3322 as the default. The code examples below illustrate how to connect your client to the server and authenticate using default options and the default username and password.
8+
You can modify defaults on the immudb server in [immudb.toml](https://github.com/codenotary/immudb/blob/master/configs/immudb.toml) in the config folder.
9+
10+
</WrappedSection>
11+
12+
:::: tabs
13+
14+
::: tab Go
15+
<<< @/src/code-examples/go/connect-with-auth/main.go
16+
:::
17+
18+
::: tab Python
19+
20+
```python
21+
from grpc import RpcError
22+
from immudb import ImmudbClient
23+
24+
URL = "localhost:3322" # immudb running on your machine
25+
LOGIN = "immudb" # Default username
26+
PASSWORD = "immudb" # Default password
27+
DB = b"defaultdb" # Default database name (must be in bytes)
28+
29+
30+
def main():
31+
client = ImmudbClient(URL)
32+
# database parameter is optional
33+
client.login(LOGIN, PASSWORD, database=DB)
34+
client.logout()
35+
36+
# Bad login
37+
try:
38+
client.login("verybadlogin", "verybadpassword")
39+
except RpcError as exception:
40+
print(exception.debug_error_string())
41+
print(exception.details())
42+
43+
44+
if __name__ == "__main__":
45+
main()
46+
47+
```
48+
:::
49+
50+
::: tab Java
51+
52+
Under the hood, during `login`, a token is being retrieved from the server,
53+
stored in memory and reused for subsequent operations.
54+
55+
The state is internally used for doing _verified_ operations (such as verifiedSet or verifiedGet).
56+
57+
```java
58+
// Setting the "store" where the internal states are being persisted.
59+
FileImmuStateHolder stateHolder = FileImmuStateHolder.newBuilder()
60+
.withStatesFolder("immu_states")
61+
.build();
62+
63+
// Creating an new ImmuClient instance.
64+
ImmuClient immuClient = ImmuClient.newBuilder()
65+
.withStateHolder(stateHolder)
66+
.withServerUrl("localhost")
67+
.withServerPort(3322)
68+
.build();
69+
70+
// Login with default credentials.
71+
immuClient.login("immudb", "immudb");
72+
```
73+
74+
:::
75+
76+
::: tab .NET
77+
78+
The following code snippets show how to create a client.
79+
80+
Using default configuration:
81+
82+
``` csharp
83+
ImmuClient immuClient = ImmuClient.NewBuilder().Build();
84+
85+
// or
86+
87+
Immuclient immuClient = new ImmuClient();
88+
Immuclient immuClient = new ImmuClient("localhost", 3322);
89+
90+
```
91+
92+
Setting `immudb` url and port:
93+
94+
``` csharp
95+
ImmuClient immuClient = ImmuClient.NewBuilder()
96+
.WithServerUrl("localhost")
97+
.WithServerPort(3322)
98+
.Build();
99+
100+
ImmuClient immuClient = ImmuClient.NewBuilder()
101+
.WithServerUrl("localhost")
102+
.WithServerPort(3322)
103+
.Build();
104+
105+
```
106+
107+
Customizing the `State Holder`:
108+
109+
``` csharp
110+
FileImmuStateHolder stateHolder = FileImmuStateHolder.NewBuilder()
111+
.WithStatesFolder("./my_immuapp_states")
112+
.Build();
113+
114+
ImmuClient immuClient = ImmuClient.NewBuilder()
115+
.WithStateHolder(stateHolder)
116+
.Build();
117+
```
118+
119+
Use `Open` and `Close` methods to initiate and terminate user sessions:
120+
121+
``` csharp
122+
await immuClient.Open("usr1", "pwd1", "defaultdb");
123+
124+
// Interact with immudb using logged-in user.
125+
//...
126+
127+
await immuClient.Close();
128+
129+
// or one liner open the session right
130+
client = await ImmuClient.NewBuilder().Open();
131+
132+
//then close it
133+
await immuClient.Close();
134+
135+
```
136+
137+
:::
138+
139+
::: tab Node.js
140+
This feature is not yet supported or not documented.
141+
Do you want to make a feature request or help out? Open an issue on [Node.js sdk github project](https://github.com/codenotary/immudb-node/issues/new)
142+
:::
143+
144+
::: tab Others
145+
If you're using another development language, please refer to the [immugw](immugw.md) option.
146+
:::
147+
148+
::::
149+
150+
<WrappedSection>
151+
152+
## With Mutual TLS
153+
154+
To enable mutual authentication, a certificate chain must be provided to both the server and client.
155+
That will cause each to authenticate with the other simultaneously.
156+
In order to generate certs, use the [generate.sh](https://github.com/codenotary/immudb/tree/master/tools/mtls) tool from immudb repository. It generates a list of folders containing certificates and private keys to set up a mTLS connection.
157+
158+
</WrappedSection>
159+
160+
<WrappedSection>
161+
162+
```bash
163+
./generate.sh localhost mysecretpassword
164+
```
165+
166+
</WrappedSection>
167+
168+
:::: tabs
169+
170+
::: tab Go
171+
<<< @/src/code-examples/go/connect-with-mtls/main.go
172+
:::
173+
174+
::: tab Python
175+
This feature is not yet supported or not documented.
176+
Do you want to make a feature request or help out? Open an issue on [Python sdk github project](https://github.com/codenotary/immudb-py/issues/new)
177+
:::
178+
179+
::: tab Java
180+
This feature is not yet supported or not documented.
181+
Do you want to make a feature request or help out? Open an issue on [Java sdk github project](https://github.com/codenotary/immudb4j/issues/new)
182+
:::
183+
184+
::: tab .NET
185+
This feature is not yet supported or not documented.
186+
Do you want to make a feature request or help out? Open an issue on [.NET SDK github project](https://github.com/codenotary/immudb4net/issues/new)
187+
:::
188+
189+
::: tab Node.js
190+
191+
```ts
192+
import ImmudbClient from 'immudb-node'
193+
import Parameters from 'immudb-node/types/parameters'
194+
195+
const IMMUDB_HOST = '127.0.0.1'
196+
const IMMUDB_PORT = '3322'
197+
const IMMUDB_USER = 'immudb'
198+
const IMMUDB_PWD = 'immudb'
199+
200+
const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
201+
202+
(async () => {
203+
const loginReq: Parameters.Login = { user: IMMUDB_USER, password: IMMUDB_PWD }
204+
const loginRes = await cl.login(loginReq)
205+
console.log('success: login:', loginRes)
206+
})()
207+
```
208+
209+
:::
210+
211+
::: tab Others
212+
If you're using another development language, please refer to the [immugw](immugw.md) option.
213+
:::
214+
215+
::::
216+
217+
<WrappedSection>
218+
219+
## No Auth
220+
221+
You also have the option to run immudb with authentication disabled. This method is depreciated and not recommended.
222+
223+
A server configured with databases and user permissions can't be instantiated without authentication enabled. If a valid token is present, authentication is enabled by default.
224+
225+
</WrappedSection>
226+
227+
<WrappedSection>
228+
229+
```bash
230+
$ ./immudb --auth=false
231+
```
232+
233+
</WrappedSection>
234+
235+
:::: tabs
236+
237+
::: tab Go
238+
<<< @/src/code-examples/go/connect-with-no-auth/main.go
239+
:::
240+
241+
::: tab Python
242+
This feature is not yet supported or not documented.
243+
Do you want to make a feature request or help out? Open an issue on [Python sdk github project](https://github.com/codenotary/immudb-py/issues/new)
244+
:::
245+
246+
::: tab Java
247+
248+
```java
249+
FileImmuStateHolder stateHolder = FileImmuStateHolder.newBuilder()
250+
.withStatesFolder("immu_states")
251+
.build();
252+
253+
ImmuClient immuClient = ImmuClient.newBuilder()
254+
.withStateHolder(stateHolder)
255+
.withServerUrl("localhost")
256+
.withServerPort(3322)
257+
.withAuth(false) // No authentication is needed.
258+
.build();
259+
try {
260+
immuClient.set(key, val);
261+
} catch (CorruptedDataException e) {
262+
// ...
263+
}
264+
```
265+
266+
:::
267+
268+
::: tab Node.js
269+
This feature is not yet supported or not documented.
270+
Do you want to make a feature request or help out? Open an issue on [Node.js sdk github project](https://github.com/codenotary/immudb-node/issues/new)
271+
:::
272+
273+
::: tab Others
274+
If you're using another development language, please refer to the [immugw](immugw.md) option.
275+
:::
276+
277+
::::
278+

0 commit comments

Comments
 (0)