Copy across basic @ sql macro and tests

Will likely change the syntax here to use @ sql_cmd instead.

Author: c42f

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Chris Foster <chris42f@gmail.com> and contributors
+Copyright (c) 2021 Julia Computing and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Project.toml

@@ -8,6 +8,7 @@ julia = "1"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
 
 [targets]
-test = ["Test"]
+test = ["Test", "UUIDs"]

README.md

@@ -1,3 +1,106 @@
 # SqlStrings
 
-[![Build Status](https://github.com/JuliaComputing/SqlStrings.jl/workflows/CI/badge.svg)](https://github.com/JuliaComputing/SqlStrings.jl/actions)
+The main thing provided here is the `@sql` macro to allow queries to be
+constructed by normal-looking string interpolation but without danger of SQL
+injection attacks.
+
+Note that `@sql` does not parse the text as SQL source as this wouldn't be
+usable across databases and would be a lot of work. Instead, it keeps any
+literal SQL text you write as-is and only treats the Julia-level string
+interpolations specially.
+
+Use `runquery` to execute queries generated by `@sql`.
+
+## Simple usage
+
+Creating a table and inserting some values
+
+```julia
+conn = LibPQ.connection(your_connection_string)
+
+runquery(conn, @sql "create table foo (email text, userid integer)")
+
+for (email,id) in [ ("admin@example.com", 1)
+                    ("foo@example.com",   2)]
+    runquery(conn, @sql "insert into foo values ($email, $id)")
+end
+```
+
+Thence:
+
+```
+julia> runquery(conn, @sql "select * from foo") |> DataFrame
+2×2 DataFrame
+ Row │ email              userid
+     │ String?            Int32?
+─────┼───────────────────────────
+   1 │ admin@example.com       1
+   2 │ foo@example.com         2
+```
+
+## Howto: Inserting values from a Julia array into a row
+
+In some circumstances it can be useful to use splatting syntax to interpolate a
+Julia collection into a comma-separated list of values. Generally simple scalar
+parameters should be preferred for simplicity, but splatting can be useful on
+occasion:
+
+```julia
+email_and_id = ("bar@example.com", 3)
+runquery(conn, @sql "insert into foo values ($(email_and_id...))")
+```
+
+## Howto: Using the `in` operator with a Julia collection
+
+There's two ways to do this. First, using `in` and splatting syntax
+
+```julia
+julia> ids = (1,2)
+       runquery(conn, @sql "select * from foo where userid in ($(ids...))") |> DataFrame
+       2×2 DataFrame
+        Row │ email              userid
+            │ String?            Int32?
+       ─────┼───────────────────────────
+          1 │ admin@example.com       1
+          2 │ foo@example.com         2
+```
+
+Second, using the SQL `any` operator and simply passing a single SQL array parameter:
+
+```
+julia> ids = [1,2]
+       runquery(conn, @sql "select * from foo where userid = any($ids)") |> DataFrame
+       2×2 DataFrame
+        Row │ email              userid
+            │ String?            Int32?
+       ─────┼───────────────────────────
+          1 │ admin@example.com       1
+          2 │ foo@example.com         2
+```
+
+## Howto: Building up a query from fragments
+
+On occasion you might want to dynamically build up a complicated query from
+fragments of SQL source text. To do this, the result of `@sql` can be
+interpolated into a larger query as follows.
+
+```julia
+conn = LibPQ.connection(your_connection_string)
+
+some_condition = true
+
+x = 100
+x = 20
+# Example of an optional clauses - use empty @sql() to disable it.
+and_clause = some_condition ? @sql("and y=$y") : @sql()
+
+# Interpolation of values produces SQL parameters; interpolating @sql
+# fragments adds them to the query.
+q = @sql "select * from table where x=$x $and_clause"
+runquery(conn, q)
+```
+
+A word of warning that constructing SQl logic with Julia-level logic can make
+the code quite hard to understand. It can be worth considering writing one
+larger SQL query which does more of the logic on the SQL side.
+

src/SqlStrings.jl

@@ -1,5 +1,141 @@
 module SqlStrings
 
-# Write your package code here.
+export @sql
+
+"""
+    Literal(str)
+
+Literal string argument to `@sql`. These are literal query fragments of SQL
+source text.
+"""
+struct Literal
+    fragment::String
+
+    Literal(val::AbstractString) = new(convert(String, val))
+end
+
+Literal(val) = Literal(string(val))
+
+"""
+    Sql
+
+A query or query-fragment which keeps track of interpolations and will pass
+them as SQL query parameters. Construct this type with the `@sql` macro.
+"""
+struct Sql
+    args::Vector
+end
+
+struct SplatArgs
+    args
+end
+
+function process_args!(processed)
+    return processed
+end
+
+function process_args!(processed, a, args...)
+    push!(processed, a)
+    return process_args!(processed, args...)
+end
+
+# Query fragments can be interpolated into other queries
+function process_args!(processed, a::Sql, args...)
+    return process_args!(processed, a.args..., args...)
+end
+
+function process_args!(processed, splat::SplatArgs, args...)
+    for (i,a) in enumerate(splat.args)
+        process_args!(processed, a)
+        if i < length(splat.args)
+            push!(processed, Literal(","))
+        end
+    end
+    return process_args!(processed, args...)
+end
+
+"""
+    sql`SOME SQL ... \$var`
+    sql`SOME SQL ... \$(var...)`
+    sql``
+
+The `@sql` macro is a tool for tracking SQL query strings together with
+their parameters, but without interpolating the parameters into the query
+string directly. Instead, interpolations like `\$x` will result in the value of
+`x` being passed as a query parameter. If you've got a collection of values to
+interpolate into a comma separated context you can also use splatting syntax
+within the interpolation, for example `insert into foo values(\$(x...))`.
+
+Use this rather than direct string interpolation to prevent SQL injection
+attacks and allow systematic conversion of Julia types into their SQL
+equivalents.
+
+Empty query fragments can be generated with ```sql`` ``` which is useful if you
+must dynamically generate SQL code based on conditionals (however also consider
+embedding any conditionals on the SQL side rather than in the Julia code.)
+"""
+macro sql(ex)
+    if ex isa String
+        args = [Literal(ex)]
+    elseif ex isa Expr && ex.head == :string
+        args = []
+        for (i,arg) in enumerate(ex.args)
+            if arg isa String
+                push!(args, Literal(arg))
+            else
+                # Sanity check: arguments should not be quoted
+                prev_quote = i > 1               && ex.args[i-1] isa String && endswith(ex.args[i-1], '\'')
+                next_quote = i < length(ex.args) && ex.args[i+1] isa String && startswith(ex.args[i+1], '\'')
+                if prev_quote || next_quote
+                    error("""Interpolated arguments should not be quoted, but found quoting in subexpression
+                             $(Expr(:string, ex.args[i-1:i+1]...))""")
+                end
+                if Meta.isexpr(arg, :...)
+                    push!(args, :(SplatArgs($(esc(arg.args[1])))))
+                else
+                    push!(args, esc(arg))
+                end
+            end
+        end
+    else
+        error("Unexpected expression passed to @sql: `$ex`")
+    end
+    quote
+        Sql(process_args!([], $(args...)))
+    end
+end
+
+macro sql()
+    Sql([])
+end
+
+function Base.:*(x::Sql, y::Sql)
+    Sql(vcat(x.args, [Literal(" ")], y.args))
+end
+
+function _prepare(query::Sql)
+    querystr = ""
+    arg_values = []
+    i = 1
+    for arg in query.args
+        if arg isa Literal
+            querystr *= arg.fragment
+        else
+            querystr *= "\$$i"
+            push!(arg_values, arg)
+            i += 1
+        end
+    end
+    querystr, arg_values
+end
+
+function Base.show(io::IO, query::Sql)
+    query, arg_values = _prepare(query)
+    print(io, query)
+    if !isempty(arg_values)
+        args_str = join(["\$$i = $(repr(val))" for (i,val) in enumerate(arg_values)], "\n  ")
+        print(io, "\n  ", args_str)
+    end
+end
 
 end

test/runtests.jl

@@ -1,6 +1,47 @@
 using SqlStrings
 using Test
+using UUIDs
+
+querystr(q) = SqlStrings._prepare(q)[1]
+queryargs(q) = SqlStrings._prepare(q)[2]
 
 @testset "SqlStrings.jl" begin
-    # Write your tests here.
+    x = 1
+    y = 2
+    q1 = @sql "select a where b=$x and c=$(x+y)"
+    @test querystr(q1) == raw"select a where b=$1 and c=$2"
+    @test queryargs(q1) == [x, x+y]
+
+    # Test concatenation
+    q2 = @sql("select a") * @sql("where b=$x")
+    @test querystr(q2) == raw"select a where b=$1"
+    @test queryargs(q2) == [x,]
+
+    # Test that interpolating queries into queries works
+    where_clause = @sql "where b=$x"
+    and_clause = @sql "and c=$y"
+    empty_clause = @sql()
+    q3 = @sql "select a $where_clause $and_clause $empty_clause"
+    @test querystr(q3) == raw"select a where b=$1 and c=$2 "
+    @test queryargs(q3) == [x, y]
+
+    # On occasion, we need to interpolate in a literal string rather than use a
+    # parameter. Test that interpolating Literal works for this case.
+    column = "x"
+    @test querystr(@sql "select $(SqlStrings.Literal(column)) from a") ==
+        raw"select x from a"
+
+    # Test that erroneously adding quoting produces an error message
+    @test_throws LoadError @macroexpand @sql "select $y where x = '$x'"
+
+    # Test splatting syntax
+    z = [1,"hi"]
+    q4 = @sql "insert into foo values($(z...))"
+    @test querystr(q4) == raw"insert into foo values($1,$2)"
+    @test queryargs(q4) == z
+
+    # Test that Literal turns values into strings
+    @test SqlStrings.Literal(:col_name).fragment == "col_name"
+    @test SqlStrings.Literal(1).fragment == "1"
 end
+