db-postgres 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dda5680ffcdd6de60c833681366779e9859e497ae9b367d3bcf3a84c68f15771
-  data.tar.gz: c9d19d688ed762c97539318765b149e477d47e0cf374b774810cd0cd830336ac
+  metadata.gz: 260820a8ff70bad753039f66377343b0740b0925cd7f8e54b4a6b5ccc6ff01e5
+  data.tar.gz: 6e65a9610fd6f07c3b026852e27f7b5d03aa0a08f2a04520c493d6d2f08a56ff
 SHA512:
-  metadata.gz: a50d56b3495fa91827ff03e1cf9da2667819f3b23e982ed2619bf5633e53222fc09218e4526c3941ee906b65976c8d1796499405a4f2b85cf3cb3ccce20de58c
-  data.tar.gz: 68c172f739f907eca43c9270c9053ce1e0ab4d33da5c8dbcf75852e73bcb4da7d52233abcf44ef628afccfa011d2d8032391e17eec28a4a27eaacf0d59fc7c53
+  metadata.gz: 726edf7a8bc3bbfe27a4faa1c1450dfaadace53b90a198e92fcff8558f9ca484012fd2b0ea9272421f3ffaf4b2fcec768cf90cfcbf7abdfd0d3b72b08271e454
+  data.tar.gz: 4fc82ac8ffdb9908c13b2fea11b69c8a4f83a4a3c8d99eab75b92c4c043d901d025b6bcf115a7f4cf3d86bc8591a30055afc38869ceadbd7be8ed4f298505a6e

checksums.yaml.gz.sig

@@ -1,2 +1,3 @@
-�_��N@Z o�3����C*ɡ�e\��o�'h}��<�a�n�316P�?�E#5��>z_��"��
-Ĭ9o%:�Fc>�������~�%~v�H9���eE2��u��+_�b��A�q��=O�������d�fۀ1��y�lA�̮�C$$�Lp���pŠu��
>CZ����z���?}�b� mx��W�cɄў#�Fp��_�;�^��Φ
+C+gY]�e�� 8/}��
��1	���L̍�t��Y��5����r���ݴ��lO�=�`�R����?�wF�X.j�o]Q�1���!�-Y�5�-b�R3�.z,�a� ���0�b�Ȋ�:qv����/��փ;L�޾��xa+r�=
+����Q諥��������n��t����!�?t�F�1����ߚl���<�&C[Q��g!##m��6��+ڵ��悀8p�#@�ƥsŊw�tM)paMaR��
+v�'R G����ԱKD�����[����(|�NV,OV=5�.C稦����� [c`qj%��Փk�"�fs��Pt���4d:�g3�/�XI�JbW��H���d��QMز��0V��sYj�K��ثɾ

data/lib/db/postgres/adapter.rb

@@ -1,19 +1,25 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
 
-require_relative 'connection'
+require_relative "connection"
 
 module DB
 	module Postgres
+		# A database adapter for connecting to PostgreSQL servers.
 		class Adapter
+			# Initialize a new adapter with connection options.
+			# @parameter options [Hash] Connection options to be passed to the connection.
 			def initialize(**options)
 				@options = options
 			end
 			
+			# @attribute [Hash] The connection options.
 			attr :options
 			
+			# Create a new database connection.
+			# @returns [Connection] A new connection instance.
 			def call
 				Connection.new(**@options)
 			end

data/lib/db/postgres/connection.rb

@@ -1,22 +1,26 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
 
-require 'async/pool/resource'
-require 'db/features'
-require_relative 'native/connection'
+require "async/pool/resource"
+require "db/features"
+require_relative "native/connection"
 
 module DB
 	module Postgres
-		# This implements the interface between the underlying 
+		# A high-level database connection that implements the standardized connection interface.
+		# This class provides a bridge between the underlying native PostgreSQL interface and the DB gem's unified connection API.
 		class Connection < Async::Pool::Resource
+			# Initialize a new database connection.
+			# @parameter options [Hash] Connection options passed to the native connection.
 			def initialize(**options)
 				@native = Native::Connection.connect(**options)
 				
 				super()
 			end
 			
+			# Close the database connection and release resources.
 			def close
 				if @native
 					@native&.close
@@ -26,16 +30,26 @@ module DB
 				super
 			end
 			
+			# Get the type mapping for database types.
+			# @returns [Hash] The type mapping configuration.
 			def types
 				@native.types
 			end
 			
