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 --name kurrentdb-node -it -p 2113:2113 \
    docker.kurrent.io/kurrent-lts/kurrentdb:latest \
    --insecure \
    --run-projections=All \
    --enable-atom-pub-over-http

Please read the server docs for more details about KurrentDB installation.

Installation

The kurrentdbclient package provides the official sync and async Python clients for KurrentDB.

Install or update Python

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

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

Install the Python clients

If you use uv:

uv add "kurrentdbclient~=1.3"

If you use poetry:

poetry add "kurrentdbclient~=1.3"

If you prefer a manual setup with pip:

python -m venv .venv
source .venv/bin/activate
pip install "kurrentdbclient~=1.3"

Python clients for KurrentDB

The kurrentdbclient Python package provides both sync and async clients for KurrentDB.

The sync and async clients have exactly the same methods and behaviors as each other.

Sync client – blocking interface suitable for sequential code and multi-threaded apps
Async client – asynchronous interface suitable for high-concurrency applications

This documentation provides examples for both sync and async clients in tabbed boxes (see below).

The official sync and async Python clients have been tested with KurrentDB versions 25.0, 25.1, 26.0, and 26.1, and EventStoreDB versions 23.10 and 24.10, with and without SSL/TLS, in both single-server and cluster modes, across Python versions 3.10, 3.11, 3.12, 3.13, and 3.14.

Client configuration

All 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"

For production services, ask your service provider for a valid connection string.

Connecting to KurrentDB

To connect to KurrentDB from Python, instantiate a client with a connection string.

sync

from kurrentdbclient import KurrentDBClient

client = KurrentDBClient(connection_string)

async

from kurrentdbclient import AsyncKurrentDBClient

client = AsyncKurrentDBClient(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 client 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 NewEvent, StreamState

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

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

async

from kurrentdbclient import NewEvent, StreamState

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

await 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 client 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)

async

for recorded_event in await 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,
)

async

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

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