fix: address review findings on concurrent-connections

Resolves issues raised in the PR #38 review:

- session: key sessions by resolved physical path (strip "file:" scheme,
  drop "?params", make absolute), matching what the native layer opens, so
  the same data path written different ways ("db" / "file:db" /
  "file:db?p=v" / ":memory:" / "file::memory:") is recognized as the same
  path instead of raising a spurious "conflicting path" error. Resolution
  is OS-aware (Windows drive-letter paths). Path()/Cleanup now use the
  resolved directory, fixing a wrong-dir RemoveAll that left the real data
  directory on disk for file:/param DSNs.
- session: gate Cleanup()'s RemoveAll on the refcount reaching zero so it
  no longer deletes a shared data directory while sibling sessions on the
  same path are still live.
- session: guard the native connection with a per-Session RWMutex. Query/
  QueryStream take a read lock and return an error on a closed session;
  Close/Cleanup take the write lock and wait for in-flight queries before
  freeing the connection. Fixes a use-after-free / crash when one session
  is queried and closed concurrently. purego connection.Close now nils its
  handle (idempotent; no double-free).
- driver: Driver.Open ties the connector's keeper session to the returned
  conn so closing the conn also releases the keeper; previously the keeper
  (a native connection + registry refcount + temp dir) leaked on every
  direct Driver.Open call.
- wrapper: ephemeralSession only retries with NewSession() on a genuine
  one-data-path-per-process conflict, surfacing unrelated errors instead of
  masking them.
- docs: chdb.md Query/QueryStream now describe attach-to-active-path
  semantics.

Tests: add before/after coverage for each fix (path spellings, shared-dir
cleanup, refcounted temp lifecycle, conflict-then-recover, Driver.Open
keeper balance, query-after-close, concurrent query/close under -race);
add defer db.Close() to driver tests that previously leaked *sql.DB; add
ActiveSessionRefs() for refcount assertions. go test ./... -race passes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: wudidapaopao

chdb-purego/chdb.go

@@ -112,9 +112,14 @@ func newChdbConn(conn *chdb_connection) ChdbConn {
 }
 
 // Close implements ChdbConn.
+//
+// Close is idempotent: it nils the underlying handle after freeing it so a
+// second Close (or a Close racing a Query that checks for a nil handle) does
+// not double-free the native connection.
 func (c *connection) Close() {
 	if c.conn != nil {
 		chdbCloseConn(c.conn)
+		c.conn = nil
 	}
 }
 

chdb.md

@@ -28,7 +28,7 @@ import "github.com/chdb-io/chdb-go/chdb"
 func Query(queryStr string, outputFormats ...string) (result chdbpurego.ChdbResult, err error)
 ```
 
-Query calls query\_conn with a default in\-memory session and default output format of "CSV" if not provided.
+Query runs a one\-shot query and returns the materialized result \(default output format "CSV"\). chDB allows only one data path per process, so if a session is already open this helper attaches to that session's data path; otherwise it uses an in\-memory database.
 
 <a name="QueryStream"></a>
 ## func [QueryStream](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb/wrapper.go#L23>)
@@ -37,7 +37,7 @@ Query calls query\_conn with a default in\-memory session and default output for
 func QueryStream(queryStr string, outputFormats ...string) (result chdbpurego.ChdbStreamResult, err error)
 ```
 
-Query calls query\_conn with a default in\-memory session and default output format of "CSV" if not provided.
+QueryStream is like Query but returns a streaming result that can be read in chunks, for large datasets that should not be fully materialized in memory. Like Query, it attaches to an already\-open session's data path, or uses an in\-memory database when none is open.
 
 <a name="Session"></a>
 ## type [Session](<https://github.com/s0und0fs1lence/chdb-go/blob/main/chdb/session.go#L14-L19>)

chdb/driver/driver.go

@@ -293,7 +293,25 @@ func (d Driver) Open(name string) (driver.Conn, error) {
 	if err != nil {
 		return nil, err
 	}
-	return cc.Connect(context.Background())
+	c, err := cc.Connect(context.Background())
+	if err != nil {
+		// Connect failed; release the keeper session NewConnect just opened so
+		// it does not leak (database/sql would normally own and close cc).
+		if closer, ok := cc.(*connector); ok {
+			_ = closer.Close()
+		}
+		return nil, err
+	}
+	// On the sql.Open path, database/sql keeps the connector and calls
+	// connector.Close() on db.Close(). A direct Driver.Open caller discards the
+	// connector, so tie the keeper session's lifetime to the returned
+	// connection: closing the conn also releases the keeper.
+	if cn, ok := c.(*conn); ok {
+		if cnr, ok := cc.(*connector); ok {
+			cn.connector = cnr
+		}
+	}
+	return c, nil
 }
 
 // OpenConnector expects the same format as driver.Open
