Coverage.md

Coverage

Every behavior documented in the README and docs/ is listed here with the test that proves it, for each database it applies to. See Testing for the rules.

• A cell links to the end-to-end test in tests/ that runs against the real database.
• Unit-only checks are used only when the behavior is decided or rejected during generation, where the generated code cannot reach it.
• test/coverage_map_test.rb checks that every linked test exists.

Options and generated files

Documented behavior	PostgreSQL	MySQL	SQLite	Unit-only checks
Options: driver, Ruby target, types, Gemfile, module name, renames, exact names, overrides and global/local merge; CamelCase query file classes (admin_users.sql → AdminUsersSql); distinct prepared statements for modules sharing a pool (also names over 63 bytes)	test_generator_options_preserve_runtime_values_and_generate_expected_layouts	unit: MySQL-specific preparedStatements is rejected	test_generator_options_preserve_runtime_values_and_generate_expected_layouts	test_unknown_options_are_rejected_with_a_hint, test_override_forms, test_immutable_data_support, test_omitted_parts_mean_the_oldest_covered_release, test_version_decisions_agree_for_every_form, test_major_only_version_orders_as_its_oldest_release, test_legacy_timeout_guard_is_emitted_only_for_pre_33_targets, test_query_file_names_become_camel_case_classes, test_statement_names_of_different_classes_never_collide
preparedStatements disabled and configured moduleName	test_flow (Ruby 4.0 variant)	test_flow (Ruby 4.0 variant)	test_flow (Ruby 4.0 variant)	test_pg_can_skip_prepared_statements
Generated query/model/connection files and generated .rbs; runtime return/attribute checks	test_models_are_generated_for_every_table, test_declared_types_match_runtime_values	test_models_are_generated_for_every_table, test_declared_types_match_runtime_values, test_declared_types_match_runtime_values_for_nulls	test_models_are_generated_for_every_table, test_declared_types_match_runtime_values	test_unknown_types_in_queries_fall_back_to_untyped, test_models_fall_back_to_untyped_for_unknown_types
RuboCop style, query/schema comments and source SQL constants	test_flow	test_flow	test_flow	test_generated_ruby_is_formatted_like_ruby, test_ruby31_struct_rows_of_unnamed_columns_are_rubocop_clean, test_query_comments_become_doc_comments, test_table_column_and_enum_comments_become_doc_comments, test_sql_is_a_frozen_raw_heredoc
Query names like HasAuthors / IsActive keep their name and stay RuboCop-clean	test_predicate_like_query_names_are_kept	test_predicate_like_query_names_are_kept	test_predicate_like_query_names_are_kept	test_predicate_like_query_names_are_rubocop_clean

Queries

