From 6cd75cc31c9e051683533c04f587141635640039 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= <markus.makela@mariadb.com>
Date: Sat, 31 Mar 2018 14:34:20 +0300
Subject: [PATCH] MXS-1752: Add `cat` documentation

Added documentation for the `cat` router.
---
 Documentation/Documentation-Contents.md |  1 +
 Documentation/Routers/Cat.md            | 40 +++++++++++++++++++++++++
 2 files changed, 41 insertions(+)
 create mode 100644 Documentation/Routers/Cat.md

diff --git a/Documentation/Documentation-Contents.md b/Documentation/Documentation-Contents.md
index 4e5198a48..3aa05ffb7 100644
--- a/Documentation/Documentation-Contents.md
+++ b/Documentation/Documentation-Contents.md
@@ -66,6 +66,7 @@ of their use.
  - [Read Connection Router](Routers/ReadConnRoute.md)
  - [Read Write Split](Routers/ReadWriteSplit.md)
  - [Schemarouter](Routers/SchemaRouter.md)
+ - [Cat](Routers/Cat.md)
 
 There are also two diagnostic routing modules. The CLI is for MaxAdmin and
 the Debug CLI client for Telnet.
diff --git a/Documentation/Routers/Cat.md b/Documentation/Routers/Cat.md
new file mode 100644
index 000000000..0f2029e96
--- /dev/null
+++ b/Documentation/Routers/Cat.md
@@ -0,0 +1,40 @@
+# Cat
+
+The `cat` router is a special router that concatenates result sets.
+
+## Configuration
+
+The router has no special parameters. To use it, define a service with
+`router=cat` and add the servers you want to use.
+
+## Behavior
+
+The order the servers are defined in is the order in which the servers are
+queried. This means that the results are ordered based on the `servers`
+parameter of the service. The result will only be completed once all servers
+have executed this.
+
+All commands executed via this router will be executed on all servers. This
+means that an INSERT through the `cat` router will send it to all servers. As
+the intended use-case of the router is to mainly reduce multiple result sets
+into one, it has no mechanisms to prevent writes from being executed on slave
+servers (which would cause data corruption or replication failure). Take great
+care when performing administrative operations though this router.
+
+If a connection to one of the servers is lost, the client connection will also
+be closed.
+
+## Example
+
+Here is a simple example service definition that uses the servers from the
+[Configuring Servers](../Tutorials/Configuring-Servers.md) tutorial and the
+credentials from the [MaxScale Tutorial](../Tutorials/MaxScale-Tutorial.md).
+
+```
+[concat-service]
+type=service
+router=cat
+servers=dbserv1,dbserv2,dbserv3
+user=maxscale
+password=maxscale_pw
+```