+			# Append an escaped string value to the buffer.
+			# @parameter value [String] The string value to escape and append.
+			# @parameter buffer [String] The buffer to append to.
+			# @returns [String] The buffer with the escaped string appended.
 			def append_string(value, buffer = String.new)
 				buffer << @native.escape_literal(value)
 				
 				return buffer
 			end
 			
+			# Append a literal value to the buffer with appropriate formatting.
+			# @parameter value [Object] The value to append (supports Time, Date, Numeric, Boolean, nil, and strings).
+			# @parameter buffer [String] The buffer to append to.
+			# @returns [String] The buffer with the formatted value appended.
 			def append_literal(value, buffer = String.new)
 				case value
 				when Time, DateTime, Date
@@ -43,11 +57,11 @@ module DB
 				when Numeric
 					buffer << value.to_s
 				when TrueClass
-					buffer << 'TRUE'
+					buffer << "TRUE"
 				when FalseClass
-					buffer << 'FALSE'
+					buffer << "FALSE"
 				when nil
-					buffer << 'NULL'
+					buffer << "NULL"
 				else
 					append_string(value, buffer)
 				end
@@ -55,12 +69,16 @@ module DB
 				return buffer
 			end
 			
+			# Append an escaped identifier to the buffer.
+			# @parameter value [String | Array(String)] The identifier or array of identifiers to escape.
+			# @parameter buffer [String] The buffer to append to.
+			# @returns [String] The buffer with the escaped identifier appended.
 			def append_identifier(value, buffer = String.new)
 				case value
 				when Array
 					first = true
 					value.each do |part|
-						buffer << '.' unless first
+						buffer << "." unless first
 						first = false
 						
 						buffer << @native.escape_identifier(part)
@@ -72,7 +90,12 @@ module DB
 				return buffer
 			end
 			
-			def key_column(name = 'id', primary: true, null: false)
+			# Generate a key column definition for table creation.
+			# @parameter name [String] The column name.
+			# @parameter primary [Boolean] Whether this is a primary key column.
+			# @parameter null [Boolean] Whether this column allows null values.
+			# @returns [String] The column definition string.
+			def key_column(name = "id", primary: true, null: false)
 				buffer = String.new
 				
 				append_identifier(name, buffer)
@@ -92,16 +115,22 @@ module DB
 				return buffer
 			end
 			
+			# Get the current connection status.
+			# @returns [Symbol] The status symbol from the server.
 			def status
 				@native.status
 			end
 			
+			# Send a query to the database server.
+			# @parameter statement [String] The SQL statement to execute.
 			def send_query(statement)
 				@native.discard_results
 				
 				@native.send_query(statement)
 			end
 			
+			# Get the next result set from a multi-result query.
+			# @returns [Native::Result | Nil] The next result set, or `nil` if no more results.
 			def next_result
 				@native.next_result
 			end
@@ -117,6 +146,7 @@ module DB
 			)
 			
 			# Database feature detection for migration and query building.
+			# @returns [DB::Features] The supported database features.
 			def features
 				FEATURES
 			end

data/lib/db/postgres/error.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 module DB
 	module Postgres
+		# An error raised by the PostgreSQL adapter.
 		class Error < StandardError
 		end
 	end

data/lib/db/postgres/native/connection.rb

@@ -1,16 +1,19 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
 
-require_relative 'result'
-require_relative 'field'
-require_relative '../error'
+require_relative "result"
+require_relative "field"
+require_relative "../error"
 
 module DB
 	module Postgres
 		module Native
+			# Helper class for managing FFI string arrays.
 			class Strings
+				# Initialize a string array for FFI.
+				# @parameter values [Array] The array of values to convert to FFI strings.
 				def initialize(values)
 					@array = FFI::MemoryPointer.new(:pointer, values.size + 1)
 					@pointers = values.map do |value|
@@ -19,6 +22,7 @@ module DB
 					@array.write_array_of_pointer(@pointers)
 				end
 				
+				# @attribute [FFI::MemoryPointer] The FFI array pointer.
 				attr :array
 			end
 			
@@ -46,7 +50,7 @@ module DB
 				# Non-blocking mode:
 				:started, # Waiting for connection to be made.
 				:made, # Connection OK; waiting to send.
-				:awaiting_response, #Waiting for a response from the postmaster.
+				:awaiting_response, # Waiting for a response from the postmaster.
 				:auth_ok, # Received authentication; waiting for backend startup.
 				:setenv, # Negotiating environment.
 				:ssl_startup, # Negotiating SSL.
