simple-sql 0.5.36 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5185777df8efad3d0d17334a70d30b35551f4abd7adf0fded3549dd2d1b1325
-  data.tar.gz: e34ee800440259bfbe8ef88f9f70fb1675dee4a91e441c162a8bdc6313e5d88f
+  metadata.gz: 75d235ac454cec6f58662af61d97c7fddf980da80c8bb6f9369db3f0e28e5c68
+  data.tar.gz: 6f047d1c86fdc3308d0b4f32616640d9c083c9bcab2360539ecf16d940bbf1da
 SHA512:
-  metadata.gz: 9b03b9f204d9bd0e87e0c349f1f2ab962bc94101f14ab33cb2522c0287861e801ddca3cd98e97f4317716df7a07a054f6acf26837309f18bc14b8a50f95eac4a
-  data.tar.gz: 5eb4fe4c83ca847aef2263251b56f95b3ea450c15abc1e8289ed92bbcaaaa5d5d8a3683814c009c2dd4928d679a4072d10717a616e3cbac2978d59f2d2f453e8
+  metadata.gz: d7e366a2dd129d99b3ca48fb9b1bd49e37f7bb403f97b7c2fcc87c7f305417fc23ba333e76bbfa457fe57e27bf2df707c2214adf75382ae280cdde9f9c155b34
+  data.tar.gz: 07ed66bd39a8c7db53807ad0f54bab797d6a72d6ee63f38a011e5da753ba170ff865fb00705eee82835d53b8fbdd5c97cc494926f2944ec5089972db4897d309

data/.gitignore

@@ -8,3 +8,4 @@ Gemfile.lock
 .rspec.status
 .DS_Store
 tmp
+log/integration_tests.log

data/.rubocop.yml

@@ -1,5 +1,6 @@
 AllCops:
-  TargetRubyVersion: 2.3
+  TargetRubyVersion: 3.2
+  NewCops: disable
   Exclude:
     - 'spec/**/*'
     - 'test/**/*'
@@ -79,3 +80,7 @@ Style/TrailingUnderscoreVariable:
   
 Style/StderrPuts:
   Enabled: false
+
+# https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Style/HashSyntax
+Style/HashSyntax:
+  EnforcedShorthandSyntax: never

data/.ruby-version

@@ -1 +1 @@
-2.7
+3.3.8

data/Gemfile

@@ -1,7 +1,11 @@
 source 'https://rubygems.org'
 
 gem 'pry-byebug'
-gem 'rubocop', '~> 0.57.2'
+gem 'rubocop', '~> 1.54.1'
+
+gem 'rake', '>= 12.3.3'
+gem 'rspec', '~> 3.7'
+gem 'simplecov', '~> 0'
 
 # Specify your gem's dependencies in {gemname}.gemspec
 gemspec

data/Makefile

@@ -1,16 +1,8 @@
-tests: test4 test5 test6
+default:
+	bundle exec rspec
 
-test4:
-	SIMPLE_SQL_ACTIVERECORD_SPECS="> 4,< 5" bundle
-	rspec
-
-test5:
-	SIMPLE_SQL_ACTIVERECORD_SPECS="> 5,< 6" bundle update activerecord
-	rspec
-
-test6:
-	SIMPLE_SQL_ACTIVERECORD_SPECS="> 6,< 7" bundle update activerecord
-	rspec
+tests: 
+	./scripts/integration_tests
 
 stats:
 	@scripts/stats lib/simple/sql

data/README.md

@@ -1,85 +1,112 @@
 # simple-sql
 
-The simple-sql gem defines a module `Simple::SQL`, which you can use to execute
-SQL statements on a Postgresql database. Care has been taken to provide the 
-simplest interface we could come up with.
+The simple-sql gem defines a module `Simple::SQL`, which you can use to execute SQL statements on a Postgresql database. Care has been taken to provide the simplest interface we could come up with.
 
-**Note:** Databases other than Postgresql are not supported, and there are no
-plans to do so. If you deem that necessary, feel free to fork this code into a
-`simple-sql-<yourdatabase>` gem to provide the same or a similar interface.
+However, apart from providing a simple interface `simple-sql` also provides a huge performance boon over `ActiveRecord` when interacting with your database, by cutting out all the `ActiveRecord` layers between the `pg` gem and you ruby code. However, `simple-sql` is still using ActiveRecord to manage connections.
 
-## Installation
+**Note:** Databases other than Postgresql are not supported, and there are no plans to do so.
+
+<!-- TOC -->
 
