> Parallel (and conjoined) API docs would solve ALL my (admittedly shallow) problems, actually, but I wonder if it would remove some confusion for others new to the lib and Clojure?
Definitely. I have only just started using Clojure and the java.jdbc library and have found this a (minor) pain point in an otherwise excellent library. On Sun, Nov 24, 2013 at 3:27 PM, Keith Irwin <ke...@devtrope.com> wrote: > Sean— > > Personally, the DSL doesn’t bother me at all. (Just a data point.) I get > where you’re going with it, and support the idea, FWIW, but if it were > gone, I wouldn’t notice. My needs are 1) so simple, strings work, or 2) so > complicated, a (or any) DSL is just extra headache. (Reading them out of a > separately maintained data file, for instance, is one way to go.) > > BUT: > > The mixture of the old API and the new API is problematic, mainly because > it’s difficult for me (anyway) to look down the list of functions and > figure out which are old and which are new. > > I understand the need to maintain the old API, and I’m not arguing against > that at all. > > Might you be able to publish a parallel version of the API *documentation* > with all the deprecated stuff removed for those folks new to the library > who are uninterested in the old API? Even users of the old API might > appreciate it for the same reasons. > > Parallel (and conjoined) API docs would solve ALL my (admittedly shallow) > problems, actually, but I wonder if it would remove some confusion for > others new to the lib and Clojure? > > On Nov 20, 2013, at 2:25 PM, Sean Corfield <seancorfi...@gmail.com> wrote: > > > Thank you both - that's excellent feedback! > > > > I certainly don't want the library to cause confusion so maybe > > hiding/removing the DSLs would be the best path going forward. > > > > Right now, a handful of the DSL functions are used to generate the SQL > > behind delete!, insert! and update! as well as the core implementation > > of the naming strategy stuff. We're also using a few of them in > > production code at World Singles but it would be easy enough to back > > off that and switch to HoneySQL (which we use extensively elsewhere). > > > > I totally agree about the API being too broad. I'd like to just drop > > the old API completely but experience with APIs changing in contrib > > libraries has shown that backward compatibility needs to be maintained > > for at least a version or two so folks can migrate off the old API. I > > was planning to streamline the API - dropping the old API that relied > > on the dynamic *db* variable - in 0.5.0 but maybe I'll make that the > > focus of 0.4.0 instead. > > > > The feedback on the DSLs - ever since my first proposal to add them - > > seems to be overwhelmingly negative so at this point I'm now > > considering removing them from 0.3.0 rather than perpetuate the > > confusion. > > > > Is anyone using the java.jdbc.sql namespace? (besides World Singles :) > > > > Sean > > > > > > > > On Wed, Nov 20, 2013 at 3:52 AM, Alice <dofflt...@gmail.com> wrote: > >> I agree with Colin and had a similar experience. > >> > >> Even if you say it's completely optional, people will first try it > because > >> it's already included. I think honeysql is good and also not any harder > to > >> use than the included DSL. It's concept is very simple and clear. > Actually, > >> your DSL is magical because it's based on macro. > >> > >> For example, I asked about specifying the default name mapping functions > >> before* and it was not the first time. I had to see the source code to > >> understand why it's not possible. I was only the second but I bet you'll > >> keep hearing this kind of questions over and over again. If you keep the > >> jdbc and DSL in the same library, it becomes confusing to users why some > >> things are not possible. > >> > >> And I don't see any problem with separating it into another library. > It's > >> just one additional line in project.clj. > >> > >> * > >> > https://groups.google.com/forum/#!searchin/clojure/jdbc/clojure/iOBs_VC09FM/8aUF2xzz7scJ > >> > >> > >> On Wednesday, November 20, 2013 6:41:33 PM UTC+9, Colin Yates wrote: > >>> > >>> Hi Sean, > >>> > >>> First - I hugely appreciate the work you have done and use java.jdbc > >>> daily. > >>> > >>> However, as a complete newbie I found the included DSL very unhelpful. > >>> The java.jdbc API is very wide and navigating it was hard, > Particularly as > >>> it was in a transition from using bound *db* to not, so effectively > there > >>> seemed two APIs. > >>> > >>> I started using the DSL and it didn't meet the expectation I think > anybody > >>> would have for a DSL in that it wasn't complete or expressive enough. > There > >>> were moments where the combined experience was very very negative and > not > >>> representative of the quality of the work you have put in. > >>> > >>> It also made it unclear what the library was supposed to do > (regardless of > >>> what the documentation says :)). > >>> > >>> Treating java.jdbc without the DSL and the DSL as separate projects (I > >>> realise they are separate namespaces already) would be a much stronger > >>> statement of intent I think. > >>> > >>> To put it another way, at the moment the risk is to interpret > java.jdbc as > >>> a DSL on top of JDBC with some low level utilities around managing > >>> connections. That clearly isn't true and the project comes off > looking very > >>> poor. > >>> > >>> Please hear me - I write this only because I think my experience will > be > >>> very similar to a lot of other people's experiences when they start > adopting > >>> the library whilst picking up Clojure at the same time! > >>> > >>> For me, the combination of honeysql and java.jdbc is close to perfect, > but > >>> my point again is that I came very close many times to throwing > java.jdbc > >>> out because of the experience of a very wide API which was effectively > two > >>> APIs and a DSL which didn't meet a reasonable definition of a full > 'DSL' > >>> (even if the documentation states it is minimal). Moving the DSL into > a > >>> separate project makes things much simpler. > >>> > >>> Just my 2 pennies from a very grateful user who wants to avoid other > >>> people missing the point. > >>> > >>> Col > >>> > >>> On Wednesday, November 20, 2013 3:05:34 AM UTC, Sean Corfield wrote: > >>>> > >>>> In response to the (very reasonable) question from Alex Hudek in a > >>>> recent thread, here are some of my responses to questions that have > >>>> arisen about the inclusion of the minimal DSLs in the java.jdbc > >>>> contrib library: > >>>> > >>>>> Just wondering if the intention is to make the DSL the primary way to > >>>>> work > >>>>> with the API or if clojure.java.jdbc.sql will be completely optional? > >>>> > >>>> Completely optional. > >>>> > >>>> The idea is just to provide some (optional) sugar for common > >>>> operations. I have no intention of going particularly deep on the DSL. > >>>> > >>>> If folks want a full DSL for SQL in Clojure, I'd suggest > >>>> https://github.com/jkk/honeysql or http://sqlkorma.com - the former > is > >>>> a DSL to generate SQL that is compatible with clojure.java.jdbc, the > >>>> latter is a DSL that wraps clojure.java.jdbc. > >>>> > >>>>> Using the latest release of java.jdbc, does anybody know how I can > >>>>> construct a where clause when I want to check if the value is one of > >>>>> many values? > >>>> > >>>> clojure.java.jdbc.sql is a deliberately minimal DSL - Justin Kramer's > >>>> HoneySQL is what I recommend for more expressive SQL construction > >>>> (that's the "official" recommendation based on discussions Justin and > >>>> I had about java.jdbc and HoneySQL at Clojure/conj 2012). > >>>> > >>>>> I want to generate sql string using clojure.java.jdbc.sql for eg. > >>>>> > >>>>> "SELECT B.ID , B.TITLE ,B.AUTHOR , C.CATEGORY , S.STATUS > >>>>> FROM BOOK B ,CATEGORY C , STATUS S > >>>>> WHERE (B.CATEGORY_ID=C.ID) AND > >>>>> (B.STATUS_ID = B.ID) AND > >>>>> (B.TITLE LIKE "%TOM%")" > >>>>> > >>>>> How to do this using clojure.java.jdbc.sql dsl functions? > >>>> > >>>> The basic DSL cannot do 'like' so you probably want to look at > >>>> HoneySQL which is the recommended way to extend clojure.java.jdbc. > >>>> > >>>> === > >>>> > >>>> The justification for the DSL at all is that it provides some sugar > >>>> for simple, common usage and also provides a template for other more > >>>> expansive DSLs that the community might write, by showing what the > >>>> primary API expects in terms of SQL strings and parameter vectors. > >>>> > >>>> At World Singles, we use the basic DSL to support a lot of "CRUD" > >>>> operations that are doing simple lookups, basic joins, and so on - and > >>>> we rely on HoneySQL for our reporting queries and anything that is > >>>> substantially more complex than the basic DSL offers. > >>>> > >>>> Will the DSL be expanded to support some additional common SQL > >>>> operations? > >>>> > >>>> Perhaps, based on user feedback - assuming people want something > >>>> between raw strings and the sophistication of HoneySQL (or any other > >>>> DSL that the community may produce). > >>>> -- > >>>> Sean A Corfield -- (904) 302-SEAN > >>>> An Architect's View -- http://corfield.org/ > >>>> World Singles, LLC. -- http://worldsingles.com/ > >>>> > >>>> "Perfection is the enemy of the good." > >>>> -- Gustave Flaubert, French realist novelist (1821-1880) > >> > >> -- > >> -- > >> You received this message because you are subscribed to the Google > >> Groups "Clojure" group. > >> To post to this group, send email to clojure@googlegroups.com > >> Note that posts from new members are moderated - please be patient with > your > >> first post. > >> To unsubscribe from this group, send email to > >> clojure+unsubscr...@googlegroups.com > >> For more options, visit this group at > >> http://groups.google.com/group/clojure?hl=en > >> --- > >> You received this message because you are subscribed to the Google > Groups > >> "Clojure" group. > >> To unsubscribe from this group and stop receiving emails from it, send > an > >> email to clojure+unsubscr...@googlegroups.com. > >> For more options, visit https://groups.google.com/groups/opt_out. > > > > > > > > -- > > Sean A Corfield -- (904) 302-SEAN > > An Architect's View -- http://corfield.org/ > > World Singles, LLC. -- http://worldsingles.com/ > > > > "Perfection is the enemy of the good." > > -- Gustave Flaubert, French realist novelist (1821-1880) > > > > -- > > -- > > You received this message because you are subscribed to the Google > > Groups "Clojure" group. > > To post to this group, send email to clojure@googlegroups.com > > Note that posts from new members are moderated - please be patient with > your first post. > > To unsubscribe from this group, send email to > > clojure+unsubscr...@googlegroups.com > > For more options, visit this group at > > http://groups.google.com/group/clojure?hl=en > > --- > > You received this message because you are subscribed to the Google > Groups "Clojure" group. > > To unsubscribe from this group and stop receiving emails from it, send > an email to clojure+unsubscr...@googlegroups.com. > > For more options, visit https://groups.google.com/groups/opt_out. > > -- > -- > You received this message because you are subscribed to the Google > Groups "Clojure" group. > To post to this group, send email to clojure@googlegroups.com > Note that posts from new members are moderated - please be patient with > your first post. > To unsubscribe from this group, send email to > clojure+unsubscr...@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en > --- > You received this message because you are subscribed to the Google Groups > "Clojure" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to clojure+unsubscr...@googlegroups.com. > For more options, visit https://groups.google.com/groups/opt_out. > -- -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
