diff --git a/doc/source/admin/drivers/sql.rst b/doc/source/admin/drivers/sql.rst
index 17bfa8d67a..4c4a729590 100644
--- a/doc/source/admin/drivers/sql.rst
+++ b/doc/source/admin/drivers/sql.rst
@@ -4,14 +4,29 @@ SQL
 ===
 
 The SQL driver supports reporters only.  Only one connection per
-database is permitted.  The connection options are:
+database is permitted.
 
-**driver=sql**
+Connection Configuration
+------------------------
 
-**dburi**
-  Database connection information in the form of a URI understood by
-  sqlalchemy. eg http://docs.sqlalchemy.org/en/rel_1_0/core/engines.html#database-urls
-  ``dburi=mysql://user:pass@localhost/db``
+The connection options for the SQL driver are:
+
+.. attr:: <sql connection>
+
+   .. attr:: driver
+      :required:
+
+      .. value:: sql
+
+         The connection must set ``driver=sql`` for SQL connections.
+
+   .. attr:: dburi
+      :required:
+
+      Database connection information in the form of a URI understood
+      by SQLAlchemy.  See `The SQLAlchemy manual
+      <http://docs.sqlalchemy.org/en/rel_1_0/core/engines.html#database-urls>`_
+      for more information.
 
 Reporter Configuration
 ----------------------
@@ -21,9 +36,26 @@ This reporter is used to store results in a database.
 A :ref:`connection<connections>` that uses the sql driver must be
 supplied to the reporter.
 
-zuul.conf contains the database connection and credentials. To store different
-reports in different databases you'll need to create a new connection per
-database.
+``zuul.conf`` contains the database connection and credentials. To
+store different reports in different databases you'll need to create a
+new connection per database.
 
-The SQL reporter does nothing on "start" or "merge-failure"; it only
-acts on "success" or "failure" reporting stages.
+The SQL reporter does nothing on :attr:`pipeline.start` or
+:attr:`pipeline.merge-failure`; it only acts on
+:attr:`pipeline.success` or :attr:`pipeline.failure` reporting stages.
+
+For example:
+
+.. code-block:: yaml
+
+   - pipeline:
+       name: post-merge
+       success:
+         mydb_conn: {}
+       failure:
+         mydb_conn: {}
+
+.. attr:: pipeline.<reporter>.<sql source>
+
+   To report to a database, add an empty dictionary to the desired
+   pipeline :ref:`reporter<reporters>` attributes.