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
+19-17Lines changed: 19 additions & 17 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.
@@ -71,11 +71,11 @@ If you are new to Event Sourcing, please study the [Handling concurrency](#handl
71
71
72
72
## Working with EventData
73
73
74
-
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**.
74
+
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**.
75
75
76
76
### eventId
77
77
78
-
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.
78
+
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.
79
79
80
80
For example, the following code will only append a single event:
@@ -106,19 +106,19 @@ It is common to see the explicit event code type name used as the type as it mak
106
106
107
107
### eventData
108
108
109
-
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.
109
+
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.
110
110
111
111
### userMetadata
112
112
113
-
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.
113
+
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.
114
114
115
115
### contentType
116
116
117
117
The content type indicates whether the event is stored as JSON or binary format. This is automatically set when using the builder methods like `builderAsJson()` or `builderAsBinary()`.
118
118
119
119
## Handling concurrency
120
120
121
-
When appending events to a stream, you can supply an *expected revision*. 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.
121
+
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.
122
122
123
123
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:
There are several available expected revision options:
152
-
-`ExpectedRevision.any()` - No concurrency check
153
-
-`ExpectedRevision.noStream()` - Stream should not exist
154
-
-`ExpectedRevision.streamExists()` - Stream should exist
155
-
-`ExpectedRevision.expectedRevision(long revision)` - Stream should be at specific revision
152
+
-`StreamState.any()` - No concurrency check
153
+
-`StreamState.noStream()` - Stream should not exist
154
+
-`StreamState.streamExists()` - Stream should exist
155
+
-`StreamState.streamRevision(long revision)` - Stream should be at specific revision
156
156
157
-
This check can be used to implement optimistic concurrency. When retrieving a stream from EventStoreDB, note the current version number. When you save it back, you can determine if somebody else has modified the record in the meantime.
157
+
This check can be used to implement optimistic concurrency. When retrieving a
158
+
stream from KurrentDB, note the current version number. When you save it back,
159
+
you can determine if somebody else has modified the record in the meantime.
158
160
159
161
First, let's define the event classes for our ecommerce example:
@@ -15,7 +15,7 @@ X.509 certificates are digital certificates that use the X.509 public key infras
15
15
16
16
## Prerequisites
17
17
18
-
1. KurrentDB 25.0 or greater, or EventStoreDB 24.10 or later.
18
+
1. KurrentDB 25.0 or greater, or KurrentDB 24.10 or later.
19
19
2. A valid X.509 certificate configured on the Database. See [configuration steps](@server/security/user-authentication.html#user-x-509-certificates) for more details.
20
20
21
21
## Connect using an x.509 certificate
@@ -36,8 +36,8 @@ The client supports the following parameters:
36
36
To authenticate, include these two parameters in your connection string or constructor when initializing the client:
To connect your application to EventStoreDB, you need to configure and create a client instance.
36
+
To connect your application to KurrentDB, you need to configure and create a client instance.
37
37
38
38
::: tip Insecure clusters
39
-
The recommended way to connect to EventStoreDB is using secure mode (which is
40
-
the default). However, if your EventStoreDB instance is running in insecure
39
+
The recommended way to connect to KurrentDB is using secure mode (which is
40
+
the default). However, if your KurrentDB instance is running in insecure
41
41
mode, you must explicitly set `tls=false` in your [connection
42
42
string](#connection-string) or client configuration.
43
43
:::
44
44
45
-
EventStoreDB uses connection strings to configure the client connection. The connection string supports two protocols:
45
+
KurrentDB uses connection strings to configure the client connection. The connection string supports two protocols:
46
46
47
-
-**`esdb://`** - for connecting directly to specific node endpoints (single node or multi-node cluster with explicit endpoints)
48
-
-**`esdb+discover://`** - for connecting using cluster discovery via DNS or gossip endpoints
47
+
-**`kurrentdb://`** - for connecting directly to specific node endpoints (single node or multi-node cluster with explicit endpoints)
48
+
-**`kurrentdb+discover://`** - for connecting using cluster discovery via DNS or gossip endpoints
49
49
50
-
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.
50
+
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.
51
51
52
-
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.
52
+
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.
53
53
54
54
::: info Gossip support
55
-
Since version 22.10, EventStoreDB supports gossip on single-node deployments, so
56
-
`esdb+discover://` can be used for any topology, including single-node setups.
55
+
Since version 22.10, KurrentDB supports gossip on single-node deployments, so
56
+
`kurrentdb+discover://` can be used for any topology, including single-node setups.
57
57
:::
58
58
59
59
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.
@@ -96,22 +96,22 @@ There are a number of query parameters that can be used in the connection string
96
96
|`dnsDiscover`|`true`, `false`|`false`| Enable DNS-based cluster discovery. When `true`, resolves hostnames to discover cluster nodes. Use with `feature=dns-lookup` for full DNS resolution. |
97
97
|`feature`|`dns-lookup`| None | Enable specific client features. Use `dns-lookup` with `dnsDiscover=true` to resolve hostnames to multiple IP addresses for cluster discovery. |
98
98
99
-
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.
99
+
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.
100
100
101
101
## Creating a client
102
102
103
103
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.
111
111
112
112
## Creating an event
113
113
114
-
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.
114
+
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.
115
115
116
116
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