diff --git a/x-pack/docs/en/sql/endpoints/jdbc.asciidoc b/x-pack/docs/en/sql/endpoints/jdbc.asciidoc
index 9ac197048dd..067a4c586fb 100644
--- a/x-pack/docs/en/sql/endpoints/jdbc.asciidoc
+++ b/x-pack/docs/en/sql/endpoints/jdbc.asciidoc
@@ -6,10 +6,133 @@ Elasticsearch's SQL jdbc driver is a rich, fully featured JDBC driver for Elasti
 It is Type 4 driver, meaning it is a platform independent, stand-alone, Direct to Database,
 pure Java driver that converts JDBC calls to Elasticsearch SQL.
 
-// TODO add example of resolving the artifact in maven and gradle.
+[float]
+=== Installation
 
-You can connect to it using the two APIs offered
-by JDBC, namely `java.sql.Driver` and `DriverManager`:
+The JDBC driver can be obtained either by downloading it from the https://www.elastic.co/downloads/jdbc-client[elastic.co] site or by using a http://maven.apache.org/[Maven]-compatible tool with the following dependency:
+
+["source","xml",subs="attributes"]
+----
+<dependency>
+  <groupId>org.elasticsearch.plugin.jdbc</groupId>
+  <artifactId>jdbc</artifactId>
+  <version>{ver}</version>
+</dependency>
+----
+
+from `artifacts.elastic.co/maven` by adding it to the repositories list:
+
+["source","xml",subs="attributes"]
+----
+<repositories>
+  <repository>
+    <id>elastic.co</id>
+    <url>https://artifacts.elastic.co/maven</url>
+  </repository>
+</repositories>
+----
+
+[[jdbc-setup]]
+[float]
+=== Setup
+
+The driver main class is `org.elasticsearch.xpack.sql.jdbc.jdbc.JdbcDriver`. Note the driver 
+also implements the JDBC 4.0 +Service Provider+ mechanism meaning it is registerd automatically
+as long as its available in the classpath.
+
+Once registered, the driver expects the following syntax as an URL:
+
+["source","text",subs="attributes"]
+----
+jdbc:es://<1>[http|https]?<2>[host[:port]]*<3>/[prefix]*<4>[?[option=value]&<5>]*
+----
+
+<1> `jdbc:es://` prefix. Mandatory.
+<2> type of HTTP connection to make - `http` (default) or `https`. Optional.
+<3> host (`localhost` by default) and port (`9200` by default). Optional.
+<4> prefix (empty by default). Typically used when hosting {es} under a certain path. Optional.
+<5> Parameters for the JDBC driver. Empty by default. Optional.
+
+The driver recognized the following parameters:
+
+[[jdbc-cfg]]
+[float]
+===== Essential
+
+`timezone` (default JVM timezone)::
+Timezone used by the driver _per connection_ indicated by its `ID`. 
+*Highly* recommended to set it (to, say, `UTC`) as the JVM timezone can vary, is global for the entire JVM and can't be changed easily when running under a security manager.
+
+[[jdbc-cfg-network]]
+[float]
+===== Network
+
+`connect.timeout` (default 30s)::
+Connection timeout (in seconds). That is the maximum amount of time waiting to make a connection to the server.
+
+`network.timeout` (default 60s)::
+Network timeout (in seconds). That is the maximum amount of time waiting for the network.
+
+`page.timeout` (default 45s)::
+Page timeout (in seconds). That is the maximum amount of time waiting for a page.
+
+`page.size` (default 1000)::
+Page size (in entries). The number of results returned per page by the server.
+
+`query.timeout` (default 90s)::
+Query timeout (in seconds). That is the maximum amount of time waiting for a query to return.
+
+[[jdbc-cfg-auth]]
+[float]
+==== Basic Authentication
+
+`user`:: Basic Authentication user name
+
+`password`:: Basic Authentication password
+
+[[jdbc-cfg-ssl]]
+[float]
+==== SSL
+
+`ssl` (default false):: Enable SSL
+
+`ssl.keystore.location`:: key store (if used) location
+
+`ssl.keystore.pass`:: key store password
+
+`ssl.keystore.type` (default `JKS`):: key store type. `PKCS12` is a common, alternative format
+
+`ssl.truststore.location`:: trust store location
+
+`ssl.truststore.pass`:: trust store password
+
+`ssl.cert.allow.self.signed` (default `false`):: Whether or not to allow self signed certificates
+
+`ssl.protocol`(default `TLS`):: SSL protocol to be used
+
+[float]
+==== Proxy
+
+`proxy.http`:: Http proxy host name
+
+`proxy.socks`:: SOCKS proxy host name
+
+
+To put all of it together, the following URL:
+
+["source","text",subs="attributes"]
+----
+jdbc:es://http://server:3456/timezone=UTC&page.size=250
+----
+
+Opens up a {es-jdbc} connection to `server` on port `3456`, setting the JDBC timezone to `UTC` and its pagesize to `250` entries.
+
+=== API usage
+
+One can use JDBC through the official `java.sql` and `javax.sql` packages:
+
+==== `java.sql`
+The former through `java.sql.Driver` and `DriverManager`:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
@@ -20,7 +143,9 @@ HTTP traffic. The port is by default 9200.
 <2> Properties for connecting to Elasticsearch. An empty `Properties`
 instance is fine for unsecured Elasticsearch.
 
-or `javax.sql.DataSource` through
+==== `javax.sql`
+
+Accessible through the `javax.sql.DataSource` API:
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{jdbc-tests}/JdbcIntegrationTestCase.java[connect-ds]