simple-sql 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 671eec226ce28823bcb0d2e749c3e11d7990ffca
-  data.tar.gz: f3447b03aa97ee19fd1e3fefd566ed24b77f2a85
+  metadata.gz: 435908aca401185b06131575ae1b5c85570c6fe4
+  data.tar.gz: d238e14b1d859326b0ed4d7e9799d3717d31a821
 SHA512:
-  metadata.gz: 1cf66f360cb3d5cd721d6f978dcdc385e6fbfac3cf3aecd40083d8d5f9a9a1b849cf52f7884a29ece948ff4ca1164bf1ccabab97076ecbc789b6e45888bbefc4
-  data.tar.gz: d2dd45b2e4822fa591286030fd9bb874fd1a23fdc5ee93946c6859e64e4cf8413f4f880801baefdf86db96cf6b0a179221e1adb6b08f2f1be9d21f3afc8b6079
+  metadata.gz: f8a497b87236bb8f0cfe1f6e1db9577bbd6364e8826b41097adec7b235cddbff4cac3cd6535a832f8b6d75e452ea21af6ae64ece5f8f9e826d48adbd59087213
+  data.tar.gz: 98d60e38cfd0b60128da263bc8372428028e4ce31fb009e324498de16024802bc65a35e9676f863e379154c76fb56066b4a1f43a6561bd629c1fce6d33b41c3b

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    simple-sql (0.2.1)
+    simple-sql (0.2.2)
       pg (~> 0.20)
       pg_array_parser (~> 0)
 

data/README.md

@@ -1,21 +1,66 @@
 # 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.
+
+**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.
+
 ## Installation
 
-The gem is available through our private gem host:
+The gem is available on rubygems as `simple-sql`. To use it add the following
+line to your `Gemfile` and bundle us usual:
 
-```ruby
-gem 'simple-sql' # + version
-```
+    gem 'simple-sql' # + version
 
 ## Usage
 
-This gem defines a module `Simple::SQL`, which you can use to execute SQL statements
-on the current ActiveRecord connection.
+### Connecting to a database
+
+Before you can send SQL commands to a database you need to connect first. `simple-sql`
+gives you the following options:
+
+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.
+
+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.
+
+   You can explictely connect to a server by calling
+
+         ::Simple::SQL.connect! "postgres://user:password@server[:port]/database"
+
+   Alternatively, you can have `simple-sql` figure out the details automatically:
+
+         ::Simple::SQL.connect!
+
+   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 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"
+```
+
+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:
 
-Simple::SQL takes care of converting arguments back and forth.
+```ruby
+Simple::SQL.all "SELECT * FROM users WHERE id = ANY($1)", [1,2,3]
+```
 
-### Running a query
+### Simple::SQL.all: Fetching all results of a query
 
 `Simple::SQL.all` runs a query, with optional arguments, and returns the result. Usage example:
 
@@ -39,12 +84,9 @@ Simple::SQL.all "SELECT id, email FROM users" do |id, email|
 end
 ```
 
-In this case SQL.all returns `self`, which lets you chain function calls. 
-
-### Getting the first result
-
-`Simple::SQL.ask` returns runs a query, with optional arguments, and returns the first result row.
+### Simple::SQL.ask:  getting the first result
 
