feat: support decimal (#58)

Author: RaphDal

README.md

@@ -188,6 +188,36 @@ will now also serialize ``float64`` (double-precision) columns as binary.
 You might see a performance uplift if this is a dominant data type in your
 ingestion workload.
 
+## Decimal columns
+
+QuestDB server version 9.2.0 and newer supports decimal columns with arbitrary precision and scale.
+The Go client converts supported decimal values to QuestDB's text/binary wire format automatically:
+
+- `DecimalColumn`: `questdb.Decimal`, including helpers like `questdb.NewDecimalFromInt64` and `questdb.NewDecimal`.
+- `DecimalColumnShopspring`: `github.com/shopspring/decimal.Decimal` values or pointers.
+- `DecimalColumnFromString`: `string` literals representing decimal values (validated at runtime).
+
+```go
+price := qdb.NewDecimalFromInt64(12345, 2) // 123.45 with scale 2
+commission := qdb.NewDecimal(big.NewInt(-750), 4) // -0.0750 with scale 4
+
+err = sender.
+    Table("trades").
+    Symbol("symbol", "ETH-USD").
+    DecimalColumn("price", price).
+    DecimalColumn("commission", commission).
+    AtNow(ctx)
+```
+
+To emit textual decimals, pass a validated string literal:
+
+```go
+err = sender.
+    Table("quotes").
+    DecimalColumnFromString("mid", "1.23456").
+    AtNow(ctx)
+```
+
 ## Pooled Line Senders
 
 **Warning: Experimental feature designed for use with HTTP senders ONLY**

buffer.go

@@ -86,7 +86,6 @@ type arrayElemType byte
 
 const (
 	arrayElemDouble arrayElemType = 10
-	arrayElemNull   arrayElemType = 33
 )
 
 // buffer is a wrapper on top of bytes.Buffer. It extends the
@@ -573,6 +572,77 @@ func (b *buffer) Float64Column(name string, val float64) *buffer {
 	return b
 }
 
+func (b *buffer) DecimalColumn(name string, val Decimal) *buffer {
+	if val.isNull() {
+		// Don't write null decimals
+		return b
+	}
+	if !b.prepareForField() {
+		return b
+	}
+	return b.decimalColumn(name, val)
+}
+
+func (b *buffer) decimalColumn(name string, val Decimal) *buffer {
+	if err := val.ensureValidScale(); err != nil {
+		b.lastErr = err
+		return b
+	}
+	b.lastErr = b.writeColumnName(name)
+	if b.lastErr != nil {
+		return b
+	}
+	b.WriteByte('=')
+	b.WriteByte('=')
+	b.WriteByte(decimalBinaryTypeCode)
+	b.WriteByte((uint8)(val.scale))
+	b.WriteByte(32 - val.offset)
+	b.Write(val.unscaled[val.offset:])
+	b.hasFields = true
+	return b
+}
+
+func (b *buffer) DecimalColumnFromString(name string, val string) *buffer {
+	if !b.prepareForField() {
+		return b
+	}
+	if err := validateDecimalText(val); err != nil {
+		b.lastErr = err
+		return b
+	}
+	b.lastErr = b.writeColumnName(name)
+	if b.lastErr != nil {
+		return b
+	}
+	b.WriteByte('=')
+	b.WriteString(val)
+	b.WriteByte('d')
+	b.hasFields = true
+	return b
+}
+
+func (b *buffer) DecimalColumnShopspring(name string, val ShopspringDecimal) *buffer {
+	if val == nil {
+		return b
+	}
+	if b.lastErr != nil {
+		return b
+	}
+	dec, err := convertShopspringDecimal(val)
+	if err != nil {
+		b.lastErr = err
+		return b
+	}
+	if dec.isNull() {
+		// Don't write null decimals
+		return b
+	}
+	if !b.prepareForField() {
+		return b
+	}
+	return b.decimalColumn(name, dec)
+}
+
 func (b *buffer) Float64ColumnBinary(name string, val float64) *buffer {
 	if !b.prepareForField() {
 		return b
@@ -597,17 +667,17 @@ func (b *buffer) Float64ColumnBinary(name string, val float64) *buffer {
 }
 
 func (b *buffer) Float64Array1DColumn(name string, values []float64) *buffer {
+	if values == nil {
+		// Don't write null arrays
+		return b
+	}
 	if !b.prepareForField() {
 		return b
 	}
 	b.lastErr = b.writeColumnName(name)
 	if b.lastErr != nil {
 		return b
 	}
-	if values == nil {
-		b.writeNullArray()
-		return b
-	}
 
 	dim1 := len(values)
 	if dim1 > MaxArrayElements {
@@ -629,6 +699,10 @@ func (b *buffer) Float64Array1DColumn(name string, values []float64) *buffer {
 }
 
 func (b *buffer) Float64Array2DColumn(name string, values [][]float64) *buffer {
+	if values == nil {
+		// Don't write null arrays
+		return b
+	}
 	if !b.prepareForField() {
 		return b
 	}
@@ -637,11 +711,6 @@ func (b *buffer) Float64Array2DColumn(name string, values [][]float64) *buffer {
 		return b
 	}
 
-	if values == nil {
-		b.writeNullArray()
-		return b
-	}
-
 	// Validate array shape
 	dim1 := len(values)
 	var dim2 int
@@ -678,6 +747,10 @@ func (b *buffer) Float64Array2DColumn(name string, values [][]float64) *buffer {
 }
 
 func (b *buffer) Float64Array3DColumn(name string, values [][][]float64) *buffer {
+	if values == nil {
+		// Don't write null arrays
+		return b
+	}
 	if !b.prepareForField() {
 		return b
 	}
@@ -686,11 +759,6 @@ func (b *buffer) Float64Array3DColumn(name string, values [][][]float64) *buffer
 		return b
 	}
 
-	if values == nil {
-		b.writeNullArray()
-		return b
-	}
-
 	// Validate array shape
 	dim1 := len(values)
 	var dim2, dim3 int
@@ -740,6 +808,10 @@ func (b *buffer) Float64Array3DColumn(name string, values [][][]float64) *buffer
 }
 
 func (b *buffer) Float64ArrayNDColumn(name string, value *NdArray[float64]) *buffer {
+	if value == nil {
+		// Don't write null arrays
+		return b
+	}
 	if !b.prepareForField() {
 		return b
 	}
@@ -748,11 +820,6 @@ func (b *buffer) Float64ArrayNDColumn(name string, value *NdArray[float64]) *buf
 		return b
 	}
 
-	if value == nil {
-		b.writeNullArray()
-		return b
-	}
-
 	shape := value.Shape()
 	numDims := value.NDims()
 	// Write nDims
@@ -831,7 +898,7 @@ func (b *buffer) At(ts time.Time, sendTs bool) error {
 		b.DiscardPendingMsg()
 		return fmt.Errorf("table name was not provided: %w", errInvalidMsg)
 	}
-	if !b.hasTags && !b.hasFields {
+	if !b.hasTags && !b.hasFields && !sendTs {
 		b.DiscardPendingMsg()
 		return fmt.Errorf("no symbols or columns were provided: %w", errInvalidMsg)
 	}
@@ -855,11 +922,3 @@ func (b *buffer) writeFloat64ArrayHeader(dims byte) {
 	b.WriteByte(byte(arrayElemDouble))
 	b.WriteByte(dims)
 }
-
-func (b *buffer) writeNullArray() {
-	b.WriteByte('=')
-	b.WriteByte('=')
-	b.WriteByte(byte(arrayCode))
-	b.WriteByte(byte(arrayElemNull))
-	b.hasFields = true
-}