sqltree

Common errors

• sqltree: command not found

  cause The `sqltree` command is not available in your system's PATH. This typically happens if the package is not installed globally or `npx` is not found.
  fix Run `sqltree` using `npx sqltree` to execute it without a global installation, or install it globally with `npm install -g sqltree`.

• Error: connect ECONNREFUSED ::1:5432

  cause The `sqltree` client could not establish a connection to the specified database server. This is commonly due to an incorrect host/port, the database server not running, or network/firewall issues.
  fix Verify that your database server is running, check the host address and port in your connection string or arguments, and ensure no firewall rules are blocking the connection from your machine.

• Error: Cannot find module 'pg' or Error: Cannot find module 'mysql2'

  cause A required database driver is missing or could not be loaded. This might occur if `npx`'s dependency resolution fails or if `sqltree` was installed in an incomplete environment.
  fix Ensure you have a stable internet connection for `npx` to download dependencies. If `sqltree` is installed globally, try reinstalling it with `npm install -g sqltree`. For programmatic usage via `child_process`, ensure `npx` is in your PATH.

Warnings

• gotcha Connection profiles, which may contain sensitive database passwords, are saved to `~/.sqltree/connections.json`. This file has restricted permissions (mode `0600`), but users must still treat it as highly sensitive.
  Fix: Ensure your user's home directory is properly secured and avoid sharing the `connections.json` file. Consider using environment variables for credentials in automated scripts.
• breaking sqltree requires Node.js version 20 or higher to run. Executing the tool with older Node.js versions will lead to errors or unexpected behavior.
  Fix: Upgrade your Node.js installation to version 20 or later. Use a version manager like `nvm` to easily switch Node.js versions (e.g., `nvm install 20 && nvm use 20`).
• gotcha sqltree is a command-line interface application and does not expose a programmatic API. Attempting to `import` or `require` the `sqltree` package in your Node.js or browser applications will result in a module not found or undefined error.
  Fix: Invoke sqltree directly from your terminal using `npx sqltree` or a globally installed `sqltree` command. For scripting, use Node.js's `child_process` module to run the CLI.

Install

• npm install sqltree npm
• yarn add sqltree yarn
• pnpm add sqltree pnpm

Imports

• sqltree (npx invocation)
  wrong:

  import sqltree from 'sqltree'

  correct:

  npx sqltree

  sqltree is primarily a command-line interface (CLI) tool. The most common way to use it is by invoking it via `npx`, which allows running the tool without a global installation. It does not provide programmatic exports.
• sqltree (global command)
  wrong:

  require('sqltree')

  correct:

  npm install -g sqltree
  sqltree

  For frequent use, sqltree can be installed globally using npm, making the `sqltree` command directly available in your shell. Avoid `require()` or `import` for programmatic use as it's not a library.
• sqltree (with connection URI)
  wrong:

  sqltree.connect({ uri: '...' })

  correct:

  npx sqltree --uri postgresql://user:pass@host:port/database

  Connection parameters, including full URIs, are passed as command-line arguments to the `sqltree` executable, not through a JavaScript/TypeScript API.

Quickstart

This Node.js script demonstrates how to programmatically launch the `sqltree` CLI tool via `npx`, connecting to a PostgreSQL database using a connection URI. It uses `child_process.spawn` to inherit the terminal's I/O, allowing the interactive TUI to function.

const { spawn } = require('child_process');

// Example: Connect to a PostgreSQL database using a URI from an environment variable.
// This demonstrates programmatically launching the sqltree CLI.
// Replace 'your_user', 'your_password', 'localhost', '5432', 'your_database_name' with actual values.
// For security, it's recommended to use environment variables for sensitive data.
const DB_URI = process.env.SQLTREE_PG_URI ?? 'postgresql://your_user:your_password@localhost:5432/your_database_name';

console.log(`Launching sqltree to connect to: ${DB_URI.replace(/:[^@]+@/, ':*****@')}`); // Mask password for logging

const child = spawn('npx', ['sqltree', '--uri', DB_URI], {
  stdio: 'inherit', // Allows sqltree's TUI to render in the current terminal
  shell: true // Required for 'npx' command to be found on some systems
});

child.on('error', (err) => {
  console.error('Failed to start sqltree process:', err);
});

child.on('close', (code) => {
  if (code !== 0) {
    console.error(`sqltree process exited with code ${code}`);
  } else {
    console.log('sqltree process exited successfully.');
  }
});