Self-Guided Demo

KurrentDB Quickstart

This quickstart will guide you through getting started with KurrentDB using GitHub Codespaces.

Info

GitHub Codespaces provides an instant and preconfigured development environment in your browser for this quickstart. To learn more about Github Codespaces,click here.

Objectives

In this quickstart, you will:

Start a KurrentDB server using Docker in GitHub Codespaces.
Append an event to KurrentDB with sample code.
View the appended event using the Admin UI.
Read the appended event with sample code using the KurrentDB client.

Prerequisites

Before starting, ensure you have the following:

A GitHub account to use GitHub Codespaces.
Basic knowledge of one of the development languages/platforms below.
Familiarity with command-line operations.

Tips

If you have trouble with this quickstart, you can find more help in the"KurrentDB From Scratch" tutorial series on Kurrent Academy.

Step 1: Set up Your Codespace

Choose one of the development languages/platforms below and click the Codespaces link:

Select >

Python

Quickstart Language/Platform	Link to Codespaces

Java

Quickstart Language/Platform	Link to Codespaces

.NET

Quickstart Language/Platform	Link to Codespaces

node.js

Quickstart Language/Platform	Link to Codespaces

Log in to GitHub if required.
Follow the instructions to create a new Codespace.
Wait for your Codespace to build. This can take up to a few minutes.
Once complete, you will see a welcome message in the terminal:

Hello!👋 Welcome to the EventStoreDB Getting Started Quickstart Guide.

Tips

For this quickstart, you can safely ignore and close any Codespaces notifications that appear on the bottom right of the page.

Step 2: Start the KurrentDB Server

Once your Codespace is loaded, run the following command in the terminal to start the KurrentDB server:
```
./start_db.sh
```
This is a custom script written for this quickstart to help start KurrentDB in Docker.
You will see the following message printed in the terminal:

🚀 EventStoreDB Server has started!! 🚀URL to the EventStoreDB Admin UI 👉: https://XXXXXXXXX.XXX

(Optional) Learn more about how to start KurrentDB in Docker and thestart_db.sh script

Understanding How to Start KurrentDB Server in Docker and How`start_db.sh` Works

start_db.sh is a custom script written for the quickstart that will:

Check if Docker is currently running locally
Pull the KurrentDB server Docker container
Start the server in Docker
Print the KurrentDB Admin UI URL in the terminal

To see how to start the KurrentDB server in Docker, follow these steps

Run the following command to openstart_db.sh:
```
code ./start_db.sh
```
Tips
Alternatively, you can locate and open the file from the EXPLORER window found on the left side of Codespaces. You can find the path to the file in the command above.
In step 3 of the script, review how KurrentDB is started with thedocker run command:

docker run                               # Start a new Docker container using the 'docker run' command     -d \                               # Run the container in detached mode (in the background)     --name esdb-node \                 # Assign the container a name ('esdb-node' in this case)     -p 2113:2113 \                     # Map port 2113 on the host to port 2113 in the Docker container. Required for the KurrentDB     eventstore/eventstore:24.10.1 \ # Specify the Docker image to use, in this case, the latest supported version of KurrentDB     --insecure \                       # Run KurrentDB in insecure mode, without authentication and SSL/TLS security (usually for development)     --run-projections=All \            # Enable all projections in KurrentDB, including system and user projections     --enable-atom-pub-over-http         # Enable the AtomPub API over HTTP. Required for the KurrentDB Admin UI

Review other parts of the script if you wish.
Feel free to modify and re-run the script in your Codespace.

Info

For more information about other KurrentDB parameters and settings,click here.

Info

To view the source code on Github, click the link below:

Select >

Python

Java

.NET

node.js

Step 3: Navigate to the KurrentDB Admin UI

In Codespaces, copy the URL to KurrentDB Admin UI printed in the terminal from the last step.
Open a new browser tab.
In the address bar of the new tab, paste the URL and navigate to it.
This will display the KurrentDB Admin UI.
Keep the Admin UI open for the next steps.

Step 4: Install Required Package for Sample Code

In Codespace, run the following command to install the KurrentDB client package. This will be used in the sample codes:

Select >

Python

pip install -r requirements.txt

