db 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1149f3daa25b0832441ed9c08eeba087be727167ff5ee12b33e2d96a2ae54138
-  data.tar.gz: efc580a879bc9d91c46bc631a76b5761f276ce24e531daf20bc797e75ea06273
+  metadata.gz: def9c55f80bfb45766ffd249a05f9c449432259bf15e57a8e00b59dabc75dc91
+  data.tar.gz: 8632f9630388c98ab4587c708acf8c1506edddcd8c29284a2b66446f4dbf799e
 SHA512:
-  metadata.gz: 104d7bce64424a3666c1a699e8b06c655a37dc44f5b025530a422188d386c3b84ad00ccc314ba8d0a4f5b9c931375c21c0799e6d0868064d012220d5fc26e6cd
-  data.tar.gz: 856321b31c8894f5fe914100b5892cc160c812f56b6bf0cc8ec4f7bc159d9535195bf5c8d406e0ca1116b6fc4d73ecc2527b03d630bf336c6d768060c11918c2
+  metadata.gz: 11f1c66a99d6dec1346f890c798efa65b77a3750e581a67dbcbbf20d970b6e5c30b337a4aeafd3d8375d68151585b6d74edc6b6cafaee4c539f6e857748424c0
+  data.tar.gz: eb43e9b1077fc237acc6cde551aeaae5299ce8fa1f6b5580b5672ae1a3ecd9d5dcee6195344b56c6b5256af817c331af39fc79a0a3a5a60e0564c21ff4b0aa62

data/lib/db/client.rb

@@ -24,7 +24,7 @@ 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
@@ -50,21 +50,21 @@ module DB
 		# 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)
+		# 	@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
 		

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

@@ -20,10 +20,12 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
+require_relative '../query'
+
 module DB
 	module Context
 		# A connected context for sending queries and reading results.
-		class Query
+		class Session
 			# Iniitalize the query context attached to the given connection pool.
 			def initialize(pool, **options)
 				@pool = pool
@@ -44,9 +46,22 @@ module DB
 				end
 			end
 			
+			def clause(*arguments)
+				Query.new(self).clause(*arguments)
+			end
+			
+			def query(fragment, **parameters)
+				if parameters.empty?
+					Query.new(self).clause(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
 			
@@ -59,6 +74,7 @@ module DB
 			# 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

data/lib/db/context/transaction.rb

@@ -20,11 +20,11 @@
 # 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")

data/lib/db/query.rb

@@ -0,0 +1,112 @@
+# 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
+		# Construct an identifier from an array of names.
+		# e.g. `DB::Identifier[:mytable, :mycolumn]`
+		#
+		# @parameter names [Array] The array of names.
+		def self.[](*names)
+			self.new(names)
+		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)
+			@session = session
+			@connection = session.connection
+			@buffer = String.new
+		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 << 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
+		
+		# 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
+	end
+end

data/lib/db/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: db
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -89,8 +89,9 @@ files:
 - 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: