db 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '00818022e4f4c8f40dae41f5f7850b89021cbcb8165f2a1e4637d07520a2c748'
-  data.tar.gz: 5d4ce254968d4f5187469537f2c1553970ba32e9125bea3a43de40ceb8d3bc40
+  metadata.gz: 64a6f849cc021f19902e7aa339156fd839b6ee03f8bb481c66a86524cdd447d8
+  data.tar.gz: c4bd22be9d7cc9b9862682f0c10856cac5723f684daf426ecf60737124faa7cc
 SHA512:
-  metadata.gz: cb6f3c928363fbc5c9a12ebf6bc902636e93202ee3308edf28d4370f40c2c69c5b57d9c64f873e66642bba3afa025bcd1934366011a52040c9f882b931fafc40
-  data.tar.gz: 0d0b154d9817cbc191c9a16203e5088538fe37375af00e060be6ae4c29379c0e03d61933420b15a36ab4efcbe003e1c279b38f0242b25b6afe156a3e10103980
+  metadata.gz: 1bfa44a0456cca0c87a6f40349a7b7da597bdf53e1169aa0490532f98a90fad3179d562a1c3d5f40750888659ec705d4007984eebf9f1aa97be242918d4c66f9
+  data.tar.gz: 130a8e292f7f584da81fb8700071d35c0cda6cac8392ebe45e0b53f0527c5f26ab527db4aac3d01d9b051772d605175f27e32625a5d12a431fde19729d8bb8cd

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

@@ -3,11 +3,10 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require 'async/pool/controller'
+require "async/pool/controller"
 
-require_relative 'context/transient'
-require_relative 'context/session'
-require_relative 'context/transaction'
+require_relative "context/session"
+require_relative "context/transaction"
 
 module DB
 	# Binds a connection pool to the specified adapter.
@@ -29,19 +28,6 @@ module DB
 			@pool.close
 		end
 		
-		# Acquire a generic context which will acquire a connection on demand.
-		def context(**options)
-			context = Context::Transient.new(@pool, **options)
-			
-			return context unless block_given?
-			
-			begin
-				yield context
-			ensure
-				context.close
-			end
-		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.
@@ -53,12 +39,16 @@ module DB
 			return session unless block_given?
 			
 			begin
+				session.connect!
+				
 				yield session
 			ensure
 				session.close
 			end
 		end
 		
+		alias context session
+		
 		# 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.
@@ -67,7 +57,7 @@ module DB
 		def transaction(**options)
 			transaction = Context::Transaction.new(@pool, **options)
 			
-			transaction.call("BEGIN")
+			transaction.begin
 			
 			return transaction unless block_given?
 			

data/lib/db/context/session.rb

@@ -3,10 +3,11 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative '../query'
-require_relative '../records'
+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
@@ -16,12 +17,11 @@ module DB
 				@connection = nil
 			end
 			
-			def connection?
-				@connection != nil
-			end
+			attr :pool
+			attr :connection
 			
-			# Lazy initialize underlying connection.
-			def connection
+			# Pin a connection to the current session.
+			def connect!
 				@connection ||= @pool.acquire
 			end
 			
@@ -33,33 +33,63 @@ 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
 			
-			def query(fragment = String.new, **parameters)
-				if parameters.empty?
-					Query.new(self, fragment)
+			# 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
 				else
-					Query.new(self).interpolate(fragment, **parameters)
+					@pool.acquire do |connection|
+						@connection = connection
+						
+						yield connection
+					ensure
+						@connection = nil
+					end
 				end
 			end
 			
-			def clause(fragment = String.new)
-				Query.new(self, fragment)
-			end
-			
 			# Send a query to the server.
 			# @parameter statement [String] The SQL query to send.
 			def call(statement, **options)
-				connection = self.connection
-				
-				connection.send_query(statement, **options)
-				
-				if block_given?
-					yield connection
-				elsif result = connection.next_result
-					return Records.wrap(result)
+				self.with_connection do |connection|
+					connection.send_query(statement, **options)
+					
+					if block_given?
+						yield connection
+					elsif result = connection.next_result
+						return Records.wrap(result)
+					end
+				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?
+						Query.new(self, fragment)
+					else
+						Query.new(self).interpolate(fragment, **parameters)
+					end
+				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)
 				end
 			end
 		end

data/lib/db/context/transaction.rb

@@ -3,17 +3,26 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'session'
+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
+				self.connect!
+				self.call("BEGIN")
+			end
+			
 			# Commit the transaction and return the connection to the connection pool.
 			def commit
 				self.call("COMMIT")
 				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/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
@@ -38,7 +43,7 @@ module DB
 		# @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 << " " unless @buffer.end_with?(" ") || @buffer.empty?
 			
 			@buffer << value
 			
@@ -50,7 +55,7 @@ module DB
 		# @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?(' ')
+			@buffer << " " unless @buffer.end_with?(" ")
 			
 			@connection.append_literal(value, @buffer)
 			
@@ -62,7 +67,7 @@ module DB
 		# @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?(' ')
+			@buffer << " " unless @buffer.end_with?(" ")
 			
 			@connection.append_identifier(value, @buffer)
 			
@@ -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.11.0"
+	VERSION = "0.13.0"
 end

data/lib/db.rb

@@ -3,6 +3,6 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'db/version'
-require_relative 'db/adapters'
-require_relative 'db/client'
+require_relative "db/version"
+require_relative "db/adapters"
+require_relative "db/client"

data/readme.md

@@ -21,6 +21,20 @@ 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.
+  - [db-mariadb](https://github.com/socketry/db-mariadb) - MariaDB/MySQL adapter for the DB gem.
+  - [db-model](https://github.com/socketry/db-model) - A simple object relational mapper (ORM) for the DB gem.
+  - [db-migrate](https://github.com/socketry/db-migrate) - Database migration tooling for the DB gem.
+  - [db-active\_record](https://github.com/socketry/db-active_record) - An ActiveRecord adapter for the DB gem.
+
 ## Contributing
 
 We welcome contributions to this project.

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.11.0
+  version: 0.13.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-07-27 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-pool
@@ -53,23 +52,26 @@ 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/context/transient.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
@@ -77,7 +79,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
@@ -85,15 +86,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: []

data/lib/db/context/transient.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
-
-require_relative 'session'
-
-module DB
-	module Context
-		# A connected context for sending queries and reading results.
-		class Transient < Session
-			def call(statement, **options, &block)
-				super
-			ensure
-				self.close
-			end
-		end
-	end
-end