Skip to content
xoPublic

About

streaming, buffered table encoder for result sets (ie from a database)

Topics

Resources

Contributing

Stars

22 stars

Watchers

3 watching

Forks

Latest commit

 

History

168 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

About tblfmt

Package tblfmt writes result sets as text tables. A result set is the rows and columns that a database query returns. tblfmt reads a result set one row at a time. The JSON, unaligned and csv formats write each row when they read it. The table formats keep the rows of a batch to calculate the column widths. By default, a batch is the whole result set, and WithCount sets a smaller batch. It writes tables like this one:

 author_id |            name            | z 
-----------+----------------------------+---
        14 | a       b       c       d  | 
        15 | aoeu                      +| 
           | test                      +| 
           |                            | 
        16 | foo\x08bar                 | 
        17 | a       b       \r        +| 
           |         a                  | 
        18 | 袈      袈              袈 | 
        19 | 袈      袈              袈+| a+
           |                            | 
(6 rows)

tblfmt writes each format that psql has: aligned, wrapped, unaligned, csv, html, asciidoc, latex, latex-longtable and troff-ms. It also writes JSON, the vertical format that the mysql client writes for \G, a plain table with no lines, and a markdown table. usql uses each of them.

Unit Tests Go Reference Discord Discussion

Installing

Install tblfmt with the Go tool:

$ go get -u github.com/xo/tblfmt

Using

tblfmt is for usql and for the database/sql types of Go. It accepts any type that has this interface:

// ResultSet is the shared interface for a result set.
type ResultSet interface {
	Next() bool
	Scan(...any) error
	Columns() ([]string, error)
	Close() error
	Err() error
	NextResultSet() bool
}

This program uses tblfmt:

// _example/example.go
package main

import (
	"log"
	"os"

	_ "github.com/lib/pq"
	"github.com/xo/dburl"

	"github.com/xo/tblfmt"
)

func main() {
	db, err := dburl.Open("postgres://booktest:booktest@localhost")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()
	res, err := db.Query("select * from authors")
	if err != nil {
		log.Fatal(err)
	}
	defer res.Close()
	enc, err := tblfmt.NewTableEncoder(
		res,
		// force minimum column widths
		tblfmt.WithWidths(20, 20),
	)
	if err != nil {
		log.Fatal(err)
	}
	if err := enc.EncodeAll(os.Stdout); err != nil {
		log.Fatal(err)
	}
}

The program writes output like this:

      author_id       |            name            | z 
----------------------+----------------------------+---
                   14 | a       b       c       d  | 
                   15 | aoeu                      +| 
                      | test                      +| 
                      |                            | 
                    2 | 袈      袈              袈 | 
(3 rows)

The Go Reference has the full API.

Differences from psql

tblfmt writes the same output as psql. The differences below are deliberate. If you find a different difference, report it as a bug. docs/BACKLOG.md lists the differences that are known faults.

Blank line after a table

psql writes one blank line after an aligned table. tblfmt does not. usql is the client that matches psql, so usql writes the line. If tblfmt wrote it too, usql would write two. See D48 in docs/PLAN.md.

Quotes in csv

tblfmt quotes a csv field that holds a space or a tab. psql quotes a field only when it holds the separator, a line break or a double quote. For a field that holds a, a tab and b, psql writes a<TAB>b, and tblfmt writes "a<TAB>b". See D52 in docs/PLAN.md.

Separator between unaligned result sets

psql writes nothing between two result sets in the unaligned and csv formats. tblfmt writes a newline by default. The caller chooses the separator with WithResultSetSeparator. See D53 in docs/PLAN.md.

Control characters in html and asciidoc

tblfmt escapes a control character in the html, asciidoc and vertical formats, as it does in a table. For example, it writes U+0008 as \x08. psql writes the character as it is in html and asciidoc. See D54 in docs/PLAN.md.

Wrapped columns that hold a wide character

In the wrapped format, psql can make a column 1 column wide when its values hold a character 2 columns wide, such as 日 or an emoji. The line with that character is then 1 column too wide. tblfmt keeps such a column at least 2 columns wide. See D56 in docs/PLAN.md.

Width of an emoji

