v4: Refactor #new and #connect

[andyundso]

This PR refactors a few aspects around #new and #connect on the TinyTds::Client.

First, use keyword arguments instead of an opts hash. the list of arguments is quite long, but it allows users to take advantage of pattern matching when passing arguments to initialising a new client. The values are also preserved as instance variables in the TinyTds::Client, allowing to implement the second point of this PR.

Second, I removed calling #connect from #new. Instead, #connect is called from either #do, #insert or #execute shortly before the SQL is sent to the server (using active?, means a reconnect also happens automatically if the FreeTDS DBPROCESS died). I originally wanted that #connect has to be called manually, but from a usage-perspective, this is rather cumbersome, especially when we know best when #connect has to be called.

[Copilot]

Pull Request Overview

This PR refactors the TinyTds::Client initialization and connection handling by separating the #new and #connect methods and modernizing the API to use keyword arguments.

• Switched from hash-based options to keyword arguments for TinyTds::Client.new
• Separated connection logic from initialization - #connect is now called automatically before SQL execution
• Implemented GVL (Global Virtual Machine Lock) handoff during connection operations for better multi-threading performance

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
lib/tiny_tds/client.rb	Refactored constructor to use keyword arguments and separated connection logic
ext/tiny_tds/client.c	Updated C extension to support automatic connection before SQL execution and GVL handoff
test/test_helper.rb	Updated test helper to use new keyword argument syntax
test/client_test.rb	Updated tests to reflect new connection behavior and API changes
test/result_test.rb	Minor test adjustment for new connection state handling
README.md	Updated documentation to reflect keyword arguments and renamed appname to app_name
CHANGELOG.md	Added changelog entries for the breaking changes

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

The removal of the #ifdef DBSETLDBNAME guard makes this code dependent on a specific FreeTDS version without fallback handling. Consider adding version checks or error handling for systems where DBSETLDBNAME is not available.

[Copilot]

There's a trailing '+' character at the end of the line that should be removed.

Suggested change

	* Instead, before running `#do`, `#execute` or `#insert`, `tiny_tds` will check if the connection is active and re-connect if needed.+
	* Instead, before running `#do`, `#execute` or `#insert`, `tiny_tds` will check if the connection is active and re-connect if needed.

[andyundso]

Looks like this introduces an issue with the connection_pool / threading on Windows:

D:/a/tiny_tds/tiny_tds/vendor/bundle/ruby/3.3.0/gems/connection_pool-2.5.4/lib/connection_pool/timed_stack.rb:65: [BUG] win32_mutex_lock: WAIT_ABANDONED
ruby 3.3.9 (2025-07-24 revision f5c772fc7c) [x64-mingw-ucrt]

-- Control frame information -----------------------------------------------
c:0008 p:---- s:0041 e:000040 CFUNC  :synchronize
c:0007 p:0049 s:0037 e:000036 METHOD D:/a/tiny_tds/tiny_tds/vendor/bundle/ruby/3.3.0/gems/connection_pool-2.5.4/lib/connection_pool/timed_stack.rb:65
c:0006 p:0081 s:0030 e:000026 METHOD D:/a/tiny_tds/tiny_tds/vendor/bundle/ruby/3.3.0/gems/connection_pool-2.5.4/lib/connection_pool.rb:160
c:0005 p:0006 s:0022 e:000021 BLOCK  D:/a/tiny_tds/tiny_tds/vendor/bundle/ruby/3.3.0/gems/connection_pool-2.5.4/lib/connection_pool.rb:108 [FINISH]
c:0004 p:---- s:0018 e:000017 CFUNC  :handle_interrupt
c:0003 p:0015 s:0013 e:000012 METHOD D:/a/tiny_tds/tiny_tds/vendor/bundle/ruby/3.3.0/gems/connection_pool-2.5.4/lib/connection_pool.rb:107
c:0002 p:0012 s:0008 e:000007 BLOCK  D:/a/tiny_tds/tiny_tds/test/thread_test.rb:28 [FINISH]
c:0001 p:---- s:0003 e:000002 DUMMY  [FINISH]

-- Ruby level backtrace information ----------------------------------------
D:/a/tiny_tds/tiny_tds/test/thread_test.rb:28:in `block (5 levels) in <class:ThreadTest>'
D:/a/tiny_tds/tiny_tds/vendor/bundle/ruby/3.3.0/gems/connection_pool-2.5.4/lib/connection_pool.rb:107:in `with'
D:/a/tiny_tds/tiny_tds/vendor/bundle/ruby/3.3.0/gems/connection_pool-2.5.4/lib/connection_pool.rb:107:in `handle_interrupt'
D:/a/tiny_tds/tiny_tds/vendor/bundle/ruby/3.3.0/gems/connection_pool-2.5.4/lib/connection_pool.rb:108:in `block in with'
D:/a/tiny_tds/tiny_tds/vendor/bundle/ruby/3.3.0/gems/connection_pool-2.5.4/lib/connection_pool.rb:160:in `checkout'
D:/a/tiny_tds/tiny_tds/vendor/bundle/ruby/3.3.0/gems/connection_pool-2.5.4/lib/connection_pool/timed_stack.rb:65:in `pop'
D:/a/tiny_tds/tiny_tds/vendor/bundle/ruby/3.3.0/gems/connection_pool-2.5.4/lib/connection_pool/timed_stack.rb:65:in `synchronize'

-- Threading information ---------------------------------------------------
Total ractor count: 1
Ruby thread count for this ractor: 15

will need to setup a development environment on Windows to see what is going on.

[andyundso]

I think I see it. I'll also have to do nogvl_setup and nogvl_cleanup for these two new functions. they need a DBPROCESS in order to find the userdata where we setup everything to not touch the Ruby VM during handing off the GVL. But for dbopen we do not have a DBPROCESS object yet, so some more refactoring needed. might need to rewrite this branch to first refactor this before trying again with the no GVL stuff.

(both tiny tds client wrapper and the DBPROCESS with dbgetuserdata point to the same userdata where these things are managed).

[andyundso]

I've removed handing off the GVL for now from this branch and will look into it with separate PRs to implement it step-by-step (first dbuse, then dbopen).