csvdb

csvdb

English | 中文

A Go library to operate CSV files like a database.

Why

This library comes from real project needs, for example when using ansible to process configuration-related files:

• I often need fine-grained CSV edits, such as updating a specific row.

More specifically, these are the recurring pain points:

• I only want to change one column or a few rows, but still end up writing repetitive read/write code.
• The business need is CRUD-like, but the code only has low-level CSV operations and gets scattered quickly.
• One-off scripts keep growing and become hard to reuse or keep behavior consistent.
• Filtering, sorting, pagination, and aggregation come up repeatedly, and rebuilding them each time is costly.

So the goal of this library is to provide a smoother way to work:

• Operate CSV with a database-like mental model.
• Package high-frequency actions (column ops, row ops, query and aggregation) into reusable APIs.
• Keep daily data-processing scripts shorter, more stable, and easier to maintain.

Installation

go get github.com/sh3yee/csvdb

Import Paths

This project is mainly used via subpackages:

import (
    "github.com/sh3yee/csvdb/column"
    "github.com/sh3yee/csvdb/row"
    "github.com/sh3yee/csvdb/query"
)

Note: The root path github.com/sh3yee/csvdb is mainly for module indexing and documentation entry. Import subpackages for actual features.

If you use gopkg.in:

go get gopkg.in/sh3yee/csvdb.v1

Quick Start

package main

import (
    "github.com/sh3yee/csvdb/column"
    "github.com/sh3yee/csvdb/row"
)

func main() {
    // Column operations
    col := column.New("users.csv")
    col.Add("email")
    col.Alter("name", "username")
    col.DeleteByName("age")

    // Row operations
    r := row.New("users.csv")
    r.Add([]string{"1", "tom", "tom@example.com"})
    r.Update(0, []string{"1", "tommy", "tommy@example.com"})
    r.Delete(0)
}

API

Column

Add columns

Alter columns

Delete columns

Row

Add rows

Update rows

Delete rows

Query rows

Query

Conditional queries

Condition struct

type Condition struct {
    Column string
    Op     string // "=", "!=", ">", "<", ">=", "<=", "like"
    Value  string
}

Chainable Result methods

Query examples

q := query.New("users.csv")

// Single-condition query
rows, _ := q.Find(query.Condition{Column: "age", Op: ">", Value: "18"})

// Multi-condition query + select + pagination
rows, _ := q.FindAll(
    query.Condition{Column: "age", Op: ">=", Value: "18"},
    query.Condition{Column: "city", Op: "=", Value: "Beijing"},
).Select("name", "email").Limit(10).Offset(5).Get()

// IN query
rows, _ := q.FindIn("id", []string{"1", "2", "3"})

// LIKE query
rows, _ := q.Find(query.Condition{Column: "name", Op: "like", Value: "tom%"})

// Sort
rows, _ := q.FindAll().OrderBy("age", "desc").Get()

// Multi-column sort
rows, _ := q.FindAll().OrderBy("age", "asc").ThenBy("name", "desc").Get()

// Query + sort + pagination
rows, _ := q.FindAll(
    query.Condition{Column: "status", Op: "=", Value: "active"},
).OrderBy("created_at", "desc").Limit(10).Get()

// Check existence
exists, _ := q.Find(query.Condition{Column: "id", Op: "=", Value: "1"}).Exists()

Aggregation

Aggregation examples

q := query.New("users.csv")

// Count
count, _ := q.FindAll().Count()

// Sum
total, _ := q.FindAll().Sum("amount")

// Average
avg, _ := q.FindAll().Avg("age")

// Min/Max (string comparison)
minName, _ := q.FindAll().Min("name")
maxName, _ := q.FindAll().Max("name")

// Min/Max (numeric comparison)
minAge, _ := q.FindAll().MinFloat("age")
maxAge, _ := q.FindAll().MaxFloat("age")

// Aggregation after filtering
total, _ := q.FindAll(
    query.Condition{Column: "status", Op: "=", Value: "active"},
).Sum("amount")

Errors

Roadmap

License

MIT