Scrap your query boilerplate with specql

SCRAP YOUR
QUERY
BOILERPLATE
WITH SPECQL
2.9.2017 ClojuTRE Tatu Tarvainen (@tatut)

WHAT IS SPECQL?
› The combination of clojure.spec, PostgreSQL and the power of
macros
clojure.spec PostgreSQL
λ

SOME BACKGROUND
› Yesql/Jeesql/Hugsql are all fine and specql does not try to ”solve”
SQL so that you don’t have to use it anymore
› When you have multiple slightly different queries, there’s
duplication or fetching too much
› Adding dynamic WHERE clauses leads to ugly NULL checking of
bound parameters

EXAMPLE
› SELECT it.foo, it.bar, it.baz
› FROM interesting_table it
› WHERE it.archived = FALSE
› AND it.organization = :user_org_id
› AND it.category IN (:categories)

EXAMPLE
How to make
variants without
duplication or
selecting too much?

EXAMPLE
How to
add/remove
clauses
dynamically?

EXAMPLE
› SELECT it.foo, it.bar, it.baz,
› o.name AS organization_name
› JOIN organization o ON it.organization_id = o.id

EXAMPLE
› SELECT it.foo, it.bar, it.baz,
› o.name AS organization_name
› JOIN organization o ON it.organization_id = o.id
How to cleanly add
these without code
duplication?

THE SPECQL WAY: DEFINE
› (define-tables db
› [”interesting_table” ::it/interesting
› {::it/organization (rel/has-one
› ::it/organization_id
› ::org/organization
› ::org/id)}])

› ::org/id)}])
The main macro
for defining things

› ::org/id)}])
The name of the
table in the
database

› ::org/id)}])
The namespaced
keyword for the
table

› ::org/id)}])
Additional
definitions for
columns

THE SPECQL WAY: FETCH
› (defn fetch-interesting [db org-id categories]
› (fetch db ::it/interesting
› #{::it/foo ::it/bar ::it/baz}
› {::it/archived false
› ::it/organization_id org-id
› ::it/category (op/in categories)}))

The table to fetch
from

Set of columns to
retrieve

The WHERE
clause map

THE SPECQL WAY: RESULT
› (fetch-interesting db 1 #{”stuff” ”things”})
› ;; => ({::it/foo 1
› ::it/bar ”example”
› ::it/baz true} …)
›

THE SPECQL WAY: JOIN
› #{::it/foo ::it/bar ::it/baz
› [::it/organization #{::org/id ::org/name}]}

› #{::it/foo ::it/bar ::it/baz
› [::it/organization #{::org/id ::org/name}]}
Nested column definition
for a JOINed tables

› ;; => ({::it/foo 1
› ::it/baz true
› ::it/organization {::org/id 1
› ::org/name ”Acme Inc”}
› …)

› ;; => ({::it/foo 1
› ::it/baz true
› ::it/organization {::org/id 1
› ::org/name ”Acme Inc”}
› …)
Joined entity is
available in a nested
map

SPECQL BENEFITS
› Clojure data!
› The column set is just data and can be easily manipulated
• Even given as parameters from the frontend
› Where clauses can be easily added and are (mostly) just data as well
› Every table and column has a single ns keyword definition
• No more ”order” vs ”order-id” vs ”ord” differences in returned query
results
• Namespaced keys are the way of the future

SPECQL BENEFITS
› Clojure data!
› The column set is just data and can be easily manipulated
• Even given as parameters from the frontend
› Where clauses can be easily added and are (mostly) just data as well
› Every table and column has a single ns keyword definition
• No more ”order” vs ”order-id” vs ”ord” differences in returned query
results
• Namespaced keys are the way of the future HERE TO STAY

SPECQL BENEFITS
› Works with ClojureScript
• The spec generation part, put your specs in .cljc files and enjoy the same
specs and have your db definitions drive your frontend as well
› Works well with ”typed document storage” pattern
• A column can be a user defined type or array
› Provides generic upsert!
• No need to branch code, let the db handle it
› Works with database VIEWs

STATUS
› The github project page (https://github.com/tatut/specql) still says
EXPERIMENTAL
• Current 0.7 alpha stage, should be ready this year
• We are already using it in production in Harja
› No concrete promises before the experimental flag is gone, but the
API should only grow
• The test suite is comprehensive and should not break

STATUS
› 0.7 is coming and adds support for stored procedures
• Macro for defining a stored procedure as a function
• Better JOIN handling
• Currently fetching multiple ”has many” collections at once doesn’t work properly
› How to help
• Please try it out if you are using PostgreSQL
• Report rough edges, I try to provide good error messages

THANK YOU
github.com/tatut/specql twitter.com/tatut

Scrap your query boilerplate with specql

Scrap your query boilerplate with specql

Recommended

More Related Content

What's hot

What's hot(20)

Similar to Scrap your query boilerplate with specql

Similar to Scrap your query boilerplate with specql(20)

Recently uploaded

Recently uploaded(20)

Scrap your query boilerplate with specql

Editor's Notes