quote-sql 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb47e85b4c7c4e1f945748295390c9e1bd49b7e0ba5291e0f7310058f6f91ddc
-  data.tar.gz: 0f5bde1afc31eb573bb3e24727b530bf5909048284114d45c56c1b24a63e97aa
+  metadata.gz: 7e308b3aef586983a61155c9ba3be6c39c2397fa5fbae069ab45522e51681caa
+  data.tar.gz: 6a3945e1a4cfc16fed91c46216d1a10c5a69e85a6b3a0df10db45a9f162c07eb
 SHA512:
-  metadata.gz: 6596b9bb50ee373030e401dcb9d0067ae31857b6467fdd7b0341e21b3dcbe8fb0e78714ec24f56615618bbf965849307474a4030978e6c98d2d728166e235151
-  data.tar.gz: f38366de3e2227835fd11f512a9c9d2a99d130d896a17f6b0a58788dd8ed7ebd13f46682992b762e2d50f09716c3bd5654d525dc4b03f350d3a52cc6b19b322e
+  metadata.gz: 3ce751f52d51a6b7b989062673f9c849b5a8b44e5e4227f0f453290d41b20856b45f0d0bbddd6cea6f5256405b313d82367a27fdd2381dd2b37f27c3ac3442e6
+  data.tar.gz: 2656c2cbacc7375fd22f2148d4a929fbba1822c97b61467bdf5794c7bcf78b75d5ba4a9bfb90a6f01b282479bad95c77d354ca2211a6f3561a6eaa60e9d90db4

data/README.md

@@ -1,22 +1,25 @@
 # QuoteSql - Tool to build and run SQL queries easier
-I've built this library as an addition to ActiveRecord and Arel, however you can use it with any sql database and plain Ruby.
-However currently it is just used with PostgreSQL.
-
 Creating SQL queries and proper quoting becomes complicated especially when you need advanced queries.
 
-I created this library while coding for different projects, and had lots of Heredoc SQL queries, which pretty quickly becomes the kind of: 
-> When I wrote these lines of code, just me and God knew what they mean. Now its just God.
+I created this library while coding for different projects, and had lots of Heredoc SQL queries, which pretty quickly became unreadable.
+
+With QuoteSql you segment SQL Queries in readable junks, which can be individually tested and then combine them to the final query.
+When us use RoR, you can combine queries or get the output with fields other than `pick` or `pluck`
+
+Please have a look at the *unfinished* documentation below or run `QuoteSql.test` in a Ruby console
 
-My strategy is to segment SQL Queries in readable junks, which can be individually tested and then combine their sql to the final query.
+If you think QuoteSql is interesting but needs extension, let's chat!
 
-If you think QuoteSql is interesting, let's chat!
-Also if you have problems using it, just drop me a note.
+If you run into problems, drop me a note.
 
 Best Martin
 
 ## Caveats & Notes
+- Currently its just built for Ruby 3, if you need Ruby 2, let me know.
 - QuoteSql is used in production, but is still bleeding edge - and there is not a fully sync between doc and code.
-- Just for my examples and in the docs, I'm using for Yajl for JSON parsing, and changed in my environments the standard parse output to *symbolized keys*. 
+- Just for my examples and in the docs, I'm using for Yajl for JSON parsing, and changed in my environments the standard parse output to *symbolized keys*.
+- I've built this library as an addition to ActiveRecord and Arel, however you can use it with any sql database and plain Ruby.
+- It is currently built for PostgreSQL only. If you want to use other DBs, please contribute your code!
 
 ## Examples
 ### Simple quoting
@@ -31,11 +34,12 @@ Best Martin
 => SELECT first_name, last_name FROM users LIMIT 10
 
 ### Quoting of columns and table from a model - or an object responding to table_name and column_names or columns
-`QuoteSql.new("SELECT %columns FROM %table_name").quote(table: User).to_sql`
+`QuoteSql.new("SELECT %columns FROM %table").quote(table: User).to_sql`
   => SELECT "id",firstname","lastname",... FROM "users"
+  
 ### Injecting raw sql in a query
