Microsoft Visual FoxPro / dBase Library for Go

Overview

Key Features

Use Cases

Quick Start

Installation

go get github.com/valentin-kaiser/go-dbase@latest

Basic Usage

package main
import (
 "fmt"
 "log"
 "github.com/valentin-kaiser/go-dbase/dbase"
)
func main() {
 // Open a dBase file - you must specify exactly one data source
 config := &dbase.Config{
 Filename: "example.dbf", // Filesystem access
 // Data: []byte("..."), // OR byte data 
 // Reader: someReader, // OR custom reader
 // IO: customIO, // OR custom IO implementation
 }
 
 table, err := dbase.OpenTable(config)
 if err != nil {
 log.Fatal(err)
 }
 defer table.Close()
 
 // Read all rows
 for !table.EOF() {
 row, err := table.Next()
 if err != nil {
 log.Fatal(err)
 }
 
 // Access data by column name
 name, _ := row.StringValueByName("NAME")
 age, _ := row.IntValueByName("AGE")
 
 fmt.Printf("Name: %s, Age: %d\n", name, age)
 }
 
 // Convert row to map
 row, _ := table.Row()
 dataMap, _ := row.ToMap()
 fmt.Printf("Row as map: %+v\n", dataMap)
 
 // Convert row to JSON
 jsonData, _ := row.ToJSON()
 fmt.Printf("Row as JSON: %s\n", jsonData)
}

Features Comparison

Technical Advantages

Supported Data Types

Type Conversion Examples

// Type-safe value retrieval
name, err := row.StringValueByName("NAME") // string
age, err := row.IntValueByName("AGE") // int64 
salary, err := row.FloatValueByName("SALARY") // float64
active, err := row.BoolValueByName("ACTIVE") // bool
hired, err := row.TimeValueByName("HIRE_DATE") // time.Time
photo, err := row.BytesValueByName("PHOTO") // []byte
// Panic versions (for when you're sure the field exists)
name := row.MustStringValueByName("NAME")
age := row.MustIntValueByName("AGE")

Character Encoding Support

Encoding Examples

// Automatic encoding detection (recommended)
config := &dbase.Config{
 Filename: "data.dbf",
 InterpretCodePage: true, // Auto-detect from file
}
// Manual encoding specification
config := &dbase.Config{
 Filename: "data.dbf", 
 Converter: dbase.ConverterFromCodePage(0x03), // Windows-1252
}
// Custom encoding registration
import "golang.org/x/text/encoding/charmap"
dbase.RegisterCustomEncoding(0x99, charmap.ISO8859_15)

Data Source Configuration

1. Filesystem Access (Filename)

config := &dbase.Config{
 Filename: "data.dbf",
 // Optionally specify other settings
 TrimSpaces: true,
}

2. Byte Data (Data)

// Read file into memory
dbfData, _ := os.ReadFile("data.dbf")
memoData, _ := os.ReadFile("data.fpt") // Optional memo file
config := &dbase.Config{
 Data: dbfData,
 MemoData: memoData, // Optional
}

3. Reader Interface (Reader)

// Use file handles
dbfFile, _ := os.OpenFile("data.dbf", os.O_RDWR, 0644)
memoFile, _ := os.OpenFile("data.fpt", os.O_RDWR, 0644) // Optional
config := &dbase.Config{
 Reader: dbfFile,
 MemoReader: memoFile, // Optional
}
// Or use custom readers
dbfReader := dbase.NewBytesReadWriteSeeker(dbfData)
config := &dbase.Config{
 Reader: dbfReader,
}

4. Custom IO (IO)

config := &dbase.Config{
 IO: customIOImplementation, // Implement the dbase.IO interface
}

Validation

// ❌ ERROR: Multiple data sources
config := &dbase.Config{
 Filename: "data.dbf",
 Data: []byte("..."), // This will cause an error
}
// ❌ ERROR: No data source 
config := &dbase.Config{
 TrimSpaces: true, // Only settings, no data source
}
// ✅ VALID: Exactly one data source
config := &dbase.Config{
 Filename: "data.dbf",
}

Advanced Examples

Creating a New Table

// Define columns
columns := []*dbase.Column{
 dbase.NewColumn("ID", dbase.Integer, 0, 0, false),
 dbase.NewColumn("NAME", dbase.Character, 50, 0, false),
 dbase.NewColumn("SALARY", dbase.Numeric, 10, 2, false),
 dbase.NewColumn("ACTIVE", dbase.Logical, 0, 0, false),
}
config := &dbase.Config{Filename: "employees.dbf"}
table, err := dbase.NewTable(dbase.FoxPro, config, columns, 0, nil)
if err != nil {
 log.Fatal(err)
}
defer table.Close()
// Create and add a new row
row := table.NewRow()
row.SetValueByName("ID", 1)
row.SetValueByName("NAME", "John Doe")
row.SetValueByName("SALARY", 75000.50)
row.SetValueByName("ACTIVE", true)
err = table.AppendRow(row)
if err != nil {
 log.Fatal(err)
}

Working with Memo Fields

// Reading memo data
memoText, err := row.StringValueByName("DESCRIPTION") // Text memo
memoBytes, err := row.BytesValueByName("DOCUMENT") // Binary memo
// Writing memo data
row := table.NewRow()
row.SetValueByName("DESCRIPTION", "Long text content...")
row.SetValueByName("DOCUMENT", []byte{0x89, 0x50, 0x4E, 0x47}) // Binary data

Search and Navigation

// Search for specific values
field := &dbase.Field{Name: "STATUS", Value: "ACTIVE"}
results, err := table.Search(field, true) // exactMatch = true
// Navigation
table.GoTo(10) // Go to specific record
table.Skip(5) // Skip 5 records forward
table.Skip(-3) // Skip 3 records backward
// Check position
if table.EOF() {
 fmt.Println("At end of file")
}
if table.BOF() {
 fmt.Println("Before first record")
}

Convert to Different Formats

// Convert row to Go struct
type Employee struct {
 ID int32 `dbase:"ID"`
 Name string `dbase:"NAME"`
 Salary float64 `dbase:"SALARY"`
 Active bool `dbase:"ACTIVE"`
}
var emp Employee
err := row.ToStruct(&emp)
// Convert to JSON
jsonBytes, err := row.ToJSON()
// Convert to map
dataMap := row.ToMap()

Error Handling and Debugging

// Enable debug mode
dbase.Debug(true, os.Stdout)
// Comprehensive error handling
if err != nil {
 if dbaseErr, ok := err.(dbase.Error); ok {
 fmt.Printf("dBase error: %s\n", dbaseErr.Error())
 // Access error details and trace
 }
}

Working with Large Files

config := &dbase.Config{
 Filename: "large_file.dbf",
 ReadOnly: true, // Read-only for better performance
 TrimSpaces: true, // Automatically trim string values
}
table, err := dbase.OpenTable(config)
if err != nil {
 log.Fatal(err)
}
defer table.Close()
// Process in batches
batchSize := 1000
processed := 0
for !table.EOF() {
 batch := make([]*dbase.Row, 0, batchSize)
 
 // Collect batch
 for i := 0; i < batchSize && !table.EOF(); i++ {
 row, err := table.Next()
 if err != nil {
 log.Printf("Error reading row %d: %v", processed+i, err)
 continue
 }
 batch = append(batch, row)
 }
 
 // Process batch
 processBatch(batch)
 processed += len(batch)
 fmt.Printf("Processed %d records\n", processed)
}

Complete Examples

Contributing

License

Disclaimer