ensql 0.6.0 → 0.6.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3097f158523b78a965c84dbf0e79f41ce4be744d5dd0842fc9f5f780ec9b5fba
-  data.tar.gz: e5a123a39ab5f6c1b1911bf46972e441f6bb77d69584fd7bb005192baa5a24c8
+  metadata.gz: a9e2413596055c82bef5870277ed617889235a66bc6854c762886f14783580c7
+  data.tar.gz: 2993ee9976c316a975fd51dc18b53f187298f7e6e2a4627b0b59dc9bd233ec54
 SHA512:
-  metadata.gz: 02a9e0a720bc3b861e27782233fac13ec9e58cfb4b3a6892b2d224f3a0d1de76051f2300370ded32fd9acfe677b71705510e3ee1dd95085cbb7b1fdfd8dda676
-  data.tar.gz: 724701d41daf5554702c6173a2aa6e063034ca3d094ed29eb4cf760c6aba467a13a623f4e5fbc904ca95418a111e281cca4104eb55e8b04ce8d3673323b2d77b
+  metadata.gz: 47ee3648dc665dacc57263befd5c46466f36688138120d7c7b82b5a3464daf3c262e28bcc2eb9dd7f58f6cdea13838a352fe93d9b58f63a9543eca2aadcab40d
+  data.tar.gz: 51afecfd75ac23a5820538cd6c1914d48aeba21fea5e2b8f07a2bb193f4474329b9a6723c43addb5bcfc24642d3ca96c6efd7883ce1762ecc2ee57598f495461

data/.github/workflows/lint.yml

@@ -0,0 +1,52 @@
+---
+###########################
+###########################
+## Linter GitHub Actions ##
+###########################
+###########################
+name: Lint Code Base
+
+#
+# Documentation:
+# https://help.github.com/en/articles/workflow-syntax-for-github-actions
+#
+
+#############################
+# Start the job on all push #
+#############################
+on:
+  pull_request:
+    branches: [master]
+
+###############
+# Set the Job #
+###############
+jobs:
+  build:
+    # Name the Job
+    name: Lint Code Base
+    # Set the agent to run on
+    runs-on: ubuntu-latest
+
+    ##################
+    # Load all steps #
+    ##################
+    steps:
+      ##########################
+      # Checkout the code base #
+      ##########################
+      - name: Checkout Code
+        uses: actions/checkout@v2
+        with:
+          # Full git history is needed to get a proper list of changed files within `super-linter`
+          fetch-depth: 0
+
+      ################################
+      # Run Linter against code base #
+      ################################
+      - name: Lint Code Base
+        uses: github/super-linter@v3
+        env:
+          VALIDATE_ALL_CODEBASE: false
+          DEFAULT_BRANCH: master
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/.github/workflows/specs.yml

@@ -0,0 +1,59 @@
+name: Specs
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+
+    # Service containers to run with `runner-job`
+    services:
+      # Label used to access the service container
+      postgres:
+        # Docker Hub image
+        image: postgres
+        env:
+          POSTGRES_HOST_AUTH_METHOD: trust
+          POSTGRES_USER: runner
+        # Set health checks to wait until postgres has started
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          # Maps tcp port 5432 on service container to the host
+          - 5432:5432
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - ruby-version: 3.0
+            gemfile: Gemfile
+          - ruby-version: 2.5
+            gemfile: gemfiles/maintained.gemfile
+          - ruby-version: 2.4.0
+            gemfile: gemfiles/minimum.gemfile
+
+
+    env: # $BUNDLE_GEMFILE must be set at the job level, so it is set for all steps
+      BUNDLE_GEMFILE: ${{ matrix.gemfile }}
+      COVERAGE: ${{ matrix.gemfile == 'Gemfile' }}
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+    - name: Install dependencies
+      run: bundle install
+    - name: Run tests
+      run: bundle exec rake

data/.yardopts

@@ -1 +1,3 @@
 --markup markdown
+-
+CHANGELOG.md

data/CHANGELOG.md

@@ -1,5 +1,35 @@
-## [Unreleased]
+# Change Log
 
