npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

psql-describe

v0.1.6

Published

psql's `\d` (describe) family of commands ported to JavaScript.

Downloads

16,728

Readme

psql-describe

psql's \d (describe) family of commands ported to JavaScript.

  • 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).
  • We use plenty of RegExp search-and-replace to turn this C code into valid JS syntax.
  • We implement some C library functions, such as strlen and strchr, and some Postgres support functions, such as printTable and printQuery, in JavaScript.
  • We write tests to catch problems, mostly related to pointer arithmetic, pointer dereferencing, and pointer output parameters. Then we fix them.

This 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.

This library is on npm and powers backslash commands in the Neon SQL Editor.

Usage

The key export is the describe() function:

describe(
  cmd,
  dbName,
  runQuery,
  outputFn,
  echoHidden = false,
  sversion = null,
  std_strings = true, 
  docsURLTemplate = (id) => `https://www.postgresql.org/docs/current/${id}.html`,
): { promise, cancel };
  • 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).
  • dbName (string) is the name of the connected database.
  • 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'.
  • outputFn is a function that receives output for display: this output will be either a string or a table object (see below).
  • 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.
  • 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.
  • std_strings (boolean) indicates the value of standard_conforming_strings in the database.
  • docsURLTemplate (function) specifies how a docs page ID is transformed into a URL, for use with \h.

The function returns an object with two keys: { promise, cancel }:

  • promise is a Promise that resolves when the command completes.
  • cancel() is a function you can call to abort the command.

The outputs of describe(), as passed to the outputFn argument, are a mix of plain strings and JS objects representing tables.

To format these outputs for display, two additional functions are exported:

  • describeDataToString(item)

This 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.

  • describeDataToHtml(item)

This function HTML-escapes string items, and formats object items as HTML tables (whose contents are HTML-escaped).

Tests

The tests compare this software's output against psql for the commands in test/tests.txt. Output is expected to be character-for-character identical, except for differences in trailing space at the end of lines.

In case of failure, the tests halt and a psql.txt and local.txt are written, which you can then diff.

To make the tests work on your machine, you'll need to create a test database (see below) and update the DB connection strings in the test command in package.json.

Database

Tests should be run against a database named psqldescribe containing the Pagila data set, with a few additions:

curl https://raw.githubusercontent.com/devrimgunduz/pagila/master/pagila-schema.sql | psql psqldescribe
curl https://raw.githubusercontent.com/devrimgunduz/pagila/master/pagila-data.sql | psql psqldescribe
psql psqldescribe < test/test-pagila-additions.sql