Skip to main content

Getting started

Getting started

This guide will help you get started with the Python clients for KurrentDB:

Running KurrentDB locally

You can start KurrentDB with "insecure" mode in Docker by using the --insecure flag:

docker run --rm \
  -p 2113:2113 \
  docker.kurrent.io/kurrent-latest/kurrentdb:latest \
  --insecure

Installation

The kurrentdbclient Python package provides the official Python clients for KurrentDB.

Install or update Python

Before installing the Python client for KurrentDB, ensure you’re using Python 3.10 or later.

For information about how to get the latest version of Python, see the official Python documentation.

Setup a virtual environment

Once you have a supported version of Python installed, create a virtual environment and activate it:

Create a virtual environment:

python -m venv .venv

Activate the virtual environment:

source .venv/bin/activate

Install the package

Install the kurrentdbclient Python package via pip:

pip install "kurrentdbclient"

If your project requires a specific version, or has compatibility concerns with certain versions, you may provide constraints when installing:

pip install "kurrentdbclient~=1.2"

Python clients for KurrentDB

The kurrentdbclient Python package provides sync and async clients for KurrentDB:

  • Sync client – blocking interface suitable for sequential code and multi-threaded apps

  • Async client – asynchronous interface suitable for high-concurrency applications

Client configuration

KurrentDB clients use a standardized connection string to configure their connection to KurrentDB.

When KurrentDB is running locally with "insecure" mode, use a connection string with tls=false:

connection_string = "kurrentdb://127.0.0.1:2113?tls=false"

Otherwise ask your server administrator for a valid connection string.

Connecting to KurrentDB

To connect to KurrentDB, instantiate a sync or async client with a suitable connection string.

sync
from kurrentdbclient import KurrentDBClient

client = KurrentDBClient(connection_string)

Creating new events

Use the NewEvent class to define new events with a type string and binary data.

from kurrentdbclient import NewEvent

new_event = NewEvent(
    type="OrderCreated",
    data=b'{"name": "Greg"}',
)

See the NewEvent documentation for more details.

Appending to a stream

The Python client's append_to_stream() method records new events in KurrentDB.

When appending to a stream, specify a stream_name, the new events and a current_version.

sync
from kurrentdbclient import StreamState

client.append_to_stream(
    stream_name="order-123",
    events=[new_event],
    current_version=StreamState.NO_STREAM,
)

See Appending Events for more information about writing to KurrentDB.

Reading a stream

The Python client's get_stream() method reads events from a named stream.

sync
for recorded_event in client.get_stream(
    stream_name="order-123"
):
    print("Stream name:", recorded_event.stream_name)
    print("Stream position:", recorded_event.stream_position)
    print("Commit position:", recorded_event.commit_position)
    print("Event type:", recorded_event.type)
    print("Event data:", recorded_event.data)
    print("Event ID:", recorded_event.id)

See Reading Events for more information about reading from KurrentDB.

Overriding user credentials

You can use the credentials parameter of the Python client methods to override the user info given in a client connection string.

Use the construct_call_credentials() method to construct a CallCredentials object from a username and password.

sync
# Construct call credentials
credentials = client.construct_call_credentials(
    username="admin",
    password="changeit",
)

# Use credentials for this specific operation
commit_position = client.append_to_stream(
    stream_name="order-123",
    current_version=StreamState.ANY,
    events=[new_event],
    credentials=credentials,
)