SQLite Schema Visualizer

4.0.0 verified Thu Apr 23 auth: no javascript

Sqleton is a command-line utility and Node.js library designed to visualize SQLite database schemas. It takes a SQLite database file or object and generates a graphical diagram, typically in formats like SVG, PNG, or PDF, by utilizing the external Graphviz engine for rendering. The current stable version is 4.0.0. While no explicit release cadence is documented, the project appears to be actively maintained. Key differentiators include its singular focus on SQLite, offering both a straightforward CLI for quick visualizations and a programmatic API for integration into Node.js applications. It provides options for customizing the graph layout, adding edge labels for foreign keys, specifying titles, fonts, and graph direction. Although it strictly supports SQLite, users can potentially visualize other database schemas by converting them to a SQLite format first.

Common errors

error Error: spawnSync dot ENOENT ↓

cause The Graphviz 'dot' executable is not found in the system's PATH, preventing sqleton from rendering the diagram.

fix

Install Graphviz on your system. For example: brew install graphviz (macOS) or sudo apt-get install graphviz (Debian/Ubuntu).

error TypeError: sqleton is not a function ↓

cause Attempting to use ES module `import sqleton from 'sqleton'` when the package is primarily CommonJS and exports its main function via `module.exports = function (...)`.

fix

Use the CommonJS require syntax: const sqleton = require('sqleton');

error Error: SQLITE_CANTOPEN: unable to open database file ↓

cause The specified SQLite database file does not exist at the given path, or the Node.js process lacks sufficient read permissions for the file or its directory.

fix

Verify the path to your SQLite database file and ensure it exists and is readable by the process running sqleton.

Warnings

gotcha Sqleton relies on the external Graphviz application (`dot` command) for rendering diagrams. Graphviz must be installed separately on your operating system and accessible via the system's PATH. Without Graphviz, sqleton will fail to generate any graphical output, often with an 'ENOENT' error. ↓

fix Install Graphviz on your operating system. Common installation commands include: `brew install graphviz` (macOS), `sudo apt-get install graphviz` (Debian/Ubuntu), `pacman -Sy graphviz` (Arch Linux). Refer to http://www.graphviz.org/download/ for platform-specific instructions.

gotcha Sqleton is exclusively designed to visualize SQLite database schemas. While creative workarounds (e.g., dumping and converting schemas) might exist for other database types, direct native support for PostgreSQL, MySQL, or other non-SQLite databases is not provided. ↓

fix Ensure you are using a SQLite database. For other database systems, consider using dedicated visualization tools for that specific database or evaluating if a schema conversion to SQLite is feasible for visualization purposes.

Install

npm install sqleton

yarn add sqleton

pnpm add sqleton

Imports

sqleton
wrong
```
import sqleton from 'sqleton'
```
correct
```
const sqleton = require('sqleton')
```
The primary programmatic API is a default function export via CommonJS. While Node.js 18+ generally supports ESM, `sqleton`'s main module is intended for `require()` based consumption.

Quickstart

Demonstrates programmatic use of `sqleton` to generate an SVG diagram of a simple SQLite schema. It sets up an in-memory database with tables and foreign keys using `better-sqlite3`, then pipes the output to a file, also handling potential Graphviz execution errors.

import Database from 'better-sqlite3';
import fs from 'node:fs';
// Sqleton is a CommonJS module, so 'require' is the canonical way to import.
const sqleton = require('sqleton');

// Create a dummy in-memory SQLite database for demonstration
const db = new Database(':memory:');
db.exec(`
  CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE
  );

  CREATE TABLE posts (
    post_id INTEGER PRIMARY KEY,
    user_id INTEGER NOT NULL,
    title TEXT NOT NULL,
    content TEXT,
    FOREIGN KEY (user_id) REFERENCES users(id)
  );

  CREATE TABLE comments (
    comment_id INTEGER PRIMARY KEY,
    post_id INTEGER NOT NULL,
    user_id INTEGER NOT NULL,
    text TEXT NOT NULL,
    FOREIGN KEY (post_id) REFERENCES posts(post_id),
    FOREIGN KEY (user_id) REFERENCES users(id)
  );
`);

const outputPath = 'db_schema.svg';
const outputStream = fs.createWriteStream(outputPath);

// Generate the schema diagram
sqleton(db, outputStream, {
  layout: 'dot', // Specify the Graphviz layout engine
  title: 'My Application Schema',
  direction: 'LR', // Graph direction: Left-to-Right
  edgeLabels: true, // Show labels on foreign key edges
})
  .then(() => {
    console.log(`Schema diagram generated successfully at ${outputPath}`);
    outputStream.end();
    db.close();
  })
  .catch((err: Error) => {
    console.error('Failed to generate schema diagram:', err.message);
    // Provide specific guidance for the common Graphviz error
    if (err.message.includes('dot: not found') || err.message.includes('ENOENT')) {
      console.error('Error: Graphviz `dot` command not found. Please ensure Graphviz is installed and in your system PATH.');
      console.error('Installation instructions: http://www.graphviz.org/download/');
    }
    outputStream.end();
    db.close();
  });