https://github.com/ashenblade/postgres-dev-helper
VS Code extension to assist PostgreSQL source code developers
https://github.com/ashenblade/postgres-dev-helper
debugging postgres postgresql vscode-extension
Last synced: 3 months ago
JSON representation
VS Code extension to assist PostgreSQL source code developers
- Host: GitHub
- URL: https://github.com/ashenblade/postgres-dev-helper
- Owner: ashenBlade
- License: mit
- Created: 2024-07-24T11:42:05.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-01-22T15:50:24.000Z (3 months ago)
- Last Synced: 2025-02-02T03:13:54.995Z (3 months ago)
- Topics: debugging, postgres, postgresql, vscode-extension
- Language: TypeScript
- Homepage:
- Size: 23.4 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# PostgreSQL Hacker Helper
This is a Visual Studio Code extension to assist PostgreSQL source code
developers. It allows to investigate `Node *` variables to obtain it's real type
based on `NodeTag` and provide some other utilities.
## Features
More info you can find in documentation for [pg variables view](docs/pg_variables.md).
### Investigate real type of `Node *`
While debugging you can observe variables of `Node *` type with it's real type.
They appear in separate action view.
It behaves like Debug->Variables view, but no colorization (limitations of VS
Code Extension framework) and automatically detects real type of `Node *`
variables.
### Show contents of containers
Extension support showing contents of containers: `List` (including subtypes)
and `Bitmapset`.
`Bitmapset` elements are displayed:
- `$elements$` - elements of set (array of integers)
- `$length$` - number of entries in set
Also, there is support for C-arrays (like `PlannerInfo->simple_rel_array`) -
array is displayed using it's length.
Currently, there are 36 registered array members, but you can add your own
using [pgsql_hacker_helper.json](#pgsql_hacker_helperjson) configuration file.
### Show where Bitmapset references
`Bitmapset` and `Relids` often store indexes of other elements in other places.
Extension knows 53 such elements. I.e. `PlannerInfo->all_relids` or `RelOptInfo->eclass_indexes`.
### Dump `Node *` state to log
In PostgreSQL there is `pprint(Node *)` which dumps passed Node variable to
stdout with pretty printing it. Using 'Dump Node to log' option in variable
context menu you also will be able to do so.
### Formatting
Extension uses `pgindent` for formatting C code. It integrates with VS Code
extension and available with `Format Document` or `Ctrl + Shift + I` shortcut
(or another key binding if overridden).
To enable this set formatter for C in settings (i.e. `.vscode/settings.json`
for workspace):
```json
{
"[c]": {
"editor.defaultFormatter": "ash-blade.postgresql-hacker-helper"
}
}
```
Or specify formatter manually using `Format Document With...`. Select
`PostgreSQL Hacker Helper` in pick up box.
Feature supported for PostgreSQL starting from 10 version.
> This feature using tools from `src/tools`. If they are unavailable extension
> will try to build or download them.
>
> Primary tool required is `pg_bsd_indent`. If PostgreSQL version lower than
> 16 extension will ask you for `pg_config` path - it is required to build
> `pg_bsd_indent`.
> Look for warning message from extension in left bottom corner.
Using command `PgSQL: Show diff preview for PostgreSQL formatter` you can
preview changes made by formatter.
### Extension bootstrapping
Extension can help with creation of basic PostgreSQL extension files: Makefile,
control file, source files (C, SQL) and tests.
Just run command `Bootstrap extension` and enter initial values (extension
name, description, required files). Extension will be created inside `contrib`
directory.
## Customization
### pgsql_hacker_helper.json
This is a configuration file for extension.
It stored inside `.vscode` directory in your repository -
`.vscode/pgsql_hacker_helper.json`. You can use config file to extend built-in
capabilities if there is no support for something yet.
Example json:
```json
{
"version": 3,
"specialMembers": {
"array": [
{
"typeName": "PlannerInfo",
"memberName": "simple_rel_array",
"lengthExpression": "simple_rel_array_size"
},
{
"typeName": "RelOptInfo",
"memberName": "partexprs",
"lengthExpression": "part_scheme->partnatts"
},
{
"typeName": "GatherMergeState",
"memberName": "gm_slots",
"lengthExpression": "nreaders + 1"
}
]
},
"aliases": [
{
"alias": "PlannerRef",
"type": "PlannerInfo *"
}
],
"typedefs": "my.typedefs.file"
}
```
In example 3 array special members - arrays will be shown with specified length,
not just pointers to arrays start.
Also, `PlannerRef` - typedef for `PlannerInfo *`.
For more info check [configuration file documentation](./docs/config_file.md).
## Extension Settings
There are 4 settings:
- `postgresql-hacker-helper.logLevel` - Log level
Minimum level of log messages in Output channel.
By default - `INFO`. If using VS Code 1.74.0 ang greater use `Output` channel
logger settings.
- `postgresql-hacker-helper.srcPath` - Path to source code directory
*Relative* path to custom PostgreSQL source code directory. Use it, if source
code files are not in your workspace root (i.e. in `${workspaceFolder}/postgresql`). Used for searching for
required files (node tag files, `pg_bsd_indent` and so on). If not specified
search starts from workspace root. (Next, this settings will be used as `*SrcPath*`).
- `postgresql-hacker-helper.nodeTagFiles` - Files with NodeTag files
List of paths points to files that contain NodeTags.
- If path is absolute - specified files will be used directly.
- If path is relative, search starts from source files directory (see
`postgresql-hacker-helper.srcPath`).
- If not specified, `*SrcPath*/src/include/nodes/nodes.h`
and `*SrcPath*/src/include/nodes/nodetags.h` will be used.
- `postgresql-hacker-helper.pg_bsd_indentPath` - Path to `pg_bsd_indent`
Path to `pg_bsd_indent` tool. Required for formatting support. Use it if you have `pg_bsd_indent` installed globally or want to use specific version.
- If not specified, it will be searched in `*SrcPath*/src/tools` directory.
- If specified, and failed to run extension will try to build it.
NOTE: If required, it will be downloaded (`wget` is required) and built.
## Compatibility
Extension tries to be compatible with multiple versions of both VS Code and
PostgreSQL.
Minimal supported version of:
- `VS Code` - 1.30
- `PostgreSQL` - 8.0
> It is tested manually and not all use cases might be covered. If you found
> bug specific to some version please [create issue](https://github.com/ashenBlade/postgres-dev-helper/issues).
Also, extension will target latest VS Code version and try to use the full
functionality of new versions. So, use latest VS Code versions to get new
features earlier.
For using formatter minimal supported version Postgres is `10`.
## Known Issues
Known issues:
- If in pointer variable was garbage, extension will not detect it and expand
this variable (may be garbage).
- To get NodeTags extension reads all available NodeTag files (from settings),
but these files may be not created (./configure or make not run). I assume by
time of debugging start files will be created, so extension catch them and
process.
- Tested only with [ms-vscode.cpptools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
extension. Currently, no support for other DAP adapters (i.e. Code LLDB)
- Sometimes formatting can misbehave. This is due to `pg_bsd_indent` internal
logic. If formatting is not applied try run command again. If file after
formatting is a mess this can be due to errors in logic.
## Release Notes
### 1.5.1
Update contents of created configuration file (by command).
### 1.5.0 (pre-release)
Add custom typedefs file setting in configuration file. This may be useful, if you want to change it and do not affect another workspaces. This is configured in `typedefs` member.
Update configuration file layout version to 3.
### 1.4.5
No changes
### 1.4.4
Add `typedefs.list` file preprocessing for feeding to `pg_bsd_indent`. Processed file saved in `/tmp/pg-hacker-helper.typedefs.list` file and may be reused between different sessions.
### 1.4.3
Add missing formatting rules when running `pg_bsd_indent`. [#3](https://github.com/ashenBlade/postgres-dev-helper/issues/3).
### 1.4.2
Fix invalid handling of `pg_bsd_indentPath` setting. [#2](https://github.com/ashenBlade/postgres-dev-helper/issues/2)
### 1.4.1
Fix invalid struct detection in variables view: top level structs are not
expandable.
Add extension files bootstrapping: Makefile, \*.c, \*.sql, \*.control, tests.
Fix variable length arrays fields displayed as expandable.
Support for fixed size array expansion.
### 1.4.0
Add support for custom PostgreSQL source code directories. Custom directory can
be specified using `postgresql-hacker-helper.srcPath` setting.
Fix invalid logging for VS Code with version greater 1.74.0.
### 1.3.0
Add formatting functionality using `pg_bsd_indent` integrated with VS Code:
can use with `Format Document` command or `Ctrl + Shift + I` (keybinding).
Add showing `RangeTblEntry` and `RelOptInfo` to which Bitmapset points.
`RangeTblEntry` shown from `Query->rtable`, `RelOptInfo` - from
`PlannerInfo->simple_rel_array`. Referencing also available for other Bitmapsets
which points not to rte or rel.
### 1.2.1
Add check for breakpoint in `bms_first_member` to avoid infinite loop.
Add support for `MemoryContext` Node.
### 1.2.0
Expand range of supported versions both for PostgreSQL (from 8.0) and VS Code
(from 1.30).
Add support for Bitmapset for versions below 16.
Add support for List with Linked List implementation.
Fix log level updated only after extension or VS Code reload.
Fix invalid Node cast in some cases when declared type has `struct` keyword.
### 1.1.2
Fix invalid `List` behaviour with different declared type - members shown for
declared type, not `List` members.
Add 137 new array special members.
Optimize extension activation performance.
Treat `Plan` struct as Node variable.
### 1.1.1
Fix Bitmapset elements not shown for postgres version below 17
### 1.1.0
Add support for `Bitmapset` and `Relids` - show elements of set.
Add custom user type aliases for Node types in configuration
Update config file layout. Current version - 2.
Hide postgres variables view when not in debug mode.
### 1.0.0
Remove EPQState from array special members
Add T_XidList support
### 0.2.0
Add more special members.
Separate json configuration file to add your own special members.
Specifying real NodeTag in variable name if it differs from declared type. Shows
in square brackets.
Setup logging infrastructure. Availability to change minimum log level.
Command and button to force refresh Pg variables view.
Setting to add custom files with NodeTags.
### 0.1.1
Only valid pointers are expanded in Pg variables view
### 0.1.0
Displaying of `Node *` variables in separate view in Debug view container.
Call `pprint(Node *)` on selected variable in `Variables` view.
## Contributing
Go to [Issues](https://github.com/ashenBlade/postgres-dev-helper/issues) if you
want to say something: bugs, features, etc...