ensql 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3097f158523b78a965c84dbf0e79f41ce4be744d5dd0842fc9f5f780ec9b5fba
+  data.tar.gz: e5a123a39ab5f6c1b1911bf46972e441f6bb77d69584fd7bb005192baa5a24c8
+SHA512:
+  metadata.gz: 02a9e0a720bc3b861e27782233fac13ec9e58cfb4b3a6892b2d224f3a0d1de76051f2300370ded32fd9acfe677b71705510e3ee1dd95085cbb7b1fdfd8dda676
+  data.tar.gz: 724701d41daf5554702c6173a2aa6e063034ca3d094ed29eb4cf760c6aba467a13a623f4e5fbc904ca95418a111e281cca4104eb55e8b04ce8d3673323b2d77b

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+2.7.2

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2021-02-15
+
+- Initial release

data/Gemfile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in ensql.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+# Ensure test coverage
+gem "simplecov", "~> 0.21.2"
+
+# Database adapters
+require_relative 'lib/ensql/version'
+gem "activerecord", ENV['ACTIVERECORD_VERSION'] || Ensql::ACTIVERECORD_VERSION
+gem "sequel",       ENV['SEQUEL_VERSION']       || Ensql::SEQUEL_VERSION
+gem "sqlite3",      ENV['SQLITE3_VERSION']      || "~> 1.4"
+gem "pg",           ENV['PG_VERSION']           || "~> 1.2"
+
+gem "yard", "~> 0.9.26"

data/Gemfile.lock

