Skip to main content

​
Prerequisites

Node.js

Version 18 or higher required for Electron compatibility

npm

Version 9+ (comes with Node.js)

Git

For version control and contributions

Docker

Optional, for running test databases

​
Installation

1

Clone the Repository

git clone https://github.com/zequel-labs/zequel.git
cd zequel
2

Install Dependencies

npm install
This will:
  • Install all Node.js dependencies
  • Run postinstall to set up Electron app dependencies
  • Configure Husky Git hooks
3

Verify Installation

Check that everything is set up correctly:
npm run typecheck
npm run test:unit
Both commands should complete without errors.

​
Development Commands

​
Core Commands

npm run dev
# Starts dev server with hot reload
# Opens app automatically
# DevTools available via F12 or Cmd+Option+I

​
Platform-Specific Builds

npm run build:mac
# Builds for macOS (Intel + Apple Silicon)
# Creates .zip installers
# Output: dist/zequel-apple-{arch}.zip

​
Type Checking

npm run typecheck
# Type-checks both main and renderer processes
# Runs: typecheck:node && typecheck:web

​
Testing

npm run test
# Runs unit + integration tests in watch mode
# Uses Vitest

​
Docker Development Databases

Docker Compose provides test databases with seed data for all 9 supported database systems.

​
Starting Databases

# Start all database containers
docker-compose up -d

# Start specific database
docker-compose up -d postgres
docker-compose up -d mysql

# View logs
docker-compose logs -f postgres

# Stop all containers
docker-compose down

# Stop and remove volumes (clean restart)
docker-compose down -v

​
Database Ports

DatabasePortUsernamePasswordDatabase
PostgreSQL54320zequelzequelzequel
MySQL33061zequelzequelzequel
MariaDB33070zequelzequelzequel
MongoDB27018zequelzequelzequel
Redis63790-zequel-
SQL Server14330saZequel123!master
ClickHouse18123 / 19000default-zequel
SQLite and DuckDB don’t require Docker. They use bundled native libraries.

​
Seed Data

Each database container includes comprehensive seed data:
  • Tables with various data types
  • Views (regular and materialized)
  • Stored procedures and functions
  • Triggers
  • Indexes and foreign keys
  • Sequences (PostgreSQL)
  • Extensions (PostgreSQL)
  • Events (MySQL/MariaDB)
  • Users and roles
Integration tests in src/tests/integration/ verify this seed data.

​
SQLite Special Case

SQLite uses a pre-built database file at docker/sqlite/zequel.db. If you modify docker/sqlite/init.sql, regenerate it: 
rm docker/sqlite/zequel.db
sqlite3 docker/sqlite/zequel.db < docker/sqlite/init.sql

​
Documentation

Zequel’s documentation (this site) is built with VitePress: 
# Start docs dev server
npm run docs:dev
# Opens at http://localhost:5173

# Build docs for production
npm run docs:build

# Preview built docs
npm run docs:preview

​
IDE Setup

Recommended Extensions:
  • Volar - Vue 3 language support
  • TypeScript Vue Plugin - TypeScript in .vue files
  • Tailwind CSS IntelliSense - Class autocomplete
  • ESLint (optional) - Linting support
Settings (.vscode/settings.json): 
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  },
  "editor.formatOnSave": false
}

​
WebStorm

  • Enable Vue.js plugin
  • Enable TypeScript language service
  • Configure Tailwind CSS support
  • Set Node interpreter to project’s Node version

​
Troubleshooting

​
Build Errors

Some dependencies (better-sqlite3, @duckdb/node-api, keytar) require native compilation.Solution: Ensure you have build tools installed:
  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Windows: Visual Studio Build Tools
  • Linux: build-essential package
Then run:
npm run postinstall
If npm run typecheck fails after pulling changes:
rm -rf node_modules
npm install
Check if ports are already in use:
lsof -i :54320  # PostgreSQL
lsof -i :33061  # MySQL
Stop conflicting services or change ports in docker-compose.yml.
E2E tests require a production build first:
npm run build
npm run test:e2e

​
Common Issues

App won’t start in dev mode:
  • Check that port 5173 (Vite dev server) isn’t in use
  • Clear Electron cache: rm -rf ~/.config/Electron
Hot reload not working:
  • Ensure you’re using npm run dev, not npm run build
  • Check console for Vite HMR errors
Git hooks not running:
  • Husky may not be installed. Run: 
    npm run prepare

​
Next Steps

Project Structure

Explore the codebase organization

Architecture

Learn Electron process architecture

Testing

Write and run tests

Database Adapters

Add support for new databases

Build docs developers (and LLMs) love

Get started for freeTalk to us