Troubleshooting

​

Connection Issues

​

Cannot Connect to Database

# Test if the port is reachable
telnet hostname port
# or
nc -zv hostname port

# PostgreSQL
pg_ctl status

# MySQL
systemctl status mysql
# or
brew services list  # macOS

# Check if process is running
ps aux | grep postgres
ps aux | grep mysql

-- Check pg_hba.conf for allowed connections
-- Add line like:
host all all 0.0.0.0/0 md5

-- Grant remote access
GRANT ALL PRIVILEGES ON *.* TO 'username'@'%' IDENTIFIED BY 'password';
FLUSH PRIVILEGES;

​

Connection Drops Frequently

1. Check timeout settings on your database server
2. Network instability: Test with ping hostname for packet loss
3. VPN disconnections: Ensure VPN remains connected
4. Server-side connection limits: Check if max connections reached

-- PostgreSQL: Check max connections
SHOW max_connections;
SELECT count(*) FROM pg_stat_activity;

-- MySQL: Check max connections
SHOW VARIABLES LIKE 'max_connections';
SHOW STATUS LIKE 'Threads_connected';

​

SSH Tunnel Connection Fails

ssh -p 22 username@ssh-host

chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub

# From SSH host, test database connection
telnet database-host 5432

# On SSH server, check /etc/ssh/sshd_config
AllowTcpForwarding yes

​

Query Issues

​

Query Times Out

1. Add a LIMIT clause to reduce result size
   SELECT * FROM large_table LIMIT 1000;
   
2. Add indexes to speed up queries
   -- PostgreSQL/MySQL
   CREATE INDEX idx_column ON table_name(column_name);
   
3. Filter with WHERE clause early
   -- Bad: Loads everything then filters
   SELECT * FROM orders WHERE date > '2024-01-01';
   
   -- Good: Uses index if available
   CREATE INDEX idx_orders_date ON orders(date);
   SELECT * FROM orders WHERE date > '2024-01-01';
   
4. Check server query timeout settings
   -- PostgreSQL
   SET statement_timeout = '30s';
   
   -- MySQL
   SET SESSION max_execution_time = 30000; -- milliseconds
   

​

Syntax Error in Query

• Wrong SQL dialect: PostgreSQL vs MySQL syntax differences
• Reserved keywords: Use quotes around reserved words
• Missing semicolon: Not required in Zequel but some habits die hard
• String quotes: Use single quotes for strings in SQL

-- Wrong: Using backticks in PostgreSQL
SELECT `name` FROM `users`;

-- Correct: Use double quotes or no quotes
SELECT "name" FROM users;
SELECT name FROM users;

-- Wrong: Reserved keyword without quotes
SELECT order FROM orders;

-- Correct: Quote reserved words
SELECT "order" FROM orders;

​

Results Not Showing

1. Query actually returns data
   SELECT COUNT(*) FROM table_name WHERE your_conditions;
   
2. Result limit is not 0
   • Check Settings → Query Settings → Default Limit
3. Scroll down - Results might be below the fold
4. Check for errors in the bottom panel logs

​

Performance Issues

​

Zequel Runs Slowly

​

Loading Schema Takes Forever

• Database has thousands of tables/columns
• Slow network connection
• Database server is slow to respond

1. Use sidebar navigation instead of Command Palette for large schemas
2. Filter by database/schema to reduce objects loaded
3. Optimize database catalog queries on the server
4. Close and reopen connection to reload schema cache

​

Data Issues

​

Changes Not Saving

1. Safe Mode is disabled
   • Look for shield icon in header bar
   • Safe Mode prevents all write operations
2. Table has a primary key
   • Zequel requires a primary key to update rows
   • Add a primary key if missing:
   ALTER TABLE table_name ADD PRIMARY KEY (id);
   
3. User has write permissions
   -- PostgreSQL: Check permissions
   SELECT grantee, privilege_type 
   FROM information_schema.role_table_grants 
   WHERE table_name='your_table';
   
   -- MySQL: Check permissions
   SHOW GRANTS FOR 'username'@'host';
   
4. Check error logs in the bottom panel for specific error messages

​

Data Appears Blurred

• Click the eye icon in the header bar to disable
• Privacy Mode blurs sensitive data for screen sharing

​

Cannot Delete Row

1. Safe Mode - Disable it
2. Permissions - User needs DELETE privilege
3. Foreign key constraints - Other tables reference this row

-- PostgreSQL: Disable foreign key checks temporarily (careful!)
SET CONSTRAINTS ALL DEFERRED;
DELETE FROM table_name WHERE id = 123;
COMMIT;

-- MySQL: Disable foreign key checks (careful!)
SET FOREIGN_KEY_CHECKS = 0;
DELETE FROM table_name WHERE id = 123;
SET FOREIGN_KEY_CHECKS = 1;

​

Application Issues

​

Zequel Won’t Start

1. Check system requirements
   • macOS 10.15 or later
   • Windows 10 or later
   • Linux with modern kernel
2. Reset app data
   • Corrupted settings might prevent startup
   • Delete app data folder:
     • macOS: ~/Library/Application Support/Zequel/
     • Windows: %APPDATA%/Zequel/
     • Linux: ~/.config/Zequel/
3. Reinstall Zequel
   • Download latest version from zequel.dev
   • Uninstall current version completely
   • Install fresh copy

​

Keyboard Shortcuts Not Working

1. Another application is capturing the shortcut
   • Close other apps and try again
   • Check for system-wide shortcut conflicts
2. Focus is in wrong place
   • Some shortcuts only work in specific contexts
   • Click into the main window area
3. Operating system differences
   • Use Cmd on macOS, Ctrl on Windows/Linux
   • Check the menu to see actual shortcuts for your platform

​

Updates Not Installing

1. Quit Zequel completely before updating
2. Check disk space - Need enough space for new version
3. Run as administrator (Windows) if permission denied
4. Manually download installer from GitHub releases
5. Check Update Channel - Switch to Stable if on Beta

​

Database-Specific Issues

​

SQLite

• Another process has the database file open
• Close other connections to the same file
• Check for .db-journal or .db-wal files (delete if stale)

​

PostgreSQL

-- Check current connections
SELECT count(*) FROM pg_stat_activity;

-- Increase max connections (requires restart)
ALTER SYSTEM SET max_connections = 200;

-- Check database encoding
SHOW server_encoding;

-- Create database with specific encoding
CREATE DATABASE mydb ENCODING 'UTF8';

​

MySQL/MariaDB

-- Check user exists and has privileges
SELECT user, host FROM mysql.user WHERE user = 'username';

-- Grant all privileges
GRANT ALL PRIVILEGES ON database.* TO 'username'@'%';
FLUSH PRIVILEGES;

​

MongoDB

• Ensure authentication database is correct (usually admin)
• Check if user exists in correct database
• Verify replica set configuration if using one

​

Getting Help

1. Check application logs
   • Location: See Settings
   • Look for error messages near the time of the issue
2. Search existing issues
   • GitHub Issues
   • Someone might have already reported and solved it
3. Report a bug
   • Include: OS version, Zequel version, database type
   • Provide: Steps to reproduce, error messages, relevant logs
   • Create new issue
4. Join discussions
   • GitHub Discussions
   • Ask questions and get help from the community

​

Emergency Recovery

​

Complete Reset

rm -rf ~/Library/Application\ Support/Zequel/
rm -rf ~/Library/Preferences/dev.zequel.*

rmdir /s "%APPDATA%\Zequel"

rm -rf ~/.config/Zequel/