@@ -0,0 +1,69 @@
+PATH
+  remote: .
+  specs:
+    ensql (0.6.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (6.1.3)
+      activesupport (= 6.1.3)
+    activerecord (6.1.3)
+      activemodel (= 6.1.3)
+      activesupport (= 6.1.3)
+    activesupport (6.1.3)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    concurrent-ruby (1.1.8)
+    diff-lcs (1.4.4)
+    docile (1.3.5)
+    i18n (1.8.9)
+      concurrent-ruby (~> 1.0)
+    minitest (5.14.3)
+    pg (1.2.3)
+    rake (13.0.3)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.2)
+    sequel (5.41.0)
+    simplecov (0.21.2)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.2)
+    sqlite3 (1.4.2)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    yard (0.9.26)
+    zeitwerk (2.4.2)
+
+PLATFORMS
+  x86_64-darwin-18
+
+DEPENDENCIES
+  activerecord (>= 5.0, < 6.2)
+  ensql!
+  pg (~> 1.2)
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  sequel (~> 5.10)
+  simplecov (~> 0.21.2)
+  sqlite3 (~> 1.4)
+  yard (~> 0.9.26)
+
+BUNDLED WITH
+   2.2.9

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Daniel Fone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,188 @@
+# Ensql
+
+Ensql lets you write SQL for your application the safe and simple way. Ditch your ORM and embrace the power and
+simplicity of writing plain SQL again.
+
+  * **Write exactly the SQL you want.** Don't limit your queries to what's in the Rails docs. Composable scopes and
+    dynamic includes can cripple performance for non-trivial queries. Break through the ORM abstraction and unlock the
+    power of your database with well-structured SQL and modern database features.
+
+  * **Keep your SQL in its own files.** Just like models or view templates, it makes sense to organise your SQL on its
+    own terms. Storing the queries in their own files encourages better formatted, well commented, literate SQL. It also
+    leverages the syntax highlighting and autocompletion available in your editor. Snippets of HTML scatter through .rb
+    files is an awkward code smell, and SQL is no different.
+
+  * **Do more with your database.** Having a place to organise clean and readable SQL encourages you to make the most of it.
+    In every project I've worked on I've been able to replace useful amounts of imperative ruby logic with a declarative
+    SQL query, improving performance and reducing the opportunity for type errors and untested branches.
+
+  * **Safely interpolate user-supplied data.** Every web developer knows the risks of SQL injection. Ensql takes a
+    fail-safe approach to interpolation, leveraging the underlying database adapter to turn ruby objects into properly
+    quoted SQL literals. As long as user-supplied input is passed as parameters, your queries will be safe and
+    well-formed.
+
+  * **Use your existing database connection.** Ensql works with ActiveRecord or Sequel so you don't need to manage a
+    separate connection to the database.
+
+```ruby
+# Run adhoc statements
+Ensql.run("SET TIME ZONE 'UTC'")
+
+# Run adhoc D/U/I statements and get the affected row count
+Ensql.sql('DELETE FROM logs WHERE timestamp < %{expiry}', expiry: 1.month.ago).count # => 100
+
+# Organise your SQL and fetch results as convenient Ruby primitives
+Ensql.sql_path = 'app/sql'
+Ensql.load_sql('customers/revenue_report', params).rows # => [{ "customer_id" => 100, "revenue" => 1000}, … ]
+
+# Easily retrive results in the simplest shape
+Ensql.sql('SELECT count(*) FROM users').first_field # => 100
+Ensql.sql('SELECT id FROM users').first_column # => [1, 2, 3, …]
+Ensql.sql('SELECT * FROM users WHERE id = %{id}', id: 1).first_row # => { "id" => 1, "email" => "test@example.com" }
+
+# Compose multiple queries with fragment interpolation
+all_results     = Ensql.load_sql('results/all', user_id: user.id)
+current_results = Ensql.load_sql('results/page', results: all_results, page: 2)
+total           = Ensql.load_sql('count', subquery: all_results)
+result = { data: current_results.rows, total: total.first_field }
+```
+
+## Installation
+
+Add this gem to your Gemfile by running:
+
+    $ bundle add ensql
+
+Or install it manually with:
+
+    $ gem install ensql
+
+## Usage
+
+Typically, you don't need to configure anything. Ensql will look for Sequel or ActiveRecord (in that order) and load the
+appropriate adapter. You can override this if you need to, or configure your own adapter. See {Ensql::Adapter} for
+details of the interface.
+
+```ruby
+Ensql.adapter = Ensql::ActiveRecordAdapter # Will use ActiveRecord instead
+```
+
+SQL can be supplied directly or read from a file. You're encouraged to organise all but the most trivial statements in
+their own *.sql files, for the reasons outlined above. You can organise them in whatever way makes most sense for your
+project, but I've found sorting them into directories based on their purpose works well. For example:
+
+    app/sql
+    ├── analytics
+    │   └── results.sql
+    ├── program_details
+    │   ├── widget_query.sql
+    │   ├── item_query.sql
+    │   ├── organisation_query.sql
+    │   └── test_query.sql
+    ├── reports
+    │   ├── csv_export.sql
+    │   ├── filtered.sql
+    │   └── index.sql
+    ├── redaction.sql
+    ├── count.sql
+    └── set_timeout.sql
+
+### Interpolation
+
+All interpolation is marked by `%{}` placeholders in the SQL. This is the only place that user-supplied input should be
+allowed. Only various forms of literal interpolation are supported - identifier interpolation is not supported at this
+stage.
+
+There are 4 types of interpolation, see {Ensql::SQL} for details.
+
+  1. `%{param}` interpolates a Ruby object as a SQL literal.
+  2. `%{(param)}` expands an array into a list of SQL literals.
+  3. `%{param( nested sql )}` interpolates the nested sql with each hash in an array.
+  4. `%{!sql_param}` only interpolates Ensql::SQL objects as SQL fragments.
+
+```ruby
+# Interpolate a literal
+Ensql.sql('SELECT * FROM users WHERE email > %{date}', date: Date.today)
+# SELECT * FROM users WHERE email > '2021-02-22'
+
+# Interpolate a list
+Ensql.sql('SELECT * FROM users WHERE name IN %{(names)}', names: ['user1', 'user2'])
+# SELECT * FROM users WHERE name IN ('user1', 'user2')
+
+# Interpolate a nested VALUES list
+Ensql.sql('INSERT INTO users (name, created_at) VALUES %{users( %{name}, now() )}',
+  users: [{ name: "Claudia Buss" }, { name: "Lundy L'Anglais" }]
+)
+# INSERT INTO users VALUES ('Claudia Buss', now()), ('Lundy L''Anglais', now())
+
+# Interpolate a SQL fragement
+Ensql.sql('SELECT * FROM users ORDER BY %{!orderby}', orderby: Ensql.sql('name asc'))
+# SELECT * FROM users ORDER BY name asc
+```
+
+Interpolation occurs just before the SQL is executed.
+
+### Results
+
+The result of an SQL query will always be a table of rows and columns, and most of the time this is what we want.
+However, sometimes our queries only return a single row, column, or value. For ease-of-use, Ensql supports all 4
+possible access patterns.
+
+1. Table: an array of rows as hashes
+2. Row: a hash of the first row
+3. Column: an array of the first column
+4. Field: an object of the first field
+
+```ruby
+Ensql.sql('SELECT * FROM users').rows # => [{ "id" => 1, …}, {"id" => 2, …}, …]
+Ensql.sql('SELECT count(*) FROM users').first_field # => 100
+Ensql.sql('SELECT id FROM users').first_column # => [1, 2, 3, …]
+Ensql.sql('SELECT * FROM users WHERE id = %{id}', id: 1).first_row # => { "id" => 1, "email" => "test@example.com" }
+```
+
+Depending on the database and adapter, the values will be deserialised into Ruby objects.
+
+```ruby
+Ensql.sql("SELECT now() AS now, CAST('[1,2,3]' AS json)", id: 1).first_row
+# => { "now" => 2021-02-23 21:17:28.105537 +1300, "json" => [1, 2, 3] }
+```
+
+Additionally, you can just return the number of rows affected, or nothing at all.
+
+```ruby
+Ensql.sql('DELETE FROM users WHERE email IS NULL').count # 10
+Ensql.sql('TRUNCATE logs').run # => nil
+Ensql.run('TRUNCATE logs') # same thing
+```
+
+## Things To Improve
+
+- Interpolation syntax. I'd love to ground this in something more reasonable than ruby's custom sprintf format. Maybe we
+  could relate it to the standard SQL `?` or chose an existing named bind parameter format.
+
+- Maybe we could use type hinting like `%{param:pgarray}` to indicated how to serialise the object as a literal.
+
+- Detecting the database and switching to a db specific adapters. This allows us to be more efficient and optimise some
+  literals in a database specific format, e.g. postgres array literals.
+
+- Handling specific connections rather than just grabbing the default.
+
+- Establishing connections directly.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You'll
+need a running postgres database. You can also run `bin/console` for an interactive prompt that will allow you to
+experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
+version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version,
+push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/danielfone/ensql.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ensql"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/ensql.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "lib/ensql/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "ensql"
+  spec.version       = Ensql::VERSION
+  spec.authors       = ["Daniel Fone"]
+  spec.email         = ["daniel@fone.net.nz"]
+
+  spec.summary       = "Write SQL the safe and simple way"
+  spec.description   = "Ditch your ORM and embrace the power and simplicity of writing plain SQL again."
+  spec.homepage      = "https://github.com/danielfone/ensql"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.4.0")
+
+  # spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
+
+  # spec.metadata["homepage_uri"] = spec.homepage
+  # spec.metadata["source_code_uri"] = "TODO: Put your gem's public repo URL here."
+  # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+end