-The gem is available on rubygems as `simple-sql`. To use it add the following
-line to your `Gemfile` and bundle us usual:
+## Installation
 
-    gem 'simple-sql' # + version
+The gem is available on rubygems as `simple-sql`.
 
-## Usage
+Also make sure to add the `pg` gem to your Gemfile. `simple-sql` should be pretty flexible about the `pg` version: the earliest supported version is `0.21`. 
 
-### Connecting to a database
+To use it add the following lines to your `Gemfile` and bundle up usual:
 
-Before you can send SQL commands to a database you need to connect first. `simple-sql`
-gives you the following options:
+```ruby
+gem 'simple-sql' # + version
+gem 'pg' # + version
+```
 
-1. **Use the current ActiveRecord connection:** when running inside a Rails application
-   you typically have a connection to Postgresql configured already. In that case you
-   don't need to do anything; `simple-sql` will just use the current database connection.
-   
-   This is usually the right thing, especially since `simple-sql`, when called from inside
-   a controller action, is using the connection valid in the current context.
+## Connecting to a database
 
-2. **Explicitely connect** on standalone applications you need to connect to a Postgresql
-   server. **Note that in this case there are no pooled connections!** simple-sql is not
-   thread-/fiber-safe in this mode.
+Before you can send SQL commands to a database you need to connect first. `simple-sql` gives you the following options:
 
-   You can explictely connect to a server by calling
+### Explicitly connect to the database
 
-         ::Simple::SQL.connect! "postgres://user:password@server[:port]/database"
+In a standalone applications you need to connect to a Postgresql server. `simple-sql` uses ActiveRecord's connection handling.
 
-   Alternatively, you can have `simple-sql` figure out the details automatically:
+You can explicitly connect to a server by calling
 
-         ::Simple::SQL.connect!
+```ruby
+db = ::Simple::SQL.connect! "postgres://user:password@server[:port]/database"
+```
 
-   In that case we try to find connection parameters in the following places:
-   
-   - the `DATABASE_URL` environment value
-   - the `config/database.yml` file from the current directory, taking `RAILS_ENV`/`RACK_ENV` into account.
+You can then use `db.ask`, `db.all`, etc. (See below)
 
-### Using placeholders
+### Automatically determine connection details
 
-Note: whenever you run a query `simple-sql` takes care of sending query parameters over the wire properly. That means that you use placeholders `$1`, `$2`, etc. to use these inside your queries; the following is a correct example:
+Alternatively, you can have `simple-sql` figure out the details automatically:
 
 ```ruby
-Simple::SQL.all "SELECT * FROM users WHERE email=$1", "foo@bar.local"
+db = ::Simple::SQL.connect!
 ```
 
-Also note that it is not possible to use an array as the argument for the `IN(?)` SQL construct. Instead you want to use `ANY`, for example:
+In that case we try to find connection parameters in the following places:
+
+- the `DATABASE_URL` environment value
+- the `config/database.yml` file from the current directory, taking `RAILS_ENV`/`RACK_ENV` into account.
+
+### Using the default connection
+
+You don't need to call `::Simple::SQL.connect!` inside a Rails application. `simple-sql` automatically uses the default connection when using `Simple::SQL` instead of an explicit database handle; i.e. typically you can use
 
 ```ruby
-Simple::SQL.all "SELECT * FROM users WHERE id = ANY($1)", [1,2,3]
+Simple::SQL.ask "SELECT ..."
 ```
 
+and `simple-sql` will be doing the right thing. 
+
+This is especially true in a Rails' applications controller action, because it allows you to mix Simple::SQL and ActiveRecord interactions with the database.
+
+## Simple queries
+
 ### Simple::SQL.all: Fetching all results of a query
 
 `Simple::SQL.all` runs a query, with optional arguments, and returns the result. Usage example:
 
-    Simple::SQL.all "SELECT id, email FROM users WHERE id = ANY($1)", [1,2,3]
+```ruby
+# returns an array of arrays `[ <id>, <email> ]`.
+Simple::SQL.all "SELECT id, email FROM users WHERE id = ANY($1)", [1,2,3]
+```
+
+If a block is passed to SQL.all, each row is yielded into the block:
+
+```ruby
+Simple::SQL.all "SELECT id, email FROM users" do |id, email|
+  # do something
+end
+```
 
-If the SQL query returns rows with one column, this method returns an array of these values.
-Otherwise it returns an array of arrays.
+Typically the SQL query returns an array of arrays (1 per row). If, however, the query is set up to only return a single column, this method returns an array of these values instead. This is especially useful with the block version:
 
 Examples:
 
 ```ruby
 Simple::SQL.all("SELECT id FROM users")        # returns an array of id values, but
-Simple::SQL.all("SELECT id, email FROM users") # returns an array of arrays `[ <id>, <email> ]`.
+
+Simple::SQL.all "SELECT id FROM users" do |id|
+  # do something with the users' ids.
+end
 ```
 
-If a block is passed to SQL.all, each row is yielded into the block:
+### Simple::SQL.each: run a block with each result of a query
+
+This is identical to `.all`. It might offer beneficial optimisations, but this is theoretical at this point.
 
 ```ruby
-Simple::SQL.all "SELECT id, email FROM users" do |id, email|
+Simple::SQL.each "SELECT id, email FROM users" do |id, email|
+  # do something
+end
+```
+
+### Simple::SQL.print: Printing results of a query
+
+```ruby
+Simple::SQL.print "SELECT id, email FROM users" do |id, email|
   # do something
 end
 ```
@@ -88,9 +115,13 @@ end
 
 `Simple::SQL.ask` runs a query, with optional arguments, and returns the first result row or nil, if there was no result.
 
-    Simple::SQL.ask "SELECT id, email FROM users WHERE id = ANY($1) LIMIT 1", [1,2,3]
+```ruby
+Simple::SQL.ask "SELECT id, email FROM users WHERE id = ANY($1) LIMIT 1", [1,2,3]
+```
+
+If the SQL query only returns a single column, this method returns the column value of the first row; otherwise it returns an array (or `nil` if there was no result).
 
-If the SQL query returns rows with one column, this method returns the column value of the first row; otherwise it returns an array (or `nil` if there was no result).
+Usually all attributes are converted to its corresponding ruby type.
 
 Examples:
 
