You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/api/appending-events.md
+11-11Lines changed: 11 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,15 +4,15 @@ order: 2
4
4
5
5
# Appending events
6
6
7
-
When you start working with EventStoreDB, your application streams are empty. The first meaningful operation is to add one or more events to the database using this API.
7
+
When you start working with KurrentDB, your application streams are empty. The first meaningful operation is to add one or more events to the database using this API.
8
8
9
9
::: tip
10
10
Check the [Getting Started](getting-started.md) guide to learn how to configure and use the client SDK.
11
11
:::
12
12
13
13
## Append your first event
14
14
15
-
The simplest way to append an event to EventStoreDB is to create an `EventData` object and call `appendToStream` method.
15
+
The simplest way to append an event to KurrentDB is to create an `EventData` object and call `appendToStream` method.
16
16
17
17
```ts {32-43}
18
18
import { v4asuuid } from"uuid";
@@ -29,7 +29,7 @@ const event = jsonEvent({
29
29
});
30
30
31
31
awaitclient.appendToStream("orders", event, {
32
-
expectedRevision:NO_STREAM,
32
+
streamStateNO_STREAM,
33
33
});
34
34
```
35
35
@@ -43,11 +43,11 @@ If you are new to Event Sourcing, please study the [Handling concurrency](#handl
43
43
44
44
## Working with EventData
45
45
46
-
Events appended to EventStoreDB must be wrapped in an `EventData` object. This allows you to specify the event's content, the type of event, and whether it's in JSON format. In its simplest form, you need three arguments: **eventId**, **eventType**, and **eventData**.
46
+
Events appended to KurrentDB must be wrapped in an `EventData` object. This allows you to specify the event's content, the type of event, and whether it's in JSON format. In its simplest form, you need three arguments: **eventId**, **eventType**, and **eventData**.
47
47
48
48
### eventId
49
49
50
-
This takes the format of a `UUID` and is used to uniquely identify the event you are trying to append. If two events with the same `UUID` are appended to the same stream in quick succession, EventStoreDB will only append one of the events to the stream.
50
+
This takes the format of a `UUID` and is used to uniquely identify the event you are trying to append. If two events with the same `UUID` are appended to the same stream in quick succession, KurrentDB will only append one of the events to the stream.
51
51
52
52
For example, the following code will only append a single event:
53
53
@@ -77,19 +77,19 @@ It is common to see the explicit event code type name used as the type as it mak
77
77
78
78
### eventData
79
79
80
-
Representation of your event data. It is recommended that you store your events as JSON objects. This allows you to take advantage of all of EventStoreDB's functionality, such as projections. That said, you can save events using whatever format suits your workflow. Eventually, the data will be stored as encoded bytes.
80
+
Representation of your event data. It is recommended that you store your events as JSON objects. This allows you to take advantage of all of KurrentDB's functionality, such as projections. That said, you can save events using whatever format suits your workflow. Eventually, the data will be stored as encoded bytes.
81
81
82
82
### userMetadata
83
83
84
-
Storing additional information alongside your event that is part of the event itself is standard practice. This can be correlation IDs, timestamps, access information, etc. EventStoreDB allows you to store a separate byte array containing this information to keep it separate.
84
+
Storing additional information alongside your event that is part of the event itself is standard practice. This can be correlation IDs, timestamps, access information, etc. KurrentDB allows you to store a separate byte array containing this information to keep it separate.
85
85
86
86
### contentType
87
87
88
88
The content type indicates whether the event is stored as JSON or binary format. You can use existing methods `jsonEvent` or `binaryEvent` to create the `EventData` object, which will set the content type accordingly.
89
89
90
90
## Handling concurrency
91
91
92
-
When appending events to a stream, you can supply a *stream state*. Your client uses this to inform EventStoreDB of the state or version you expect the stream to be in when appending an event. If the stream isn't in that state, an exception will be thrown.
92
+
When appending events to a stream, you can supply a *stream state*. Your client uses this to inform KurrentDB of the state or version you expect the stream to be in when appending an event. If the stream isn't in that state, an exception will be thrown.
93
93
94
94
For example, if you try to append the same record twice, expecting both times that the stream doesn't exist, you will get an exception on the second:
95
95
@@ -133,7 +133,7 @@ There are several available expected revision options:
133
133
-`bigint` - Stream should be at specific revision
134
134
135
135
This check can be used to implement optimistic concurrency. When retrieving a
136
-
stream from EventStoreDB, note the current version number. When you save it back,
136
+
stream from KurrentDB, note the current version number. When you save it back,
137
137
you can determine if somebody else has modified the record in the meantime.
To connect your application to EventStoreDB, you need to configure and create a client instance.
32
+
To connect your application to KurrentDB, you need to configure and create a client instance.
33
33
34
34
::: tip Insecure clusters
35
-
The recommended way to connect to EventStoreDB is using secure mode (which is
36
-
the default). However, if your EventStoreDB instance is running in insecure
35
+
The recommended way to connect to KurrentDB is using secure mode (which is
36
+
the default). However, if your KurrentDB instance is running in insecure
37
37
mode, you must explicitly set `tls=false` in your connection string or client configuration.
38
38
:::
39
39
40
-
EventStoreDB uses connection strings to configure the client connection. The connection string supports two protocols:
40
+
KurrentDB uses connection strings to configure the client connection. The connection string supports two protocols:
41
41
42
-
-**`esdb://`** - for connecting directly to specific node endpoints (single node or multi-node cluster with explicit endpoints)
43
-
-**`esdb+discover://`** - for connecting using cluster discovery via DNS or gossip endpoints
42
+
-**`kurrentdb://`** - for connecting directly to specific node endpoints (single node or multi-node cluster with explicit endpoints)
43
+
-**`kurrentdb+discover://`** - for connecting using cluster discovery via DNS or gossip endpoints
44
44
45
-
When using `esdb://`, you specify the exact endpoints to connect to. The client will connect directly to these endpoints. For multi-node clusters, you can specify multiple endpoints separated by commas, and the client will query each node's Gossip API to get cluster information, then picks a node based on the URI's node preference.
45
+
When using `kurrentdb://`, you specify the exact endpoints to connect to. The client will connect directly to these endpoints. For multi-node clusters, you can specify multiple endpoints separated by commas, and the client will query each node's Gossip API to get cluster information, then picks a node based on the URI's node preference.
46
46
47
-
With `esdb+discover://`, the client uses cluster discovery to find available nodes. This is particularly useful when you have a DNS A record pointing to cluster nodes or when you want the client to automatically discover the cluster topology.
47
+
With `kurrentdb+discover://`, the client uses cluster discovery to find available nodes. This is particularly useful when you have a DNS A record pointing to cluster nodes or when you want the client to automatically discover the cluster topology.
48
48
49
49
::: info Gossip support
50
-
Since version 22.10, esdb supports gossip on single-node deployments, so
51
-
`esdb+discover://` can be used for any topology, including single-node setups.
50
+
Since version 22.10, kurrentdb supports gossip on single-node deployments, so
51
+
`kurrentdb+discover://` can be used for any topology, including single-node setups.
52
52
:::
53
53
54
54
For cluster connections using discovery, use the following format:
There are a number of query parameters that can be used in the connection string to instruct the cluster how and where the connection should be established. All query parameters are optional.
@@ -89,21 +89,21 @@ There are a number of query parameters that can be used in the connection string
89
89
|`userCertFile`| String, file path | None | User certificate file for X.509 authentication. |
90
90
|`userKeyFile`| String, file path | None | Key file for the user certificate used for X.509 authentication. |
91
91
92
-
When connecting to an insecure instance, specify `tls=false` parameter. For example, for a node running locally use `esdb://localhost:2113?tls=false`. Note that usernames and passwords aren't provided there because insecure deployments don't support authentication and authorisation.
92
+
When connecting to an insecure instance, specify `tls=false` parameter. For example, for a node running locally use `kurrentdb://localhost:2113?tls=false`. Note that usernames and passwords aren't provided there because insecure deployments don't support authentication and authorisation.
93
93
94
94
## Creating a client
95
95
96
96
First, create a client and get it connected to the database.
The client instance can be used as a singleton across the whole application. It doesn't need to open or close the connection.
103
103
104
104
## Creating an event
105
105
106
-
You can write anything to EventStoreDB as events. The client needs a byte array as the event payload. Normally, you'd use a serialized object, and it's up to you to choose the serialization method.
106
+
You can write anything to KurrentDB as events. The client needs a byte array as the event payload. Normally, you'd use a serialized object, and it's up to you to choose the serialization method.
107
107
108
108
The code snippet below creates an event object instance, serializes it, and adds it as a payload to the `EventData` structure, which the client can then write to the database.
0 commit comments