data/lib/ensql.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "ensql/version"
+require_relative "ensql/sql"
+
+#
+# Primary interface for loading, interpolating and executing SQL statements
+# using your preferred database connection. See {.sql} for interpolation details.
+#
+# @example
+#     # Run adhoc statements
+#     Ensql.run("SET TIME ZONE 'UTC'")
+#
+#     # Run adhoc D/U/I statements and get the affected row count
+#     Ensql.sql('DELETE FROM logs WHERE timestamp < %{expiry}', expiry: 1.month.ago).count # => 100
+#
+#     # Organise your SQL and fetch results as convenient Ruby primitives
+#     Ensql.sql_path = 'app/sql'
+#     Ensql.load_sql('customers/revenue_report', params).rows # => [{ "customer_id" => 100, "revenue" => 1000}, … ]
+#
+#     # Easily retrive results in alternative dimensions
+#     Ensql.sql('select count(*) from users').first_field # => 100
+#     Ensql.sql('select id from users').first_column # => [1, 2, 3, …]
+#     Ensql.sql('select * from users where id = %{id}', id: 1).first_row # => { "id" => 1, "email" => "test@example.com" }
+#
+module Ensql
+  # Wrapper for errors raised by Ensql
+  class Error < StandardError; end
+
+  class << self
+
+    # (see SQL)
+    # @return [Ensql::SQL] SQL statement
+    def sql(sql, params={})
+      SQL.new(sql, params)
+    end
+
+    # Path to search for *.sql queries in, defaults to "sql/". For example, if
+    # {sql_path} is set to 'app/queries', `load_sql('users/active')` will read
+    # 'app/queries/users/active.sql'.
+    # @see .load_sql
+    #
+    # @example
+    #   Ensql.sql_path = Rails.root.join('app/queries')
+    #
+    def sql_path
+      @sql_path ||= 'sql'
+    end
+    attr_writer :sql_path
+
+    # Load SQL from a file within {sql_path}. This is the recommended way to
+    # manage SQL in a non-trivial project. For details of how to write
+    # interpolation placeholders, see {SQL}.
+    #
+    # @see .sql_path=
+    # @return [Ensql::SQL]
+    #
+    # @example
+    #   Ensql.load_sql('users/activity', report_params)
+    #   Ensql.load_sql(:upsert_users, imported_users_attrs)
+    #
+    def load_sql(name, params={})
+      path = File.join(sql_path, "#{name}.sql")
+      SQL.new(File.read(path), params, name)
+    end
+
+    # Convenience method to interpolate and run the supplied SQL on the current
+    # adapter.
+    # @return [void]
+    #
+    # @example
+    #   Ensql.run("DELETE FROM users WHERE id = %{id}", id: user.id)
+    #   Ensql.run("ALTER TABLE test RENAME TO old_test")
+    #
+    def run(sql, params={})
+      SQL.new(sql, params).run
+    end
+
+    # Connection adapter to use. Must implement the interface defined in
+    # {Ensql::Adapter}. If not specified, it will try to autoload an adapter
+    # based on the availability of Sequel or ActiveRecord, in that order.
+    #
+    # @example
+    #     require 'sequel'
+    #     Ensql.adapter # => Ensql::SequelAdapter
+    #     Ensql.adapter = Ensql::ActiveRecordAdapter # override adapter
+    #     Ensql.adapter = CustomMSSQLAdapater # supply your own adapter
+    #
+    def adapter
+      @adapter ||= autoload_adapter
+    end
+    attr_writer :adapter
+
+  private
+
+    def autoload_adapter
+      if defined? Sequel
+        require_relative 'ensql/sequel_adapter'
+        SequelAdapter
+      elsif defined? ActiveRecord
+        require_relative 'ensql/active_record_adapter'
+        ActiveRecordAdapter
+      else
+        raise Error, "Couldn't autodetect an adapter, please specify manually."
+      end
+    end
+
+  end
+end

