CLICKHOUSE-3878: Add some comments and small readme

dbms/programs/odbc-bridge/HandlerFactory.h

@@ -13,6 +13,9 @@
 
 namespace DB
 {
+/** Factory for '/ping' and '/' handlers.
+  * Also stores Session pools for ODBC connections
+  */
 class HandlerFactory : public Poco::Net::HTTPRequestHandlerFactory
 {
 public:

dbms/programs/odbc-bridge/Handlers.h

@@ -11,6 +11,11 @@
 
 namespace DB
 {
+/** Main handler for requests to ODBC driver
+  * requires connection_string and columns in request params
+  * and also query in request body
+  * response in RowBinary format
+  */
 class ODBCHandler : public Poco::Net::HTTPRequestHandler
 {
 public:
@@ -41,6 +46,8 @@ private:
     PoolPtr getPool(const std::string & connection_str);
 };
 
+/** Simple ping handler, answers "Ok." to GET request
+  */
 class PingHandler : public Poco::Net::HTTPRequestHandler
 {
 public:

dbms/programs/odbc-bridge/ODBCBridge.h

@@ -1,14 +1,18 @@
 #pragma once
 
-#include <daemon/BaseDaemon.h>
-#include <Poco/Logger.h>
 #include <Interpreters/Context.h>
+#include <Poco/Logger.h>
+#include <daemon/BaseDaemon.h>
 
 namespace DB
 {
+/** Class represents clickhouse-odbc-bridge server, which listen
+  * incoming HTTP POST and GET requests on specified port and host.
+  * Has two handlers '/' for all incoming POST requests to ODBC driver
+  * and /ping for GET request about service status
+  */
 class ODBCBridge : public BaseDaemon
 {
-
 public:
     void defineOptions(Poco::Util::OptionSet & options) override;
 
@@ -20,7 +24,6 @@ protected:
     int main(const std::vector<std::string> & args) override;
 
 private:
-
     void handleHelp(const std::string &, const std::string &);
 
     bool is_help;
@@ -35,5 +38,4 @@ private:
 
     std::shared_ptr<Context> context; /// need for settings only
 };
-
 }

dbms/programs/odbc-bridge/README.md

@@ -0,0 +1,38 @@
+# clickhouse-odbc-bridge
+
+Simple HTTP-server which works like a proxy for ODBC driver. The main motivation
+was possible segfaults or another faults in ODBC implementations, which can
+crash whole clickhouse-server process.
+
+This tool works via HTTP, not via pipes, shared memory, or TCP because:
+- It's simplier to implement
+- It's simplier to debug
+- jdbc-bridge can be implemented in the same way
+
+## Usage
+
+`clickhouse-server` use this tool inside odbc table function and StorageODBC.
+However it can be used as standalone tool from command line with the following
+parameters in POST-request URL:
+- `connection_string` -- ODBC connection string.
+- `columns` -- columns in ClickHouse NamesAndTypesList format, name in backticks,
+  type as string. Name and type are space separated, rows separated with
+  newline.
+- `max_block_size` -- optional parameter, sets maximum size of single block.
+Query is send in post body. Response is returned in RowBinary format.
+
+## Example:
+
+```bash
+$ clickhouse-odbc-bridge --http-port 9018 --daemon
+
+$ curl -d "query=SELECT PageID, ImpID, AdType FROM Keys ORDER BY PageID, ImpID" --data-urlencode "connection_string=DSN=ClickHouse;DATABASE=stat" --data-urlencode "columns=columns format version: 1
+3 columns:
+\`PageID\` String
+\`ImpID\` String
+\`AdType\` String
+"  "http://localhost:9018/" > result.txt
+
+$ cat result.txt
+12246623837185725195925621517
+```