Documented behavior	PostgreSQL	MySQL	SQLite	Unit-only checks
:one, :many, :exec, nil for no row, bang finder methods and NotFound error	test_flow, test_one_on_empty_table_returns_nil, test_every_one_query_has_a_bang_method, test_bang_finder_raises_not_found	test_flow, test_one_on_empty_table_returns_nil, test_every_one_query_has_a_bang_method, test_bang_finder_raises_not_found	test_flow, test_every_one_query_has_a_bang_method, test_bang_finder_raises_not_found	test_command_signatures
:execrows, :execlastid, :execresult semantics	test_execrows_returns_affected_row_count, test_execlastid_returns_the_returning_column, test_execresult_returns_rows_affected	test_execrows_returns_affected_row_count, test_execrows_counts_changed_rows_unless_found_rows_is_set, test_execlastid_returns_the_new_id, test_execresult_returns_rows_affected_and_last_id	test_execrows_returns_affected_row_count, test_execlastid_returns_the_returning_column, test_execresult_returns_rows_affected_and_last_id	test_pg_and_sqlite_execlastid_need_returning
:execresult with RETURNING runs the statement	covered by :execresult semantics	covered by :execresult semantics	test_execresult_with_returning_runs_the_statement
:batchexec, :batchone, :batchmany; batches use one connection and are not atomic unless wrapped in a transaction	test_batch_commands_run_once_per_args, test_batches_are_not_atomic_without_a_transaction	test_batch_commands_run_once_per_args, test_batches_are_not_atomic_without_a_transaction	test_batch_commands_run_once_per_args, test_batches_are_not_atomic_without_a_transaction	test_batch_commands_take_an_array_of_args
:copyfrom round trips, all-or-none behavior and conflict clauses	test_copyfrom_many_rows_and_none, test_seeded_random_copyfrom_round_trip_and_duplicate_is_atomic	test_copyfrom_loads_binary_values, test_seeded_random_copyfrom_round_trip_and_duplicate_is_atomic	test_copyfrom_is_all_or_nothing, test_copyfrom_keeps_conflict_clauses	test_copyfrom_keeps_or_rejects_conflict_clauses
:copyfrom keeps the case of quoted / mixed-case table and column names (MySQL LOAD DATA)	test_copyfrom_keeps_the_case_of_table_and_column_names	test_copyfrom_keeps_the_case_of_table_and_column_names	test_copyfrom_keeps_the_case_of_table_and_column_names
:copyfrom takes any Enumerable (empty, lazy, Enumerator)	test_copyfrom_takes_any_enumerable	test_copyfrom_takes_any_enumerable	test_copyfrom_takes_any_enumerable
sqlc.arg, sqlc.narg, positional/named keyword args, optional nils and argument errors	test_named_nullable_arguments_are_optional, test_required_argument_after_optional_named_argument, test_missing_keyword_arguments_are_errors	test_nullable_named_arg, test_required_argument_after_optional_named_argument, test_missing_keyword_arguments_are_errors	test_nullable_named_arg, test_required_argument_after_optional_named_argument, test_missing_keyword_arguments_are_errors	test_named_nullable_parameters_are_optional_keywords
sqlc.slice, placeholder order and repeated parameters	unit: PostgreSQL uses arrays instead of slices	test_slice	test_slice, test_numbered_placeholders_keep_their_bindings_after_slice_expansion, test_non_slice_numbered_placeholders_keep_sql_order, test_batch_numbered_placeholders_keep_sql_order	test_slices_are_rejected_for_postgres
Empty sqlc.slice: IN matches nothing, NOT IN everything	unit: PostgreSQL uses arrays instead of slices	test_empty_slice_matches_nothing, test_not_in_an_empty_slice_matches_everything	test_empty_slice_matches_nothing, test_not_in_an_empty_slice_matches_everything
sqlc.embed, outer-join nil, same table embedded twice	test_embed, test_embed_on_the_outer_side_of_a_join_is_nil_without_a_match, test_same_table_embedded_twice	test_embed, test_outer_join_embed_is_nil_without_a_match, test_same_table_embedded_twice	test_embed, test_outer_join_embed_is_nil_without_a_match, test_same_table_embedded_twice	test_embedded_tables_become_model_attributes
Unnamed result columns (column_1, ...) and aliases with quotes	test_unnamed_result_columns_are_read_by_position, test_alias_with_a_quote_is_read	test_unnamed_result_columns_are_read_by_position, test_alias_with_a_quote_is_read	test_unnamed_result_columns_are_read_by_position, test_alias_with_a_quote_is_read

Rows, models and names

Documented behavior	PostgreSQL	MySQL	SQLite	Unit-only checks
Frozen Ruby 3.2+ Data, mutable older Struct, with, to_h, pattern matching	test_rows_and_embedded_models_have_supported_layout_and_pattern_matching	test_rows_and_embedded_models_have_supported_layout_and_pattern_matching	test_rows_and_embedded_models_have_supported_layout_and_pattern_matching	test_struct_classes_are_valid_and_usable, test_data_classes_are_usable
Rows through Marshal (Rails.cache) and JSON (to_h.to_json)	test_rows_round_trip_through_marshal_and_json	test_rows_round_trip_through_marshal_and_json	test_rows_round_trip_through_marshal_and_json
Names: keywords, method collisions (also private row hooks such as initialize), acronyms, quoted mixed case, repeated $n, plural models	test_keyword_and_method_names_keep_distinct_row_and_argument_names, test_repeated_column_parameters_get_distinct_names	test_keyword_and_method_names_keep_distinct_row_and_argument_names, test_repeated_positional_parameters_get_distinct_names	test_keyword_and_method_names_keep_distinct_row_and_argument_names	test_snake_case_keeps_acronyms_together, test_query_names_cannot_replace_generated_methods, test_tables_with_the_same_singular_get_distinct_models, test_columns_named_like_row_methods_still_build_and_read_rows
Models named like Ruby / driver constants (Exception, Data, Thread, Set, Monitor, ...) do not shadow them	test_models_named_like_core_constants_do_not_shadow_them	test_models_named_like_core_constants_do_not_shadow_them	test_models_named_like_core_constants_do_not_shadow_them

