Add Database#checkout, Connection#release for non block connection use (#38)

spec/database_spec.cr

@@ -114,6 +114,41 @@ describe DB::Database do
     end
   end
 
+  it "should checkout different connections until they are released" do
+    DummyDriver::DummyConnection.clear_connections
+    DB.open "dummy://localhost:1027?initial_pool_size=1&max_pool_size=2&retry_attempts=0" do |db|
+      the_first_cnn = uninitialized DB::Connection
+      the_second_cnn = uninitialized DB::Connection
+
+      the_first_cnn = db.checkout
+      the_second_cnn = db.checkout
+      the_second_cnn.should_not eq(the_first_cnn)
+      db.pool.is_available?(the_first_cnn).should be_false
+      db.pool.is_available?(the_second_cnn).should be_false
+
+      the_first_cnn.release
+      db.pool.is_available?(the_first_cnn).should be_true
+      db.pool.is_available?(the_second_cnn).should be_false
+
+      db.checkout.should eq(the_first_cnn)
+      the_first_cnn.release
+      the_second_cnn.release
+    end
+  end
+
+  it "should not return explicit checked out connections to the pool after query" do
+    DummyDriver::DummyConnection.clear_connections
+    DB.open "dummy://localhost:1027?initial_pool_size=1&max_pool_size=2&retry_attempts=0" do |db|
+      cnn = db.checkout
+
+      cnn.query_all("1", as: String)
+
+      db.pool.is_available?(cnn).should be_false
+      cnn.release
+      db.pool.is_available?(cnn).should be_true
+    end
+  end
+
   describe "prepared_statements connection option" do
     it "defaults to true" do
       with_dummy "dummy://localhost:1027" do |db|

src/db/connection.cr

@@ -71,9 +71,16 @@ module DB
     protected def after_release
     end
 
+    # return this connection to the pool
+    # managed by the database. Should be used
+    # only if the connection was obtained by `Database#checkout`.
+    def release
+      @database.return_to_pool(self)
+    end
+
     # :nodoc:
     def release_from_statement
-      @database.return_to_pool(self) if @auto_release && !@transaction
+      self.release if @auto_release && !@transaction
     end
 
     # :nodoc:

src/db/database.cr

@@ -94,18 +94,26 @@ module DB
     end
 
     # yields a connection from the pool
-    # the connection is returned to the pool after
+    # the connection is returned to the pool
     # when the block ends
     def using_connection
-      connection = @pool.checkout
-      connection.auto_release = false
+      connection = self.checkout
       begin
         yield connection
       ensure
-        return_to_pool connection
+        connection.release
       end
     end
 
+    # returns a connection from the pool
+    # the returned connection must be returned
+    # to the pool by explictly calling `Connection#release`
+    def checkout
+      connection = @pool.checkout
+      connection.auto_release = false
+      connection
+    end
+
     # yields a `Transaction` from a connection of the pool
     # Refer to `BeginTransaction#transaction` for documentation.
     def transaction