db 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6969650d4cd9fde35de4541f64d10b67b78f0e55e42d4f4b6d6daff54022ed62
-  data.tar.gz: f97c19216d6ccaa88fc5fb37c71e40c614e4e843c928df37edfb1723d4afbeb5
+  metadata.gz: 1149f3daa25b0832441ed9c08eeba087be727167ff5ee12b33e2d96a2ae54138
+  data.tar.gz: efc580a879bc9d91c46bc631a76b5761f276ce24e531daf20bc797e75ea06273
 SHA512:
-  metadata.gz: 04fa032c0a0d79283fa5d51fff48ecac9d8dd5d04b1f0e7cfef9b5d279d63f7d1b947185ff8a257b1df0e031cdae7b7b548d75a4bbe6a7d85889764fb1c83e30
-  data.tar.gz: e695f898cf1e6b37e130f3addd3d8631a3451f62cba9b49ec52584b018a2d8900ed5ef60c5175a10e654d9b034295e244ffafddfb8ba3be1505b633dc5cd2696
+  metadata.gz: 104d7bce64424a3666c1a699e8b06c655a37dc44f5b025530a422188d386c3b84ad00ccc314ba8d0a4f5b9c931375c21c0799e6d0868064d012220d5fc26e6cd
+  data.tar.gz: 856321b31c8894f5fe914100b5892cc160c812f56b6bf0cc8ec4f7bc159d9535195bf5c8d406e0ca1116b6fc4d73ecc2527b03d630bf336c6d768060c11918c2

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

@@ -28,36 +28,30 @@ require_relative 'context/query'
 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
 		
+		# 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::Query]
+		# @returns [Context::Query] A connected session if no block is given.
 		def call(statement = nil, **options)
 			query = Context::Query.new(@pool, **options)
 			
@@ -74,6 +68,11 @@ module DB
 			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

@@ -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
@@ -23,14 +22,18 @@
 
 module DB
 	module Context
+		# A connected context for sending queries and reading results.
 		class Query
+			# 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 +44,29 @@ module DB
 				end
 			end
 			
+			# Send a query to the server.
+			# @parameter statement [String] The SQL query to send.
 			def send_query(statement, **options)
 				@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)
 				@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 +75,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
@@ -26,20 +25,24 @@ require_relative 'query'
 module DB
 	module Context
 		class Transaction < Query
+			# 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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: db
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Samuel Williams
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-07-06 00:00:00.000000000 Z
+date: 2020-07-07 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,17 +82,10 @@ 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
@@ -128,7 +93,8 @@ files:
 - lib/db/context/transaction.rb
 - lib/db/version.rb
 homepage: https://github.com/socketry/db
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message:
 rdoc_options: []
@@ -138,7 +104,7 @@ 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:
   - - ">="

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