github.com/ncruces/go-sqlite3@v0.15.1-0.20240520133447-53eef1510ff0/README.md (about)

     1  # Go bindings to SQLite using Wazero
     2  
     3  [![Go Reference](https://pkg.go.dev/badge/image)](https://pkg.go.dev/github.com/ncruces/go-sqlite3)
     4  [![Go Report](https://goreportcard.com/badge/github.com/ncruces/go-sqlite3)](https://goreportcard.com/report/github.com/ncruces/go-sqlite3)
     5  [![Go Coverage](https://github.com/ncruces/go-sqlite3/wiki/coverage.svg)](https://github.com/ncruces/go-sqlite3/wiki/Test-coverage-report)
     6  
     7  Go module `github.com/ncruces/go-sqlite3` is a `cgo`-free [SQLite](https://sqlite.org/) wrapper.\
     8  It provides a [`database/sql`](https://pkg.go.dev/database/sql) compatible driver,
     9  as well as direct access to most of the [C SQLite API](https://sqlite.org/cintro.html).
    10  
    11  It wraps a [Wasm](https://webassembly.org/) [build](embed/) of SQLite,
    12  and uses [wazero](https://wazero.io/) as the runtime.\
    13  Go, wazero and [`x/sys`](https://pkg.go.dev/golang.org/x/sys) are the _only_ runtime dependencies [^1].
    14  
    15  ### Packages
    16  
    17  - [`github.com/ncruces/go-sqlite3`](https://pkg.go.dev/github.com/ncruces/go-sqlite3)
    18    wraps the [C SQLite API](https://sqlite.org/cintro.html)
    19    ([example usage](https://pkg.go.dev/github.com/ncruces/go-sqlite3#example-package)).
    20  - [`github.com/ncruces/go-sqlite3/driver`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/driver)
    21    provides a [`database/sql`](https://pkg.go.dev/database/sql) driver
    22    ([example usage](https://pkg.go.dev/github.com/ncruces/go-sqlite3/driver#example-package)).
    23  - [`github.com/ncruces/go-sqlite3/embed`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/embed)
    24    embeds a build of SQLite into your application.
    25  - [`github.com/ncruces/go-sqlite3/vfs`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs)
    26    wraps the [C SQLite VFS API](https://sqlite.org/vfs.html) and provides a pure Go implementation.
    27  - [`github.com/ncruces/go-sqlite3/gormlite`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/gormlite)
    28    provides a [GORM](https://gorm.io) driver.
    29  
    30  ### Extensions
    31  
    32  - [`github.com/ncruces/go-sqlite3/ext/array`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/array)
    33    provides the [`array`](https://sqlite.org/carray.html) table-valued function.
    34  - [`github.com/ncruces/go-sqlite3/ext/blobio`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/blobio)
    35    simplifies [incremental BLOB I/O](https://sqlite.org/c3ref/blob_open.html).
    36  - [`github.com/ncruces/go-sqlite3/ext/csv`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/csv)
    37    reads [comma-separated values](https://sqlite.org/csv.html).
    38  - [`github.com/ncruces/go-sqlite3/ext/fileio`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/fileio)
    39    reads, writes and lists files.
    40  - [`github.com/ncruces/go-sqlite3/ext/hash`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/hash)
    41    provides cryptographic hash functions.
    42  - [`github.com/ncruces/go-sqlite3/ext/lines`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/lines)
    43    reads data [line-by-line](https://github.com/asg017/sqlite-lines).
    44  - [`github.com/ncruces/go-sqlite3/ext/pivot`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/pivot)
    45    creates [pivot tables](https://github.com/jakethaw/pivot_vtab).
    46  - [`github.com/ncruces/go-sqlite3/ext/statement`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/statement)
    47    creates [parameterized views](https://github.com/0x09/sqlite-statement-vtab).
    48  - [`github.com/ncruces/go-sqlite3/ext/stats`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/stats)
    49    provides [statistics](https://www.oreilly.com/library/view/sql-in-a/9780596155322/ch04s02.html) functions.
    50  - [`github.com/ncruces/go-sqlite3/ext/unicode`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/unicode)
    51    provides [Unicode aware](https://sqlite.org/src/dir/ext/icu) functions.
    52  - [`github.com/ncruces/go-sqlite3/ext/zorder`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/zorder)
    53    maps multidimensional data to one dimension.
    54  - [`github.com/ncruces/go-sqlite3/vfs/memdb`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs/memdb)
    55    implements an in-memory VFS.
    56  - [`github.com/ncruces/go-sqlite3/vfs/readervfs`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs/readervfs)
    57    implements a VFS for immutable databases.
    58  - [`github.com/ncruces/go-sqlite3/vfs/adiantum`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs/adiantum)
    59    wraps a VFS to offer encryption at rest.
    60  
    61  ### Advanced features
    62  
    63  - [incremental BLOB I/O](https://sqlite.org/c3ref/blob_open.html)
    64  - [nested transactions](https://sqlite.org/lang_savepoint.html)
    65  - [custom functions](https://sqlite.org/c3ref/create_function.html)
    66  - [virtual tables](https://sqlite.org/vtab.html)
    67  - [custom VFSes](https://sqlite.org/vfs.html)
    68  - [online backup](https://sqlite.org/backup.html)
    69  - [JSON support](https://sqlite.org/json1.html)
    70  - [math functions](https://sqlite.org/lang_mathfunc.html)
    71  - [full-text search](https://sqlite.org/fts5.html)
    72  - [geospatial search](https://sqlite.org/geopoly.html)
    73  - [encryption at rest](vfs/adiantum/README.md)
    74  - [and more…](embed/README.md)
    75  
    76  ### Caveats
    77  
    78  This module replaces the SQLite [OS Interface](https://sqlite.org/vfs.html)
    79  (aka VFS) with a [pure Go](vfs/) implementation,
    80  which has advantages and disadvantages.
    81  
    82  Read more about the Go VFS design [here](vfs/README.md).
    83  
    84  ### Testing
    85  
    86  This project aims for [high test coverage](https://github.com/ncruces/go-sqlite3/wiki/Test-coverage-report).
    87  It also benefits greatly from [SQLite's](https://sqlite.org/testing.html) and
    88  [wazero's](https://tetrate.io/blog/introducing-wazero-from-tetrate/#:~:text=Rock%2Dsolid%20test%20approach) thorough testing.
    89  
    90  Every commit is [tested](.github/workflows/test.yml) on
    91  Linux (amd64/arm64/386/riscv64/s390x), macOS (amd64/arm64),
    92  Windows (amd64), FreeBSD (amd64), illumos (amd64), and Solaris (amd64).
    93  
    94  The Go VFS is tested by running SQLite's
    95  [mptest](https://github.com/sqlite/sqlite/blob/master/mptest/mptest.c).
    96  
    97  ### Performance
    98  
    99  Perfomance of the [`database/sql`](https://pkg.go.dev/database/sql) driver is
   100  [competitive](https://github.com/cvilsmeier/go-sqlite-bench) with alternatives.
   101  
   102  The Wasm and VFS layers are also tested by running SQLite's
   103  [speedtest1](https://github.com/sqlite/sqlite/blob/master/test/speedtest1.c).
   104  
   105  ### Alternatives
   106  
   107  - [`modernc.org/sqlite`](https://pkg.go.dev/modernc.org/sqlite)
   108  - [`crawshaw.io/sqlite`](https://pkg.go.dev/crawshaw.io/sqlite)
   109  - [`github.com/mattn/go-sqlite3`](https://pkg.go.dev/github.com/mattn/go-sqlite3)
   110  - [`github.com/zombiezen/go-sqlite`](https://pkg.go.dev/github.com/zombiezen/go-sqlite)
   111  
   112  [^1]: anything else you find in `go.mod` is either a test dependency,
   113        or needed by one of the extensions.