Skip to content

Commit 90075ff

Browse files
authored
docs: Add environment variables (#1264)
1 parent 3bf3469 commit 90075ff

File tree

2 files changed

+113
-0
lines changed

2 files changed

+113
-0
lines changed

docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ code ever again.
6363
reference/datatypes.md
6464
reference/query-annotations.md
6565
reference/language-support.rst
66+
reference/environment-variables.md
6667

6768
.. toctree::
6869
:maxdepth: 2
Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Environment variables
2+
3+
## SQLCDEBUG
4+
5+
The `SQLCDEBUG` variable controls debugging variables within the runtime. It is
6+
a comma-separated list of name=val pairs settings.
7+
8+
### dumpast
9+
10+
The `dumpast` command shows the SQL AST that was generated by the parser. Note
11+
that this is the generic SQL AST, not the engine-specific SQL AST.
12+
13+
```
14+
SQLCDEBUG=dumpast=1
15+
```
16+
17+
```
18+
([]interface {}) (len=1 cap=1) {
19+
(*catalog.Catalog)(0xc0004f48c0)({
20+
Comment: (string) "",
21+
DefaultSchema: (string) (len=6) "public",
22+
Name: (string) "",
23+
Schemas: ([]*catalog.Schema) (len=3 cap=4) {
24+
(*catalog.Schema)(0xc0004f4930)({
25+
Name: (string) (len=6) "public",
26+
Tables: ([]*catalog.Table) (len=1 cap=1) {
27+
(*catalog.Table)(0xc00052ff20)({
28+
Rel: (*ast.TableName)(0xc00052fda0)({
29+
Catalog: (string) "",
30+
Schema: (string) "",
31+
Name: (string) (len=7) "authors"
32+
}),
33+
```
34+
35+
### dumpcatalog
36+
37+
The `dumpcatalog` command outputs the entire catalog. If you're using MySQL or
38+
PostgreSQL, this can be a bit overwhelming. Expect this output to change in
39+
future versions.
40+
41+
```
42+
SQLCDEBUG=dumpcatalog=1
43+
```
44+
45+
```
46+
([]interface {}) (len=1 cap=1) {
47+
(*catalog.Catalog)(0xc00050d1f0)({
48+
Comment: (string) "",
49+
DefaultSchema: (string) (len=6) "public",
50+
Name: (string) "",
51+
Schemas: ([]*catalog.Schema) (len=3 cap=4) {
52+
(*catalog.Schema)(0xc00050d260)({
53+
Name: (string) (len=6) "public",
54+
Tables: ([]*catalog.Table) (len=1 cap=1) {
55+
(*catalog.Table)(0xc0000c0840)({
56+
Rel: (*ast.TableName)(0xc0000c06c0)({
57+
Catalog: (string) "",
58+
Schema: (string) "",
59+
Name: (string) (len=7) "authors"
60+
}),
61+
```
62+
63+
### trace
64+
65+
The `trace` command is helpful for tracking down performance issues.
66+
67+
`SQLCDEBUG=trace=1`
68+
69+
By default, the trace output is written to `trace.out` in the current working
70+
directory. You can configure a different path if needed.
71+
72+
`SQLCDEBUG=trace=name.out`
73+
74+
View the execution trace using the Go `trace` tool.
75+
76+
```
77+
go tool trace trace.out
78+
```
79+
80+
There's a ton of different views for the trace output, but here's an example
81+
log showing the execution time for each package.
82+
83+
```
84+
0.000043897 . 1 task sqlc (id 1, parent 0) created
85+
0.000144923 . 101026 1 region generate started (duration: 47.619781ms)
86+
0.001048975 . 904052 1 region package started (duration: 14.588456ms)
87+
0.001054616 . 5641 1 name=authors dir=/Users/kyle/projects/sqlc/examples/python language=python
88+
0.001071257 . 16641 1 region parse started (duration: 7.966549ms)
89+
0.009043960 . 7972703 1 region codegen started (duration: 6.587086ms)
90+
0.009171704 . 127744 1 new goroutine 35: text/template/parse.lex·dwrap·1
91+
0.010361654 . 1189950 1 new goroutine 36: text/template/parse.lex·dwrap·1
92+
0.015641815 . 5280161 1 region package started (duration: 10.904938ms)
93+
0.015644943 . 3128 1 name=booktest dir=/Users/kyle/projects/sqlc/examples/python language=python
94+
0.015647431 . 2488 1 region parse started (duration: 4.207749ms)
95+
0.019860308 . 4212877 1 region codegen started (duration: 6.681624ms)
96+
0.020028488 . 168180 1 new goroutine 37: text/template/parse.lex·dwrap·1
97+
0.021020310 . 991822 1 new goroutine 8: text/template/parse.lex·dwrap·1
98+
0.026551163 . 5530853 1 region package started (duration: 9.217294ms)
99+
0.026554368 . 3205 1 name=jets dir=/Users/kyle/projects/sqlc/examples/python language=python
100+
0.026556804 . 2436 1 region parse started (duration: 3.491005ms)
101+
0.030051911 . 3495107 1 region codegen started (duration: 5.711931ms)
102+
0.030213937 . 162026 1 new goroutine 20: text/template/parse.lex·dwrap·1
103+
0.031099938 . 886001 1 new goroutine 38: text/template/parse.lex·dwrap·1
104+
0.035772637 . 4672699 1 region package started (duration: 10.267039ms)
105+
0.035775688 . 3051 1 name=ondeck dir=/Users/kyle/projects/sqlc/examples/python language=python
106+
0.035778150 . 2462 1 region parse started (duration: 4.094518ms)
107+
0.039877181 . 4099031 1 region codegen started (duration: 6.156341ms)
108+
0.040010771 . 133590 1 new goroutine 39: text/template/parse.lex·dwrap·1
109+
0.040894567 . 883796 1 new goroutine 40: text/template/parse.lex·dwrap·1
110+
0.046042779 . 5148212 1 region writefiles started (duration: 1.718259ms)
111+
0.047767781 . 1725002 1 task end
112+
```

0 commit comments

Comments
 (0)