db 0.5.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6969650d4cd9fde35de4541f64d10b67b78f0e55e42d4f4b6d6daff54022ed62
-  data.tar.gz: f97c19216d6ccaa88fc5fb37c71e40c614e4e843c928df37edfb1723d4afbeb5
+  metadata.gz: 4cde27a0a6510347217c2823470f138bd5d35bac35292f0ff7a085ec5c37c26c
+  data.tar.gz: 4e597ecdbfb05092a2a5c7f3f57ea2816ac16e7cfd05f5b1ca92ffeabe298fc0
 SHA512:
-  metadata.gz: 04fa032c0a0d79283fa5d51fff48ecac9d8dd5d04b1f0e7cfef9b5d279d63f7d1b947185ff8a257b1df0e031cdae7b7b548d75a4bbe6a7d85889764fb1c83e30
-  data.tar.gz: e695f898cf1e6b37e130f3addd3d8631a3451f62cba9b49ec52584b018a2d8900ed5ef60c5175a10e654d9b034295e244ffafddfb8ba3be1505b633dc5cd2696
+  metadata.gz: 829dd25eeaf87078bfaee1f719040abae45fcd531cd00e68dc57e6abc6cad637fbd95e60bcd0305945f580eba893ea52c5a9f341dcca9e01b5f963b64256209c
+  data.tar.gz: 2a6726e95b389ad06810f0c14cd4abdb90997aa3bfe419aff8a284feff613c879b36d170f7392078e078719e831070419535258fd65a1b4e42c593a0015435a1

data/lib/db/adapters.rb

@@ -1,12 +1,43 @@
+# frozen_string_literal: true
+
+# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# 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.
 
 module DB
+	# A global map of registered adapters.
+	# e.g. `DB::Adapters.register(:mariadb, DB::MariaDB::Adapter)`
 	module Adapters
 		@adapters = {}
 		
+		# Register the adapter class to the specified name.
+		# @parameter name [Symbol] The adapter name.
+		# @parameter adapter [Class] The adapter class.
 		def self.register(name, adapter)
 			@adapters[name] = adapter
 		end
 		
+		# Enumerate all registered adapters.
+		# @yields {|name, adapter| ...} The adapters if a block is given.
+		# 	@parameter name [Symbol] The adapter name.
+		# 	@parameter adapter [Class] The adapter class
+		# @returns [Enumerator(Symbol, Class)] If no block is given.
 		def self.each(&block)
 			@adapters.each(&block)
 		end

data/lib/db/client.rb

@@ -24,56 +24,55 @@ require 'async/io'
 require 'async/io/stream'
 require 'async/pool/controller'
 
-require_relative 'context/query'
+require_relative 'context/session'
 require_relative 'context/transaction'
 
 module DB
+	# Binds a connection pool to the specified adapter.
 	class Client
+		# Initialize the client and internal connection pool using the specified adapter.
+		# @parameter adapter [Object] The adapter instance.
 		def initialize(adapter, **options)
 			@adapter = adapter
 			
 			@pool = connect(**options)
 		end
 		
-		attr :endpoint
-		attr :protocol
-		
-		# @return [client] if no block provided.
-		# @yield [client, task] yield the client in an async task.
-		def self.open(*arguments, &block)
-			client = self.new(*arguments)
-			
-			return client unless block_given?
-			
-			Async do |task|
-				begin
-					yield client, task
-				ensure
-					client.close
-				end
-			end.wait
-		end
+		# The adapter used for making connections.
+		# @attribute [Object]
+		attr :adapter
 		
+		# Close all open connections in the connection pool.
 		def close
 			@pool.close
 		end
 		
-		def call(statement = nil, **options)
-			query = Context::Query.new(@pool, **options)
+		# Acquires a connection and sends the specified statement if given.
+		# @parameters statement [String | Nil] An optional statement to send.
+		# @yields {|session| ...} A connected session if a block is given. Implicitly closed.
+		# 	@parameter session [Context::Session]
+		# @returns [Context::Session] A connected session if no block is given.
+		def session(statement = nil, **options)
+			session = Context::Session.new(@pool, **options)
 			
 			if statement
