Move database spec details to end of walkthrough

Author: seancorfield

articles/ecosystem/java_jdbc/home.md

@@ -60,7 +60,7 @@ more popular options are:
 ### Setting up a data source
 
 A "database spec" is a Clojure map that specifies how to access the data
-source. Most commonly, you specify the database type, the the database name,
+source. Most commonly, you specify the database type, the database name,
 and the username and password. For example,
 
 ```clojure
@@ -71,71 +71,8 @@ and the username and password. For example,
    :password "secret"})
 ```
 
-Some DBs require a different format for the "database spec". Here is an example
-that was required for an in-memory [H2 database](http://www.h2database.com) prior
-to `java.jdbc` release 0.7.6:
-
-```clojure
-(def db-spec
-  {:classname   "org.h2.Driver"
-   :subprotocol "h2:mem"                  ; the prefix `jdbc:` is added automatically
-   :subname     "demo;DB_CLOSE_DELAY=-1"  ; `;DB_CLOSE_DELAY=-1` very important!!!
-                    ; http://www.h2database.com/html/features.html#in_memory_databases
-   :user        "sa"                      ; default "system admin" user
-   :password    ""                        ; default password => empty string
-  })
-```
-
-Note that file-based H2 databases have been supported directly via the simple
-"database spec" for a long time:
-
-```clojure
-(def db-spec
-  {:dbtype "h2"
-   :dbname "/path/to/my/database"})
-```
-
-As of `java.jdbc` 0.7.6, the in-memory version is supported directly:
-
-```clojure
-(def db-spec
-  {:dbtype "h2:mem"
-   :dbname "mydb"})
-```
-
-Out of the box, `java.jdbc` understands the following `:dbtype` values (with
-their default class names):
-
-* `"derby"` - `org.apache.derby.jdbc.EmbeddedDriver`
-* `"h2"` - `org.h2.Driver`
-* `"h2:mem"` - `org.h2.Driver`
-* `"hsqldb"` or `"hsql"` - `org.hsqldb.jdbcDriver`
-* `"jtds:sqlserver"` or `"jtds"` - `net.sourceforge.jtds.jdbc.Driver`
-* `"mysql"` - `com.mysql.jdbc.Driver`
-* `"oracle:oci"` - `oracle.jdbc.OracleDriver`
-* `"oracle:thin"` or `"oracle"` - `oracle.jdbc.OracleDriver`
-* `"postgresql"` or `"postgres"` - `org.postgresql.Driver`
-* `"pgsql"` - `com.impossibl.postgres.jdbc.PGDriver`
-* `"redshift"` - `com.amazon.redshift.jdbc.Driver`
-* `"sqlite"` - `org.sqlite.JDBC`
-* `"sqlserver"` - `"mssql"` - `com.microsoft.sqlserver.jdbc.SQLServerDriver`
-
-You must specify the appropriate JDBC driver dependency in your project -- these
-drivers are not included with `java.jdbc`.
-
-You can overide the default class name by specifying `:classname` as well as
-`:dbtype`.
-
-For databases that require a hostname or IP address, `java.jdbc` assumes
-`"127.0.0.1"` but that can be overidden with the `:host` option.
-
-For databases that require a port, `java.jdbc` has the following defaults,
-which can be overridden with the `:port` option:
-
-* Microsoft SQL Server - 1433
-* MySQL - 3306
-* Oracle - 1521
-* PostgreSQL - 5432
+See [**Database Support**][#database-support] below for a complete list of
+databases and drivers supported by `java.jdbc` out of the box.
 
 ### A "Hello World" Query
 
@@ -249,7 +186,79 @@ Ensure you tear down your tables and indexes in the opposite order of creation:
 
 These are all the commands we need to write a simple migration for our database!
 
-## More detailed java.jdbc documentation
+## Database Support
+
+Out of the box, `java.jdbc` understands the following `:dbtype` values (with
+their default class names):
+
+* `"derby"` - `org.apache.derby.jdbc.EmbeddedDriver`
+* `"h2"` - `org.h2.Driver`
+* `"h2:mem"` - `org.h2.Driver`
+* `"hsqldb"` or `"hsql"` - `org.hsqldb.jdbcDriver`
+* `"jtds:sqlserver"` or `"jtds"` - `net.sourceforge.jtds.jdbc.Driver`
+* `"mysql"` - `com.mysql.jdbc.Driver`
+* `"oracle:oci"` - `oracle.jdbc.OracleDriver`
+* `"oracle:thin"` or `"oracle"` - `oracle.jdbc.OracleDriver`
+* `"postgresql"` or `"postgres"` - `org.postgresql.Driver`
+* `"pgsql"` - `com.impossibl.postgres.jdbc.PGDriver`
+* `"redshift"` - `com.amazon.redshift.jdbc.Driver`
+* `"sqlite"` - `org.sqlite.JDBC`
+* `"sqlserver"` - `"mssql"` - `com.microsoft.sqlserver.jdbc.SQLServerDriver`
+
+You must specify the appropriate JDBC driver dependency in your project -- these
+drivers are not included with `java.jdbc`.
+
+You can overide the default class name by specifying `:classname` as well as
+`:dbtype`.
+
+For databases that require a hostname or IP address, `java.jdbc` assumes
+`"127.0.0.1"` but that can be overidden with the `:host` option.
+
+For databases that require a port, `java.jdbc` has the following defaults,
+which can be overridden with the `:port` option:
+
+* Microsoft SQL Server - 1433
+* MySQL - 3306
+* Oracle - 1521
+* PostgreSQL - 5432
+
+Some databases require a different format for the "database spec". Here is an example
+that was required for an in-memory [H2 database](http://www.h2database.com) prior
+to `java.jdbc` release 0.7.6:
+
+```clojure
+(def db-spec
+  {:classname   "org.h2.Driver"
+   :subprotocol "h2:mem"                  ; the prefix `jdbc:` is added automatically
+   :subname     "demo;DB_CLOSE_DELAY=-1"  ; `;DB_CLOSE_DELAY=-1` very important!!!
+                    ; http://www.h2database.com/html/features.html#in_memory_databases
+   :user        "sa"                      ; default "system admin" user
+   :password    ""                        ; default password => empty string
+  })
+```
+
+This is the most general form of database spec, that allows you to control each
+piece of the JDBC connection URL that would be created.
+
+Note: as of `java.jdbc` 0.7.6, in-memory H2 databases are supported directly
+via the simple spec form:
+
+```clojure
+(def db-spec
+  {:dbtype "h2:mem"
+   :dbname "mydb"})
+```
+
+For file-based databases, such as H2, Derby, SQLite etc, the `:dbname` will
+specify the filename:
+
+```clojure
+(def db-spec
+  {:dbtype "h2"
+   :dbname "/path/to/my/database"})
+```
+
+## More detailed `java.jdbc` documentation
 
 * [Using SQL:][using-sql] a more detailed guide on using SQL with `java.jdbc`
 * [Using DDL:][using-ddl] how to create your tables using the `java.jdbc` DDL