sqlite/AGENTS.md at master · sqlite/sqlite · GitHub
//blob/show" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
//blob/show;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
sqlite
sqlite
Public
Notifications<br>You must be signed in to change notification settings
Fork<br>1.5k
Star<br>9.7k
FilesExpand file tree
master
/AGENTS.md
Copy path
Blame<br>More file actions
Blame<br>More file actions
Latest commit
History<br>History<br>History
125 lines (96 loc) · 5.01 KB
master
/AGENTS.md
Top
File metadata and controls<br>Preview
Code
Blame
125 lines (96 loc) · 5.01 KB
Raw<br>Copy raw file<br>Download raw file
OutlineEdit and raw actions
AGENTS.md
Guidance for AI coding agents working in this repository.
Project nature
SQLite is a self-contained, serverless SQL database engine written in C. The<br>source is public domain — no copyright or license header should ever be<br>added to any file. The blessing comment that appears at the top of each source<br>file is intentional and should be preserved unchanged.
SQLite does not accept pull requests without prior agreement and/or<br>accompanying legal paperwork that places the pull request in the public domain.<br>However, the human SQLite developers will review a concise and well-written<br>pull request as a proof-of-concept prior to reimplementing the changes<br>themselves.
SQLite does not accept agentic code. However the project<br>will accept agentic bug reports that include a reproducible test case.<br>Patches or pull requests demonstrating a possible fix, for documentation<br>purposes, are welcomed.
SQLite uses the Fossil for version control,<br>not Git. The canonical repository is at https://sqlite.org/src.
Build
The configure script uses autosetup,<br>not GNU Autoconf.
apt install gcc make tcl-dev # prerequisites (Debian/Ubuntu)
./configure --dev # debug build<br>make sqlite3 # CLI shell<br>make sqlite3d # Debugging variant of the CLI shell<br>make sqlite3.c # amalgamation (single-file distribution form)<br>make testfixture # test runner binary (requires tcl-dev)<br>make tclextension-install # install TCL extension before running tests
Testing
Tests are TCL scripts run through the testfixture enhanced interpreter.
# From the build directory:<br>./testfixture test/main.test # single test file<br>test/testrunner.tcl # quick suite<br>test/testrunner.tcl full # full suite<br>test/testrunner.tcl fts5% # pattern match
# Check for failures:<br>grep '!' testrunner.log
make devtest is the fastest way to run a representative subset. Always run<br>at least devtest after any change to src/.
Architecture
SQL text → tokenizer (tokenize.c) → parser (parse.y / Lemon) →<br>code generator (build.c, select.c, insert.c, update.c, delete.c,<br>expr.c) → optimizer (where*.c) → VDBE (vdbe.c) → B-Tree<br>(btree.c) → Pager (pager.c) → WAL (wal.c) → VFS<br>(os_unix.c, os_win.c).
The master internal header is src/sqliteInt.h. Major subsystems have private<br>headers: vdbeInt.h, btreeInt.h, whereInt.h. The public API is defined in<br>src/sqlite.h.in (template) which generates sqlite3.h.
Do not edit generated files
These files are produced by scripts and must not be edited by hand:
File<br>Regenerate with
sqlite3.h<br>tool/mksqlite3h.tcl
parse.c, parse.h<br>build lemon (tool/lemon.c) then run on src/parse.y
opcodes.h<br>tool/mkopcodeh.tcl (reads src/vdbe.c)
opcodes.c<br>tool/mkopcodec.tcl (reads opcodes.h)
keywordhash.h<br>tool/mkkeywordhash.c
pragma.h<br>tool/mkpragmatab.tcl
sqlite3.c<br>tool/mksqlite3c.tcl (the amalgamation)
Editing rules:
To add a PRAGMA: edit tool/mkpragmatab.tcl, then regenerate pragma.h.
To add a VDBE opcode: add the case OP_Xxx: handler in src/vdbe.c; the<br>opcode number and name are extracted automatically by mkopcodeh.tcl.
To change the SQL grammar: edit src/parse.y, not parse.c.
Coding conventions
C89/C99 compatible C only. No C++, no STL, no exceptions, no VLAs.
All memory allocation goes through sqlite3Malloc / sqlite3_malloc64<br>(never raw malloc). The sqlite3MallocZero variant zero-initializes.
Integer widths: use i64 (sqlite3_int64) for 64-bit values, u32/u64<br>for unsigned. Avoid bare long or int for values that could exceed 2G.
Error propagation: functions return SQLITE_OK (0) on success and a<br>SQLITE_* error code on failure. Many routines also set db->mallocFailed<br>on OOM, allowing...