@@ -81,7 +85,13 @@ module DB
 			ffi_attach_function :PQescapeLiteral, [:pointer, :string, :size_t], :pointer, as: :escape_literal
 			ffi_attach_function :PQescapeIdentifier, [:pointer, :string, :size_t], :pointer, as: :escape_identifier
 			
+			# A native FFI connection to the PostgreSQL client library.
 			class Connection < FFI::Pointer
+				# Establish a connection to the PostgreSQL server.
+				# @parameter types [Hash] Type mapping configuration.
+				# @parameter options [Hash] Connection options (database, username, password, host, port, etc.).
+				# @returns [Connection] A new connected instance.
+				# @raises [Error] If the connection fails.
 				def self.connect(types: DEFAULT_TYPES, **options)
 					# Postgres expects "dbname" as the key name:
 					if database = options.delete(:database)
@@ -96,7 +106,7 @@ module DB
 					keys = Strings.new(options.keys)
 					values = Strings.new(options.values)
 					
-					pointer = Native.connect_start_params(keys.array, values.array, 0)
+					pointer = Native.connect_start_params(keys.array, values.array, 1)
 					Native.set_nonblocking(pointer, 1)
 					
 					io = ::IO.new(Native.socket(pointer), "r+", autoclose: false)
@@ -121,6 +131,10 @@ module DB
 					return self.new(pointer, io, types)
 				end
 				
+				# Initialize a native connection wrapper.
+				# @parameter address [FFI::Pointer] The pointer to the native connection.
+				# @parameter io [IO] The IO object for the socket.
+				# @parameter types [Hash] Type mapping configuration.
 				def initialize(address, io, types)
 					super(address)
 					
@@ -128,6 +142,7 @@ module DB
 					@types = types
 				end
 				
+				# @attribute [Hash] The type mapping configuration.
 				attr :types
 				
 				# Return the status of the connection.
@@ -152,6 +167,9 @@ module DB
 					@io.close
 				end
 				
+				# Escape a literal string value for safe inclusion in SQL queries.
+				# @parameter value [String] The value to escape.
+				# @returns [String] The escaped string with quotes.
 				def escape_literal(value)
 					value = value.to_s
 					
@@ -164,6 +182,9 @@ module DB
 					return string
 				end
 				
+				# Escape an identifier for safe inclusion in SQL queries.
+				# @parameter value [String] The identifier to escape.
+				# @returns [String] The escaped identifier with quotes.
 				def escape_identifier(value)
 					value = value.to_s
 					
@@ -176,16 +197,23 @@ module DB
 					return string
 				end
 				
+				# Enable single row mode for streaming large result sets.
 				def single_row_mode!
 					Native.set_single_row_mode(self)
 				end
 				
+				# Send a query to the server for execution.
+				# @parameter statement [String] The SQL statement to execute.
 				def send_query(statement)
 					check! Native.send_query(self, statement)
 					
 					flush
 				end
 				
+				# Get the next result set from a multi-result query.
+				# @parameter types [Hash] Type mapping to use for this result.
+				# @returns [Result | Nil] The next result set, or `nil` if no more results.
+				# @raises [Error] If the query resulted in an error.
 				def next_result(types: @types)
 					if result = self.get_result
 						status = Native.result_status(result)

data/lib/db/postgres/native/field.rb

