I've updated the Getting Started page in the docs (on master) to convert the explicit Component example over to the new component function, showing that you don't need to create a record with start/`stop` methods.

Spec for opts, e.g. in get-connection can be nilable, with nil it works just fine. Isn't map? too restrictive? It forces me to do (or opts {}) just to be able to use instrumentation. (This may be question for clojure-spec channel though)

@nikolavojicic Can you be a bit more specific about what you're asking? Which library? Which spec? Which file/line?

Both clojure.java.jdbc and next.jdbc provide their own specs and both have :opts as an optional parameter for get-connection:

;; clojure.java.jdbc/get-connection:
(s/fdef sql/get-connection
        :args (s/cat :db-spec ::db-spec
                     :opts    (s/? ::connection-options))
        :ret  ::connection)
;; next.jdbc/get-connection:
(s/fdef jdbc/get-connection
        :args (s/cat :spec ::db-spec
                     :opts (s/? ::opts-map)))

If you are using those libraries, you should be using their specs.

I'm using next.jdbc. My question is would it be ok to change get-connection spec to accept nil opts, i.e: :opts (s/? (s/nilable ::opts-map)) ? Use case is when opts for connection is taken from another map, and it may be absent -> nil. With nil opts, get-connection works the same as with {} opts.

Ofc I can override it for my project so it's not a big deal.

@nikolavojicic Sorry for the delay. I'm on vacation today so I'm away from my computer quite a bit. I really don't like optional parameters that can also be nil or the intended value, which is why the specs are as they are. I understand that nil "works" in place of opts in some (all?) API functions in next.jdbc (and clojure.java.jdbc) but that's just an artifact of the implementation and not something I'm prepared to support as an official part of the API -- so the specs will remain stricter than the implementation here. Since you are fetching your options from another map, you can supply a "not found" value of {} at the point of access: (:jdbc-opts my-map {}) or (get my-map :jdbc-opts {}) and then the intent is clear.

(and if that key in your map can be nil then I'd say you have an upstream problem: finding nil values in a Clojure hash map is a code/design smell as far as I'm concerned -- except in very specific cases where nil has a specific semantic meaning and you need to distinguish between contains? and an actual nil value)