-## [0.1.0] - 2021-02-15
+## [0.6.5] - 2021-03-24
+
+- Raises `Ensql::Error` with a more helpful message when `load_sql` can't find a file.
+
+## [0.6.4] - 2021-03-12
+
+- Exposes `PostgresAdapter#query_type_map` to extend PG type mapping.
+- Defers building type maps for PostgreSQL connections, to avoid bugs with ActiveRecord.
+
+## [0.6.3] - 2021-03-11
+
+- Supports transaction flow control using any flavour SQL with `Ensql.transaction` and `Ensql.rollback!`.
+- Eliminates cyclic dependencies for `Error` and `Ensql.adapter`.
+- Tidies specs.
+- Adopts [standardrb](https://github.com/testdouble/standard).
+
+## [0.6.2] - 2021-03-09
+
+- Adds a specialised adapter for PostgreSQL.
+- Uses instances instead of modules for SequelAdapter and ActiveRecordAdapter. The use of the (now) classes as adapters is deprecated.
+- Adds connection pool wrappers for ActiveRecord and Sequel.
+- Ensures SQL#each_row returns nil.
+- Makes adapter attribute thread-safe.
+
+## [0.6.1] - 2021-02-25
+
+- Enables the use of streaming with the SequelAdapter
+- Improves performance of #first_row and #each_row
+- Tests against Sequel 5.9
+
+## [0.6.0] - 2021-02-15
 
 - Initial release

data/Gemfile

@@ -5,17 +5,11 @@ 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"
+group :adapters do
+  require_relative "lib/ensql/version"
+  gem "activerecord", Ensql::SUPPORTED_ACTIVERECORD_VERSIONS
+  gem "sequel", Ensql::SUPPORTED_SEQUEL_VERSIONS
+  gem "sqlite3", "~> 1.4"
+  gem "pg", "~> 1.2"
+  gem "sequel_pg"
+end

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    ensql (0.6.0)
+    ensql (0.6.5)
+      connection_pool (>= 0.9.3, < 3)
 
 GEM
   remote: https://rubygems.org/
@@ -18,11 +19,12 @@ GEM
       tzinfo (~> 2.0)
       zeitwerk (~> 2.3)
     concurrent-ruby (1.1.8)
+    connection_pool (2.2.3)
     diff-lcs (1.4.4)
     docile (1.3.5)
     i18n (1.8.9)
       concurrent-ruby (~> 1.0)
-    minitest (5.14.3)
+    minitest (5.14.4)
     pg (1.2.3)
     rake (13.0.3)
     rspec (3.10.0)
@@ -39,6 +41,9 @@ GEM
       rspec-support (~> 3.10.0)
     rspec-support (3.10.2)
     sequel (5.41.0)
+    sequel_pg (1.14.0)
+      pg (>= 0.18.0, != 1.2.0)
+      sequel (>= 4.38.0)
     simplecov (0.21.2)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
@@ -53,6 +58,7 @@ GEM
 
 PLATFORMS
   x86_64-darwin-18
+  x86_64-linux
 
 DEPENDENCIES
   activerecord (>= 5.0, < 6.2)
@@ -60,7 +66,8 @@ DEPENDENCIES
   pg (~> 1.2)
   rake (~> 13.0)
   rspec (~> 3.0)
-  sequel (~> 5.10)
+  sequel (~> 5.9)
+  sequel_pg
   simplecov (~> 0.21.2)
   sqlite3 (~> 1.4)
   yard (~> 0.9.26)

data/README.md

@@ -1,38 +1,41 @@
 # 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.
+[![Gem Version](https://badge.fury.io/rb/ensql.svg)](https://badge.fury.io/rb/ensql)
+[![Ruby](https://github.com/danielfone/ensql/actions/workflows/specs.yml/badge.svg)](https://github.com/danielfone/ensql/actions/workflows/specs.yml)
+[![Maintainability](https://api.codeclimate.com/v1/badges/a4ab07e1a03c4d1e8043/maintainability)](https://codeclimate.com/github/danielfone/ensql/maintainability)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
 
-  * **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.
+Ensql provides a light-weight wrapper over your existing database connections, letting you write plain SQL for your
+application safely and simply. Escape your ORM and embrace the power and ease of writing SQL again.
 
-  * **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.
+* **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.
 
-  * **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.
+* **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 scattered through .rb
+  files is an awkward code smell, and SQL is no different.
 
-  * **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.
+* **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 substantial amounts of imperative Ruby logic with a
+  declarative SQL query, improving performance and reducing the opportunity for type errors and untested branches.
 
-  * **Use your existing database connection.** Ensql works with ActiveRecord or Sequel so you don't need to manage a
-    separate connection to the database.
+* **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.
 
-```ruby
-# Run adhoc statements
-Ensql.run("SET TIME ZONE 'UTC'")
+* **Use your existing database connection.** As well as using PostrgeSQL connections directly, Ensql can work with
+  ActiveRecord or Sequel so you don't need to manage a separate connection to the database.
 
-# 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
+```ruby
+# Safely interpolate parameters into adhoc statements with correct quoting and escaping.
+Ensql.run("INSERT INTO users (email) VALUES (%{email})", email: params[:email])
+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'
+# Organise your SQL and fetch results as convenient Ruby primitives.
+Ensql.sql_path = 'app/sql' # Defaults to './sql'. This can be set in an initializer or similar.
 Ensql.load_sql('customers/revenue_report', params).rows # => [{ "customer_id" => 100, "revenue" => 1000}, … ]
 
 # Easily retrive results in the simplest shape
@@ -46,59 +49,87 @@ 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 }
 ```
+Links:
+
+* [Source Code](https://github.com/danielfone/ensql)
+* [API Documentation](https://rubydoc.info/gems/ensql)
+* [Ruby Gem](https://rubygems.org/gems/ensql)
 
 ## Installation
 
 Add this gem to your Gemfile by running:
 
-    $ bundle add ensql
-
+```shell
+bundle add ensql
+```
 Or install it manually with:
 
-    $ gem install ensql
+```shell
+gem install ensql
+```
+Ensql requires:
+
+* ruby >= 2.4.0
+* sequel >= 5.9 if using SequelAdapter
+* activerecord >= 5.0 if using ActiveRecordAdapter
+* pg >= 0.19 if using PostgresAdapter
 
 ## 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.
+appropriate adapter. You can override this if the wrong adapter is autoconfigured, or if you're using PostgreSQL and
+want to use the much faster and more convenient PostgresAdapter.
 
 ```ruby
-Ensql.adapter = Ensql::ActiveRecordAdapter # Will use ActiveRecord instead
+# Use ActiveRecord instead of Sequel if both are available
+Ensql.adapter = Ensql::ActiveRecordAdapter.new
+
+# Use the PostgreSQL specific adapter, with ActiveRecord's connection pool
+Ensql.adapter = Ensql::PostgresAdapter.new Ensql::ActiveRecordAdapter.pool
+
+# Use the PostgreSQL specific adapter, with Sequel's connection pool
+DB = Sequel.connect(ENV['DATABASE_URL'])
+Ensql.adapter = Ensql::PostgresAdapter.new Ensql::SequelAdapter.pool(DB)
+
+# Use the PostgreSQL specific adapter, with our own thread-safe connection pool
+Ensql.adapter = Ensql::PostgresAdapter.pool { PG.connect ENV['DATABASE_URL'] }
 ```
+You can also supply your own adapter (see [the API docs](https://rubydoc.info/gems/ensql/Ensql/Adapter) for details of the interface).
 
 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
+```text
+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.
+allowed. Only literal interpolation is supported - identifier interpolation is not supported at this stage.
 
-There are 4 types of interpolation, see {Ensql::SQL} for details.
+There are 3 types of safe (correctly quoted/escaped) interpolation:
 
-  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.
+  1. `%{param}` interpolates a Ruby object as a single SQL literal.
+  2. `%{(param)}` expands a Ruby Array into a list of SQL literals.
+  3. `%{param( nested sql )}` interpolates an Array of Hashes into the nested sql with each hash in an array.
+
+In addition you can interpolate raw SQL with `%{!sql_param}`. It's up to you to ensure this is safe!
 
 ```ruby
 # Interpolate a literal
@@ -115,12 +146,12 @@ Ensql.sql('INSERT INTO users (name, created_at) VALUES %{users( %{name}, now() )
 )
 # INSERT INTO users VALUES ('Claudia Buss', now()), ('Lundy L''Anglais', now())
 
-# Interpolate a SQL fragement
+# Interpolate a raw SQL fragment without quoting. Use with care!
 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.
+See [the API docs](https://rubydoc.info/gems/ensql/Ensql/SQL) for details.
 
 ### Results
 
@@ -155,6 +186,22 @@ Ensql.sql('TRUNCATE logs').run # => nil
 Ensql.run('TRUNCATE logs') # same thing
 ```
 
+### Transactions
+
+Ensql encourages you to write pure unmediated SQL with very little procedural management. However, transaction blocks
+are the exception to this rule. Any exceptions inside a transaction block will trigger a rollback, otherwise the block
+will be committed. The block uses SQL-standard commands by default, but custom SQL can be supplied.
+
+```ruby
+Ensql.transaction(start: 'BEGIN ISOLATION LEVEL SERIALIZABLE') do
+  do_thing1
+  result = check_thing2
+  Ensql.rollback! unless result
+  do_thing3
+end
+```
+See [the API docs](https://rubydoc.info/gems/ensql/Ensql#transaction-class_method) for details.
+
 ## Things To Improve
 
 - Interpolation syntax. I'd love to ground this in something more reasonable than ruby's custom sprintf format. Maybe we
@@ -163,25 +210,38 @@ Ensql.run('TRUNCATE logs') # same thing
 - 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.
+  literals in a database specific format, e.g. PostgreSQL array literals.
 
-- Handling specific connections rather than just grabbing the default.
-
-- Establishing connections directly.
+- Proper single-row mode support for the pg adapter
 
 ## 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
+need a running PostgreSQL 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).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### PR Checklist
+
+- [ ] Confirm the code works locally
+- [ ] Update any relevant documentation
+- [ ] Try to break it
+- [ ] Tests the described behaviour
+- [ ] Add a changelog entry (with version bump if needed)
+
+### Release Checklist
+
+- [ ] Review changes in master since last release, especially the public API.
+- [ ] Ensure documentation is up to date.
+- [ ] Bump appropriate part of version in `version.rb`.
+- [ ] Update the spec version in each `.lock`.
+- [ ] Update `Changelog.md` with summary of new version.
+- [ ] Run `rake release` to 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.
+Bug reports and pull requests are welcome on GitHub at <https://github.com/danielfone/ensql>.
 
 ## License