tblfmt measures the width of text by grapheme cluster. A grapheme cluster is the group of code points that a terminal draws as one character. psql measures each code point. An emoji with a skin tone, such as 👍🏽, is two code points, and a current terminal draws it 2 columns wide. psql counts it 4 columns wide and pads the cell by 2 columns too few. tblfmt counts it 2 columns wide. A joined emoji, such as 👨‍👩‍👧, and a flag are one grapheme cluster each, and tblfmt counts each of them 2 columns wide. See D39 in docs/PLAN.md.

A terminal that draws each code point on its own, such as xterm, does not line up such a column.

Numbers in the numeric locale

With numericlocale, psql writes ASCII digits, and it groups the digits by one group size. tblfmt writes a number as the locale does: with the digits of the locale, and with its group sizes. For en-IN, psql writes 1234567 as 1,234,567, and tblfmt writes 12,34,567. For en-US, the default locale, the output is the same. See D73 in docs/PLAN.md.

A real that the driver returns as a float64

tblfmt writes a value by its Go type, and it does not change the type. pgx returns a PostgreSQL real as a float64, so tblfmt writes it as psql writes a float8. For '1450817.032'::real, psql writes 1.450817e+06, and tblfmt writes 1450817. To write a real as psql does, scan it into a float32, as usql does. See D72 in docs/PLAN.md.

Comparison with other packages

Other Go packages write text tables too. They take the rows as strings and draw the table in their own style. tblfmt reads a result set from a database, and writes it as psql does. The table below compares the versions that the benchmark uses. "Some" means that the package has the feature only in a mode or an option.

Feature tblfmt text/tabwriter tablewriter v1.1.5 go-pretty v6.8.3 lipgloss v1.1.0 simpletable v1.0.0 rodaine/table v1.4.1 aquasecurity/table v1.11.0
Reads a *sql.Rows yes no no no no no no no
Writes a row before it reads the next row some no some no no no no no
Writes a table as psql does yes no no no no no no no
Writes each row as a record (expanded) yes no no no no no no no
Wraps a table to a width yes no yes yes yes no no yes
Formats other than a text table csv, json, markdown, html, asciidoc, latex, troff no markdown, html, svg csv, tsv, html, markdown no no no no
Colors and text styles no no yes yes yes no yes yes

tblfmt writes each row of the unaligned, csv and json formats when it reads it. The table formats keep one batch of rows, and WithCount sets the size of the batch. tablewriter writes each row in its streaming mode.

The benchmark in test/ writes a table of 10,000 rows with each package. Each row holds an integer, 100 bytes of text and a float, as strings. Each package draws its default style. text/tabwriter and rodaine/table draw no lines, and tblfmt also escapes each value and measures it by grapheme cluster. The results on an AMD Ryzen 9 9950X with Go 1.27.1, on 2026-10-31:

Package Time Memory Allocations
text/tabwriter 2.8 ms 9.4 MiB 30,000
rodaine/table 6.3 ms 7.6 MiB 210,000
tblfmt 8.8 ms 9.2 MiB 213,000
go-pretty 11.1 ms 12.4 MiB 125,000
tablewriter 40.1 ms 49.0 MiB 1,086,000
simpletable 45.0 ms 25.4 MiB 545,000
lipgloss 82.0 ms 78.1 MiB 735,000
aquasecurity/table 215.5 ms 344.7 MiB 9,421,000

To run the benchmark, run this command in the test directory:

go test -run '^$' -bench BenchmarkWrite -benchmem

Documentation

Document What it holds
CONTRIBUTING.md What a change must do, and the commands to run before a pull request
docs/PLAN.md Each decision that shapes tblfmt, and the reason for it
docs/BACKLOG.md Known faults and work that is not done
AGENTS.md The rules for a coding agent. CLAUDE.md imports it

Testing

Run the tests with go test:

$ go test -v

To measure each format at 10,000 and 1,000,000 rows, run the benchmarks:

$ go test -run '^$' -bench BenchmarkEncode -benchmem

The benchmark against other packages is in the test module. See "Comparison with other packages".

TestPsql in the test module compares the output with psql 18, query by query. It needs a PostgreSQL server. "Tests" in AGENTS.md says how to start one with dbrun from dbmeta.

About

streaming, buffered table encoder for result sets (ie from a database)

Topics

Resources

Contributing

Stars

22 stars

Watchers

3 watching

Forks

Releases

Packages

Used by

Contributors

Languages

⌂ 换网址