db 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 190f7bf46c9e6f9e7af5b291eb71d07db32a6db3ac8997bc73dd50a058327744
-  data.tar.gz: fac1ca594b8f900b4ff7ac6e68cca1930c24fbc199a5187176f8d5e30e9006e7
+  metadata.gz: e32753720467fe5085b599ca44812117efa453bbb6ae959e4bb8990cab6d4087
+  data.tar.gz: b3a6480f045f16d015c0d9b105e361b6eddbbff489a45ac3e9145a49011ea07e
 SHA512:
-  metadata.gz: 1d0e7f56d1ea4f323e3c7d1525d3f4f2ef35cc8c9509b3d4f181ac3e992cd9c3ae954c696acc0b898ca1c196fd5638f46d0dac5ac36bdc99d9f989e081f24761
-  data.tar.gz: a5bca6583eeff6c0b1eb4debb7b9b8ff3d3011de914394742905bfad795e9f02ed6f65d452a36a9953db13016df67fffc546430df1f8269c60763fb7bfcfe0dc
+  metadata.gz: 78a879265c001e502faa4c8227a0f3457501bee7b55ac15eb4f7fe7ed267cdba0c476e411bc862dfe310b44d64fadcdb02f358fb0038f22fe3a56f4cb60c8ce9
+  data.tar.gz: 3b8be8be3b52d3f0d1b3cddbac2149e664a29fffed62d994eb8759f11ebb264df12ed6e620f8bf00da68ee1391c5486af59be0f5e6e274716408b585d89e1c74

data/context/datatypes.md

