Clojurians Log v2
honeysql
As a bit of user feedback:
It's been several times now that I've been reading the README and I have trouble resolving mentally where some vars are coming from due to the use of :refer :all. E.g. right now I'm searching where insert-into is coming from (again). Can the README maybe use an alias, or an explicit :refer [...]?
Or can all of these functions maybe be part of the honey.sql namespace?
The helpers have always traditionally been in a separate ns and that folks can either :refer specific ones or use an alias as they prefer. I think the DSL reads much more clearly with referred symbols than with using an alias. In v2 there are only two namespaces: honey.sql for working with the data structure and format'ing it, honey.sql.helpers with all the helper functions. In v2, honey.sql has one primary API: the format function, and you only care about the other public functions if you're extending HoneySQL.
I get the impression that only a minority of HoneySQL users rely on the helpers at all -- most folks seem to prefer to work with the data structures and just sql/format. I'm still working on the docs (the major piece of work blocking a "gold" release) and I'll definitely make a couple more passes over the readme. The readme already has [honey.sql.helpers :refer :all :as h] (v1 had :as helpers instead of :as h and used that alias in precisely one place, to disambiguate update).
One data point: we use the data structures, unless we need to resort to using sql/raw for certain Postgresql-specific constructs not supported in HoneySQL 1.x.
Sometimes we need to dig into the code a bit to find the exact shape of the data structures because the README mainly uses helpers (e.g., to do a multi-JOIN) but the code is extremely clear and helpful (thanks a lot for that!)
Looking forward to migrating to v2, as some rough edges of 1.x have been polished quite a bit!
Thanks, I hope the new SQL Clause Reference docs in v2 solve the "exact shape of the data structures" issue?
(as for moving the helpers into honey.sql -- definitely not, at this point)
@seancorfield I was using insert-into since I didn't know how to do this using data structures
There were no examples I could find on this
@seancorfield I'm referring to the main README where I ctrl-f-ed on insert which only comes up with examples with insert-into (from the namespace I had to guess)
if :insert-into is preferred, maybe the main README should suggest this instead?
I had no idea it existed
Everything has always been available as data structures. The helpers in v1 don't even cover all of the clauses. When I overhaul the README I will link more heavily to the reference doc sections.
I will also make the whole data structure vs helper DSL thing clearer (the v2 readme is still modeled after the v1 readme, for the most part).
Thanks!
(this is good feedback esp. since you're a new-to-HoneySQL user, right?)
yeah
I'm using it now from babashka mainly to poke at our work database, since this is faster than pgadmin which is annoyingly slow right now when connecting to a database in the US region (from Europe)
Feel free to add any and all readme/doc thoughts to https://github.com/seancorfield/honeysql/issues/307 so I don't lose track of any suggestions.