Link existing events to another stream

CHANGELOG.md

@@ -12,6 +12,7 @@
 - Use PostgreSQL advisory locks to enforce only one subscription instance ([#98](https://github.com/commanded/eventstore/pull/98)).
 - Remove stream process ([#99](https://github.com/commanded/eventstore/pull/99)).
 - Use PostgreSQL's `NOTIFY` / `LISTEN` for event pub/sub ([#100](https://github.com/commanded/eventstore/pull/100)).
+- Link existing events to another stream ([#103](https://github.com/commanded/eventstore/pull/103)).
 
 ## v0.13.2
 

README.md

@@ -22,6 +22,7 @@ MIT License
   - [Reading from a stream](guides/Usage.md#reading-from-a-stream)
   - [Reading from all streams](guides/Usage.md#reading-from-all-streams)
   - [Stream from all streams](guides/Usage.md#stream-from-all-streams)
+  - [Linking events between streams](guides/Usage.md#linking-events-between-streams)
   - [Subscribe to streams](guides/Subscriptions.md)
     - [Ack received events](guides/Subscriptions.md#ack-received-events)
     - [Example subscriber](guides/Subscriptions.md#example-subscriber)

guides/Cluster.md

@@ -4,7 +4,7 @@ EventStore supports running on multiple nodes as either a [distributed Erlang](h
 
 ## Event publication
 
-PostgreSQL `LISTEN` / `NOTIFY` is used to pub/sub event notifications.
+PostgreSQL's `LISTEN` / `NOTIFY` is used to pub/sub event notifications.
 
 A single listener process will connect to the database to listen for events when using a distributed cluster. Events will be broadcast to all connected nodes using Erlang's [pg2](http://erlang.org/doc/man/pg2.html) process groups. This limits the number of database connections to at most the number of running clusters.
 
@@ -73,7 +73,7 @@ Please refer to the [`libcluster` documentation](https://hexdocs.pm/libcluster/)
       $ MIX_ENV=distributed iex --name node3@127.0.0.1 -S mix
       ```
 
-The cluster will be automatically formed as soon as the nodes start.     
+The cluster will be automatically formed as soon as the nodes start.
 
 ## Static cluster topology and formation
 

guides/Getting Started.md

@@ -44,10 +44,10 @@ $ mix event_store.init
 
 ## Reset an existing database
 
-To drop an existing EventStore database and recreate it you can run the `mix` task:
+To drop an existing EventStore database and recreate it you can run the following `mix` tasks:
 
 ```console
-$ mix event_store.reset
+$ mix do event_store.drop, event_store.create, event_store.init
 ```
 
 *Warning* this will delete all EventStore data.

guides/Subscriptions.md

@@ -10,17 +10,17 @@ Subscriptions must be uniquely named and support a single subscriber. Attempting
 
 ## Event pub/sub
 
-PostgreSQL's `LISTEN` and `NOTIFY` commands are used to pub/sub event notifications from the database. An after update trigger on the `event_counter` table is used to execute `NOTIFY` for each batch of inserted events. The notification payload contains the first and last event number (e.g. `1,5`).
+PostgreSQL's `LISTEN` and `NOTIFY` commands are used to pub/sub event notifications from the database. An after update trigger on the `streams` table is used to execute `NOTIFY` for each batch of inserted events. The notification payload contains the stream uuid, stream id, and first / last stream versions (e.g. `stream-12345,1,1,5`).
 
 A single listener process will connect to the database to listen for these notifications. It fetches the event data and broadcasts to all interested subscriptions. This approach supports running the EventStore on multiple nodes, regardless of whether they are connected together to form a cluster. A single listener will be used when nodes form a cluster, otherwise one connection per node is used.
 
 ## Subscription start from
 
 By default subscriptions are created from the stream origin; they will receive all events from the stream. You can optionally specify a given start position:
 
-- `:origin` - subscribe to events from the start of the stream (identical to using 0). This is the current behaviour and will remain the default.
+- `:origin` - subscribe to events from the start of the stream (identical to using `0`). This is the default behaviour.
 - `:current` - subscribe to events from the current version.
-- `stream_version` or `event_number` (integer) - specify an exact stream version to subscribe from for a single stream subscription. You provide an event id for an all stream subscription.
+- `event_number` (integer) - specify an exact event number to subscribe from. This will be the same as the stream version for single stream subscriptions.
 
 ## Ack received events
 
@@ -85,9 +85,9 @@ The supported options are:
 
   - `:origin` - Start receiving events from the beginning of the stream or all streams.
   - `:current` - Subscribe to newly appended events only, skipping already persisted events.
-  - `event_number` or `stream_version` - Provide the event id (all streams) of stream version (single stream) to begin receiving events from.
+  - `event_number` (integer) - Specify an exact event number to subscribe from. This will be the same as the stream version for single stream subscriptions.
 
-Example all stream subscription that will receive events appended after the subscription has been created:
+Example all stream subscription that will receive new events appended after the subscription has been created:
 
 ```elixir
 {:ok, subscription} = EventStore.subscribe_to_all_streams("example_subscription", self(), start_from: :current)

guides/Usage.md

@@ -97,3 +97,27 @@ all_events = EventStore.stream_all_forward() |> Enum.to_list()
 ```
 
 This will read *all* events into memory, it is for illustration only. Use the `Stream` functions to process the events in a memory efficient way.
+
+## Linking events between streams
+
+Event linking allows you to include events in multiple streams, such as copying an event from one stream to another, but only a reference to the original event is stored.
+
+An event may be present in a stream only once, but may be linked into as many streams as required.
+
+Linked events are used to build the `$all` stream containing every persisted event, globally ordered.
+
+Use each recorded event's `event_number` field for the position of the event within the read/received stream. The `stream_uuid` and `stream_version` fields refer to the event's original stream.
+
+Read source events:
+
+```elixir
+{:ok, events} = EventStore.read_stream_forward(source_stream_uuid)
+```
+
+Link read events to another stream:
+
+```elixir
+:ok = EventStore.link_to_stream(target_stream_uuid, 0, events)
+```
+
+You can also pass a list of `event_ids` instead of recorded event structs to link events.