@@ -0,0 +1,28 @@
+# Data Types
+
+This guide explains about SQL data types, and how they are used by the DB gem.
+
+Structured Query Language (SQL) defines a set of data types that can be used to store data in a database. The data types are used to define a column in a table, and each column in a table must have a data type associated with it. The data type of a column typically defines the kind of data that the column can store, althought some database systems allow you to store any kind of data in any column.
+
+When you build a program with a database, you need to be aware of the data types that are available in the database system you are using. The DB gem tries to expose standard data types, so that you can use the same data types across different database systems. There are two main operations that are affected by datatypes: appending literal values to SQL queries, and reading values from the database.
+
+## Appending Literal Data Types
+
+The DB gem converts Ruby objects to SQL literals when you append them to a query. This is generally taken care of by the {ruby DB::Query#literal} and {ruby DB::Query#interpolate} methods, which are used to append literal values to a query. Generally speaking, the following native data types are supported:
+
+- `Time`, `DateTime` and `Date` objects convert to an appropriate format for the database system you are using. Some systems don't natively support timezones, and so time zone information may be lost.
+- `String` objects are escaped and quoted.
+- `Numeric` (including `Integer` and `Float`) objects are appended as-is.
+- `TrueClass` and `FalseClass` objects are converted to the appropriate boolean value for the database system you are using.
+- `NilClass` objects are converted to `NULL`.
+
+## Reading Data Types
+
+When you read data from the database, the DB gem tries to convert the data to the appropriate Ruby object. When a query yields rows of fields, and those fields have a well defined field type, known by the adapter, the adapter will cast those objects back into rich Ruby objects where possible. The following conversions are generally supported:
+
+- `TEXT` and `VARCHAR` fields are converted to `String` objects.
+- `INTEGER` and `FLOAT` fields are converted to `Integer` and `Float` objects respectively.
+- `BOOLEAN` fields are converted to `TrueClass` and `FalseClass` objects.
+- `TIMESTAMP` and `DATETIME` fields are converted to `Time` objects.
+- `DATE` fields are converted to `Date` objects.
+- `NULL` values are converted to `nil`.

data/context/example-queries.md

@@ -0,0 +1,263 @@
+# Example Queries
+
+This guide shows a variety of example queries using the DB gem.
+
+## Setup
+
+~~~ ruby
+require 'async'
+require 'db/client'
+require 'db/postgres'
+
+client = DB::Client.new(DB::Postgres::Adapter.new(
+	database: 'test',
+	host:	    '172.17.0.3',
+	password: 'test',
+	username: 'postgres',
+))
+~~~
+
+## A simple CREATE, INSERT and SELECT, with raw SQL
+
+~~~ ruby
+Sync do
+	session = client.session
+
+	create = "CREATE TABLE IF NOT EXISTS my_table (a_timestamp TIMESTAMP NOT NULL)"
+	session.query(create).call
+
+	insert = "INSERT INTO my_table VALUES (NOW()), ('2022-12-12 12:13:14')"
+	session.query(insert).call
+
+	result = session.query("SELECT * FROM my_table WHERE a_timestamp > NOW()").call
+
+	Console.info result.field_types.to_s
+	Console.info result.field_names.to_s
+	Console.info result.to_a.to_s
+ensure
+	session&.close
+end
+~~~
+
+### Output
+
+~~~
+ 0.01s     info: [#<DB::Postgres::Native::Types::DateTime:0x00007eff3b13e688 @name="TIMESTAMP">]
+ 0.01s     info: ["a_timestamp"]
+ 0.01s     info: [[2022-12-12 12:13:14 UTC]]
+~~~
+
+## Parameterized CREATE, INSERT and SELECT
+
+The same process as before, but parameterized. Always use the parameterized form when dealing with untrusted data.
+
+~~~ ruby
+Sync do
+	session = client.session
+
+	session.clause("CREATE TABLE IF NOT EXISTS")
+		.identifier(:my_table)
+		.clause("(")
+			.identifier(:a_timestamp).clause("TIMESTAMP NOT NULL")
+		.clause(")")
+		.call
+
+	session.clause("INSERT INTO")
+		.identifier(:my_table)
+		.clause("VALUES (")
+			.literal("NOW()")
+		.clause("), (")
+			.literal("2022-12-12 12:13:14")
+		.clause(")")
+		.call
+
+	result = session.clause("SELECT * FROM")
+		.identifier(:my_table)
+		.clause("WHERE")
+		.identifier(:a_timestamp).clause(">").literal("NOW()")
+		.call
+
+	Console.info result.field_types.to_s
+	Console.info result.field_names.to_s
+	Console.info result.to_a.to_s
+ensure
+	session&.close
+end
+~~~
+
+### Output
+
+~~~
+ 0.01s     info: [#<DB::Postgres::Native::Types::DateTime:0x00007eff3b13e688 @name="TIMESTAMP">]
+ 0.01s     info: ["a_timestamp"]
+ 0.01s     info: [[2022-12-12 12:13:14 UTC]]
+~~~
+
+## A parameterized SELECT
+
+~~~ ruby
+Sync do |task|
+	session = client.session
+	result = session
+		.clause("SELECT")
+		.identifier(:column_one)
+		.clause(",")
+		.identifier(:column_two)
+		.clause("FROM")
+		.identifier(:another_table)
+		.clause("WHERE")
+		.identifier(:id)
+		.clause("=")
+		.literal(42)
+		.call
+
+	Console.info "#{result.field_names}"
+	Console.info "#{result.to_a}"
+end
+~~~
+
+### Output
+
+~~~
+ 0.01s     info: ["column_one", "column_two"]
+ 0.01s     info: [["foo", "bar"], ["baz", "qux"]]
+~~~
+
+## Concurrent queries
+
+(Simulating slow queries with `PG_SLEEP`)
+
+~~~ ruby
+Sync do |task|
+	start = Time.now
+	tasks = 10.times.map do
+		task.async do
+			session = client.session
+			result = session.query("SELECT PG_SLEEP(10)").call
+			result.to_a
+		ensure
+			session&.close
+		end
+	end
+
+	results = tasks.map(&:wait)
+
+	Console.info "Elapsed time: #{Time.now - start}s"
+end
+~~~
+
+### Output
+
+~~~
+10.05s     info: Elapsed time: 10.049756222s
+~~~
+
+## Limited to 3 connections
+
+(Simulating slow queries with `PG_SLEEP`)
+
+~~~ ruby
+require 'async/semaphore'
+
+Sync do
+	semaphore = Async::Semaphore.new(3)
+	tasks = 10.times.map do |i|
+		semaphore.async do
+			session = client.session
+			Console.info "Starting task #{i}"
+			result = session.query("SELECT PG_SLEEP(10)").call
+			result.to_a
+		ensure
+			session&.close
+		end
+	end
+
+	results = tasks.map(&:wait)
+	Console.info "Done"
+end
+~~~
+
+### Output
+
+~~~
+  0.0s     info: Starting task 0
+  0.0s     info: Starting task 1
+  0.0s     info: Starting task 2
+10.02s     info: Completed task 0 after 10.017388464s
+10.02s     info: Starting task 3
+10.02s     info: Completed task 1 after 10.02111175s
+10.02s     info: Starting task 4
+10.03s     info: Completed task 2 after 10.027889587s
+10.03s     info: Starting task 5
+20.03s     info: Completed task 3 after 10.011089096s
+20.03s     info: Starting task 6
+20.03s     info: Completed task 4 after 10.008169111s
+20.03s     info: Starting task 7
+20.04s     info: Completed task 5 after 10.007644749s
+20.04s     info: Starting task 8
+30.04s     info: Completed task 6 after 10.011244562s
+30.04s     info: Starting task 9
+30.04s     info: Completed task 7 after 10.011565997s
+30.04s     info: Completed task 8 after 10.004611464s
+40.05s     info: Completed task 9 after 10.008239803s
+40.05s     info: Done
+~~~
+
+## Sequential vs Concurrent INSERTs
+
+~~~ ruby
+DATA = 1_000_000.times.map { SecureRandom.hex }
+
+def setup_tables(client)
+	session = client.session
+
+	create = "CREATE TABLE IF NOT EXISTS salts (salt CHAR(32))"
+	session.query(create).call
+
+	truncate = "TRUNCATE TABLE salts"
+	session.query(truncate).call
+
+	session.close
+end
+
+def chunked_insert(rows, client, task=Async::Task.current)
+	task.async do
+		session = client.session
+		rows.each_slice(1000) do |slice|
+			insert = "INSERT INTO salts VALUES " + slice.map { |x| "('#{x}')" }.join(",")
+			session.query(insert).call
+		end
+	ensure
+		session&.close
+	end
+end
+
+Sync do
+	Console.info "Setting up tables"
+	setup_tables(client)
+	Console.info "Done"
+
+	start = Time.now
+	Console.info "Starting sequential insert"
+	chunked_insert(DATA, client).wait
+	Console.info "Completed sequential insert in #{Time.now - start}s"
+
+	start = Time.now
+	Console.info "Starting concurrent insert"
+	DATA.each_slice(10_000).map do |slice|
+		chunked_insert(slice, client)
+	end.each(&:wait)
+	Console.info "Completed concurrent insert in #{Time.now - start}s"
+end
+~~~
+
+### Output
+
+~~~
+ 1.45s     info: Setting up tables
+ 1.49s     info: Done
+ 1.49s     info: Starting sequential insert
+ 8.49s     info: Completed sequential insert in 7.006533933s
+ 8.49s     info: Starting concurrent insert
+ 9.92s     info: Completed concurrent insert in 1.431470847s
+~~~

data/context/executing-queries.md

@@ -0,0 +1,158 @@
+# Executing Queries
+
+This guide explains how to escape and execute queries.
+
+In order to execute a query, you need a connection. Database connections are stateful, and this state is encapsulated by a context.
+
+## Contexts
+
+Contexts represent a stateful connection to a remote server. The most generic kind, {ruby DB::Context::Session} provides methods for sending queries and processing results. {ruby DB::Context::Transaction} extends this implementation and adds methods for database transactions.
+
+### Sessions
+
+A {ruby DB::Context::Session} represents a connection to the database server and can be used to send queries to the server and read rows of results.
+
+~~~ ruby
+require 'async'
+require 'db/client'
+require 'db/postgres'
+
+client = DB::Client.new(DB::Postgres::Adapter.new(database: 'test'))
+
+Sync do
+	session = client.session
+	
+	# Build a query, injecting the literal 42 and the identifier LIFE into the statement:
+	result = session
+		.clause("SELECT").literal(42)
+		.clause("AS").identifier(:LIFE).call
+	
+	pp result.to_a
+	# => [[42]]
+end
+~~~
+
+### Transactions
+
+Transactions ensure consistency when selecting and inserting data. While the exact semantics are server specific, transactions normally ensure that all statements execute at a consistent point in time and that if any problem occurs during the transaction, the entire transaction is aborted.
+
+~~~ ruby
+require 'async'
+require 'db/client'
+require 'db/postgres'
+
+client = DB::Client.new(DB::Postgres::Adapter.new(database: 'test'))
+
+Sync do
+	session = client.transaction
+	
+	# Use the explicit DSL for generating queries:
+	session.clause("CREATE TABLE")
+		.identifier(:users)
+		.clause("(")
+			.identifier(:id).clause("BIGSERIAL PRIMARY KEY,")
+			.identifier(:name).clause("VARCHAR NOT NULL")
+		.clause(")").call
+	
+	# Use interpolation for generating queries:
+	session.query(<<~SQL, table: :users, column: :name, value: "ioquatix").call
+		INSERT INTO %{table} (%{column}) VALUES (%{value})
+	SQL
+	
+	result = session.clause("SELECT * FROM").identifier(:users).call
+	
+	pp result.to_a
+	
+	session.abort
+	
+ensure
+	session.close
+end
+~~~
+
+Because the session was aborted, the table and data are never committed:
+
+~~~ ruby
+require 'async'
+require 'db/client'
+require 'db/postgres'
+
+client = DB::Client.new(DB::Postgres::Adapter.new(database: 'test'))
+
+Sync do
+	session = client.session
+	
+	result = session.clause("SELECT * FROM").identifier(:users).call
+	# => DB::Postgres::Error: Could not get next result: ERROR:  relation "users" does not exist
+	
+	pp result.to_a
+	
+ensure
+	session.close
+end
+~~~
+
+### Closing Sessions
+
+It is important that you close a session or commit/abort a transaction (implicit close). Closing a session returns it to the connection pool. If you don't do this, you will leak connections. Both {ruby DB::Client#session} and {ruby DB::Client#transaction} can accept blocks and will implicitly close/commit/abort as appropriate.
+
+## Query Builder
+
+A {ruby DB::Query} builder is provided to help construct queries and avoid SQL injection attacks. This query builder is bound to a {ruby DB::Context::Session} instance and provides convenient methods for constructing a query efficiently.
+
+### Low Level Methods
+
+There are several low level methods for constructing queries.
+
+- {ruby DB::Query#clause} appends an unescaped fragment of SQL text.
+- {ruby DB::Query#literal} appends an escaped literal value (e.g. {ruby String}, {ruby Integer}, {ruby true}, {ruby nil}, etc).
+- {ruby DB::Query#identifier} appends an escaped identifier ({ruby Symbol}, {ruby Array}, {ruby DB::Identifier}).
+
+~~~ ruby
+require 'async'
+require 'db/client'
+require 'db/postgres'
+
+client = DB::Client.new(DB::Postgres::Adapter.new(database: 'test'))
+
+Sync do
+	session = client.session
+	
+	# Build a query, injecting the literal 42 and the identifier LIFE into the statement:
+	result = session
+		.clause("SELECT").literal(42)
+		.clause("AS").identifier(:LIFE)
+		.call
+	
+	pp result.to_a
+	# => [[42]]
+end
+~~~
+
+### Interpolation Method
+
+You can also use string interpolation to safely construct queries.
+
+- {ruby DB::Query#interpolate} appends an interpolated query string with escaped parameters.
+
+~~~ ruby
+require 'async'
+require 'db/client'
+require 'db/postgres'
+
+client = DB::Client.new(DB::Postgres::Adapter.new(database: 'test'))
+
+Sync do
+	session = client.session
+	
+	# Build a query, injecting the literal 42 and the identifier LIFE into the statement:
+	result = session.query(<<~SQL, value: 42, column: :LIFE).call
+		SELECT %{value} AS %{column}
+	SQL
+	
+	pp result.to_a
+	# => [[42]]
+end
+~~~
+
+Named parameters are escaped and substituted into the given fragment.

data/context/getting-started.md

@@ -0,0 +1,88 @@
+# Getting Started
+
+This guide explains how to use `db` for database queries.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add db
+~~~
+
+## Core Concepts
+
+`db` has several core concepts:
+
+- A {ruby DB::Client} instance which is configured to connect to a specific database using an adapter, and manages a connection pool.
+- A {ruby DB::Context::Session} instance which is bound to a specific connection and allows you to execute queries and enumerate results.
+
+## Connecting to Postgres
+
+Add the Postgres adaptor to your project:
+
+~~~ bash
+$ bundle add db-postgres
+~~~
+
+Set up the client with the appropriate credentials:
+
+~~~ ruby
+require 'async'
+require 'db/client'
+require 'db/postgres'
+
+# Create the client and connection pool:
+client = DB::Client.new(DB::Postgres::Adapter.new(database: 'test'))
+
+# Create an event loop:
+Sync do
+	# Connect to the database:
+	session = client.session
+	
+	# Execute the query and get a result set:
+	result = session.call("SELECT VERSION()")
+	
+	# Convert the result set to an array and print it out:
+	pp result.to_a
+	# => [["PostgreSQL 16.3 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 14.1.1 20240522, 64-bit"]]
+ensure
+	# Return the connection to the client connection pool:
+	session.close
+end
+~~~
+
+## Connection to MariaDB/MySQL
+
+Add the MariaDB adaptor to your project:
+
+~~~ bash
+$ bundle add db-mariadb
+~~~
+
+Set up the client with the appropriate credentials:
+
+~~~ ruby
+require 'async'
+require 'db/client'
+require 'db/mariadb'
+
+# Create the client and connection pool:
+client = DB::Client.new(DB::MariaDB::Adapter.new(database: 'test'))
+
+# Create an event loop:
+Sync do
+	# Connect to the database:
+	session = client.session
+	
+	# Execute the query and get a result set:
+	result = session.call("SELECT VERSION()")
+	
+	# Convert the result set to an array and print it out:
+	pp result.to_a
+	# => [["10.4.13-MariaDB"]]
+ensure
+	# Return the connection to the client connection pool:
+	session.close
+end
+~~~

data/context/index.yaml

@@ -0,0 +1,22 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: A low level database access gem.
+metadata:
+  documentation_uri: https://socketry.github.io/db/
+  funding_uri: https://github.com/sponsors/ioquatix
+  source_code_uri: https://github.com/socketry/db.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `db` for database queries.
+- path: executing-queries.md
+  title: Executing Queries
+  description: This guide explains how to escape and execute queries.
+- path: example-queries.md
+  title: Example Queries
+  description: This guide shows a variety of example queries using the DB gem.
+- path: datatypes.md
+  title: Data Types
+  description: This guide explains about SQL data types, and how they are used by
+    the DB gem.

data/lib/db/client.rb

@@ -25,6 +25,10 @@ module DB
 		
 		# Close all open connections in the connection pool.
 		def close
+			@pool.wait_until_free do
+				Console.warn(self) {"Waiting for #{@adapter} pool to drain: #{@pool}"}
+			end
+			
 			@pool.close
 		end
 		

data/lib/db/context/session.rb

@@ -7,6 +7,7 @@ require_relative "../query"
 require_relative "../records"
 
 module DB
+	# Provides context for database operations including sessions and transactions.
 	module Context
 		# A connected context for sending queries and reading results.
 		class Session
@@ -32,10 +33,15 @@ module DB
 				end
 			end
 			
+			# Check if the session connection is closed.
+			# @returns [Boolean] True if the connection is closed (nil), false otherwise.
 			def closed?
 				@connection.nil?
 			end
 			
+			# Execute a block with a database connection, acquiring one if necessary.
+			# @yields {|connection| ...} The connection block.
+			# 	@parameter connection [Object] The database connection object.
 			def with_connection(&block)
 				if @connection
 					yield @connection
@@ -64,6 +70,10 @@ module DB
 				end
 			end
 			
+			# Create a new query builder with optional initial fragment and parameters.
+			# @parameter fragment [String] Initial SQL fragment for the query.
+			# @parameter parameters [Hash] Parameters for interpolation into the fragment.
+			# @returns [Query] A new query builder instance.
 			def query(fragment = String.new, **parameters)
 				with_connection do
 					if parameters.empty?
@@ -74,6 +84,9 @@ module DB
 				end
 			end
 			
+			# Create a new query builder with an initial clause fragment.
+			# @parameter fragment [String] Initial SQL clause fragment.
+			# @returns [Query] A new query builder instance.
 			def clause(fragment = String.new)
 				with_connection do
 					Query.new(self, fragment)

data/lib/db/context/transaction.rb

@@ -7,6 +7,7 @@ require_relative "session"
 
 module DB
 	module Context
+		# A database transaction context that extends Session with transaction management capabilities.
 		class Transaction < Session
 			# Begin a transaction.
 			def begin
@@ -20,6 +21,8 @@ module DB
 				self.close
 			end
 			
+			# Commit the transaction if it's still open, otherwise do nothing.
+			# This is a safe version of commit that checks if the transaction is still active.
 			def commit?
 				unless self.closed?
 					self.commit

data/lib/db/features.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+module DB
+	# Standardized feature detection for database adapters.
+	# All features default to false, and adapters can enable specific capabilities.
+	class Features
+		def initialize(**features)
+			@features = features
+		end
+		
+		# Check if a specific feature is enabled.
+		def enabled?(feature)
+			@features.fetch(feature, false)
+		end
+		
+		# Get all enabled features.
+		def enabled_features
+			@features.select{|_, enabled| enabled}.keys
+		end
+		
+		# Create a new Features instance with additional or modified features.
+		def with(**additional_features)
+			self.class.new(**@features, **additional_features)
+		end
+		
+		# PostgreSQL-style column type modification: ALTER COLUMN name TYPE type USING expression.
+		def alter_column_type?
+			@features.fetch(:alter_column_type, false)
+		end
+		
+		# MySQL-style column modification: MODIFY COLUMN name type.
+		def modify_column?
+			@features.fetch(:modify_column, false)
+		end
+		
+		# Support for USING clause in column type changes.
+		def using_clause?
+			@features.fetch(:using_clause, false)
+		end
+		
+		# Support for IF EXISTS/IF NOT EXISTS clauses.
+		def conditional_operations?
+			@features.fetch(:conditional_operations, false)
+		end
+		
+		# Schema operations can be rolled back within transactions.
+		def transactional_schema?
+			@features.fetch(:transactional_schema, false)
+		end
+		
+		# Multiple operations can be combined in a single ALTER TABLE statement.
+		def batch_alter_table?
+			@features.fetch(:batch_alter_table, false)
+		end
+		
+		# Support for concurrent/online schema changes.
+		def concurrent_schema?
+			@features.fetch(:concurrent_schema, false)
+		end
+		
+		# Support for adding constraints with validation deferred.
+		def deferred_constraints?
+			@features.fetch(:deferred_constraints, false)
+		end
+		
+		# PostgreSQL-style SERIAL/BIGSERIAL auto-increment columns.
+		def serial_columns?
+			@features.fetch(:serial_columns, false)
+		end
+		
+		# MySQL-style AUTO_INCREMENT auto-increment columns.
+		def auto_increment?
+			@features.fetch(:auto_increment, false)
+		end
+		
+		# SQLite-style INTEGER PRIMARY KEY auto-increment.
+		def integer_primary_key_autoincrement?
+			@features.fetch(:integer_primary_key_autoincrement, false)
+		end
+		
+		# Support for IDENTITY columns (SQL Server/newer PostgreSQL).
+		def identity_columns?
+			@features.fetch(:identity_columns, false)
+		end
+	end
+end

data/lib/db/query.rb

@@ -6,6 +6,9 @@
 module DB
 	# Represents one or more identifiers for databases, tables or columns.
 	class Identifier < Array
+		# Convert various input types to an Identifier instance.
+		# @parameter name_or_identifier [Identifier, Array, Symbol, String] The value to convert.
+		# @returns [Identifier] An Identifier instance.
 		def self.coerce(name_or_identifier)
 			case name_or_identifier
 			when Identifier
@@ -19,6 +22,8 @@ module DB
 			end
 		end
 		
+		# Append this identifier to the provided query builder.
+		# @parameter query [Query] The query builder to append to.
 		def append_to(query)
 			query.identifier(self)
 		end
@@ -90,6 +95,10 @@ module DB
 			return self
 		end
 		
+		# Generate a key column expression based on the connection's requirements.
+		# @parameter arguments [Array] Arguments passed to the connection's key_column method.
+		# @parameter options [Hash] Options passed to the connection's key_column method.
+		# @returns [Query] The mutable query itself.
 		def key_column(*arguments, **options)
 			@buffer << @connection.key_column(*arguments, **options)
 			
@@ -103,10 +112,14 @@ module DB
 			@context.call(@buffer, &block)
 		end
 		
+		# Get the string representation of the query buffer.
+		# @returns [String] The accumulated query string.
 		def to_s
 			@buffer
 		end
 		
+		# Inspect the query instance showing the class and current buffer contents.
+		# @returns [String] A string representation for debugging.
 		def inspect
 			"\#<#{self.class} #{@buffer.inspect}>"
 		end

data/lib/db/records.rb

@@ -6,6 +6,9 @@
 module DB
 	# A buffer of records.
 	class Records
+		# Wrap a database result into a Records instance.
+		# @parameter result [Object] The database result object with field_count, field_names, and to_a methods.
+		# @returns [Records, Nil] A Records instance or nil if there are no columns.
 		def self.wrap(result)
 			# We want to avoid extra memory allocations when there are no columns:
 			if result.field_count == 0
@@ -15,11 +18,16 @@ module DB
 			return self.new(result.field_names, result.to_a)
 		end
 		
+		# Initialize a new Records instance with columns and rows.
+		# @parameter columns [Array] Array of column names.
+		# @parameter rows [Array] Array of row data.
 		def initialize(columns, rows)
 			@columns = columns
 			@rows = rows
 		end
 		
+		# Freeze the Records instance and its internal data structures.
+		# @returns [Records] The frozen Records instance.
 		def freeze
 			return self if frozen?
 			
@@ -32,6 +40,8 @@ module DB
 		attr :columns
 		attr :rows
 		
+		# Get the rows as an array.
+		# @returns [Array] The array of row data.
 		def to_a
 			@rows
 		end

data/lib/db/version.rb

@@ -3,6 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
+# @namespace
 module DB
-	VERSION = "0.12.0"
+	VERSION = "0.14.0"
 end

data/lib/db.rb

@@ -6,3 +6,4 @@
 require_relative "db/version"
 require_relative "db/adapters"
 require_relative "db/client"
+require_relative "db/features"

data/readme.md

@@ -21,6 +21,12 @@ Please see the [project documentation](https://socketry.github.io/db/) for more
 
   - [Data Types](https://socketry.github.io/db/guides/datatypes/index) - This guide explains about SQL data types, and how they are used by the DB gem.
 
+## Releases
+
+Please see the [project releases](https://socketry.github.io/db/releases/index) for all releases.
+
+### v0.13.0
+
 ## See Also
 
   - [db-postgres](https://github.com/socketry/db-postgres) - Postgres adapter for the DB gem.

data/releases.md

@@ -0,0 +1,3 @@
+# Releases
+
+## v0.13.0

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: db
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Samuel Williams
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -37,7 +36,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-09-21 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-pool
@@ -53,22 +52,27 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/datatypes.md
+- context/example-queries.md
+- context/executing-queries.md
+- context/getting-started.md
+- context/index.yaml
 - lib/db.rb
 - lib/db/adapters.rb
 - lib/db/client.rb
 - lib/db/context/session.rb
 - lib/db/context/transaction.rb
+- lib/db/features.rb
 - lib/db/query.rb
 - lib/db/records.rb
 - lib/db/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/db
 licenses:
 - MIT
@@ -76,7 +80,6 @@ metadata:
   documentation_uri: https://socketry.github.io/db/
   funding_uri: https://github.com/sponsors/ioquatix
   source_code_uri: https://github.com/socketry/db.git
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -84,15 +87,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A low level database access gem.
 test_files: []