Java

mvn package

.NET

This step is not required for .NET. Please continue to the next step.

node.js

yarn install

(Optional) Learn more about the KurrentDB client packages

Understanding Required Packages for KurrentDB Development

The KurrentDB client packages enable your code to connect to the database, append events, and read events from streams in the language/platform of your choice.

To understand what packages are installed, follow these steps:

Run the following command to examine package dependencies:

Select >

Python

code ./requirements.txt

Java

code ./pom.xml

.NET

code ./SampleAppend/SampleAppend.csproj

node.js

code ./package.json

Tips

Alternatively, you can locate and open the file from the EXPLORER window on the left of Codespaces. You can find the path to the file in the command above.

Review the KurrentDB client packages listed as dependencies:

Select >

Python

esdbclient==1.0.19

Java

<dependency>   <groupId>com.eventstore</groupId>   <artifactId>db-client-java</artifactId>   <version>5.3.2</version></dependency>

For the most recent version of the KurrentDB client package, seeMaven Central.

.NET

<ItemGroup>   <PackageReference Include="EventStore.Client.Grpc.Streams" Version="23.1.0" /></ItemGroup>

node.js

"dependencies": {   "@eventstore/db-client":"^6.1.0"}

Note

The version of the KurrentDB client above may be outdated. For more information about the client,click here.

Info

To view the source code on GitHub, click the link below:

Select >

Python

Java

.NET

node.js

Step 5: Append an Event to KurrentDB

In Codespaces, run this command to execute the sample. This appends an event to KurrentDB:

Select >

Python

python3 sample_append.py

Java

java -cp \   target/eventstoredb-demo-1.0-SNAPSHOT-jar-with-dependencies.jar \   com.eventstoredb_demo.SampleWrite

.NET

dotnet run --project SampleAppend/

node.js

node sample_append.js

You should see a confirmation for the event append, similar to this:

************************🎉 Congratulations, you have written an event!Stream: SampleStreamEvent Type: SampleEventTypeEvent Body: {"id":"1","importantData":"some value"}************************"

(Optional) Learn more about the sample code

Understanding How the Append Sample Works

To help you understand how events are appended to KurrentDB programmatically, you will explore the sample code used in this step.

The sample code demonstrates:

Establishing a Connection: Connect to KurrentDB using the client library.
Creating an Event: Create a new event with a specific type and data payload.
Appending the Event to a Stream: Append the new event to a specific stream.

To see how this works, follow these steps:

Run the following command to open the sample code:

Select >

Python

code ./sample_append.py

Java

code ./src/main/java/com/eventstoredb_demo/SampleWrite.java

.NET

code ./SampleAppend/Program.cs

node.js

code ./sample_append.js

Tips

Alternatively, you can locate and open the file from the EXPLORER window on the left of Codespaces. You can find the path to the file in the command above.

In step 1 of the code, review how the client connects to KurrentDB:

Select >

Python

# Create an instance of EventStoreDBClient, connecting to the KurrentDB at localhost without TLSclient= EventStoreDBClient(uri="esdb://localhost:2113?tls=false")

Java

// configure the settings to connect to KurrentDB locally without TLSEventStoreDBClientSettings settings= EventStoreDBConnectionString.parseOrThrow("esdb://localhost:2113?tls=false");// apply the settings and create an instance of the clientEventStoreDBClient client= EventStoreDBClient.create(settings);

.NET

// Create an instance of EventStoreClientSettings, connecting to the KurrentDB at localhost without TLSvar settings = EventStoreClientSettings.Create("esdb://localhost:2113?tls=false");awaitusing var client = newEventStoreClient(settings);

node.js

// Create an instance of EventStoreDBClient, connecting to the KurrentDB at localhost without TLSconst client = EventStoreDBClient.connectionString("esdb://localhost:2113?tls=false");

In step 2 of the code, review how a new event is initiated:

Select >

Python

event_type= "SampleEventType"                        # Define the event type for the new eventnew_event= NewEvent(# Create a new event with a type and body    type=event_type,# Specify the event type    data=b'{"id":"1", "importantData":"some value"}'  # Specify the event data body as a JSON in byte format)

Java

