{"id":14973852,"url":"https://github.com/neondatabase/psql-describe","last_synced_at":"2025-04-07T08:16:44.146Z","repository":{"id":203343771,"uuid":"709287951","full_name":"neondatabase/psql-describe","owner":"neondatabase","description":"psql's \\d (describe) family of commands ported to JavaScript","archived":false,"fork":false,"pushed_at":"2025-02-12T11:03:49.000Z","size":737,"stargazers_count":38,"open_issues_count":1,"forks_count":1,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-31T07:09:11.533Z","etag":null,"topics":["describe","postgresql","psql"],"latest_commit_sha":null,"homepage":"https://neon.tech/blog/bringing-psqls-d-to-your-web-browser","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neondatabase.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}},"created_at":"2023-10-24T12:18:26.000Z","updated_at":"2025-03-20T06:15:31.000Z","dependencies_parsed_at":null,"dependency_job_id":"b937cad4-1a8e-4c3c-b618-0bbebe34e5f1","html_url":"https://github.com/neondatabase/psql-describe","commit_stats":{"total_commits":58,"total_committers":1,"mean_commits":58.0,"dds":0.0,"last_synced_commit":"2dd44cca4b9236773ee4462dd7eabc2a06c6bdfd"},"previous_names":["neondatabase/psql-describe"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neondatabase%2Fpsql-describe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neondatabase%2Fpsql-describe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neondatabase%2Fpsql-describe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neondatabase%2Fpsql-describe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neondatabase","download_url":"https://codeload.github.com/neondatabase/psql-describe/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247615382,"owners_count":20967184,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["describe","postgresql","psql"],"created_at":"2024-09-24T13:49:34.533Z","updated_at":"2025-04-07T08:16:44.116Z","avatar_url":"https://github.com/neondatabase.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# psql-describe\n\npsql's `\\d` (describe) family of commands ported to JavaScript.\n\n* From Postgres `REL_17_0`, we take `exec_command_d`, `exec_command_list` and `exec_command_sf_sv` from `command.c`, and all of `describe.c` and `sql_help.c`, from `src/bin/psql` (note that `sql_help.c` is generated during compilation of psql: you need to run `./configure` in the Postgres repo root followed by `make` in `src/bin/psql`).\n* We use plenty of RegExp search-and-replace to turn this C code into valid JS syntax.\n* We implement some C library functions, such as `strlen` and `strchr`, and some Postgres support functions, such as `printTable` and `printQuery`, in JavaScript.\n* We write tests to catch problems, mostly related to pointer arithmetic, pointer dereferencing, and pointer output parameters. Then we fix them.\n\nThis approach means that some of the 13,000+ lines of code in `describe.mjs` may never actually have been looked at. If you find a bug, please file an issue.\n\nThis library is [on npm](https://www.npmjs.com/package/psql-describe) and [powers backslash commands in the Neon SQL Editor](https://neon.tech/blog/bringing-psqls-d-to-your-web-browser).\n\n## Usage\n\nThe key export is the `describe()` function:\n\n```typescript\ndescribe(\n  cmd,\n  dbName,\n  runQuery,\n  outputFn,\n  echoHidden = false,\n  sversion = null,\n  std_strings = true, \n  docsURLTemplate = (id) =\u003e `https://www.postgresql.org/docs/current/${id}.html`,\n): { promise, cancel };\n```\n\n* `cmd` (string) is the desired describe command, including the leading backslash, such as `\\d` (don't forget you may need to escape the backslash in a literal string).\n* `dbName` (string) is the name of the connected database.\n* `runQuery` is an async function that takes a SQL query (string) and must return *unparsed* query results in the same format used by node-postgres when specifying `rowMode: 'array'`.\n* `outputFn` is a function that receives output for display: this output will be either a string or a table object (see below).\n* `echoHidden` (boolean) has the same effect as the `-E` argument to psql: if `true`, all SQL queries are output to `outputFn`, in addition to the final results.\n* `sversion` (number) should be the same value as `SHOW server_version_num` executed on the server. It is used to determine what features the database supports. If it is not provided, the server is queried for it.\n* `std_strings` (boolean) indicates the value of `standard_conforming_strings` in the database.\n* `docsURLTemplate` (function) specifies how a docs page ID is transformed into a URL, for use with `\\h`. \n\nThe function returns an object with two keys: `{ promise, cancel }`: \n\n* `promise` is a `Promise` that resolves when the command completes. \n* `cancel()` is a function you can call to abort the command.\n\nThe outputs of `describe()`, as passed to the `outputFn` argument, are a mix of plain strings and JS objects representing tables.\n\nTo format these outputs for display, two additional functions are exported:\n\n* ```describeDataToString(item)```\n\nThis function passes though string items unchanged. When an object item is passed in, a formatted plain-text table is returned, identical to those produced by the psql CLI.\n\n* ```describeDataToHtml(item)```\n\nThis function HTML-escapes string items, and formats object items as HTML tables (whose contents are HTML-escaped).\n\n\n## Tests\n\nThe tests compare this software's output against `psql` (release 17.0) for the commands in `test/tests.txt`. Output should be character-for-character identical, except for differences in trailing whitespace.\n\nIn case of failure, the tests halt and a `psql.txt` and `local.txt` are written, which you can then `diff`.\n\nTo make the tests work on your machine, you'll need to create a test database (see below), and probably update the DB connection strings in the `test` command in `package.json`.\n\n\n### Database\n\nTests should be run against a database named `psqldescribe` containing the [Pagila](https://github.com/devrimgunduz/pagila) data set, with a few additions:\n\n```bash\ncurl https://raw.githubusercontent.com/devrimgunduz/pagila/master/pagila-schema.sql | psql psqldescribe\ncurl https://raw.githubusercontent.com/devrimgunduz/pagila/master/pagila-data.sql | psql psqldescribe\npsql psqldescribe \u003c test/test-pagila-additions.sql\n```\n\n## License\n\nThis package is released under the [Postgres license](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneondatabase%2Fpsql-describe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneondatabase%2Fpsql-describe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneondatabase%2Fpsql-describe/lists"}