data/lib/ensql/active_record_adapter.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+require_relative 'adapter'
+
+# Ensure our optional dependency has a compatible version
+gem 'activerecord', Ensql::ACTIVERECORD_VERSION
+require 'active_record'
+
+module Ensql
+  #
+  # Implements the {Adapter} interface for ActiveRecord. Requires an
+  # ActiveRecord connection to be configured and established. Uses
+  # ActiveRecord::Base for the connection.
+  #
+  # @example
+  #   require 'active_record'
+  #   ActiveRecord::Base.establish_connection(adapter: 'postgresql', database: 'mydb')
+  #   Ensql.adapter = Ensql::ActiveRecordAdapter
+  #
+  # @see Adapter
+  # @see ACTIVERECORD_VERSION Required gem version
+  #
+  module ActiveRecordAdapter
+    extend Adapter
+
+    # @!visibility private
+    def self.fetch_rows(sql)
+      result = connection.exec_query(sql)
+      result.map do |row|
+        # Deserialize column types if needed
+        row.each_with_object({}) do |(column, value), hash|
+          hash[column] = result.column_types[column] ? result.column_types[column].deserialize(value) : value
+        end
+      end
+    end
+
+    # @!visibility private
+    def self.run(sql)
+      connection.execute(sql)
+    end
+
+    # @!visibility private
+    def self.fetch_count(sql)
+      connection.exec_update(sql)
+    end
+
+    # @!visibility private
+    def self.literalize(value)
+      connection.quote(value)
+    end
+
+    def self.connection
+      ActiveRecord::Base.connection
+    end
+
+    private_class_method :connection
+
+  end
+end