-				query.send_query(statement)
+				session.send_query(statement)
 			end
 			
-			return query unless block_given?
+			return session unless block_given?
 			
 			begin
-				yield query
+				yield session
 			ensure
-				query.close
+				session.close
 			end
 		end
 		
+		# Acquires a connection and starts a transaction.
+		# @parameters statement [String | Nil] An optional statement to send. Defaults to `"BEGIN"`.
+		# @yields {|session| ...} A connected session if a block is given. Implicitly commits, or aborts the connnection if an exception is raised.
+		# 	@parameter session [Context::Transaction]
+		# @returns [Context::Transaction] A connected and started transaction if no block is given.
 		def transaction(statement = "BEGIN", **options)
 			transaction = Context::Transaction.new(@pool, **options)
 			

data/lib/db/context/{query.rb → session.rb}

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# Copyright, 2018, by Huba Nagy.
+# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -21,16 +20,22 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
+require_relative '../query'
+
 module DB
 	module Context
-		class Query
+		# A connected context for sending queries and reading results.
+		class Session
+			# Iniitalize the query context attached to the given connection pool.
 			def initialize(pool, **options)
 				@pool = pool
 				@connection = pool.acquire
 			end
 			
+			# The underlying connection.
 			attr :connection
 			
+			# Flush the connection and then return it to the connection pool.
 			def close
 				if @connection
 					self.flush
@@ -41,20 +46,43 @@ module DB
 				end
 			end
 			
+			def clause(fragment = String.new)
+				Query.new(self, fragment)
+			end
+			
+			def query(fragment = String.new, **parameters)
+				if parameters.empty?
+					Query.new(self, fragment)
+				else
+					Query.new(self).interpolate(fragment, **parameters)
+				end
+			end
+			
+			# Send a query to the server.
+			# @parameter statement [String] The SQL query to send.
 			def send_query(statement, **options)
+				# Console.logger.info(self, statement)
 				@connection.send_query(statement, **options)
 			end
 			
+			# Read the next result. Sending a query usually generates 1 or more results.
+			# @returns [Enumerable] The resulting records.
 			def next_result
 				@connection.next_result
 			end
 			
+			# Send a query to the server and read the next result.
+			# @returns [Enumerable] The resulting records.
 			def call(statement, **options)
+				# Console.logger.info(self, statement)
 				@connection.send_query(statement, **options)
 				
 				return @connection.next_result
 			end
 			
+			# Enumerate all results.
+			# @yields {|result ...} The results if a block is given.
+			# 	@parameter result [Enumerable]
 			def results
 				while result = self.next_result
 					yield result
@@ -63,6 +91,7 @@ module DB
 				return nil
 			end
 			
+			# Flush all outstanding results.
 			def flush
 				until @connection.next_result.nil?
 				end

data/lib/db/context/transaction.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# Copyright, 2018, by Huba Nagy.
+# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -21,25 +20,29 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-require_relative 'query'
+require_relative 'session'
 
 module DB
 	module Context
-		class Transaction < Query
+		class Transaction < Session
+			# Commit the transaction and return the connection to the connection pool.
 			def commit
 				self.call("COMMIT")
 				self.close
 			end
 			
+			# Abort the transaction and return the connection to the connection pool.
 			def abort
 				self.call("ROLLBACK")
 				self.close
 			end
 			
+			# Mark a savepoint in the transaction.
 			def savepoint(name)
 				self.call("SAVEPOINT #{name}")
 			end
 			
+			# Return back to a previously registered savepoint.
 			def rollback(name)
 				self.call("ROLLBACK #{name}")
 			end