// Build the KurrentDB event data structureString eventType= "SampleEventType";                                  // Define the name of the event type for the new eventbyte[] eventBody= "{\"id\":\"1\",\"importantData\":\"some value\"}"  // Define the body of the event in a UTF8 encoded byte array      .getBytes(StandardCharsets.UTF_8);EventData eventData=      EventData.builderAsJson(eventType, eventBody)                    // Create the new event object with the type and body               .build();

.NET

var eventType = "SampleEventType";// Define the event type for the new eventvar eventData = newEventData(// Create a new event with a type and body    Uuid.NewUuid(),// Specify a new UUID for the event    eventType,// Specify the event type    @"{""id"":""1"",""importantData"":""some value""}"u8  // Specify the event data body as JSON encoded with UTF8        .ToArray()// Convert the body into a byte array);

node.js

const eventType = "SampleEventType"            // Define the event type for the new eventconst event = jsonEvent({// Create a new event with a type and body   type: eventType,// Specify the event type   data: {//      "id":"1","importantData":"some value"   // Specify the event data body   },});

In step 3 of the code, review how the client appends the new event to KurrentDB:

Select >

Python

event_stream= "SampleStream"        # Define the stream name where the event will be appendedclient.append_to_stream(# Append the event to a stream    event_stream,# Name of the stream to append the event to    events=[new_event],# The event to append (in a list)    current_version=StreamState.ANY  # Set to append regardless of the current stream state (you can ignore this for now))

Java

// Set append option to append regardless of what revision the stream is at (i.e. disable concurrency check)AppendToStreamOptions options= AppendToStreamOptions.get().expectedRevision(ExpectedRevision.any());// Append event to streamString eventStream= "SampleStream";client.appendToStream(eventStream, options, eventData).get();

.NET

var eventStream = "SampleStream";// Define the stream name where the event will be appendedawaitclient.AppendToStreamAsync(// Append the event to a stream    eventStream,// Name of the stream to append the event to    StreamState.Any,// Set to append regardless of the current stream state (you can ignore this for now)    [eventData]// The event to append (in a list));

node.js

const eventStream = "SampleStream";await client.appendToStream(eventStream,event);// append the event to the stream

Feel free to modify and re-run the sample in your Codespace.

Info

To learn more about other KurrentDB client functions,click here.

Info

To view the source code on GitHub, click the link below:

Select >

Python

Java

.NET

node.js

Step 6: Verify the Appended Event in the Admin UI

In the Admin UI, click theStream Browser link from the top navigation bar.
UnderRecently Changed Streams, click theSampleStream link.
Click on theJSON link in the rightmost column of the table.
You should see the content of the appended event.

Step 7: Read the Event from KurrentDB Programmatically

In Codespaces, run this command to execute the sample. This reads the event from KurrentDB:

Select >

Python

python3 sample_read.py

Java

java -cp \   target/eventstoredb-demo-1.0-SNAPSHOT-jar-with-dependencies.jar \   com.eventstoredb_demo.SampleRead

.NET

dotnet run --project SampleRead/

node.js

node sample_read.js

You should see the content of the appended event similar to this:

************************You have read an event!Stream: SampleStreamEvent Type: SampleEventTypeEvent Body: {"id":"1","importantData":"some value"}************************"

(Optional) Learn more about the sample code

Understanding How the Read Sample Works

You will explore the sample code used in this step to gain a deeper understanding of how events are read from KurrentDB programmatically. The sample code demonstrates the following:

Establishing a Connection: Illustrates how to connect to KurrentDB using the client library.
Reading Events from a Stream: Reads events from a specific stream.
Processing Retrieved Events: Iterates over the events retrieved from the stream.
Deserializing Event Data: Extracts and deserializes the event data from the retrieved events.
Displaying Event Information: Prints out the event details—such as the stream name, event type, and event body—to the console.

Run the following command to open the sample code:

Select >

Python

code ./sample_read.py

Java

code ./src/main/java/com/eventstoredb_demo/SampleRead.java

.NET

code ./SampleRead/Program.cs

node.js

code ./sample_read.js

Tips

Alternatively, you can locate and open the file from the EXPLORER window on the left of Codespaces. You can find the path to the file in the command above.