@@ -312,6 +330,10 @@ type conn struct {
 	useUnsafe   bool
 	isStreaming bool
 	session     *chdb.Session
+	// connector is set only on the legacy Driver.Open path (not the sql.Open
+	// path, where database/sql owns and closes the connector). When set, Close
+	// also releases the connector's keeper session.
+	connector *connector
 
 	QueryFun  queryHandle
 	streamFun queryStream
@@ -334,6 +356,12 @@ func (c *conn) Close() error {
 		c.session.Close()
 		c.session = nil
 	}
+	// Only set on the Driver.Open path; releases the keeper that pins the data
+	// path/temp dir for the connector.
+	if c.connector != nil {
+		_ = c.connector.Close()
+		c.connector = nil
+	}
 	return nil
 }
 

chdb/driver/driver_open_test.go

@@ -0,0 +1,61 @@
+package chdbdriver
+
+import (
+	"database/sql"
+	"testing"
+
+	"github.com/chdb-io/chdb-go/chdb"
+)
+
+// TestDriverOpenNoKeeperLeak verifies that the legacy Driver.Open path does not
+// leak the connector's keeper session. database/sql owns the connector on the
+// sql.Open path and calls connector.Close(), but a direct Driver.Open(name)
+// discards the connector, so closing the returned conn must release the keeper
+// too. Pre-fix the keeper session (a native connection + a registry refcount)
+// leaks on every Open call.
+func TestDriverOpenNoKeeperLeak(t *testing.T) {
+	baseline := chdb.ActiveSessionRefs()
+
+	c, err := Driver{}.Open("session=" + session.ConnStr())
+	if err != nil {
+		t.Fatalf("Driver.Open failed: %s", err)
+	}
+	if err := c.Close(); err != nil {
+		t.Fatalf("conn.Close failed: %s", err)
+	}
+
+	if got := chdb.ActiveSessionRefs(); got != baseline {
+		t.Fatalf("Driver.Open leaked sessions: refs=%d, baseline=%d (keeper not released on conn.Close)", got, baseline)
+	}
+}
+
+// TestDbCloseReleasesRefs verifies the database/sql path balances refcounts:
+// opening a *sql.DB, running queries across multiple pooled connections, and
+// closing it returns the registry to its baseline (keeper + per-conn sessions
+// all released).
+func TestDbCloseReleasesRefs(t *testing.T) {
+	baseline := chdb.ActiveSessionRefs()
+
+	db, err := sql.Open("chdb", "session="+session.ConnStr())
+	if err != nil {
+		t.Fatalf("open db failed: %s", err)
+	}
+	db.SetMaxOpenConns(4)
+
+	for i := 0; i < 8; i++ {
+		var n int
+		if err := db.QueryRow("SELECT count() FROM numbers(10)").Scan(&n); err != nil {
+			t.Fatalf("query failed: %s", err)
+		}
+		if n != 10 {
+			t.Fatalf("got %d want 10", n)
+		}
+	}
+
+	if err := db.Close(); err != nil {
+		t.Fatalf("db.Close failed: %s", err)
+	}
+	if got := chdb.ActiveSessionRefs(); got != baseline {
+		t.Fatalf("db.Close left refs leaked: refs=%d, baseline=%d", got, baseline)
+	}
+}

chdb/driver/driver_test.go

@@ -50,6 +50,7 @@ func TestDb(t *testing.T) {
 	if err != nil {
 		t.Fatalf("open db fail, err:%s", err)
 	}
+	defer db.Close()
 	if db.Ping() != nil {
 		t.Fatalf("ping db fail")
 	}
@@ -88,6 +89,7 @@ func TestDbWithCompiledArgs(t *testing.T) {
 	if err != nil {
 		t.Errorf("open db fail, err:%s", err)
 	}
+	defer db.Close()
 	if db.Ping() != nil {
 		t.Errorf("ping db fail")
 	}
@@ -170,6 +172,7 @@ func TestDbWithSession(t *testing.T) {
 	if err != nil {
 		t.Fatalf("open db fail, err: %s", err)
 	}
+	defer db.Close()
 	if db.Ping() != nil {
 		t.Fatalf("ping db fail, err: %s", err)
 	}
@@ -217,6 +220,7 @@ func TestDbWithConnection(t *testing.T) {
 	if err != nil {
 		t.Fatalf("open db fail, err: %s", err)
 	}
+	defer db.Close()
 	if db.Ping() != nil {
 		t.Fatalf("ping db fail, err: %s", err)
 	}
@@ -251,6 +255,7 @@ func TestDbWithConnectionSqlDriverOnly(t *testing.T) {
 	if err != nil {
 		t.Fatalf("open db fail, err: %s", err)
 	}
+	defer db.Close()
 	if db.Ping() != nil {
 		t.Fatalf("ping db fail, err: %s", err)
 	}
@@ -309,6 +314,7 @@ func TestQueryRow(t *testing.T) {
 	if err != nil {
 		t.Fatalf("open db fail, err: %s", err)
 	}
+	defer db.Close()
 	if db.Ping() != nil {
 		t.Fatalf("ping db fail, err: %s", err)
 	}
@@ -339,6 +345,7 @@ func TestExec(t *testing.T) {
 	if err != nil {
 		t.Fatalf("open db fail, err: %s", err)
 	}
+	defer db.Close()
 	if db.Ping() != nil {
 		t.Fatalf("ping db fail, err: %s", err)
 	}