Types

Documented behavior	PostgreSQL	MySQL	SQLite	Unit-only checks
Enums, constants (also for keyword / invalid names), database labels and MySQL SET	test_enum_column, test_enum_values_named_like_ruby_keywords_get_valid_constants	test_enum_and_set_columns, test_enum_values_named_like_ruby_keywords_get_valid_constants	not supported by the SQLite schema	test_models_cover_tables_and_enums
Top-level Float JSON parameters, Symbol enum values	test_top_level_float_json_parameters_round_trip_exactly	test_symbol_enum_value_is_bound_as_its_name	not SQLite (no enums / JSON encoding)
PostgreSQL arrays, JSON/JSONB, type round trips and RBS; a Time keeps its instant in a timestamp column whatever its offset; a DateTime keeps its instant in timestamp / timestamptz	test_array_parameters, test_numeric_types_round_trip, test_string_types_round_trip, test_datetime_types_round_trip, test_array_types_round_trip, test_special_types_round_trip, test_type_families_round_trip_nil, test_declared_types_match_runtime_values, test_declared_types_match_runtime_values_for_nulls, test_timestamp_parameters_keep_their_instant_whatever_their_offset, test_datetime_parameters_keep_their_instant, test_json_and_jsonb_parameters_round_trip_all_json_value_types	not PostgreSQL types	not PostgreSQL types	test_multi_dimensional_arrays, test_more_postgres_types_composites_and_domains
PostgreSQL arrays of enums created after the connection was opened	test_enum_arrays_of_a_type_created_after_connecting_are_decoded	not MySQL	not SQLite
MySQL unsigned integers, BIT, YEAR, DATETIME/TIME (a Time keeps its instant in any zone, also in :copyfrom), JSON, enums/SET and client quoting	not PostgreSQL	test_client_side_quoting_round_trips_supported_values, test_time_values_keep_their_instant_whatever_their_offset, test_time_values_follow_a_utc_database_timezone, test_declared_types_match_runtime_values	not MySQL	test_mysql_uses_client_side_binding_and_sqlite_closes_prepared_statements
SQLite affinity, JSON/UUID, and NUMERIC integer/float results	not PostgreSQL	not MySQL	test_declared_types_match_runtime_values, test_declared_types_with_parameters	test_sqlite_declared_types_follow_type_affinity, test_sqlite_json_and_uuid_declarations_are_strings
SQLite JSON / UUID columns are Strings, also numeric-looking text	not PostgreSQL	not MySQL	test_json_and_uuid_columns_return_strings_that_look_numeric

Connections

