feat(client): introduce safer timestamp API (#23)

README.md

@@ -1,4 +1,4 @@
-[![GoDoc reference](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/questdb/go-questdb-client)
+[![GoDoc reference](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/questdb/go-questdb-client/v2)
 
 # go-questdb-client
 
@@ -8,9 +8,9 @@ Features:
 * Context-aware API.
 * Optimized for batch writes.
 * Supports TLS encryption and [ILP authentication](https://questdb.io/docs/reference/api/ilp/authenticate).
-* Tested against QuestDB 6.4.1 and newer versions.
+* Tested against QuestDB 7.3.2 and newer versions.
 
-Documentation is available [here](https://pkg.go.dev/github.com/questdb/go-questdb-client).
+Documentation is available [here](https://pkg.go.dev/github.com/questdb/go-questdb-client/v2).
 
 ## Usage
 
@@ -23,7 +23,7 @@ import (
 	"log"
 	"time"
 
-	qdb "github.com/questdb/go-questdb-client"
+	qdb "github.com/questdb/go-questdb-client/v2"
 )
 
 func main() {

examples.manifest.yaml

@@ -4,13 +4,13 @@
   lang: go
   path: examples/basic/main.go
   header: |-
-    Go client library [docs](https://pkg.go.dev/github.com/questdb/go-questdb-client)
+    Go client library [docs](https://pkg.go.dev/github.com/questdb/go-questdb-client/v2)
     and [repo](https://github.com/questdb/go-questdb-client).
 - name: ilp-auth
   lang: go
   path: examples/auth/main.go
   header: |-
-    Go client library [docs](https://pkg.go.dev/github.com/questdb/go-questdb-client)
+    Go client library [docs](https://pkg.go.dev/github.com/questdb/go-questdb-client/v2)
     and [repo](https://github.com/questdb/go-questdb-client).
   auth:
     kid: testUser1
@@ -22,7 +22,7 @@
   lang: go
   path: examples/auth-and-tls/main.go
   header: |-
-    Go client library [docs](https://pkg.go.dev/github.com/questdb/go-questdb-client)
+    Go client library [docs](https://pkg.go.dev/github.com/questdb/go-questdb-client/v2)
     and [repo](https://github.com/questdb/go-questdb-client).
   auth:
     kid: testUser1

examples/auth-and-tls/main.go

@@ -5,7 +5,7 @@ import (
 	"log"
 	"time"
 
-	qdb "github.com/questdb/go-questdb-client"
+	qdb "github.com/questdb/go-questdb-client/v2"
 )
 
 func main() {
@@ -14,32 +14,48 @@ func main() {
 		ctx,
 		qdb.WithAddress("localhost:9009"),
 		qdb.WithAuth(
-			"testUser1",
-			"5UjEMuA0Pj5pjK8a-fa24dyIf-Es5mYny3oE_Wmus48"),
+			"testUser1", // token name here
+			"5UjEMuA0Pj5pjK8a-fa24dyIf-Es5mYny3oE_Wmus48", // token here
+		),
 		qdb.WithTls(),
 	)
 	if err != nil {
 		log.Fatal(err)
 	}
 	// Make sure to close the sender on exit to release resources.
 	defer sender.Close()
+
 	// Send a few ILP messages.
+	bday, err := time.Parse(time.DateOnly, "1856-07-10")
+	if err != nil {
+		log.Fatal(err)
+	}
 	err = sender.
-		Table("trades").
-		Symbol("name", "test_ilp1").
-		Float64Column("value", 12.4).
-		At(ctx, time.Now().UnixNano())
+		Table("inventors").
+		Symbol("born", "Austrian Empire").
+		TimestampColumn("birthdate", bday). // Epoch in micros.
+		Int64Column("id", 0).
+		StringColumn("name", "Nicola Tesla").
+		At(ctx, time.Now()) // Epoch in nanos.
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	bday, err = time.Parse(time.DateOnly, "1847-02-11")
 	if err != nil {
 		log.Fatal(err)
 	}
 	err = sender.
-		Table("trades").
-		Symbol("name", "test_ilp2").
-		Float64Column("value", 11.4).
-		At(ctx, time.Now().UnixNano())
+		Table("inventors").
+		Symbol("born", "USA").
+		TimestampColumn("birthdate", bday).
+		Int64Column("id", 1).
+		StringColumn("name", "Thomas Alva Edison").
+		AtNow(ctx)
 	if err != nil {
 		log.Fatal(err)
 	}
+
 	// Make sure that the messages are sent over the network.
 	err = sender.Flush(ctx)
 	if err != nil {

examples/auth/main.go

@@ -5,7 +5,7 @@ import (
 	"log"
 	"time"
 
-	qdb "github.com/questdb/go-questdb-client"
+	qdb "github.com/questdb/go-questdb-client/v2"
 )
 
 func main() {
@@ -14,31 +14,47 @@ func main() {
 		ctx,
 		qdb.WithAddress("localhost:9009"),
 		qdb.WithAuth(
-			"testUser1",
-			"5UjEMuA0Pj5pjK8a-fa24dyIf-Es5mYny3oE_Wmus48"),
+			"testUser1", // token name here
+			"5UjEMuA0Pj5pjK8a-fa24dyIf-Es5mYny3oE_Wmus48", // token here
+		),
 	)
 	if err != nil {
 		log.Fatal(err)
 	}
 	// Make sure to close the sender on exit to release resources.
 	defer sender.Close()
+
 	// Send a few ILP messages.
+	bday, err := time.Parse(time.DateOnly, "1856-07-10")
+	if err != nil {
+		log.Fatal(err)
+	}
 	err = sender.
-		Table("trades").
-		Symbol("name", "test_ilp1").
-		Float64Column("value", 12.4).
-		At(ctx, time.Now().UnixNano())
+		Table("inventors").
+		Symbol("born", "Austrian Empire").
+		TimestampColumn("birthdate", bday). // Epoch in micros.
+		Int64Column("id", 0).
+		StringColumn("name", "Nicola Tesla").
+		At(ctx, time.Now()) // Epoch in nanos.
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	bday, err = time.Parse(time.DateOnly, "1847-02-11")
 	if err != nil {
 		log.Fatal(err)
 	}
 	err = sender.
-		Table("trades").
-		Symbol("name", "test_ilp2").
-		Float64Column("value", 11.4).
-		At(ctx, time.Now().UnixNano())
+		Table("inventors").
+		Symbol("born", "USA").
+		TimestampColumn("birthdate", bday).
+		Int64Column("id", 1).
+		StringColumn("name", "Thomas Alva Edison").
+		AtNow(ctx)
 	if err != nil {
 		log.Fatal(err)
 	}
+
 	// Make sure that the messages are sent over the network.
 	err = sender.Flush(ctx)
 	if err != nil {

examples/basic/main.go

@@ -5,7 +5,7 @@ import (
 	"log"
 	"time"
 
-	qdb "github.com/questdb/go-questdb-client"
+	qdb "github.com/questdb/go-questdb-client/v2"
 )
 
 func main() {
@@ -17,23 +17,38 @@ func main() {
 	}
 	// Make sure to close the sender on exit to release resources.
 	defer sender.Close()
+
 	// Send a few ILP messages.
+	bday, err := time.Parse(time.DateOnly, "1856-07-10")
+	if err != nil {
+		log.Fatal(err)
+	}
 	err = sender.
-		Table("trades").
-		Symbol("name", "test_ilp1").
-		Float64Column("value", 12.4).
-		At(ctx, time.Now().UnixNano())
+		Table("inventors").
+		Symbol("born", "Austrian Empire").
+		TimestampColumn("birthdate", bday). // Epoch in micros.
+		Int64Column("id", 0).
+		StringColumn("name", "Nicola Tesla").
+		At(ctx, time.Now()) // Epoch in nanos.
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	bday, err = time.Parse(time.DateOnly, "1847-02-11")
 	if err != nil {
 		log.Fatal(err)
 	}
 	err = sender.
-		Table("trades").
-		Symbol("name", "test_ilp2").
-		Float64Column("value", 11.4).
-		At(ctx, time.Now().UnixNano())
+		Table("inventors").
+		Symbol("born", "USA").
+		TimestampColumn("birthdate", bday).
+		Int64Column("id", 1).
+		StringColumn("name", "Thomas Alva Edison").
+		AtNow(ctx)
 	if err != nil {
 		log.Fatal(err)
 	}
+
 	// Make sure that the messages are sent over the network.
 	err = sender.Flush(ctx)
 	if err != nil {

go.mod

@@ -1,42 +1,63 @@
-module github.com/questdb/go-questdb-client
+module github.com/questdb/go-questdb-client/v2
 
 go 1.17
 
 require (
-	github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
-	github.com/Microsoft/go-winio v0.4.17 // indirect
-	github.com/Microsoft/hcsshim v0.8.23 // indirect
-	github.com/cenkalti/backoff/v4 v4.1.2 // indirect
-	github.com/containerd/cgroups v1.0.1 // indirect
-	github.com/containerd/containerd v1.5.9 // indirect
+	github.com/stretchr/testify v1.8.4
+	github.com/testcontainers/testcontainers-go v0.25.0
+)
+
+require (
+	dario.cat/mergo v1.0.0 // indirect
+	github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161 // indirect
+	github.com/Microsoft/go-winio v0.6.1 // indirect
+	github.com/Microsoft/hcsshim v0.11.1 // indirect
+	github.com/cenkalti/backoff/v4 v4.2.1 // indirect
+	github.com/containerd/cgroups v1.1.0 // indirect
+	github.com/containerd/containerd v1.7.6 // indirect
+	github.com/cpuguy83/dockercfg v0.3.1 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
-	github.com/docker/distribution v2.7.1+incompatible // indirect
-	github.com/docker/docker v20.10.11+incompatible // indirect
+	github.com/distribution/reference v0.5.0 // indirect
+	github.com/docker/distribution v2.8.3+incompatible // indirect
+	github.com/docker/docker v24.0.6+incompatible // indirect
 	github.com/docker/go-connections v0.4.0 // indirect
-	github.com/docker/go-units v0.4.0 // indirect
+	github.com/docker/go-units v0.5.0 // indirect
+	github.com/go-ole/go-ole v1.3.0 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
-	github.com/golang/groupcache v0.0.0-20200121045136-8c9f03a8e57e // indirect
-	github.com/golang/protobuf v1.5.2 // indirect
-	github.com/google/uuid v1.3.0 // indirect
-	github.com/magiconair/properties v1.8.5 // indirect
-	github.com/moby/sys/mount v0.2.0 // indirect
-	github.com/moby/sys/mountinfo v0.5.0 // indirect
-	github.com/moby/term v0.0.0-20210619224110-3f7ff695adc6 // indirect
-	github.com/morikuni/aec v0.0.0-20170113033406-39771216ff4c // indirect
+	github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
+	github.com/golang/protobuf v1.5.3 // indirect
+	github.com/google/uuid v1.3.1 // indirect
+	github.com/klauspost/compress v1.17.0 // indirect
+	github.com/lufia/plan9stats v0.0.0-20230326075908-cb1d2100619a // indirect
+	github.com/magiconair/properties v1.8.7 // indirect
+	github.com/moby/patternmatcher v0.6.0 // indirect
+	github.com/moby/sys/mount v0.3.3 // indirect
+	github.com/moby/sys/mountinfo v0.6.2 // indirect
+	github.com/moby/sys/sequential v0.5.0 // indirect
+	github.com/moby/term v0.5.0 // indirect
+	github.com/morikuni/aec v1.0.0 // indirect
 	github.com/opencontainers/go-digest v1.0.0 // indirect
-	github.com/opencontainers/image-spec v1.0.2 // indirect
-	github.com/opencontainers/runc v1.0.2 // indirect
+	github.com/opencontainers/image-spec v1.1.0-rc5 // indirect
+	github.com/opencontainers/runc v1.1.9 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/sirupsen/logrus v1.8.1 // indirect
-	github.com/stretchr/objx v0.2.0 // indirect
-	github.com/stretchr/testify v1.7.1 // indirect
-	github.com/testcontainers/testcontainers-go v0.13.0 // indirect
-	go.opencensus.io v0.22.3 // indirect
-	golang.org/x/net v0.0.0-20211108170745-6635138e15ea // indirect
-	golang.org/x/sys v0.0.0-20211124211545-fe61309f8881 // indirect
-	google.golang.org/genproto v0.0.0-20201110150050-8816d57aaa9a // indirect
-	google.golang.org/grpc v1.33.2 // indirect
-	google.golang.org/protobuf v1.27.1 // indirect
-	gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b // indirect
+	github.com/power-devops/perfstat v0.0.0-20221212215047-62379fc7944b // indirect
+	github.com/shirou/gopsutil/v3 v3.23.9 // indirect
+	github.com/shoenig/go-m1cpu v0.1.6 // indirect
+	github.com/sirupsen/logrus v1.9.3 // indirect
+	github.com/stretchr/objx v0.5.0 // indirect
+	github.com/tklauser/go-sysconf v0.3.12 // indirect
+	github.com/tklauser/numcpus v0.6.1 // indirect
+	github.com/yusufpapurcu/wmi v1.2.3 // indirect
+	go.opencensus.io v0.24.0 // indirect
+	golang.org/x/exp v0.0.0-20231005195138-3e424a577f31 // indirect
+	golang.org/x/mod v0.13.0 // indirect
+	golang.org/x/net v0.16.0 // indirect
+	golang.org/x/sys v0.13.0 // indirect
+	golang.org/x/tools v0.14.0 // indirect
+	google.golang.org/genproto v0.0.0-20230920204549-e6e6cdab5c13 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20231002182017-d307bd883b97 // indirect
+	google.golang.org/grpc v1.58.2 // indirect
+	google.golang.org/protobuf v1.31.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 )