data/lib/ensql/adapter.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "../ensql"
+
+module Ensql
+  #
+  # @abstract Do not use this module directly.
+  #
+  # A common interface for executing SQL statements and retrieving (or not)
+  # their results. Some methods have predefined implementations for convenience
+  # that can be improved in the adapters.
+  #
+  module Adapter
+
+    # @!group 1. Interface Methods
+
+    # @!method literalize(value)
+    #
+    # Convert a Ruby object into a string that can be safely interpolated into
+    # an SQL statement. Strings will be correctly quoted. The precise result
+    # will depend on the adapter and the underlying database driver, but most
+    # RDBMs have limited ways to express literals.
+    #
+    # @return [String] a properly quoted SQL literal
+    #
+    # @see https://www.postgresql.org/docs/13/sql-syntax-lexical.html#SQL-SYNTAX-CONSTANTS
+    # @see https://dev.mysql.com/doc/refman/8.0/en/literals.html
+    # @see https://sqlite.org/lang_expr.html#literal_values_constants_
+    #
+    # @example
+    #   literalize("It's quoted") # => "'It''s quoted'"
+    #   literalize(1.23) # => "1.23"
+    #   literalize(true) # => "1"
+    #   literalize(nil) # => "NULL"
+    #   literalize(Time.now) # => "'2021-02-22 23:44:28.942947+1300'"
+
+    # @!method fetch_rows(sql)
+    #
+    # Execute the query and return an array of rows represented by { column => field }
+    # hashes. Fields should be deserialised depending on the column type.
+    #
+    # @return [Array<Hash>] rows as hashes keyed by column name
+
+    # @!method fetch_count(sql)
+    #
+    # Execute the statement and return the number of rows affected. Typically
+    # used for DELETE, UPDATE, INSERT, but will work with SELECT on some
+    # databases.
+    #
+    # @return <Integer> the number of rows affected by the statement
+
+    # @!method run(sql)
+    #
+    # Execute the statement on the database without returning any result. This
+    # can avoid the overhead of other fetch_* methods.
+    #
+    # @return <void>
+
+    # @!group 2. Predefined Methods
+
+    # Execute the query and yield each resulting row. This should provide a more
+    # efficient method of iterating through large datasets.
+    #
+    # @yield <Hash> row
+    def fetch_each_row(sql, &block)
+      fetch_rows(sql).each(&block)
+    end
+
+    # Execute the query and return only the first row of the result.
+    # @return <Hash>
+    def fetch_first_row(sql)
+      fetch_rows(sql).first
+    end
+
+    # Execute the query and return only the first column of the result.
+    # @return <Array>
+    def fetch_first_column(sql)
+      fetch_rows(sql).map(&:values).map(&:first)
+    end
+
+    # Execute the query and return only the first field of the first row of the result.
+    def fetch_first_field(sql)
+      fetch_first_row(sql)&.values&.first
+    end
+
+  end
+end