data/lib/db/query.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# 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.
+
+module DB
+	# Represents one or more identifiers for databases, tables or columns.
+	class Identifier < Array
+		def self.coerce(name_or_identifier)
+			case name_or_identifier
+			when Identifier
+				name_or_identifier
+			when Array
+				self.new(name_or_identifier)
+			when Symbol
+				self[name_or_identifier]
+			else
+				self[name_or_identifier.to_sym]
+			end
+		end
+		
+		def append_to(query)
+			query.identifier(self)
+		end
+	end
+	
+	# A mutable query builder.
+	class Query
+		# Create a new query builder attached to the specified session.
+		# @parameter session [Context::Session] the connected session which is used for escaping arguments.
+		def initialize(session, buffer = String.new)
+			@session = session
+			@connection = session.connection
+			@buffer = +buffer
+		end
+		
+		# Append a raw textual clause to the query buffer.
+		# @parameter value [String] A raw SQL string, e.g. `WHERE x > 10`.
+		# @returns [Query] The mutable query itself.
+		def clause(value)
+			@buffer << ' ' unless @buffer.end_with?(' ') || @buffer.empty?
+			
+			@buffer << value
+			
+			return self
+		end
+		
+		# Append a literal value to the query buffer.
+		# Escapes the field according to the requirements of the underlying connection.
+		# @parameter value [Object] Any kind of object, passed to the underlying database connection for conversion to a string representation.
+		# @returns [Query] The mutable query itself.
+		def literal(value)
+			@buffer << ' ' unless @buffer.end_with?(' ')
+			
+			@connection.append_literal(value, @buffer)
+			
+			return self
+		end
+		
+		# Append an identifier value to the query buffer.
+		# Escapes the field according to the requirements of the underlying connection.
+		# @parameter value [String | Symbol | DB::Identifier] Passed to the underlying database connection for conversion to a string representation.
+		# @returns [Query] The mutable query itself.
+		def identifier(value)
+			@buffer << ' ' unless @buffer.end_with?(' ')
+			
+			@connection.append_identifier(value, @buffer)
+			
+			return self
+		end
+		
+		# Interpolate a query fragment with the specified parameters.
+		# The parameters are escaped before being appended.
+		#
+		# @parameter fragment [String] A fragment of SQL including placeholders, e.g. `WHERE x > %{column}`.
+		# @parameter parameters [Hash] The substitution parameters.
+		# @returns [Query] The mutable query itself.
+		def interpolate(fragment, **parameters)
+			parameters.transform_values! do |value|
+				case value
+				when Symbol, Identifier
+					@connection.append_identifier(value)
+				else
+					@connection.append_literal(value)
+				end
+			end
+			
+			@buffer << sprintf(fragment, parameters)
+			
+			return self
+		end
+		
+		def key_column(*arguments, **options)
+			@buffer << @connection.key_column(*arguments, **options)
+			
+			return self
+		end
+		
+		# Send the query to the remote server to be executed. See {Context::Session#send_query} for more details.
+		def send
+			@session.send_query(@buffer)
+		end
+		
+		# Send the query to the remote server to be executed. See {Context::Session#call} for more details.
+		# @returns [Enumerable] The resulting records.
+		def call
+			@session.call(@buffer)
+		end
+		
+		def to_s
+			@buffer
+		end
+		
+		def inspect
+			"\#<#{self.class} #{@buffer.inspect}>"
+		end
+	end
+end

data/lib/db/version.rb

@@ -21,5 +21,5 @@
 # THE SOFTWARE.
 
 module DB
-	VERSION = "0.5.0"
+	VERSION = "0.8.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: db
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Samuel Williams
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-07-06 00:00:00.000000000 Z
+date: 2021-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-io
@@ -39,21 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: bake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: bake-bundler
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -80,20 +66,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -110,25 +82,20 @@ dependencies:
         version: '3.0'
 description:
 email:
-- samuel.williams@oriontransfer.co.nz
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/development.yml"
-- ".gitignore"
-- ".rspec"
-- README.md
-- db.gemspec
-- gems.rb
 - lib/db.rb
 - lib/db/adapters.rb
 - lib/db/client.rb
-- lib/db/context/query.rb
+- lib/db/context/session.rb
 - lib/db/context/transaction.rb