@@ -1,17 +1,17 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
-require_relative 'types'
+require_relative "types"
 
 module DB
 	module Postgres
 		module Native
 			DEFAULT_TYPES = {
 				# Pseudo types:
-				primary_key: Types::Integer.new('BIGSERIAL PRIMARY KEY'),
-				foreign_key: Types::Integer.new('BIGINT'),
+				primary_key: Types::Integer.new("BIGSERIAL PRIMARY KEY"),
+				foreign_key: Types::Integer.new("BIGINT"),
 				text: Types::Text.new("TEXT"),
 				string: Types::Text.new("VARCHAR(255)"),
 				
@@ -46,8 +46,8 @@ module DB
 				
 				114 => Types::JSON.new,
 				
-				700 => Types::Float.new('float4'),
-				701 => Types::Float.new('float8'),
+				700 => Types::Float.new("float4"),
+				701 => Types::Float.new("float8"),
 				
 				1082 => Types::Date.new,
 				1083 => Types::DateTime.new("TIME"),

data/lib/db/postgres/native/result.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
 
-require_relative '../native'
+require_relative "../native"
 
 module DB
 	module Postgres
@@ -38,7 +38,12 @@ module DB
 			ffi_attach_function :PQgetCopyData, [:pointer, :pointer, :int], :int, as: :get_copy_data
 			ffi_attach_function :PQfreemem, [:pointer], :void, as: :free_memory
 			
+			# A result set from a database query with row iteration and type casting.
 			class Result < FFI::Pointer
+				# Initialize a new result set wrapper.
+				# @parameter connection [Connection] The connection that produced this result.
+				# @parameter types [Hash] Type mapping for field conversion.
+				# @parameter address [FFI::Pointer] The pointer to the native result.
 				def initialize(connection, types = {}, address)
 					super(address)
 					
@@ -48,22 +53,33 @@ module DB
 					@casts = nil
 				end
 				
+				# Get the number of fields in this result set.
+				# @returns [Integer] The field count.
 				def field_count
 					Native.field_count(self)
 				end
 				
+				# Get the type converters for each field.
+				# @returns [Array] The array of type converter objects.
 				def field_types
 					field_count.times.collect{|i| @types[Native.field_type(self, i)]}
 				end
 				
+				# Get the field names for this result set.
+				# @returns [Array(String)] The array of field names.
 				def field_names
 					field_count.times.collect{|i| Native.field_name(self, i)}
 				end
 				
+				# Get the number of rows in this result set.
+				# @returns [Integer] The row count.
 				def row_count
 					Native.row_count(self)
 				end
 				
+				# Cast row values to appropriate Ruby types.
+				# @parameter row [Array] The raw row data.
+				# @returns [Array] The row with values cast to proper types.
 				def cast!(row)
 					@casts ||= self.field_types
 					
@@ -76,6 +92,9 @@ module DB
 					return row
 				end
 				
+				# Iterate over each row in the result set.
+				# @yields {|row| ...} Each row as an array.
+				# 	@parameter row [Array] The current row data.
 				def each
 					row_count.times do |i|
 						yield cast!(get_row(i))
@@ -84,6 +103,10 @@ module DB
 					Native.clear(self)
 				end
 				
+				# Map over each row in the result set.
+				# @yields {|row| ...} Each row as an array.
+				# 	@parameter row [Array] The current row data.
+				# @returns [Array] The mapped results.
 				def map(&block)
 					results = []
 					
@@ -94,6 +117,8 @@ module DB
 					return results
 				end
 				
+				# Convert the entire result set to an array.
+				# @returns [Array(Array)] All rows as arrays.
 				def to_a
 					rows = []
 					

data/lib/db/postgres/native/types.rb

@@ -1,90 +1,137 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
-require 'json'
-require 'bigdecimal'
+require "json"
+require "bigdecimal"
 
 module DB
 	module Postgres
 		module Native
+			# Provides type converters for translating between PostgreSQL types and Ruby types.
 			module Types
+				# A text/string type converter.
 				class Text
+					# Initialize a text type converter.
+					# @parameter name [String] The SQL type name.
 					def initialize(name = "TEXT")
 						@name = name
 					end
 					
+					# @attribute [String] The SQL type name.
 					attr :name
 					
+					# Parse a string value from the database.
+					# @parameter string [String | Nil] The raw string value.
+					# @returns [String | Nil] The string value.
 					def parse(string)
 						string
 					end
 				end
 				
+				# An integer type converter.
 				class Integer
+					# Initialize an integer type converter.
+					# @parameter name [String] The SQL type name.
 					def initialize(name = "INTEGER")
 						@name = name
 					end
 					
+					# @attribute [String] The SQL type name.
 					attr :name
 					
+					# Parse an integer value from the database.
+					# @parameter string [String | Nil] The raw string value.
+					# @returns [Integer | Nil] The parsed integer.
 					def parse(string)
 						Integer(string) if string
 					end
 				end
 				
+				# A boolean type converter.
 				class Boolean
+					# Get the SQL type name for boolean.
+					# @returns [String] The type name.
 					def name
 						"BOOLEAN"
 					end
 					
+					# Parse a boolean value from the database.
+					# @parameter string [String | Nil] The raw string value ('t' or 'f').
+					# @returns [Boolean] The parsed boolean value.
 					def parse(string)
-						string == 't'
+						string == "t"
 					end
 				end
 				
+				# A decimal type converter.
 				class Decimal
+					# Get the SQL type name for decimal.
+					# @returns [String] The type name.
 					def name
 						"DECIMAL"
 					end
 					
+					# Parse a decimal value from the database.
+					# @parameter string [String | Nil] The raw string value.
+					# @returns [BigDecimal | Nil] The parsed decimal.
 					def parse(string)
 						BigDecimal(string) if string
 					end
 				end
 				
+				# A floating point type converter.
 				class Float
+					# Initialize a float type converter.
+					# @parameter name [String] The SQL type name.
 					def initialize(name = "FLOAT")
 						@name = name
 					end
 					
+					# @attribute [String] The SQL type name.
 					attr :name
 					
+					# Parse a float value from the database.
+					# @parameter string [String | Nil] The raw string value.
+					# @returns [Float | Nil] The parsed float.
 					def parse(string)
 						Float(string) if string
 					end
 				end
 				
+				# A symbol/enum type converter.
 				class Symbol
+					# Get the SQL type name for enum.
+					# @returns [String] The type name.
 					def name
 						"ENUM"
 					end
 					
+					# Parse a symbol value from the database.
+					# @parameter string [String | Nil] The raw string value.
+					# @returns [Symbol | Nil] The parsed symbol.
 					def parse(string)
 						string&.to_sym
 					end
 				end
 				
+				# A datetime/timestamp type converter.
 				class DateTime
+					# Initialize a datetime type converter.
+					# @parameter name [String] The SQL type name.
 					def initialize(name = "TIMESTAMP")
 						@name = name
 					end
 					
+					# @attribute [String] The SQL type name.
 					attr :name
 					
+					# Parse a datetime value from the database.
+					# @parameter string [String | Nil] The raw string value or special values like 'infinity'.
+					# @returns [Time | String | Nil] The parsed datetime as a Time object, or special values as strings.
 					def parse(string)
-						if string == '-infinity' || string == 'infinity' || string.nil?
+						if string == "-infinity" || string == "infinity" || string.nil?
 							return string
 						end
 						
@@ -94,7 +141,7 @@ module DB
 							parts[5] = Rational(parts[5])
 							
 							if parts[6].nil?
-								parts[6] = '+00'
+								parts[6] = "+00"
 							end
 							
 							return Time.new(*parts)
@@ -102,11 +149,17 @@ module DB
 					end
 				end
 				
+				# A date type converter.
 				class Date
+					# Get the SQL type name for date.
+					# @returns [String] The type name.
 					def name
 						"DATE"
 					end
 					
+					# Parse a date value from the database.
+					# @parameter string [String | Nil] The raw string value.
+					# @returns [Time | Nil] The parsed date as a UTC Time object.
 					def parse(string)
 						if string
 							parts = string.split(/[\-\s:]/)
@@ -116,11 +169,17 @@ module DB
 					end
 				end
 				
+				# A JSON type converter.
 				class JSON
+					# Get the SQL type name for JSON.
+					# @returns [String] The type name.
 					def name
 						"JSON"
 					end
 					
+					# Parse a JSON value from the database.
+					# @parameter string [String | Nil] The raw string value.
+					# @returns [Hash | Array | Nil] The parsed JSON with symbolized keys.
 					def parse(string)
 						::JSON.parse(string, symbolize_names: true) if string
 					end

data/lib/db/postgres/native.rb

@@ -1,20 +1,21 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
 
-require 'ffi/native'
-require 'ffi/native/config_tool'
+require "ffi/native"
+require "ffi/native/config_tool"
 
 module DB
 	module Postgres
+		# Provides FFI bindings to the native PostgreSQL client library (libpq).
 		module Native
 			extend FFI::Native::Library
 			extend FFI::Native::Loader
 			extend FFI::Native::ConfigTool
 			
-			ffi_load('pq') ||
-				ffi_load_using_config_tool(%w{pg_config --libdir}, names: ['pq']) ||
+			ffi_load("pq") ||
+				ffi_load_using_config_tool(%w{pg_config --libdir}, names: ["pq"]) ||
 				ffi_load_failure(<<~EOF)
 					Unable to load libpq!
 					

data/lib/db/postgres/version.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
 
+# @namespace
 module DB
+	# @namespace
 	module Postgres
-		VERSION = "0.9.0"
+		VERSION = "0.10.0"
 	end
 end

data/lib/db/postgres.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
 
-require_relative 'postgres/native'
-require_relative 'postgres/connection'
+require_relative "postgres/native"
+require_relative "postgres/connection"
 
-require_relative 'postgres/adapter'
+require_relative "postgres/adapter"
 
-require 'db/adapters'
+require "db/adapters"
 DB::Adapters.register(:postgres, DB::Postgres::Adapter)

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2018-2024, by Samuel Williams.  
+Copyright, 2018-2026, by Samuel Williams.  
 Copyright, 2021, by Tony Schneider.  
 Copyright, 2022, by Aidan Samuel.  
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: db-postgres
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -122,7 +122,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Ruby FFI bindings for libpq C interface.
 test_files: []