+`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]
 
@@ -57,21 +99,28 @@ 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`)
 ```
 
-## Notes
+### Simple::SQL.record/Simple::SQL.records:  fetching hashes
 
-Remember that Postgresql uses $1, $2, etc. as placeholders; the following is correct:
+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 record and records functions:
 
-```ruby
-Simple::SQL.all "SELECT * FROM users WHERE email=$1", "foo@bar.local"
-```
+    # returns a single Hash (or nil)
+    Simple::SQL.record("SELECT id FROM users") 
 
-Also note that `IN(?)` is not supported by the Postgresql client library; instead you
-must use `= ANY`, for example:
+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:
 
-```ruby
-Simple::SQL.all "SELECT * FROM users WHERE id = ANY($1)", [1,2,3]
-```
+    sql = "SELECT id, email FROM users WHERE id = ANY($1) LIMIT 1", 
+    Simple::SQL.records sql, [1,2,3], into: OpenStruct
+
+### 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).
 
+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. 
 
 ## Bugs and Limitations
 

data/lib/simple-sql.rb

@@ -0,0 +1 @@
+require "simple/sql"

data/lib/simple/sql.rb

@@ -2,8 +2,8 @@ require_relative "sql/version.rb"
 require_relative "sql/decoder.rb"
 require_relative "sql/encoder.rb"
 require_relative "sql/config.rb"
-require_relative "sql/transactions.rb"
 require_relative "sql/logging.rb"
+require_relative "sql/connection.rb"
 
 require "logger"
 
@@ -11,7 +11,6 @@ module Simple
   # The Simple::SQL module
   module SQL
     extend self
-    extend Transactions
 
     attr_accessor :logger
     self.logger = Logger.new(STDERR)
@@ -88,6 +87,9 @@ module Simple
       end
     end
 
+    extend Forwardable
+    delegate :transaction => :connection
+
     private
 
     def exec_logged(sql, *args)
@@ -127,7 +129,7 @@ module Simple
     }
 
     def connect_to_active_record
-      return ActiveRecord::Base.connection.raw_connection if defined?(ActiveRecord)
+      return Connection.new(ActiveRecord::Base.connection) if defined?(ActiveRecord)
 
       STDERR.puts <<-SQL
 Simple::SQL works out of the box with ActiveRecord-based postgres connections, reusing the current connection.
@@ -150,7 +152,7 @@ SQL
       config = Config.parse_url(database_url)
 
       require "pg"
-      connection = PG::Connection.new(config)
+      connection = Connection.new(PG::Connection.new(config))
       self.connector = lambda { connection }
     end
   end

data/lib/simple/sql/connection.rb

@@ -0,0 +1,76 @@
+# private
+module Simple::SQL::Connection
+  def self.new(connection)
+    if defined?(ActiveRecord)
+      if connection.is_a?(ActiveRecord::ConnectionAdapters::PostgreSQLAdapter)
+        return ActiveRecordConnection.new(connection)
+      end
+    end
+
+    SimpleConnection.new(connection)
+  end
+
+  class RawConnection
+    def initialize(raw_connection)
+      @raw_connection = raw_connection
+    end
+
+    extend Forwardable
+    delegate %w(exec_params exec escape) => :@raw_connection
+
+    def transaction(&block)
+      raise ArgumentError, "Implementation missing for #transaction"
+    end
+  end
+
+  class SimpleConnection < RawConnection
+    def initialize(raw_connection)
+      super(raw_connection)
+      @tx_nesting_level = 0
+    end
+
+    private
+
+    def transaction(&block)
+      # Notes: by using "ensure" (as opposed to rescue) we are rolling back 
+      # both when an exception was raised and when a value was thrown. This 
+      # also means we have to track whether or not to rollback. i.e. do roll
+      # back when we yielded to &block but not otherwise.
+      #
+      # Also the transaction support is a bit limited: you cannot rollback.
+      # Rolling back from inside a nested transaction would require SAVEPOINT
+      # support; without the code is simpler at least :)
+
+      if @tx_nesting_level == 0
+        exec "BEGIN"
+        tx_started = true
+      end
+
+      @tx_nesting_level += 1
+
+      return_value = yield
+
+      # Only commit if we started a transaction here.
+      if tx_started
+        exec "COMMIT"
+        tx_committed = true
+      end
+
+      return_value
+    ensure
+      @tx_nesting_level -= 1
+      if tx_started && !tx_committed
+        exec "ROLLBACK"
+      end
+    end
+  end
+
+  class ActiveRecordConnection < RawConnection
+    def initialize(connection)
+      super(connection.raw_connection)
+      @connection = connection
+    end
+
+    delegate :transaction => :@connection
+  end
+end

data/lib/simple/sql/version.rb

@@ -1,5 +1,5 @@
 module Simple
   module SQL
-    VERSION = "0.2.1"
+    VERSION = "0.2.2"
   end
 end

data/tasks/release.rake

@@ -54,7 +54,7 @@ namespace :release do
     Dir.chdir(GEM_ROOT) do
       version = VersionNumberTracker.version
       sh("git add #{VERSION_FILE_PATH}")
-      sh("git commit -m \"bump auth to v#{version}\"")
+      sh("git commit -m \"bump to v#{version}\"")
       sh("git tag -a v#{version} -m \"Tag\"")
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: simple-sql
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - radiospiel
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-01-19 00:00:00.000000000 Z
+date: 2018-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg_array_parser
@@ -165,12 +165,13 @@ files:
 - Rakefile
 - bin/rake
 - config/database.yml
+- lib/simple-sql.rb
 - lib/simple/sql.rb
 - lib/simple/sql/config.rb
+- lib/simple/sql/connection.rb
 - lib/simple/sql/decoder.rb
 - lib/simple/sql/encoder.rb
 - lib/simple/sql/logging.rb
-- lib/simple/sql/transactions.rb
 - lib/simple/sql/version.rb
 - log/.gitkeep
 - simple-sql.gemspec

data/lib/simple/sql/transactions.rb

@@ -1,44 +0,0 @@
-# private
-module Simple::SQL::Transactions
-  SELF = self
-
-  def self.nesting_level
-    Thread.current[:nesting_level] ||= 0
-  end
-
-  def self.nesting_level=(nesting_level)
-    Thread.current[:nesting_level] = nesting_level
-  end
-
-  def transaction(&block)
-    # Notes: by using "ensure" (as opposed to rescue) we are rolling back 
-    # both when an exception was raised and when a value was thrown. This 
-    # also means we have to track whether or not to rollback. i.e. do roll
-    # back when we yielded to &block but not otherwise.
-    #
-    # Also the transaction support is a bit limited: you cannot rollback.
-    # Rolling back from inside a nested transaction would require SAVEPOINT
-    # support; without the code is simpler at least :)
-    if SELF.nesting_level == 0
-      transaction_started = true
-      ask "BEGIN"
-    end
-
-    SELF.nesting_level += 1
-
-    return_value = yield
-
-    # Only commit if we started a transaction here.
-    if transaction_started
-      ask "COMMIT"
-      transaction_committed = true
-    end
-
-    return_value
-  ensure
-    SELF.nesting_level -= 1
-    if transaction_started && !transaction_committed
-      ask "ROLLBACK"
-    end
-  end
-end