{"id":17767593,"url":"https://github.com/jnidzwetzki/pg-dev-container","last_synced_at":"2026-02-10T01:18:55.654Z","repository":{"id":257974352,"uuid":"872563268","full_name":"jnidzwetzki/pg-dev-container","owner":"jnidzwetzki","description":"Visual Studio Code - Development Container - PostgreSQL","archived":false,"fork":false,"pushed_at":"2025-04-29T20:41:31.000Z","size":1045,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-29T21:26:27.442Z","etag":null,"topics":["devcontainer","postgresql","vscode"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jnidzwetzki.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-10-14T16:49:58.000Z","updated_at":"2025-04-29T20:41:35.000Z","dependencies_parsed_at":"2024-12-08T10:22:40.586Z","dependency_job_id":"2e4421a0-bc9c-464a-b92e-4b4a5126c071","html_url":"https://github.com/jnidzwetzki/pg-dev-container","commit_stats":null,"previous_names":["jnidzwetzki/pg-dev-container"],"tags_count":1,"template":true,"template_full_name":null,"purl":"pkg:github/jnidzwetzki/pg-dev-container","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnidzwetzki%2Fpg-dev-container","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnidzwetzki%2Fpg-dev-container/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnidzwetzki%2Fpg-dev-container/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnidzwetzki%2Fpg-dev-container/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jnidzwetzki","download_url":"https://codeload.github.com/jnidzwetzki/pg-dev-container/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnidzwetzki%2Fpg-dev-container/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29288140,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T21:57:15.303Z","status":"ssl_error","status_checked_at":"2026-02-09T21:57:11.537Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["devcontainer","postgresql","vscode"],"created_at":"2024-10-26T20:49:07.574Z","updated_at":"2026-02-10T01:18:55.637Z","avatar_url":"https://github.com/jnidzwetzki.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Visual Studio Code - Development Container - PostgreSQL\n\nThis project provides a Visual Studio Code (VSCode) [development container](https://code.visualstudio.com/docs/devcontainers/containers) for PostgreSQL. This container contains all the tools needed to debug PostgreSQL and a PostgreSQL build that is compiled without optimizations, enabled assertions, and debug symbols. This PostgreSQL build is slower than a production build but allows it to develop and test PostgreSQL extensions. For instance, the build performs checks to catch programming mistakes due to the enabled assertions (`USE_ASSERT_CHECKING`) and cleaning freed memory early (`CLOBBER_FREED_MEMORY`). The created debug symbols and the missing optimizations make it easily to attach with a debugger to this instance.\n\n## Prerequisites\n\nTo use the development container, the following prerequisites have to be met:\n\n* VSCode is [installed](https://code.visualstudio.com/Download)\n* Docker is [installed](https://code.visualstudio.com/docs/devcontainers/tutorial#_install-docker)\n* The VSCode _Dev Containers_ extension is [installed](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)\n\n## Open the Project\n\nAfter the prerequisites are meet, the VSCode project can be opened. After loading the project, VSCode asks if the project should be `Reopened in Container`; this option should be selected.\n\n![Open VSCode project](./docs/images/open_container.png)\n\nAfterward, VSCode downloads the needed base container image, installs the tools, and compiles PostgreSQL. This step might _need some time_ to complete. Details about the build process are shown by clicking on the `show log` link.\n\n![Build container](./docs/images/build_container.png)\n\n## First Start\n\nAfter the container is built, the PostgreSQL source code that is part of the development container should be added to VSCode. This allows it to browse the source code and perform full-text search from VSCode as well. To import the source code, a new terminal should be opened and the following command should be executed:\n\n```\ncode --add /usr/local/src/postgresql\n```\n\n_Note:_ VSCode might need to reload the windows after executing the command.\n\nFor example, you can search for the PostgreSQL function `add_path()` after the header files (`.h`) of the source code is added to VSCode, and you should find some matches.\n\n![Search for PostgreSQL functions](./docs/images/search.png)\n\n\n### Connecting to the PostgreSQL server\n\nThe development container automatically starts the PostgreSQL server when the container is executed. Using the integrated terminal, you can connect to this PostgreSQL server after you have created a database using `createdb`. For example, the following commands create a database, connect to the database, create a table, perform a `SELECT` statement, and delete the database.\n\n```\ncreatedb test\npsql test\nCREATE TABLE test (id INTEGER);\nSELECT * FROM test;\nquit\ndropdb test\n```\n\n![Connect to PostgreSQL](./docs/images/connect_psql.png)\n\n### Installing an Extension\n\nThe container also contains a simple `hello_world` PostgreSQL extension, which provides the function `hello_world(TEXT)`. The function takes a parameter of the type `TEXT` and returns `Hello %PARAMETER` also as a `TEXT`. The source code of the extension can be found in the `src/extension/01_hello_world/` directory.\n\nTo install and test the extension, you need to change in the directory of the extension. Afterward, you can compile it by running `make`. This builds the library `hello_world.so`. By running `sudo make install`, the library is copied into the `lib` folder of the database server, and helper files are copied into the `extensions` directory of PostgreSQL. The command must be prefixed with `sudo` since only root has write permissions on these directories. After the extension is installed it can be tested. By running `make installcheck` a new database is created and, the test statements of the file `test/sql/00_hello.sql` are executed and the results are compared with the output stored in `test/expected/00_hello.out`.\n\n```\ncd src/extensions/01_hello_world/\nmake\nsudo make install\nmake installcheck\n```\n\nThe extension can be also tested interactively. To use the extension, a new database needs to be created first:\n\n```\ncreatedb test\npsql test\n```\n\nAfterward, the extension should be available for installation. This can be verified by the following command:\n\n```sql\nSELECT * FROM pg_available_extensions;\n\n         name | default_version | installed_version |                      comment                       \n--------------+-----------------+-------------------+----------------------------------------------------\n postgres_fdw |             1.1 |                   | foreign-data wrapper for remote PostgreSQL servers\n plpgsql      |             1.0 |               1.0 | PL/pgSQL procedural language\n hello_world  |             1.0 |                   | Simple hello world extension\n(3 rows)\n```\n\nIt shows that the extensions `postgres_fdw`, `plpgsql`, and `hello_world` are known by the database server.\n\nBy executing:\n\n```sql\nCREATE EXTENSION hello_world;\n```\n\nthe extension can be installed in the current database. By executing `\\dx` (a helper command provided by `psql`), the installed extensions are listed:\n\n```\n\\dx\n List of installed extensions\n   Name      | Version |   Schema   |         Description          \n-------------+---------+------------+------------------------------\n hello_world | 1.0     | public     | Simple hello world extension\n plpgsql     | 1.0     | pg_catalog | PL/pgSQL procedural language\n(2 rows)\n```\n\nDuring the installation, the content of the install script of the extension `hello_world--1.0.sql` is executed. The script registers a new function in the database catalog and defines the entry point in the C code. In other words, the function is known at the SQL level afterward and PostgreSQL knows that it should call the implementation in our extension. By running the helper command `\\df+ hello_world` the information about the function can be retrieved from the catalog.\n\n```sql\n\\df+ hello_world\n\n Schema |    Name | Result data type | Argument data types | Type | Volatility | Parallel | Owner | Security | Access privileges | Language | Internal name | Description \n--------+-------------+------------------+---------------------+------+------------+----------+--------+----------+-------------------+----------+---------------+-------------\n public | hello_world | text | text | func | volatile   | unsafe | vscode | invoker  |                   | c        | hello_world   | \n```\n\nThe function can now be called:\n\n```sql\nselect hello_world('Mr X');\n\n hello_world \n-------------\n Hello Mr X\n(1 row)\n```\n\n### Using the Debugger\nTo debug the extension, the source code `hello_world.c` needs to be opened. Afterward, a breakpoint can be set by clicking on the dot right of the line number.\n\n![Set a breakpoint](./docs/images/set_breakpoint.png)\n\nTo stop the execution at this point, open a new connection to the database server by running `psql test` from the terminal.\n\nAfterward, click on the editor and press `F5`. A drop-down menu is shown, which asks you to which process the debugger should connect. Type `test` and you should see two PostgreSQL processes containing the name of the `test` database. One process is the `psql` client, the other process is the actual PostgreSQL server backend. It is named `postgresql: vscode test [local] idle`. `vscode` is the user that is connected to the database, `test` is the database name, `[local]` is the name of the client host, and `idle` is the transaction status of this backend. This process should be selected from the drop-down list. Afterward the debugger attaches to this process.\n\n![Set a breakpoint](./docs/images/attach_debugger.png)\n\nAfterward, execute the command `select hello_world('Mr X');` again from your terminal (there might be multiple terminals now, one of the debugger and your terminal executing `psql`. Make sure you select the right one from the list on the right in the terminal tab).\n\nAfter the command is executed, the debugger stops at the breakpoint. On the left plane, you see the actual values of the `Locals` (the variables that are visible in the scope). In addition, the call stack is shown below, and you can switch between the frames on the call stack. On the top, you find some new buttons that allow you to continue the execution or perform an execution line by line or enter the called functions and execute them line by line.\n\n![Execute the Debugger](./docs/images/execute_debugger.png)\n\n\n_Note:_ You can also switch to the implementation of the used functions by pressing `F12`. For example, click on the function `text_to_cstring()` and press `F12` afterward. The file `varlena.c` of the PostgreSQL source code is opened in a new tab, and the cursor is moved to the function definition.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjnidzwetzki%2Fpg-dev-container","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjnidzwetzki%2Fpg-dev-container","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjnidzwetzki%2Fpg-dev-container/lists"}