# Connecting to EventStoreDB

# Required packages

Install the client SDK package to your project.

    $ dotnet add package EventStore.Client.Grpc.Streams --version 20.10
    
    # Add the gRPC Client 2.32+ if you're connecting to an insecure cluster
    $ dotnet add package Grpc.Net.Client --version 2.34.0
    
    # Maven
    <dependency>
      <groupId>com.eventstore</groupId>
      <artifactId>db-client-java</artifactId>
      <version>0.5</version>
    </dependency>
    
    # Gradle
    implementation 'com.eventstore:db-client-java:0.5'
    
    # SBT
    libraryDependencies += "com.eventstore" % "db-client-java" % "0.6"
    
    # Yarn
    $ yarn add @eventstore/db-client
    
    # NPM
    $ npm install --save @eventstore/db-client
    
    No additional configuration is needed having Rust installed. Go check https://rustup.rs.
    
    // Make sure to add code blocks to your code group

    Preview clients

    The following SDKs are currently in preview and can get API changes:

    • NodeJS
    • Java
    • Go
    • Rust

    # Connection string

    Each SDK has its own way to configure the client, but it's always possible to use the connection string. The connection string below is generated according to the configuration you specified above, and it should work with each official SDK of EventStoreDB.

    You can either put the connection string in the input box below, or use the connection details page to generate the connection string from your EventStoreDB deployment.

    # Creating a client

    First thing first, we need a client.

      var settings = EventStoreClientSettings
      	.Create("<your value>");
      var client = new EventStoreClient(settings);
      EventStoreDBClientSettings settings = EventStoreDBConnectionString.parse("<your value>");
      EventStoreDBClient client = EventStoreDBClient.create(settings);
      const client = EventStoreDBClient.connectionString("<your value>");
      
      let settings = "<your value>".parse()?;
      let client = Client::create(settings).await?;
      // Make sure to add code blocks to your code group

      The client instance can be used as a singleton across the whole application. It doesn't need to open or close the connection.

      # Creating an event

      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.

      Server-side projections

      User-defined server-side projections require events to be serialized to JSON format.

      We use JSON for serialization in the documentation examples.

      The code snippet below creates an event object instance, serializes it and puts it as payload to the EventData structure, which the client is able to write to the database.

        var evt = new TestEvent
        {
        	EntityId = Guid.NewGuid().ToString("N"),
        	ImportantData = "I wrote my first event!"
        };
        
        var eventData = new EventData(
        	Uuid.NewUuid(),
        	"TestEvent",
        	JsonSerializer.SerializeToUtf8Bytes(evt)
        );
        TestEvent event = new TestEvent();
        event.setId(UUID.randomUUID().toString());
        event.setImportantData("I wrote my first event!");
        
        EventData eventData = EventData
                .builderAsJson("TestEvent", event)
                .build();
        const event = jsonEvent({
          type: "TestEvent",
          data: {
            entityId: uuid(),
            importantData: "I wrote my first event!",
          },
        });
        let event = TestEvent {
            id: Uuid::new_v4().to_string(),
            important_data: "I wrote my first event!".to_string(),
        };
        
        let event_data = EventData::json("TestEvent", event)?.id(Uuid::new_v4());
        // Make sure to add code blocks to your code group

        # Appending events

        Each event in the database has its own unique identifier (UUID). The database uses it to ensure idempotent writes, but it only works if you specify the stream revision when appending events to the stream.

        In the snippet below, we append the event to the stream some-stream.

          await client.AppendToStreamAsync(
          	"some-stream",
          	StreamState.Any,
          	new[] { eventData },
          	cancellationToken: cancellationToken
          );
          client.appendToStream("some-stream", eventData)
                  .get();
          await client.appendToStream("some-stream", event);
          
          client
              .append_to_stream("some-stream", &Default::default(), event_data)
              .await?;
          // Make sure to add code blocks to your code group

          Here we are appending events without checking if the stream exists or if the stream version matches the expected event version. See more advanced scenarios in appending events documentation.

          # Reading events

          Finally, we can read events back from the some-stream stream.

            var result = client.ReadStreamAsync(
                Direction.Forwards,
                "some-stream",
                StreamPosition.Start,
                cancellationToken: cancellationToken);
            
            var events = await result.ToListAsync(cancellationToken);
            ReadStreamOptions options = ReadStreamOptions.get()
                    .forwards()
                    .fromStart();
            
            ReadResult result = client.readStream("some-stream", 10, options)
                    .get();
            
            List<ResolvedEvent> events = result.getEvents();
            const events = await client.readStream("some-stream", {
              direction: FORWARDS,
              fromRevision: START,
              maxCount: 10
            });
            let result = client
                .read_stream("some-stream", &Default::default(), 10)
                .await?;
            
            if let ReadResult::Ok(events) = result {
                // Doing something productive with the events.
            }
            // Make sure to add code blocks to your code group

            When you read events from the stream, you get a collection of ResolvedEvent structures. The event payload is returned as a byte array and needs to be deserialized. See more advanced scenarios in reading events documentation.

            Last Updated: 3/2/2021, 1:16:11 PM