@@ -99,75 +130,146 @@ Simple::SQL.ask "SELECT id FROM users WHERE email=$1", "foo@local"         # ret
 Simple::SQL.ask "SELECT id, email FROM users WHERE email=$?", "foo@local"  # returns an array `[ <id>, <email> ]` (or `nil`)
 ```
 
-### Simple::SQL.ask/Simple::SQL.all:  fetching hashes
+### Using placeholders
+
+Note: whenever you run a query `simple-sql` takes care of sending query parameters over the wire properly. That means that you use placeholders `$1`, `$2`, etc. to use these inside your queries; the following is a correct example:
+
+```ruby
+Simple::SQL.all "SELECT * FROM users WHERE email=$1", "foo@bar.local"
+```
+
+Usually arguments are converted correctly when sending over to the database. One notable exception is sending `jsonb` data - you must use JSON.encode on the argument:
+
+```ruby
+Simple::SQL.ask "INSERT INTO table (column) VALUES($1)", JSON.encode(..)
+```
+
+It is probably worth pointing out that you cannotto use an array as the argument for the `IN(?)` SQL construct. Instead you want to use `ANY`, for example:
+
+```ruby
+Simple::SQL.all "SELECT * FROM users WHERE id = ANY($1)", [1,2,3]
+```
+
+### Determining the result type
+
+By default `ask` and `all` convert each result row into an Array. Sometimes you might want to use Hashes or similar objects instead. To do so, you use the `into:` keyword argument:
+
+```ruby
+# returns a single Hash (or nil)
+Simple::SQL.ask("SELECT id FROM users", into: Hash) 
+```
+
+If you want the returned record to be in a structure which is not a Hash, you can use the `into: <klass>` option. The following would return an array of up to two `OpenStruct` objects:
 
-While `ask` and `all` convert each result row into an Array, sometimes you might want
-to use Hashes or similar objects instead. To do so, you use the `into:` keyword argument:
+```ruby
+sql = "SELECT id, email FROM users WHERE id = ANY($1) LIMIT 1", 
+Simple::SQL.all sql, [1,2,3], into: OpenStruct
+```
 
-    # returns a single Hash (or nil)
-    Simple::SQL.ask("SELECT id FROM users", into: Hash) 
+This supports all target types that take a constructor accepting Hash arguments.
 
-If you want the returned record to be in a structure which is not a Hash, you can use
-the `into: <klass>` option. The following would return an array of up to two `OpenStruct`
-objects:
+It also supports a `:struct` argument, in which case simple-sql creates uses a Struct-class. Struct classes are reused when possible, and are maintained by `Simple::SQL`. This is potentially the best performing option when you want to use dot-notation.
 
-    sql = "SELECT id, email FROM users WHERE id = ANY($1) LIMIT 1", 
-    Simple::SQL.all sql, [1,2,3], into: OpenStruct
+```ruby
+sql = "SELECT id, email FROM users WHERE id = ANY($1) LIMIT 1", 
+Simple::SQL.all sql, [1,2,3], into: :struct
+```
 
-This supports all target types that take a contructor which acceps Hash arguments.
+### Running non-`SELECT` queries
 
-It also supports a :struct argument, in which case simple-sql creates uses a Struct-class.
-Struct classes are reused when possible, and are maintained by Simple::SQL. 
+You can use `all` and `ask` with other queries as well. However, both only support running a single query. If you want to run multiple queries (i.e. a SQL script) you would probably look into `Simple::SQL.exec` instead.
 
-    sql = "SELECT id, email FROM users WHERE id = ANY($1) LIMIT 1", 
-    Simple::SQL.all sql, [1,2,3], into: :struct
+Be aware that `Simple::SQL.exec` does not support placeholders: you cannot pass in arguments into `Simple::SQL.exec`.
 
 ### Transaction support
 
-`simple-sql` has limited support for nested transactions. When running with a ActiveRecord
-connection, we use ActiveRecord's transaction implementation (which uses savepoints for nested
-transactions, so you might be able to rollback from inside a nested transaction).
+`simple-sql` borrows transaction support from `ActiveRecord`.
 
-When connecting via `Simple::SQL.connect!` we do not support the same level of nesting support (yet). You can still nest transactions, but raising an error terminates *all* current transactions. 
+## Using scopes
 
-## Logging
+A scope lets you build a condition over time, like this:
+
+```ruby
+scope = db.scope "SELECT * FROM users"
+scope = scope.where(email: ["foo@foobar.test", "bar@foobar.test"])
+scope = scope.where("deleted_at is NULL")
+users = scope.all
+```
 
-`simple-sql` builds a logger which logs all queries. The logger, by default, is
-created to write to STDERR; to get another logger use code like
+This also works with the default connection, via `scope = Simple::SQL.scope ...`.
 
-    Simple::SQL.logger = Rails.logger
+A scope supports the following methods to set up a scope:
 
-## Bugs and Limitations
+|                           |                                             |
+|---------------------------|---------------------------------------------|
+| `where(args...)`          | add additional conditions. `where` also has additional support for using `?` instead of `$nn`, and supports JSONB query conditions. See [where.rb](lib/simple/sql/connection/scope/where.rb) for details.|
+| `order_by(sql_fragment)`  ||
+| `limit(limit)`            ||
+| `offset(offset)`          ||
+| `paginate(per:, page:)`   | adds pagination (calls `limit` and `offset`) |
 
-### 1. Multiple connections
 
-It is currently not possible to run SQL queries against a database which is not
-connected via ActiveRecord::Base.connection.
+These methods can then be used to evaluate the scope:
 
-### 2. Postgresql only
+|                           |                                             |
+|---------------------------|---------------------------------------------|
+| `all(into: ...)`          | returns all matching entries |
+| `first(into: ...)`        | returns the first matching entry|
+| `count`                   | returns the exact count of matching records|
+| `count_estimate`          | returns a fast estimate of the count of matching records. Note that this needs suitable and up-to-date indices.|
+| `enumerate_groups(sql)`   | returns all groups |
+| `count_by(sql)`           | counts by groups |
+| `print`                   | print all matching entries|
+| `explain`                 | returns the query plan|
 
-Only Postgresql is supported.
+## Inserting objects
 
-### 3. Limited support for types
+Inserting objects is much faster via `simple-sql`. You should be able to insert ~1000 or so records per second into a table with no trouble.
 
-This gem does not use `pg`'s support for encoding and decoding types, since
-that might probably interfere with how ActiveRecord is setting up the `pg`
-gem.
+```ruby
+Simple::SQL.insert :users, first_name: "foo", last_name: "bar"
+```
+
+```ruby
+users = []
+users.push first_name: "first", last_name: "user"
+users.push first_name: "second", last_name: "user"
+
+Simple::SQL.insert :users, users
+```
+
+The `.insert` method lets you set up conflict resolution, via 
+
+```ruby
+Simple::SQL.insert :users, users, on_conflict: :ignore
+```
+
+## Advisory Locks
+
+```ruby
+Simple::SQL.transaction do
+  Simple::SQL.lock!(4711)
+
+  # do something.
+end
+```
+
+## Logging
 
-It therefore assumes ActiveRecord is used in the same project, which sets up
-pg to not decode data in any meaningful way, and provides some code to decode
-the data returned from the database. Only a handful of types is currently
-supported by the Decoder - it is fairly easy to add new types, though.
+`simple-sql` builds a logger which logs all queries. The logger, by default, is created to write to STDERR; to get another logger use code like
 
-### 4. text arrays
+```ruby
+Simple::SQL.logger = Rails.logger
+```
+
+## Bugs and Limitations
+
+**Limited support for types:** This gem does not use `pg`'s support for encoding and decoding types, since that might probably interfere with how ActiveRecord is setting up the `pg` gem.
 
-The library used to parse array results seems to be buggy if the array contains
-strings containing the "`" character.
+It therefore assumes ActiveRecord is used in the same project, which sets up pg to not decode data in any meaningful way, and provides some code to decode the data returned from the database. Only a handful of types is currently supported by the Decoder - it is fairly easy to add new types, though.
 
 ## Test
 
 1. `createdb simple-sql-test`
 2. `bundle install`
 3. `bin/rspec`