Documented behavior	PostgreSQL	MySQL	SQLite	Unit-only checks
Connections, injected pools, reconnect behavior and SQLite serialization	test_queries_can_share_an_injected_pool, test_a_connection_closed_by_the_server_is_reconnected, test_connection_lost_inside_transaction_is_not_reconnected_until_the_transaction_ends	test_queries_can_share_an_injected_pool, test_a_connection_closed_by_the_server_is_replaced, test_a_stopped_async_task_does_not_leave_a_closed_connection_in_the_pool	test_fibers_sharing_a_database_take_turns, test_threads_sharing_a_database_take_turns_in_transactions, test_a_database_returning_hash_rows_still_builds_rows	test_engine_must_match_the_driver
pg: QuerySql.connect takes a connection URL (DATABASE_URL)	test_connect_accepts_a_connection_url	not MySQL (mysql2 takes no URL)	not SQLite (no connect)
A connection shared with another library keeps its settings (pg type maps / field_name_type, mysql2 query options and default_query_options, SQLite results_as_hash)	test_a_connection_shared_with_another_library_keeps_its_settings	test_a_client_with_other_query_options_still_returns_typed_rows	test_a_database_shared_with_another_library_keeps_its_settings
Forked processes (Puma / Sidekiq workers): pooled connections are replaced in the child without ending the parent's sessions; pg direct connections reconnect, mysql2 direct clients raise, SQLite children open their own database	test_a_forked_child_leaves_the_parent_connections_usable	test_a_forked_child_leaves_the_parent_connections_usable	test_a_forked_child_opens_its_own_database_and_leaves_the_parent_usable
A forked child's plain exit leaves the parent's sessions open: a pooled connection another thread has checked out at fork time, a direct connection the child never uses	test_a_child_exit_leaves_connections_checked_out_or_unused_at_fork_open	test_a_child_exit_leaves_connections_checked_out_or_unused_at_fork_open	not SQLite (a child opens its own database)
Schema-per-tenant search_path switching with prepared statements	test_queries_follow_the_search_path_of_each_tenant	not MySQL (databases, no search path)	not SQLite (no schemas)
Primary + read-replica query objects; a write to the read-only replica raises and leaves it usable	test_primary_and_read_replica_query_objects	test_primary_and_read_replica_query_objects	test_primary_and_read_replica_query_objects
Memoized frozen query objects, subclasses and prepended wrappers forwarding ... / **, SimpleDelegator, shared across threads	test_memoized_frozen_subclassed_and_wrapped_query_objects	test_memoized_frozen_subclassed_and_wrapped_query_objects	test_memoized_frozen_subclassed_and_wrapped_query_objects
Fiber scheduler concurrency / MySQL no prepared-statement leaks	test_queries_run_concurrently_under_the_fiber_scheduler	test_generated_queries_overlap_under_sync_including_transactions, test_generated_queries_do_not_create_server_side_prepared_statements	test_fibers_sharing_a_database_take_turns
SQLite busy_handler_timeout= waits for another connection without blocking other threads	not PostgreSQL	not MySQL	test_busy_handler_timeout_waits_for_another_connection_without_blocking_threads

PostgreSQL prepared statements

