{"id":16540,"library":"sqltree","title":"sqltree","description":"sqltree is an interactive Terminal User Interface (TUI) client designed for seamless navigation and interaction with PostgreSQL and MySQL databases. It currently ships with version 1.4.7, with updates primarily driven by dependency bumps and feature enhancements, indicating active development. The tool differentiates itself through a two-column layout featuring a navigable tree browser for databases, schemas, and tables on one side, and a full-screen SQL REPL with auto-completion on the other. It supports paginated data browsing, result export to CSV/JSON, and persistent connection profiles, all within a unified interface for both database types. sqltree runs on Node.js 20 or higher.","status":"active","version":"1.4.3","language":"javascript","source_language":"en","source_url":"https://github.com/logicalangel/sqltree","tags":["javascript","database","cli","postgresql","mysql","terminal","client","tui","sql"],"install":[{"cmd":"npm install sqltree","lang":"bash","label":"npm"},{"cmd":"yarn add sqltree","lang":"bash","label":"yarn"},{"cmd":"pnpm add sqltree","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime dependency for connecting to MySQL databases.","package":"mysql2","optional":false},{"reason":"Runtime dependency for connecting to PostgreSQL databases.","package":"pg","optional":false}],"imports":[{"note":"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.","wrong":"import sqltree from 'sqltree'","symbol":"sqltree (npx invocation)","correct":"npx sqltree"},{"note":"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.","wrong":"require('sqltree')","symbol":"sqltree (global command)","correct":"npm install -g sqltree\nsqltree"},{"note":"Connection parameters, including full URIs, are passed as command-line arguments to the `sqltree` executable, not through a JavaScript/TypeScript API.","wrong":"sqltree.connect({ uri: '...' })","symbol":"sqltree (with connection URI)","correct":"npx sqltree --uri postgresql://user:pass@host:port/database"}],"quickstart":{"code":"const { spawn } = require('child_process');\n\n// Example: Connect to a PostgreSQL database using a URI from an environment variable.\n// This demonstrates programmatically launching the sqltree CLI.\n// Replace 'your_user', 'your_password', 'localhost', '5432', 'your_database_name' with actual values.\n// For security, it's recommended to use environment variables for sensitive data.\nconst DB_URI = process.env.SQLTREE_PG_URI ?? 'postgresql://your_user:your_password@localhost:5432/your_database_name';\n\nconsole.log(`Launching sqltree to connect to: ${DB_URI.replace(/:[^@]+@/, ':*****@')}`); // Mask password for logging\n\nconst child = spawn('npx', ['sqltree', '--uri', DB_URI], {\n  stdio: 'inherit', // Allows sqltree's TUI to render in the current terminal\n  shell: true // Required for 'npx' command to be found on some systems\n});\n\nchild.on('error', (err) => {\n  console.error('Failed to start sqltree process:', err);\n});\n\nchild.on('close', (code) => {\n  if (code !== 0) {\n    console.error(`sqltree process exited with code ${code}`);\n  } else {\n    console.log('sqltree process exited successfully.');\n  }\n});","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`).","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Run `sqltree` using `npx sqltree` to execute it without a global installation, or install it globally with `npm install -g sqltree`.","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.","error":"sqltree: command not found"},{"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.","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.","error":"Error: connect ECONNREFUSED ::1:5432"},{"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.","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.","error":"Error: Cannot find module 'pg' or Error: Cannot find module 'mysql2'"}],"ecosystem":"npm"}