data/lib/ensql/sequel_adapter.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+require_relative 'adapter'
+
+# Ensure our optional dependency has a compatible version
+gem 'sequel', Ensql::SEQUEL_VERSION
+require 'sequel'
+
+module Ensql
+  #
+  # Implements the {Adapter} interface for Sequel. Requires a Sequel connection to
+  # be established. Uses the first connection found in Sequel::DATABASES. You
+  # may want to utilize the relevant extensions to make the most of the
+  # deserialization.
+  #
+  # @example
+  #   require 'sequel'
+  #   DB = Sequel.connect('postgres://localhost/mydb')
+  #   DB.extend(:pg_json)
+  #   Ensql.adapter = Ensql::SequelAdapter
+  #
+  # @see Adapter
+  # @see SEQUEL_VERSION Required gem version
+  #
+  module SequelAdapter
+    extend Adapter
+
+    # @!visibility private
+    def self.fetch_rows(sql)
+      db.fetch(sql).map { |r| r.transform_keys(&:to_s) }
+    end
+
+    # @!visibility private
+    def self.fetch_count(sql)
+      db.execute_dui(sql)
+    end
+
+    # @!visibility private
+    def self.run(sql)
+      db << sql
+    end
+
+    # @!visibility private
+    def self.literalize(value)
+      db.literal(value)
+    end
+
+    def self.db
+      Sequel::DATABASES.first or raise Error, "no connection found in Sequel::DATABASES"
+    end
+
+    private_class_method :db
+
+  end
+end

