HoneySQL -- What do you want from 2.0?

Showcase Your Projects and Libraries
11

I wanted to give everyone an update on HoneySQL 2.0 since I have been working on it quite a bit this past week. Here are some high-level notes about the status, based on issues raised in this thread – with more detailed notes following below:

  • When a release is cut, it will be seancorfield/honeysql "2.0.0-alpha1" so that we don’t perpetuate the unqualified lib name – see the last section of https://insideclojure.org/2020/07/28/clj-exec/ for a bit more background on that whole issue.
  • The new version will contain only honey.sql and honey.sql.helpers so it will not conflict with 1.0 and you’ll be able to use both versions side-by-side as you migrate piecemeal.
  • Documentation will be written for the data DSL and the helpers with lots of examples – and differences between 1.0 and 2.0.
  • There will be a :pretty? true formatting mode that inserts newlines to make the SQL readable.
  • Invoking functions will be a lot easier and a lot more consistent.
  • Inline/raw/etc are all going to be “just functions” (technically “just special syntax” – see below) and strings will be SQLized properly, i.e., [:inline "foo"] produces 'foo' in the SQL “as expected” :slight_smile:
  • The helpers will all have docstrings to explain their behavior (although they will still be variadic since they are intended for people to write – for programs, generate the data DSL directly) – and they’ll be documented, as will the data DSL (see above comment about documentation!).
  • Anywhere that a keyword is accepted and treated as “something special” (table, column, function, operator, etc) you will be able to use a symbol instead if you want.
  • The whole tagged literal thing will go away and so will the types and the call syntax.
  • It will support vendor dialects with the default being an extensive ANSI/PostgreSQL blend – it will support everything that you currently need nilenso/honeysql-postgres for and as much of the PostgreSQL syntax beyond that as I can reasonably include. There will also be a MySQL dialect (and the beginnings of SQL Server and Oracle – which will evolve over time).
  • The extension mechanism will be through a few register-*! functions to add new clauses, new operators, and new “syntax” (essentially new function-like things).
  • You will be able to set a default dialect at app startup and then override it per-call (to format).

I mentioned (back in August, in this thread) that things like date_sub( col, interval n hour ) were hard to write in 1.0. In 2.0, that’s [:date_sub :col [:interval 24 :hour]] or '[date_sub col [interval 24 hour]] if you prefer to use quoted symbols like Datalog syntax. You can also use lists if you want: '(date_sub col (interval 24 hour)) – things like interval are implemented via the “special syntax” machinery, which are function-like expressions that can generate arbitrary SQL from their arguments, e.g., cast, inline, raw.

The %func.arg syntax will still be valid (apparently enough people use this that forcing them to write [:func arg] would be unpopular) but it won’t be enhanced with SQLization etc.

The current status is:

  • There’s a v2 branch with this work-in-progress code on it and the start of documentation (right now that’s just a “differences” file, for the most part).
  • Nearly all of the 1.0 formatting tests pass with the 2.0 code – with a few specific changes around sql/call, sql/inline, and sql/raw etc.
  • None of the parameterizer stuff is implemented yet but I have a plan and that will be the next piece of work (specifically named parameters will be the very next piece of work I do).
  • It already supports PostgreSQL’s upsert features via ON CONFLICT / DO UPDATE SET / DO NOTHING etc with other PG-specific stuff “coming soon”.

You can track progress via the 2.0 milestone. Feel free to add comments on any of the open issues there (or create new issues if you think something is missing).

16 Likes