-`QuoteSql.new("SELECT a,b,%raw FROM table").quote(raw: "jsonb_build_object('a', 1)").to_sql`
-  => SELECT "a,b,jsonb_build_object('a', 1) FROM table
+`QuoteSql.new("SELECT a,b,%raw FROM my_table").quote(raw: "jsonb_build_object('a', 1)").to_sql`
+  => SELECT "a,b,jsonb_build_object('a', 1) FROM my_table
 
 ### Injecting ActiveRecord, Arel.sql or QuoteSql
 `QuoteSql.new("SELECT %column_names FROM (%any_name) a").
@@ -54,15 +58,34 @@ Values are be ordered in sequence of columns. Missing value entries are substitu
       ON CONFLICT ("id") DO NOTHING
       
 ### Columns from a list
-`QuoteSql.new("SELECT %columns").quote(columns: [:a, :"b.c", c: {d: field}]).to_sql`
-  => SELECT "a","b"."c",jsonb_build_object('d', field) AS c 
+`QuoteSql.new("SELECT %columns").quote(columns: [:a, "b.c", d: {e: field}]).to_sql`
+  => SELECT "a","b"."c",jsonb_build_object('e', field) AS d 
+
+`QuoteSql.new("SELECT %columns").quote(columns: [:a, "b.c", d: {e: field, nil: false}]).to_sql`
+  => SELECT "a","b"."c",jsonb_strip_nulls(jsonb_build_object('e', 1)) AS d
+
+## Executing
+### Getting the results
+  `QuoteSql.new('SELECT %x AS a').quote(x: 1).result`
+    => [{:a=>1}]
+
+### Binds
+You can use binds ($1, $2, ...) in the SQL and add arguments to the result call
+  `QuoteSql.new('SELECT $1 AS a').result(1)`  
+
+#### using JSON
 
-`QuoteSql.new("SELECT %columns").quote(columns: [:a, :"b.c", c: {d: field, nil: false}]).to_sql`
-  => SELECT "a","b"."c",jsonb_strip_nulls(jsonb_build_object('d', 1)) AS c 
+    v = {a: 1, b: "foo", c: true}
+    QuoteSQL(%q{SELECT * FROM %x_json}, x_json: 1, x_casts: {a: "int", b: "text", c: "boolean"}).result(v.to_json)
+    
+  => SELECT * FROM json_to_recordset($1) AS "x"("a" int,"b" text,"c" boolean) => [{a: 1, b: "foo", c: true}]
+
+Insert fom json
+  
+    v = {a: 1, b: "foo", c: true}
+    QuoteSql.new("INSERT INTO table (%x_columns) SELECT * FROM %x_json").quote({:x_json=>1}).result(v.to_json)
 
 
-### Execution of a query
-`QuoteSql.new("Select 1 as abc").result` => [{:abc=>1}]
 
 
 ## Substitution of mixins with quoted values 
@@ -73,24 +96,14 @@ Values are be ordered in sequence of columns. Missing value entries are substitu
   **Caution! You need to take care, no protection against infinite recursion **
   
 ### Special mixins
-- `%table` | `%table_name` | `%table_names`
-- `%column` | `%columns` | `%column_names`
+- `%table` +String+, +ActiveRecord::Base+, Object responding to #to_sql, and +Array+ of these
+- `%columns` +Array+ of +String+, +Hash+ keys: AS +Symbol+, +String+. fallback: 1) %casts keys, 2) %table.columns 
+- `%casts` +Hash+ keys: column name, values: Cast e.g. "text", "integer"
 - `%ident` | `%constraint` | `%constraints` quoting for database columns
 - `%raw` | `%sql` inserting raw SQL
-- `%value` | `%values` creates value section for e.g. insert
-  - In the right order
-    - Single value => (2)
-    - +Array+ => (column, column, column) n.b. has to be the correct order
-    - +Array+ of +Array+ => (...),(...),(...),...
-  - if the columns option is given (or implicitely by setting table)
-    - +Hash+ values are ordered according to the columns option, missing values are replaced by `DEFAULT`
-    - +Array+ of +Hash+ multiple record insert
-- `%bind` is replaced with the current bind sequence.
-  Without appended number the first %bind => $1, the second => $2 etc.
-  - %bind\\d+ => $+Integer+ e.g. `%bind7` => $7
-  - `%bind__text` => $1 and it is registered as text - this is used in prepared statements (TO BE IMPLEMENTED)
-  - `%key_bind__text` => $1 and it is registered as text when using +Hash+ in the execute
-    $1 will be mapped to the key's value in the +Hash+ TODO
+- `%values` creates the value section for INSERT `INSERT INTO foo (a,b) %values`
+- `%x_values` creates the value secion for FROM `SELECT column1, column2, column3 FROM %x_values`
+- `%x_json` creates `json_for_recordset(JSON) x (CASTS)`. "x" can be any other identifier, you need to define the casts e.g. `quotes(x_json: {a: "a", b: 1}, x_casts: {a: :text, b: :integer)`
 
 All can be preceded by additional letters and underscore e.g. `%foo_bar_column`
 
@@ -110,22 +123,27 @@ with optional array dimension
 - When the value responds to :to_sql or is a +Arel::Nodes::SqlLiteral+ its added as raw SQL
 - +Proc+ are executed with the +QuoteSQL::Quoter+ object as parameter and added as raw SQL
 
-### Special quoting columns
-- +String+ or +Symbol+ without a dot  e.g. :firstname => "firstname"
-- +String+ or +Symbol+ containing a dot e.g. "users.firstname" or => "users"."firstname"
+### Special quoting for %columns
+
+    `QuoteSql.new("SELECT %columns FROM %table, other_table").quote(columns: ["a", "other_table.a", :a ], table: "my_table")`
+    => SELECT "a", "other_table"."a", "my_table"."a" from "my_table", "other_table"
+
+- +String+ without a dot  e.g. "firstname" => "firstname"
+- +String+ containing a dot e.g. "users.firstname" or => "users"."firstname"
+- +Symbol+ prepended with table from table: quote if present.
+- +Proc+ is called in the current context
+- +QuoteSql::Raw+ or +Arel::Nodes::SqlLiteral+ are injected as is
+- Object responding to #to_sql is called and injected 
 - +Array+
-  - +String+ and +Symbols+ see above
   - +Hash+ see below
-- +Hash+ or within the +Array+
-  - +Symbol+ value will become the column name e.g. {table: :column} => "table"."column"
-  - +String+ value will become the expression, the key the AS {result: "SUM(*)"} => SUM(*) AS result
-  - +Proc+ are executed with the +QuoteSQL::Quoter+ object as parameter and added as raw SQL
+  - other see above
+- +Hash+
+  - keys become the "AS"
+  - values
+    - +Hash+, +Array+ casted as JSONB
+    - others see above
+    
 
-## Executing
-### Getting the results
-### Binds
-  `v = {a: 1, b: "foo", c: true};QuoteSQL(%q{Select * From %x_json}, x_json: 1, x_casts: {a: "int", b: "text", c: "boolean"}).result(v.to_json)`
-  => Select * From json_to_recordset($1) AS "x"("a" int,"b" text,"c" boolean) => [{a: 1, b: "foo", c: true}]
 
 ## Shortcuts and functions
 - `QuoteSQL("select %abc", abc: 1)` == `QuoteSql.new("select %abc").quote(abc: 1)`
@@ -137,8 +155,8 @@ If you have pg_format installed you can get the resulting query inspected:
   `QuoteSql.new("select %abc").quote(abc: 1).dsql`
 
 # Test
-Minimal tests you can run by
-`QuoteSql.test.all`
+Currently there are just minimal tests
+run `QuoteSql.test`
 You can find them in /lib/quote_sql/test.rb
 
 ## Installing
@@ -151,8 +169,15 @@ Add this to config/initializers/quote_sql.rb
 
     ActiveSupport.on_load(:active_record) do
       require 'quote_sql'
-      QuoteSql.db_connector = ActiveRecord::Base
+      
+      # if you want to execute from Strings 
+      #   e.g. "select %a".quote_sql(a: 1).result
       String.include QuoteSql::Extension
+
+      # if you use Active Record 
+      QuoteSql.db_connector = ActiveRecord::Base
+      # if you want to execute from a Model 
+      #   e.g. User.select("name, %a").quote_sql(a: 1).result
       ActiveRecord::Relation.include QuoteSql::Extension
     end  
 

data/lib/quote_sql/test.rb

@@ -49,14 +49,14 @@ class QuoteSql::Test
     )
   end
 
-  def test_binds
-    expected <<~SQL
-      SELECT $1, $2::UUID, $1 AS get_bind_1_again FROM "my_table"
-    SQL
-    QuoteSql.new("SELECT %bind, %bind__uuid, %bind1 AS get_bind_1_again FROM %table").quote(
-      table: "my_table"
-    )
-  end
+  # def test_binds
+  #   expected <<~SQL
+  #     SELECT $1, $2::UUID, $1 AS get_bind_1_again FROM "my_table"
+  #   SQL
+  #   QuoteSql.new("SELECT %bind, %bind__uuid, %bind1 AS get_bind_1_again FROM %table").quote(
+  #     table: "my_table"
+  #   )
+  # end
 
   def test_from_values_array
     expected <<~SQL

data/lib/quote_sql/version.rb

@@ -1,3 +1,3 @@
 class QuoteSql
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quote-sql
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Martin Kufner