+- lib/db/query.rb
 - lib/db/version.rb
 homepage: https://github.com/socketry/db
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message:
 rdoc_options: []
@@ -138,14 +105,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
 summary: A low level database access gem.

data/.github/workflows/development.yml

@@ -1,65 +0,0 @@
-name: Development
-
-on: [push, pull_request]
-
-jobs:
-  test:
-    runs-on: ${{matrix.os}}-latest
-    continue-on-error: ${{matrix.experimental}}
-    
-    strategy:
-      matrix:
-        os:
-          - ubuntu
-        
-        ruby:
-          - 2.5
-          - 2.6
-          - 2.7
-        
-        experimental: [false]
-        env: [""]
-        
-        include:
-          - os: ubuntu
-            ruby: truffleruby
-            experimental: true
-          - os: ubuntu
-            ruby: jruby
-            experimental: true
-            env: JRUBY_OPTS="--debug -X+O"
-          - os: ubuntu
-            ruby: head
-            experimental: true
-    
-    steps:
-    - uses: actions/checkout@v2
-    - uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{matrix.ruby}}
-    
-    - name: Install dependencies
-      run: ${{matrix.env}} bundle install
-    
-    - name: Preparing Postgres (ubuntu)
-      if: matrix.os == 'ubuntu'
-      run: |
-        sudo apt-get install postgresql postgresql-contrib
-        echo "local all all trust" | sudo tee -a /var/lib/postgresql/12/main/pg_hba.conf
-        sudo systemctl restart postgresql
-        sudo -u postgres createuser -s -d $(id -un)
-        sudo -u postgres createdb test
-    
-    - name: Preparing MariaDB (ubuntu)
-      if: matrix.os == 'ubuntu'
-      run: |
-        sudo apt-get install libmariadb-dev
-        sudo systemctl start mysql
-        mysql -uroot -proot -e "STATUS"
-        mysql -uroot -proot -e "CREATE USER '$(id -un)'@'localhost'; GRANT ALL ON *.* TO '$(id -un)'@'localhost'; FLUSH PRIVILEGES; CREATE DATABASE test;"
-    
-    - name: Run tests
-      timeout-minutes: 5
-      run: |
-        export MYSQL_UNIX_PORT=/var/run/mysqld/mysqld.sock
-        ${{matrix.env}} bundle exec rspec

data/.gitignore

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

data/.rspec

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

data/README.md

@@ -1,35 +0,0 @@
-# Db
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/db`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'db'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install db
-
-## Usage
-
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. 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 tags, 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/[USERNAME]/db.

data/db.gemspec

@@ -1,29 +0,0 @@
-
-require_relative "lib/db/version"
-
-Gem::Specification.new do |spec|
-	spec.name = "db"
-	spec.version = DB::VERSION
-	spec.authors = ["Samuel Williams"]
-	spec.email = ["samuel.williams@oriontransfer.co.nz"]
-	
-	spec.summary = "A low level database access gem."
-	spec.homepage = "https://github.com/socketry/db"
-	
-	spec.files = Dir.chdir(__dir__) do
-		`git ls-files -z`.split("\x0").reject {|f| f.match(%r{^(test|spec|features)/})}
-	end
-	
-	spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-	spec.require_paths = ["lib"]
-	
-	spec.add_dependency "async-io"
-	spec.add_dependency "async-pool"
-	
-	spec.add_development_dependency "bake"
-	spec.add_development_dependency "bake-bundler"
-	
-	spec.add_development_dependency "covered"
-	spec.add_development_dependency "bundler", "~> 2.0"
-	spec.add_development_dependency "rspec", "~> 3.0"
-end

data/gems.rb

@@ -1,15 +0,0 @@
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in db.gemspec
-gemspec
-
-group :adapters do
-	gem "db-postgres"#, path: "../db-postgres"
-	gem "db-mariadb"#, path: "../db-mariadb"
-end
-
-group :benchmark do
-	gem "benchmark-ips"
-	gem "mysql2"
-	gem "pg"
-end