Skip to content

Commit dbf2cdc

Browse files
committed
Add guidance for using model packs and data extensions in CodeQL commands
1 parent db8b77c commit dbf2cdc

File tree

1 file changed

+50
-0
lines changed

1 file changed

+50
-0
lines changed

.github/prompts/data_extensions_development.prompt.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,56 @@ Essential commands for query development:
8585
- [codeql bqrs decode](../../resources/cli/codeql/codeql_bqrs_decode.prompt.md) - Convert binary results to text
8686
- [codeql bqrs info](../../resources/cli/codeql/codeql_bqrs_info.prompt.md) - Inspect result metadata
8787

88+
### Model Pack / Data Extension Options
89+
90+
During development, you'll typically test data extensions with a **single query** or **unit test** — not `codeql database analyze` (which is for full analysis runs / CI).
91+
92+
#### Running a single query with model packs
93+
94+
Use `codeql query run` with `--model-packs` or `--additional-packs`:
95+
96+
```bash
97+
# Use a published model pack by name against a single query
98+
codeql query run \
99+
--database=/path/to/db \
100+
--model-packs=my-org/my-model-pack \
101+
--output=results.bqrs \
102+
-- path/to/MyQuery.ql
103+
104+
# Use a local (unpublished) model pack during development
105+
codeql query run \
106+
--database=/path/to/db \
107+
--additional-packs=languages/<language>/custom/src \
108+
--output=results.bqrs \
109+
-- path/to/MyQuery.ql
110+
```
111+
112+
#### Running unit tests with model packs
113+
114+
`codeql test run` does **not** support `--model-packs`. Instead, data extensions are resolved through `qlpack.yml` configuration:
115+
116+
1. The **model pack** declares `extensionTargets` and `dataExtensions` in its `qlpack.yml`
117+
2. The **test pack** declares a dependency on the model pack in its `qlpack.yml`
118+
3. Use `--additional-packs` to point the test runner at a local (unpublished) model pack:
119+
120+
```bash
121+
codeql test run \
122+
--additional-packs=languages/<language>/custom/src \
123+
--keep-databases \
124+
--show-extractor-output \
125+
-- languages/<language>/<pack-basename>/test/<QueryBasename>/
126+
```
127+
128+
#### Full option reference
129+
130+
| Option | Available on | Purpose |
131+
|---|---|---|
132+
| `--model-packs=<name@range>` | `codeql query run`, `codeql database analyze` | Reference published model packs by name |
133+
| `--additional-packs=<dir>[;<dir>...]` | `codeql query run`, `codeql test run`, `codeql database analyze` | Search local directories for packs (primary mechanism for local development) |
134+
| `--no-database-extension-packs` | `codeql database analyze` | Omit extensions bundled into the database at creation time |
135+
| `--no-database-threat-models` | `codeql database analyze` | Omit threat model config stored in the database |
136+
| `--threat-model=<name>` | `codeql database analyze` | Enable/disable threat model categories (e.g., `local`, `remote`, `all`) |
137+
88138
## Related Resources
89139

90140
- [Test-Driven QL Development](./test_driven_ql_development.prompt.md) - Comprehensive TDD workflow

0 commit comments

Comments
 (0)