Documented behavior	PostgreSQL	MySQL	SQLite	Unit-only checks
Modules sharing a connection keep separate prepared statements	test_generator_options_preserve_runtime_values_and_generate_expected_layouts	not MySQL (no server-side prepared statements)	not SQLite (statements are per call)	test_statements_are_named_after_the_module_and_query_class
PostgreSQL statements dropped by DEALLOCATE ALL / DISCARD ALL, or refused after a column type change (cached plan must not change result type), are prepared again	test_statements_are_prepared_again_after_deallocate_all, test_statements_are_prepared_again_after_a_column_type_change	not MySQL (no server-side prepared statements)	not SQLite	test_statements_are_named_after_the_module_and_query_class
PostgreSQL PREPARE interrupted (Timeout / Thread#raise, an exception raised by it) after the server ran it leaves the statement usable	test_an_interrupt_during_prepare_leaves_the_statement_usable, test_a_statement_left_prepared_by_a_failed_prepare_is_used	not MySQL (no server-side prepared statements)	not SQLite

Transactions

Documented behavior	PostgreSQL	MySQL	SQLite	Unit-only checks
Transaction result, commit/rollback, nested savepoint, exit semantics, rescued PostgreSQL error and rescued MySQL deadlock / lock wait timeout	test_nested_savepoint_rolls_back_while_outer_transaction_commits, test_transaction_nonlocal_exit_semantics_follow_timeout_version, test_transaction_whose_failed_statement_was_rescued_raises_instead_of_committing	test_nested_savepoint_rolls_back_while_outer_transaction_commits, test_transaction_nonlocal_exit_semantics_follow_timeout_version, test_rescued_deadlock_in_a_transaction_raises_instead_of_committing, test_rescued_deadlock_in_a_nested_transaction_raises_instead_of_committing, test_rescued_lock_wait_timeout_rolls_back_only_its_statement	test_nested_transaction_rolls_back_to_a_savepoint, test_transaction_nonlocal_exit_semantics_follow_timeout_version	test_nested_transactions_reject_isolation_and_mode
Isolation applied; invalid isolation/mode rejected with ArgumentError before begin; SQLite locks	test_transaction_isolation_level	test_transaction_isolation_level_is_applied	test_transaction_mode, test_immediate_and_exclusive_transactions_block_a_second_connection, test_unknown_transaction_mode_is_rejected_before_beginning	test_nested_transactions_reject_isolation_and_mode
transaction inside a transaction opened by another library: a savepoint (PostgreSQL, SQLite); MySQL limitation: commits it	test_transaction_inside_a_transaction_opened_by_another_library_is_a_savepoint	test_transaction_inside_a_transaction_opened_by_another_library_commits_it	test_transaction_inside_a_transaction_opened_by_another_library_is_a_savepoint
Transaction tx used from an Enumerator, Fiber, Thread, Async task and nested savepoint; TransactionEnded after the transaction	test_transaction_query_object_works_from_other_fibers_and_threads	test_transaction_query_object_works_from_other_fibers_and_threads	test_transaction_query_object_works_from_other_fibers_and_threads

Errors and interrupts

Documented behavior	PostgreSQL	MySQL	SQLite	Unit-only checks
A transaction ended by the database keeps the original error; a query abandoned by Timeout is cancelled; a Timeout in a PostgreSQL transaction raises Timeout::Error, also with Ruby 3.1's bundled timeout 0.2.0	test_query_abandoned_by_a_timeout_is_cancelled, test_transaction_timeout_rolls_back_and_keeps_connection_usable	test_deadlock_in_a_nested_transaction_raises_the_deadlock_error	test_conflict_that_ends_the_transaction_raises_the_constraint_error
Interrupts at BEGIN / COMMIT (Thread#raise, raised by the statement) roll back and leave no open transaction	test_interrupts_around_begin_and_commit_never_leave_the_connection_in_a_transaction	test_interrupts_around_begin_and_commit_never_leave_the_connection_in_a_transaction	test_interrupts_around_begin_and_commit_never_leave_the_database_in_a_transaction
Thread#kill inside a transaction rolls back; on PostgreSQL a kill during a query (inside or outside a transaction) cancels it at once and leaves the connection idle; on MySQL a kill during a query replaces the client and ends its transaction	test_thread_kill_rolls_back_and_leaves_connection_idle, test_thread_kill_during_a_query_cancels_it_and_leaves_the_connection_idle	test_thread_kill_rolls_back_and_leaves_connection_outside_transaction, test_thread_kill_during_a_query_replaces_the_connection_and_ends_its_transaction	test_thread_kill_rolls_back_and_leaves_connection_inactive

Logging

Documented behavior	PostgreSQL	MySQL	SQLite	Unit-only checks
Logger debug format, transaction logs, secret-free parameters	test_logger_receives_query_names_and_durations	test_logger_receives_query_names_and_durations	test_logger_receives_query_names_and_durations	test_logger_support

Generation errors

Documented behavior	PostgreSQL	MySQL	SQLite	Unit-only checks
Duplicate result columns, unsupported options, invalid :copyfrom clauses and generation errors	E2E cannot reach generation-time rejection	E2E cannot reach generation-time rejection	E2E cannot reach generation-time rejection	test_duplicate_result_columns_are_rejected, test_copyfrom_keeps_or_rejects_conflict_clauses, test_unknown_options_are_rejected_with_a_hint, test_query_names_cannot_replace_generated_methods
SQLite parameters sqlc does not report (ON CONFLICT ... DO UPDATE SET) are generation errors	not PostgreSQL	not MySQL	unit: rejected at generation	test_sqlite_parameters_sqlc_does_not_report_are_generation_errors, test_sqlite_placeholders_in_literals_and_comments_are_not_parameters