update documentation

Author: agoncear-mwb

README.md

@@ -67,9 +67,9 @@ func main() {
 	fmt.Println(result)
 
 	tmp_path := filepath.Join(os.TempDir(), "chdb_test")
-	defer os.RemoveAll(tmp_path)
 	// Stateful Query (persistent)
 	session, _ := chdb.NewSession(tmp_path)
+	// session cleanup will also delete the folder
 	defer session.Cleanup()
 
 	_, err = session.Query("CREATE DATABASE IF NOT EXISTS testdb; " +

chdb-purego/chdb.go

@@ -93,7 +93,7 @@ type connection struct {
 	conn **chdb_conn
 }
 
-func NewChdbConn(conn **chdb_conn) ChdbConn {
+func newChdbConn(conn **chdb_conn) ChdbConn {
 	c := &connection{
 		conn: conn,
 	}
@@ -131,7 +131,6 @@ func (c *connection) Query(queryStr string, formatStr string) (result ChdbResult
 	return newChdbResult(res), nil
 }
 
-// Ready implements ChdbConn.
 func (c *connection) Ready() bool {
 	if c.conn != nil {
 		deref := *c.conn
@@ -142,6 +141,7 @@ func (c *connection) Ready() bool {
 	return false
 }
 
+// RawQuery will execute the given clickouse query without using any session.
 func RawQuery(argc int, argv []string) (result ChdbResult, err error) {
 	res := queryStableV2(argc, argv)
 	if res == nil {
@@ -157,10 +157,38 @@ func RawQuery(argc int, argv []string) (result ChdbResult, err error) {
 	return newChdbResult(res), nil
 }
 
+// Session will keep the state of query.
+// If path is None, it will create a temporary directory and use it as the database path
+// and the temporary directory will be removed when the session is closed.
+// You can also pass in a path to create a database at that path where will keep your data.
+//
+// You can also use a connection string to pass in the path and other parameters.
+// Examples:
+//   - ":memory:" (for in-memory database)
+//   - "test.db" (for relative path)
+//   - "file:test.db" (same as above)
+//   - "/path/to/test.db" (for absolute path)
+//   - "file:/path/to/test.db" (same as above)
+//   - "file:test.db?param1=value1&param2=value2" (for relative path with query params)
+//   - "file::memory:?verbose&log-level=test" (for in-memory database with query params)
+//   - "///path/to/test.db?param1=value1&param2=value2" (for absolute path)
+//
+// Connection string args handling:
+//
+//	Connection string can contain query params like "file:test.db?param1=value1&param2=value2"
+//	"param1=value1" will be passed to ClickHouse engine as start up args.
+//
+//	For more details, see `clickhouse local --help --verbose`
+//	Some special args handling:
+//	- "mode=ro" would be "--readonly=1" for clickhouse (read-only mode)
+//
+// Important:
+//   - There can be only one session at a time. If you want to create a new session, you need to close the existing one.
+//   - Creating a new session will close the existing one.
 func NewConnection(argc int, argv []string) (ChdbConn, error) {
 	conn := connectChdb(argc, argv)
 	if conn == nil {
 		return nil, fmt.Errorf("could not create a chdb connection")
 	}
-	return NewChdbConn(conn), nil
+	return newChdbConn(conn), nil
 }

chdb-purego/chdb.h

@@ -1,7 +1,6 @@
 package chdbpurego
 
 import (
-	"runtime"
 	"unsafe"
 )
 
@@ -20,21 +19,3 @@ func ptrToGoString(ptr *byte) string {
 
 	return string(unsafe.Slice(ptr, length))
 }
-
-func stringToPtr(s string, pinner *runtime.Pinner) *byte {
-	// Pinne for convert string to bytes
-	// maybe there is simpler solution but it was late when I write this code.
-	data := make([]byte, len(s)+1)
-	copy(data, s)
-	data[len(s)] = 0 // Null-terminator
-
-	ptr := &data[0]
-	pinner.Pin(ptr)
-
-	return (*byte)(unsafe.Pointer(ptr))
-}
-
-func strToBytePtr(s string) *byte {
-	b := append([]byte(s), 0) // Convert to []byte and append null terminator
-	return &b[0]              // Get pointer to first byte
-}

chdb-purego/helpers.go

@@ -32,18 +32,29 @@ type chdb_conn struct {
 }
 
 type ChdbResult interface {
+	// Raw bytes result buffer, used for reading the result of clickhouse query
 	Buf() []byte
+	// String rapresentation of the the buffer
 	String() string
+	// Lenght in bytes of the buffer
 	Len() int
+	// Number of seconds elapsed for the query execution
 	Elapsed() float64
+	// Amount of rows returned by the query
 	RowsRead() uint64
+	// Amount of bytes returned by the query
 	BytesRead() uint64
+	// If the query had any error during execution, here you can retrieve the cause.
 	Error() error
+	// Free the query result and all the allocated memory
 	Free() error
 }
 
 type ChdbConn interface {
+	//Query executes the given queryStr in the underlying clickhouse connection, and output the result in the given formatStr
 	Query(queryStr string, formatStr string) (result ChdbResult, err error)
+	//Ready returns a boolean indicating if the connections is successfully established.
 	Ready() bool
+	//Close the connection and free the underlying allocated memory
 	Close()
 }

chdb-purego/types.go

@@ -8,27 +8,28 @@ import "github.com/chdb-io/chdb-go/chdb"
 
 ## Index
 
-- [func Query\(queryStr string, outputFormats ...string\) \*chdbstable.LocalResult](<#Query>)
+- [func Query\(queryStr string, outputFormats ...string\) \(result chdbpurego.ChdbResult, err error\)](<#Query>)
 - [type Session](<#Session>)
   - [func NewSession\(paths ...string\) \(\*Session, error\)](<#NewSession>)
   - [func \(s \*Session\) Cleanup\(\)](<#Session.Cleanup>)
   - [func \(s \*Session\) Close\(\)](<#Session.Close>)
+  - [func \(s \*Session\) ConnStr\(\) string](<#Session.ConnStr>)
   - [func \(s \*Session\) IsTemp\(\) bool](<#Session.IsTemp>)
   - [func \(s \*Session\) Path\(\) string](<#Session.Path>)
-  - [func \(s \*Session\) Query\(queryStr string, outputFormats ...string\) \*chdbstable.LocalResult](<#Session.Query>)
+  - [func \(s \*Session\) Query\(queryStr string, outputFormats ...string\) \(result chdbpurego.ChdbResult, err error\)](<#Session.Query>)
 
 
 <a name="Query"></a>
-## func [Query](<https://github.com/chdb-io/chdb-go/blob/main/chdb/wrapper.go#L8>)
+## func [Query](<https://github.com/agoncear-mwb/chdb-go/blob/main/chdb/wrapper.go#L8>)
 
 ```go
-func Query(queryStr string, outputFormats ...string) *chdbstable.LocalResult
+func Query(queryStr string, outputFormats ...string) (result chdbpurego.ChdbResult, err error)
 ```
 
-Query calls queryToBuffer with a default output format of "CSV" if not provided.
+Query calls query\_conn with a default in\-memory session and default output format of "CSV" if not provided.
 
 <a name="Session"></a>
-## type [Session](<https://github.com/chdb-io/chdb-go/blob/main/chdb/session.go#L11-L14>)
+## type [Session](<https://github.com/agoncear-mwb/chdb-go/blob/main/chdb/session.go#L15-L20>)
 
 
 
@@ -39,7 +40,7 @@ type Session struct {
 ```
 
 <a name="NewSession"></a>
-### func [NewSession](<https://github.com/chdb-io/chdb-go/blob/main/chdb/session.go#L19>)
+### func [NewSession](<https://github.com/agoncear-mwb/chdb-go/blob/main/chdb/session.go#L25>)
 
 ```go
 func NewSession(paths ...string) (*Session, error)
@@ -48,7 +49,7 @@ func NewSession(paths ...string) (*Session, error)
 NewSession creates a new session with the given path. If path is empty, a temporary directory is created. Note: The temporary directory is removed when Close is called.
 
 <a name="Session.Cleanup"></a>
-### func \(\*Session\) [Cleanup](<https://github.com/chdb-io/chdb-go/blob/main/chdb/session.go#L57>)
+### func \(\*Session\) [Cleanup](<https://github.com/agoncear-mwb/chdb-go/blob/main/chdb/session.go#L77>)
 
 ```go
 func (s *Session) Cleanup()
@@ -57,7 +58,7 @@ func (s *Session) Cleanup()
 Cleanup closes the session and removes the directory.
 
 <a name="Session.Close"></a>
-### func \(\*Session\) [Close](<https://github.com/chdb-io/chdb-go/blob/main/chdb/session.go#L49>)
+### func \(\*Session\) [Close](<https://github.com/agoncear-mwb/chdb-go/blob/main/chdb/session.go#L67>)
 
 ```go
 func (s *Session) Close()
@@ -69,8 +70,17 @@ Close closes the session and removes the temporary directory
 temporary directory is created when NewSession was called with an empty path.
 ```
 
+<a name="Session.ConnStr"></a>
+### func \(\*Session\) [ConnStr](<https://github.com/agoncear-mwb/chdb-go/blob/main/chdb/session.go#L88>)
+
+```go
+func (s *Session) ConnStr() string
+```
+
+ConnStr returns the current connection string used for the underlying connection
+
 <a name="Session.IsTemp"></a>
-### func \(\*Session\) [IsTemp](<https://github.com/chdb-io/chdb-go/blob/main/chdb/session.go#L68>)
+### func \(\*Session\) [IsTemp](<https://github.com/agoncear-mwb/chdb-go/blob/main/chdb/session.go#L93>)
 
 ```go
 func (s *Session) IsTemp() bool
@@ -79,7 +89,7 @@ func (s *Session) IsTemp() bool
 IsTemp returns whether the session is temporary.
 
 <a name="Session.Path"></a>
-### func \(\*Session\) [Path](<https://github.com/chdb-io/chdb-go/blob/main/chdb/session.go#L63>)
+### func \(\*Session\) [Path](<https://github.com/agoncear-mwb/chdb-go/blob/main/chdb/session.go#L83>)
 
 ```go
 func (s *Session) Path() string
@@ -88,12 +98,12 @@ func (s *Session) Path() string
 Path returns the path of the session.
 
 <a name="Session.Query"></a>
-### func \(\*Session\) [Query](<https://github.com/chdb-io/chdb-go/blob/main/chdb/session.go#L39>)
+### func \(\*Session\) [Query](<https://github.com/agoncear-mwb/chdb-go/blob/main/chdb/session.go#L56>)
 
 ```go
-func (s *Session) Query(queryStr string, outputFormats ...string) *chdbstable.LocalResult
+func (s *Session) Query(queryStr string, outputFormats ...string) (result chdbpurego.ChdbResult, err error)
 ```
 
-Query calls queryToBuffer with a default output format of "CSV" if not provided.
+Query calls \`query\_conn\` function with the current connection and a default output format of "CSV" if not provided.
 
 Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)