In step 1 of the code, review how the client connects to KurrentDB:

Select >

Python

# Create an instance of EventStoreDBClient, connecting to the EventStoreDB at localhost without TLSclient= EventStoreDBClient(uri="esdb://localhost:2113?tls=false")

Java

// configure the settings to connect to EventStoreDB locally without TLSEventStoreDBClientSettings settings= EventStoreDBConnectionString.   parseOrThrow("esdb://localhost:2113?tls=false");// apply the settings and create an instance of the clientEventStoreDBClient client= EventStoreDBClient.create(settings);

.NET

// Create an instance of EventStoreClientSettings, connecting to the KurrentDB at localhost without TLSvar settings = EventStoreClientSettings.Create("esdb://localhost:2113?tls=false");awaitusing var client = newEventStoreClient(settings);

node.js

// Create an instance of KurrentDBClient, connecting to the KurrentDB at localhost without TLSconst client = EventStoreDBClient.connectionString("esdb://localhost:2113?tls=false");

In step 2 of the code, review how the client reads all the events from the stream:

Select >

Python

events= client.get_stream("SampleStream")# Read all events from SampleStream

Java

ReadStreamOptions options=   ReadStreamOptions.get()  // Create a read option for client to read events      .forwards()           // Client should read events forward in time      .fromStart()          // Client should read from the start of stream      .maxCount(10);        // Client should read at most 10 events// get events from streamString eventStream= "SampleStream";ReadResult result= client.readStream(eventStream, options).get();

.NET

var events = client.ReadStreamAsync(// Read events from stream   Direction.Forwards,// Read events forward in time   "SampleStream",// Name of stream to read from   StreamPosition.Start               // Read from the start of the stream);

node.js

// Read events from the SampleStreamconst stream_name = "SampleStream";// Define the name of the stream to read fromlet events = client.readStream(// Read events from stream   stream_name,// Specify the stream name   {//      fromRevision: START,// Read from the start of the stream      direction: FORWARDS,// Read events forward in time      maxCount: 20                     // Read at most 20 events   });

In step 3 of the code, review how the events are deserialized and printed:

Select >

Python

for eventin events:# For each event   print("************************");#   print("You have read an event!");#   print("Stream: " + event.stream_name);# Print the stream name of the event   print("Event Type: " + event.type);# Print the type of the event   print("Event Body: " + event.data.decode());# Print the body of the event after converting it to string from a byte array   print("************************");

Java

for (ResolvedEvent resolvedEvent: result.getEvents()) {// For each event in stream   RecordedEvent recordedEvent= resolvedEvent.getOriginalEvent();                // Get the original event (can ignore for now)                                                                                  //   System.out.println("************************");                                //   System.out.println("You have read an event!");                                 //   System.out.println("Stream: " + recordedEvent.getStreamId());                  // Print the stream name of the event   System.out.println("Event Type: " + recordedEvent.getEventType());             // Print the type of the event   System.out.println("Event Body: " + new String(recordedEvent.getEventData(),// Print the body of the event after converting it from a byte array                                                   StandardCharsets.UTF_8));      // UTF8 is used to convert byte array to string   System.out.println("************************");}

.NET

awaitforeach (var evt in events) {// For each event in stream   Console.WriteLine("************************");//   Console.WriteLine("You have read an event!");//   Console.WriteLine("Stream: " + evt.Event.EventStreamId);// Print the stream name of the event   Console.WriteLine("Event Type: " + evt.Event.EventType);// Print the type of the event   Console.WriteLine("Event Body: " + Encoding.UTF8.GetString(// Print the body of the event. convert the byte array to string                                          evt.Event.Data.ToArray()));// Gets the event body as a byte array   Console.WriteLine("************************");}

node.js

for await (const resolvedEvent of events) {// For each event found in SampleStream   console.log("************************");//   console.log("You have read an event!");//   console.log("Stream: " + resolvedEvent.event?.streamId);// Print the stream name of the event   console.log("Event Type: " + resolvedEvent.event?.type);// Print the type of the event   console.log("Event Body: " + JSON.stringify(resolvedEvent.event?.data));// Print the body of the event as a string   console.log("************************");}