data/lib/ensql/sql.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require_relative "../ensql"
+
+module Ensql
+  #
+  # Encapsulates a plain-text SQL statement and optional parameters to interpolate. Interpolation is indicated by one
+  # of the four placeholder formats:
+  #
+  # 1. **Literal:** `%{param}`
+  #    - Interpolates `param` as a quoted string or a numeric literal depending on the class.
+  #    - `nil` is interpolated as `'NULL'`.
+  #    - Other objects depend on the database and the adapter, but most (like `Time`) are serialised as a quoted SQL
+  #      string.
+  #
+  # 2. **List Expansion:** `%{(param)}`
+  #    - Expands an array to a list of quoted literals.
+  #    - Mostly useful for `column IN (1,2)` or postgres row literals.
+  #    - Empty arrays are interpolated as `(NULL)` for SQL conformance.
+  #    - The parameter will be converted to an Array.
+  #
+  # 3. **Nested List:** `%{param(nested sql)}`
+  #    - Takes an array of parameter hashes and interpolates the nested SQL for each Hash in the Array.
+  #    - Raises an error if param is nil or a non-hash array.
+  #    - Primary useful for SQL `VALUES ()` clauses.
+  #
+  # 4. **SQL Fragment:** `%{!sql_param}`
+  #    - Interpolates the parameter without quoting, as a SQL fragment.
+  #    - The parameter _must_ be an {Ensql::SQL} object or this will raise an error.
+  #    - `nil` will not be interpolated.
+  #    - Allows composition of SQL via subqueries.
+  #
+  # Any placeholders in the SQL must be present in the params hash or a KeyError will be raised during interpolation.
+  #
+  # @example
+  #   # Interpolate a literal
+  #   Ensql.sql('SELECT * FROM users WHERE email > %{date}', date: Date.today)
+  #   # SELECT * FROM users WHERE email > '2021-02-22'
+  #
+  #   # Interpolate a list
+  #   Ensql.sql('SELECT * FROM users WHERE name IN %{(names)}', names: ['user1', 'user2'])
+  #   # SELECT * FROM users WHERE name IN ('user1', 'user2')
+  #
+  #   # Interpolate a nested VALUES list
+  #   Ensql.sql('INSERT INTO users (name, created_at) VALUES %{users( %{name}, now() )}',
+  #     users: [{ name: "Claudia Buss" }, { name: "Lundy L'Anglais" }]
+  #   )
+  #   # INSERT INTO users VALUES ('Claudia Buss', now()), ('Lundy L''Anglais', now())
+  #
+  #   # Interpolate a SQL fragement
+  #   Ensql.sql('SELECT * FROM users ORDER BY %{!orderby}', orderby: Ensql.sql('name asc'))
+  #   # SELECT * FROM users ORDER BY name asc
+  #
+  class SQL
+
+    # @!visibility private
+    def initialize(sql, params={}, name='SQL')
+      @sql = sql
+      @name = name.to_s
+      @params = params
+    end
+
+    # (see Adapter.fetch_rows)
+    def rows
+      adapter.fetch_rows(to_sql)
+    end
+
+    # (see Adapter.fetch_first_row)
+    def first_row
+      adapter.fetch_first_row(to_sql)
+    end
+
+    # (see Adapter.fetch_first_column)
+    def first_column
+      adapter.fetch_first_column(to_sql)
+    end
+
+    # (see Adapter.fetch_first_field)
+    def first_field
+      adapter.fetch_first_field(to_sql)
+    end
+
+    # (see Adapter.fetch_count)
+    def count
+      adapter.fetch_count(to_sql)
+    end
+
+    # (see Adapter.run)
+    def run
+      adapter.run(to_sql)
+      nil
+    end
+
+    # (see Adapter.fetch_each_row)
+    def each_row(&block)
+      adapter.fetch_each_row(to_sql, &block)
+    end
+
+    # Interpolate the params into the SQL statement.
+    #
+    # @raise [Ensql::Error] if any param is missing or invalid.
+    # @return [String] a SQL string with parameters interpolated.
+    def to_sql
+      interpolate(sql, params)
+    end
+
+  private
+
+    attr_reader :sql, :params, :name
+
+    NESTED_LIST  = /%{(\w+)\((.+)\)}/m
+    LIST         = /%{\((\w+)\)}/
+    SQL_FRAGMENT = /%{!(\w+)}/
+    LITERAL      = /%{(\w+)}/
+
+    def interpolate(sql, params)
+      params = params.transform_keys(&:to_s)
+      sql
+        .gsub(NESTED_LIST) { interpolate_nested_list params.fetch($1), $2 }
+        .gsub(LIST) { interpolate_list params.fetch($1) }
+        .gsub(SQL_FRAGMENT) { interpolate_sql params.fetch($1) }
+        .gsub(LITERAL) { literalize params.fetch($1) }
+    rescue => e
+      raise Error, "failed interpolating `#{$1}` into #{name}: #{e}"
+    end
+
+    def interpolate_nested_list(array, nested_sql)
+      raise Error, "array must not be empty" if Array(array).empty?
+
+      Array(array)
+        .map { |attrs| interpolate(nested_sql, Hash(attrs)) }
+        .map { |sql| "(#{sql})" }
+        .join(', ')
+    end
+
+    def interpolate_list(array)
+      return '(NULL)' if Array(array).empty?
+
+      '(' + Array(array).map { |v| literalize v }.join(', ') + ')'
+    end
+
+    def interpolate_sql(sql)
+      return if sql.nil?
+
+      raise "SQL fragment interpolation requires #{self.class}, got #{sql.class}" unless sql.is_a?(self.class)
+
+      sql.to_sql
+    end
+
+    def literalize(value)
+      adapter.literalize value
+    rescue => e
+      raise "error serialising #{value.class} into a SQL literal: #{e}"
+    end
+
+    def adapter
+      Ensql.adapter
+    end
+
+  end
+end

data/lib/ensql/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Ensql
+  # Gem version
+  VERSION = "0.6.0"
+  # Version of the activerecord gem required to use the {ActiveRecordAdapter}
+  ACTIVERECORD_VERSION = ['>= 5.0', '< 6.2'].freeze
+  # Version of the sequel gem required to use the {SequelAdapter}
+  SEQUEL_VERSION = '~> 5.10'
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: ensql
+version: !ruby/object:Gem::Version
+  version: 0.6.0
+platform: ruby
+authors:
+- Daniel Fone
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-02-23 00:00:00.000000000 Z
+dependencies: []
+description: Ditch your ORM and embrace the power and simplicity of writing plain
+  SQL again.
+email:
+- daniel@fone.net.nz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- ".yardopts"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/rspec
+- bin/setup
+- ensql.gemspec
+- lib/ensql.rb
+- lib/ensql/active_record_adapter.rb
+- lib/ensql/adapter.rb
+- lib/ensql/sequel_adapter.rb
+- lib/ensql/sql.rb
+- lib/ensql/version.rb
+homepage: https://github.com/danielfone/ensql
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.9
+signing_key:
+specification_version: 4
+summary: Write SQL the safe and simple way
+test_files: []