Skip to content

Commit 3c674f1

Browse files
committed
cache: redesign as a Bazel-style CAS and action cache
Replace the ad-hoc on-disk caches with a design modeled on Bazel's local disk cache: - A content-addressable store (cas/) holding blobs keyed by the BLAKE3 hash of their contents, written atomically and verified on read, with corrupt entries evicted and repaired. - An action cache (ac/) mapping the digest of a unit of cacheable work and its inputs to the CAS digests of its outputs. Entries whose outputs are missing from the CAS are treated as misses. The query analysis cache becomes a QueryAnalysis action keyed by the sqlc version, config, schema, and query, with the marshaled analysis stored in the CAS. The WASM plugin cache becomes a FetchPlugin action keyed by the URL and expected sha256, with the plugin binary stored in the CAS; the declared sha256 is still re-verified on every cache hit. wazero's compiled-code cache keeps its own directory (wazero/) since its format is managed by the runtime. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MPgq3rwip76D554BktbqR4
1 parent 98ef75d commit 3c674f1

10 files changed

Lines changed: 609 additions & 67 deletions

File tree

‎docs/reference/environment-variables.md‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,23 @@ they are introduced.
2020
## SQLCCACHE
2121

2222
The `SQLCCACHE` environment variable dictates where `sqlc` will store cached
23-
WASM-based plugins and modules. By default `sqlc` follows the [XDG Base
24-
Directory
23+
data. By default `sqlc` follows the [XDG Base Directory
2524
Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
2625

26+
The cache is designed after Bazel's local disk cache and has three parts:
27+
28+
- `cas/` — a content-addressable store holding blobs (WASM plugin binaries,
29+
query analysis results) keyed by the BLAKE3 hash of their contents.
30+
- `ac/` — an action cache mapping the digest of a unit of cacheable work and
31+
its inputs (for example, fetching a plugin from a URL with an expected
32+
checksum, or analyzing a query against a schema) to the CAS digests of its
33+
outputs.
34+
- `wazero/` — compiled WASM machine code, managed by the
35+
[wazero](https://wazero.io) runtime in its own format.
36+
37+
The entire directory is safe to delete at any time; sqlc will rebuild it as
38+
needed.
39+
2740
## SQLCDEBUG
2841

2942
The `SQLCDEBUG` variable controls debugging variables within the runtime. It is

‎go.mod‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ require (
3030
google.golang.org/grpc v1.83.0
3131
google.golang.org/protobuf v1.36.11
3232
gopkg.in/yaml.v3 v3.0.1
33+
lukechampine.com/blake3 v1.4.1
3334
modernc.org/sqlite v1.55.0
3435
)
3536

@@ -43,6 +44,7 @@ require (
4344
github.com/jackc/pgpassfile v1.0.0 // indirect
4445
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
4546
github.com/jackc/puddle/v2 v2.2.2 // indirect
47+
github.com/klauspost/cpuid/v2 v2.0.9 // indirect
4648
github.com/kr/text v0.2.0 // indirect
4749
github.com/mattn/go-isatty v0.0.20 // indirect
4850
github.com/ncruces/go-sqlite3-wasm/v3 v3.2.35303 // indirect

‎go.sum‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,8 @@ github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo
4747
github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
4848
github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
4949
github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
50+
github.com/klauspost/cpuid/v2 v2.0.9 h1:lgaqFMSdTdQYdZ04uHyN2d/eKdOMyi2YLSvlQIBFYa4=
51+
github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
5052
github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
5153
github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
5254
github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
@@ -149,6 +151,8 @@ gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EV
149151
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
150152
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
151153
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
154+
lukechampine.com/blake3 v1.4.1 h1:I3Smz7gso8w4/TunLKec6K2fn+kyKtDxr/xcQEN84Wg=
155+
lukechampine.com/blake3 v1.4.1/go.mod h1:QFosUxmjB8mnrWFSNwKmvxHpfY72bmD2tQ0kBMM3kwo=
152156
modernc.org/cc/v4 v4.29.0 h1:CXgwL8cvxmyzBQZzbSl/6xFtMCryb6u8IOqDci39cgc=
153157
modernc.org/cc/v4 v4.29.0/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
154158
modernc.org/ccgo/v4 v4.34.6 h1:sBgfIwyN0TQ9C5hwIeuqyeAKyMWnbvj2fvpF4L11uzU=

‎internal/analyzer/analyzer.go‎

Lines changed: 31 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,8 @@ package analyzer
33
import (
44
"context"
55
"encoding/json"
6-
"fmt"
7-
"hash/fnv"
6+
"errors"
87
"log/slog"
9-
"os"
10-
"path/filepath"
118

129
"google.golang.org/protobuf/proto"
1310

@@ -47,14 +44,17 @@ func (c *CachedAnalyzer) Analyze(ctx context.Context, n ast.Node, q string, sche
4744
return result, err
4845
}
4946

47+
// The name of the sole output blob a QueryAnalysis action produces.
48+
const analysisOutput = "analysis.pb"
49+
5050
func (c *CachedAnalyzer) analyze(ctx context.Context, n ast.Node, q string, schema []string, np *named.ParamSet) (*analysis.Analysis, bool, error) {
5151
// Only cache queries for managed databases. We can't be certain the
5252
// database is in an unchanged state otherwise
5353
if !c.db.Managed {
5454
return nil, true, nil
5555
}
5656

57-
dir, err := cache.AnalysisDir()
57+
store, err := cache.Open()
5858
if err != nil {
5959
return nil, true, err
6060
}
@@ -66,27 +66,27 @@ func (c *CachedAnalyzer) analyze(ctx context.Context, n ast.Node, q string, sche
6666
}
6767
}
6868

69-
// Calculate cache key
70-
h := fnv.New64()
71-
h.Write([]byte(info.Version))
72-
h.Write(c.configBytes)
69+
// Analyzing a query is an action whose inputs are the sqlc version, the
70+
// configuration, the schema migrations, and the query itself.
71+
action := cache.NewAction("QueryAnalysis").
72+
AddInput("version", []byte(info.Version)).
73+
AddInput("config", c.configBytes)
7374
for _, m := range schema {
74-
h.Write([]byte(m))
75+
action.AddInput("schema", []byte(m))
7576
}
76-
h.Write([]byte(q))
77-
78-
key := fmt.Sprintf("%x", h.Sum(nil))
79-
path := filepath.Join(dir, key)
80-
if _, err := os.Stat(path); err == nil {
81-
contents, err := os.ReadFile(path)
82-
if err != nil {
83-
return nil, true, err
77+
actionDigest := action.AddInput("query", []byte(q)).Digest()
78+
79+
if cached, err := store.Actions.Get(actionDigest); err == nil {
80+
contents, err := store.CAS.Get(cached.Outputs[analysisOutput])
81+
if err == nil {
82+
var a analysis.Analysis
83+
if err := proto.Unmarshal(contents, &a); err == nil {
84+
return &a, false, nil
85+
}
8486
}
85-
var a analysis.Analysis
86-
if err := proto.Unmarshal(contents, &a); err != nil {
87-
return nil, true, err
87+
if !errors.Is(err, cache.ErrNotFound) {
88+
slog.Warn("reading analysis from cache failed", "err", err)
8889
}
89-
return &a, false, nil
9090
}
9191

9292
result, err := c.a.Analyze(ctx, n, q, schema, np)
@@ -97,10 +97,17 @@ func (c *CachedAnalyzer) analyze(ctx context.Context, n ast.Node, q string, sche
9797
slog.Warn("unable to marshal analysis", "err", err)
9898
return result, false, nil
9999
}
100-
if err := os.WriteFile(path, contents, 0644); err != nil {
101-
slog.Warn("saving analysis to disk failed", "err", err)
100+
outDigest, err := store.CAS.Put(contents)
101+
if err != nil {
102+
slog.Warn("saving analysis to cache failed", "err", err)
102103
return result, false, nil
103104
}
105+
err = store.Actions.Put(actionDigest, &cache.ActionResult{
106+
Outputs: map[string]cache.Digest{analysisOutput: outDigest},
107+
})
108+
if err != nil {
109+
slog.Warn("saving analysis action result failed", "err", err)
110+
}
104111
}
105112

106113
return result, false, err

‎internal/cache/action.go‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
package cache
2+
3+
import (
4+
"encoding/json"
5+
"fmt"
6+
"os"
7+
"path/filepath"
8+
)
9+
10+
// ActionResult records the outputs of a completed action, mirroring Bazel's
11+
// ActionResult message. Outputs are not stored inline: each named output is a
12+
// digest pointing into the CAS.
13+
type ActionResult struct {
14+
// Outputs maps an output name (e.g. "analysis.pb", "plugin.wasm") to the
15+
// CAS digest of its contents.
16+
Outputs map[string]Digest `json:"outputs"`
17+
}
18+
19+
// ActionCache maps action digests to ActionResults, stored as JSON files at
20+
// ac/<xx>/<hash> under the cache root. Unlike CAS entries, action cache
21+
// entries are not self-validating — the value is not derivable from the key —
22+
// so Get additionally checks that every referenced output still exists in the
23+
// CAS before reporting a hit, exactly like Bazel's disk cache does.
24+
type ActionCache struct {
25+
root string
26+
cas *CAS
27+
}
28+
29+
func newActionCache(root string, cas *CAS) *ActionCache {
30+
return &ActionCache{root: root, cas: cas}
31+
}
32+
33+
func (a *ActionCache) path(d Digest) string {
34+
return filepath.Join(a.root, "ac", d.Hash[:2], d.Hash)
35+
}
36+
37+
// Get returns the cached result for an action, or ErrNotFound on a miss. An
38+
// entry whose outputs are missing or corrupt in the CAS is treated as a miss
39+
// and evicted.
40+
func (a *ActionCache) Get(action Digest) (*ActionResult, error) {
41+
if !action.valid() {
42+
return nil, ErrNotFound
43+
}
44+
path := a.path(action)
45+
data, err := os.ReadFile(path)
46+
if err != nil {
47+
if os.IsNotExist(err) {
48+
return nil, ErrNotFound
49+
}
50+
return nil, fmt.Errorf("cache: %w", err)
51+
}
52+
var result ActionResult
53+
if err := json.Unmarshal(data, &result); err != nil {
54+
os.Remove(path)
55+
return nil, ErrNotFound
56+
}
57+
for _, d := range result.Outputs {
58+
if !a.cas.Contains(d) {
59+
os.Remove(path)
60+
return nil, ErrNotFound
61+
}
62+
}
63+
return &result, nil
64+
}
65+
66+
// Put records the result of an action. All outputs must already be in the
67+
// CAS; writes are staged and renamed so concurrent processes never observe a
68+
// partial entry.
69+
func (a *ActionCache) Put(action Digest, result *ActionResult) error {
70+
for name, d := range result.Outputs {
71+
if !a.cas.Contains(d) {
72+
return fmt.Errorf("cache: output %q (%s) missing from CAS", name, d)
73+
}
74+
}
75+
data, err := json.Marshal(result)
76+
if err != nil {
77+
return fmt.Errorf("cache: %w", err)
78+
}
79+
path := a.path(action)
80+
if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
81+
return fmt.Errorf("cache: %w", err)
82+
}
83+
f, err := os.CreateTemp(a.cas.tmp, action.Hash[:8]+"-*")
84+
if err != nil {
85+
return fmt.Errorf("cache: %w", err)
86+
}
87+
defer os.Remove(f.Name())
88+
if _, err := f.Write(data); err != nil {
89+
f.Close()
90+
return fmt.Errorf("cache: %w", err)
91+
}
92+
if err := f.Close(); err != nil {
93+
return fmt.Errorf("cache: %w", err)
94+
}
95+
if err := os.Rename(f.Name(), path); err != nil {
96+
return fmt.Errorf("cache: %w", err)
97+
}
98+
return nil
99+
}

‎internal/cache/cache.go‎

Lines changed: 47 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,18 @@
1+
// Package cache implements sqlc's on-disk cache, designed after Bazel's
2+
// local disk cache.
3+
//
4+
// It has two halves:
5+
//
6+
// - A content-addressable store (CAS) holding blobs keyed by the BLAKE3
7+
// hash of their contents, laid out as cas/<xx>/<hash>.
8+
// - An action cache (AC) mapping the digest of an action — a description of
9+
// cacheable work and all of its inputs — to the digests of the outputs
10+
// that work produced, laid out as ac/<xx>/<hash>.
11+
//
12+
// Executing cached work therefore takes two steps, just like Bazel: hash the
13+
// action, look its digest up in the action cache, then fetch the referenced
14+
// output blobs from the CAS. Both the query analysis cache and the WASM
15+
// plugin cache are built on this pair.
116
package cache
217

318
import (
@@ -6,10 +21,14 @@ import (
621
"path/filepath"
722
)
823

9-
// The cache directory defaults to os.UserCacheDir(). This location can be
10-
// overridden by the SQLCCACHE environment variable.
11-
//
12-
// Currently the cache stores two types of data: plugins and query analysis
24+
// Cache bundles the CAS and the action cache that shares it.
25+
type Cache struct {
26+
CAS *CAS
27+
Actions *ActionCache
28+
}
29+
30+
// Dir returns the cache root, defaulting to os.UserCacheDir(). The location
31+
// can be overridden with the SQLCCACHE environment variable.
1332
func Dir() (string, error) {
1433
cache := os.Getenv("SQLCCACHE")
1534
if cache != "" {
@@ -22,25 +41,38 @@ func Dir() (string, error) {
2241
return filepath.Join(cacheHome, "sqlc"), nil
2342
}
2443

25-
func PluginsDir() (string, error) {
26-
cacheRoot, err := Dir()
44+
// Open returns the cache rooted at Dir().
45+
func Open() (*Cache, error) {
46+
root, err := Dir()
2747
if err != nil {
28-
return "", err
48+
return nil, err
2949
}
30-
dir := filepath.Join(cacheRoot, "plugins")
31-
if err := os.MkdirAll(dir, 0755); err != nil && !os.IsExist(err) {
32-
return "", fmt.Errorf("failed to create %s directory: %w", dir, err)
50+
return OpenAt(root)
51+
}
52+
53+
// OpenAt returns the cache rooted at the given directory, creating it if
54+
// necessary.
55+
func OpenAt(root string) (*Cache, error) {
56+
cas, err := newCAS(root)
57+
if err != nil {
58+
return nil, err
3359
}
34-
return dir, nil
60+
return &Cache{
61+
CAS: cas,
62+
Actions: newActionCache(root, cas),
63+
}, nil
3564
}
3665

37-
func AnalysisDir() (string, error) {
38-
cacheRoot, err := Dir()
66+
// WazeroDir returns the directory for wazero's compilation cache. Compiled
67+
// module machine code is managed by wazero in its own format, so it lives
68+
// beside the CAS rather than inside it.
69+
func WazeroDir() (string, error) {
70+
root, err := Dir()
3971
if err != nil {
4072
return "", err
4173
}
42-
dir := filepath.Join(cacheRoot, "query_analysis")
43-
if err := os.MkdirAll(dir, 0755); err != nil && !os.IsExist(err) {
74+
dir := filepath.Join(root, "wazero")
75+
if err := os.MkdirAll(dir, 0755); err != nil {
4476
return "", fmt.Errorf("failed to create %s directory: %w", dir, err)
4577
}
4678
return dir, nil

0 commit comments

Comments
 (0)