Fork me on GitHub
#honeysql
<
2021-03-02
>
borkdude10:03:24

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?

3
seancorfield17:03:30

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.

seancorfield17:03:23

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).

iarenaza15:03:41

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!)

iarenaza15:03:49

Looking forward to migrating to v2, as some rough edges of 1.x have been polished quite a bit!

seancorfield17:03:33

Thanks, I hope the new SQL Clause Reference docs in v2 solve the "exact shape of the data structures" issue?

seancorfield17:03:00

(as for moving the helpers into honey.sql -- definitely not, at this point)

borkdude18:03:35

@seancorfield I was using insert-into since I didn't know how to do this using data structures

borkdude18:03:50

There were no examples I could find on this

borkdude18:03:53

@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)

borkdude18:03:17

if :insert-into is preferred, maybe the main README should suggest this instead?

borkdude18:03:24

I had no idea it existed

seancorfield18:03:25

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.

seancorfield18:03:27

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).

seancorfield18:03:28

(this is good feedback esp. since you're a new-to-HoneySQL user, right?)

borkdude18:03:27

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)

seancorfield18:03:09

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.