-
-## Test again

data/VERSION

@@ -1 +1 @@
-0.5.36
+0.9.0

data/bin/db_restore

@@ -3,7 +3,13 @@ require 'yaml'
 
 env = ENV["POSTJOB_ENV"] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
 
-configs = YAML.load_file "config/database.yml"
+path = "config/database.yml"
+configs = if Psych::VERSION > '4.0'
+  YAML.safe_load(File.read(path), aliases: true)
+else
+  YAML.safe_load(File.read(path), [], [], true)
+end
+
 config = configs.fetch(env) { configs.fetch("defaults") }
 
 ENV["PGHOST"]     = config["host"]

data/bin/pg

@@ -3,7 +3,13 @@ require 'yaml'
 
 env = ENV["POSTJOB_ENV"] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
 
-configs = YAML.load_file "config/database.yml"
+path = "config/database.yml"
+configs = if Psych::VERSION > '4.0'
+  YAML.safe_load(File.read(path), aliases: true)
+else
+  YAML.safe_load(File.read(path), [], [], true)
+end
+
 config = configs.fetch(env) { configs.fetch("defaults") }
 
 ENV["PGHOST"]     = config["host"]

data/config/database.yml

@@ -2,8 +2,8 @@ defaults: &defaults
   adapter: postgresql
   encoding: utf8
   host: '127.0.0.1'
-  username: admin
-  password: admin
+  # username: admin
+  # password: admin
   pool: 5
   timeout: 5000
 

data/lib/simple/sql/config.rb

@@ -16,7 +16,7 @@ module Simple::SQL::Config
 
     config = {
       dbname: uri.path.sub(%r{^/}, ""),
-      host:   uri.hostname
+      host: uri.hostname
     }
     config[:port] = uri.port if uri.port
     config[:user] = uri.user if uri.user
@@ -55,7 +55,12 @@ module Simple::SQL::Config
 
   def load_activerecord_base_configuration(path:, env:)
     require "yaml"
-    database_config = YAML.load_file(path)
+    database_config = if Psych::VERSION > '4.0'
+                        YAML.safe_load(File.read(path), aliases: true)
+                      else
+                        YAML.safe_load(File.read(path), [], [], true)
+                      end
+
     env ||= ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
 
     database_config[env] ||

data/lib/simple/sql/connection/base.rb

@@ -81,6 +81,7 @@ class Simple::SQL::Connection
   # - <tt>Simple::SQL.ask "SELECT id, email FROM users WHERE email=$?", "foo@local"</tt>
   #   returns an array <tt>[ <id>, <email> ]</tt> (or +nil+)
   def ask(sql, *args, into: nil)
+    # rubocop:disable Lint/UnreachableLoop
     catch(:ok) do
       each(sql, *args, into: into) { |row| throw :ok, row }
       nil

data/lib/simple/sql/connection/insert.rb

@@ -28,9 +28,9 @@ class Simple::SQL::Connection
 
   class Inserter
     CONFICT_HANDLING = {
-      nil      => "",
+      nil => "",
       :nothing => "ON CONFLICT DO NOTHING",
-      :ignore  => "ON CONFLICT DO NOTHING"
+      :ignore => "ON CONFLICT DO NOTHING"
     }
 
     #
@@ -89,6 +89,7 @@ class Simple::SQL::Connection
 
     def json_encode(value)
       return value unless value.is_a?(Hash) || value.is_a?(Array)
+
       JSON.generate(value)
     end
   end

data/lib/simple/sql/connection/reflection.rb

@@ -1,5 +1,7 @@
 # rubocop:disable Metrics/ClassLength
 
+require "ostruct"
+
 class Simple::SQL::Connection
   def reset_reflection
     @reflection = nil