MSSQLTui Documentation: Setup and Troubleshooting

Installation

MSSQLTui is a single compiled binary built with Rust. It connects to Microsoft SQL Server (on-prem, Azure SQL, AWS RDS, Docker) and exposes both a TUI and an embedded web UI in the same binary. No SSMS, no Azure Data Studio, no Electron. Open source (GPL-3.0).

Download

• Pre-built binary: buy the binary ($4.99 one-time): macOS (Apple Silicon, Intel) and Linux (x86_64, aarch64)
• One-line install (pre-built, macOS Apple Silicon; use ?platform=mac-intel, linux or linux-arm for other builds):

sudo curl -L -o /usr/local/bin/mssqltui "https://dl-mssqltui.voltrus.id/latest?platform=mac-arm" && sudo chmod +x /usr/local/bin/mssqltui

• Build from source (free): GitHub repo: cargo build --release
• Product page: /mssqltui/

System Requirements

First Launch

The binary is self-contained (~7 MB). On macOS, clear Gatekeeper's quarantine once: xattr -d com.apple.quarantine /usr/local/bin/mssqltui.

Quick Start

1. Connect with SQL Server Authentication (30 seconds)

The most common path: username and password against a local or Docker instance.

mssqltui -s localhost -p 1433 -d MyDatabase -u sa -P 'YourPass123!'

1. The TUI opens with a sidebar of Tables and Views, schema-qualified (e.g. dbo.Orders, sales.Invoices), each with a live row count.
2. Press j/k to move, Enter to open a table.
3. The paginated view loads 500 rows at a time (Prev/Next with u/d).

2. Run a T-SQL query

Switch to the Query tab. Autocomplete fires on T-SQL keywords, table names, and columns, including SQL Server specifics (TOP, NOLOCK, EXEC). Press Ctrl+S to execute.

SELECT TOP 50
    o.OrderID, c.CustomerName, o.OrderDate, o.TotalAmount
FROM dbo.Orders o WITH (NOLOCK)
JOIN dbo.Customers c WITH (NOLOCK) ON c.CustomerID = o.CustomerID
WHERE o.OrderDate >= DATEADD(day, -30, GETDATE())
ORDER BY o.TotalAmount DESC;

3. Export results

From the export menu on any table or query result, choose CSV, JSON, or SQL (INSERT statements with correct [schema].[name] quoting). Full table or current page, TUI or Web UI.

4. Launch the Web UI

Prefer a browser? Add --ui for a dark-theme web interface on port 5000.

mssqltui -s localhost -d master -u sa -P 'YourPass123!' --ui

Configuration

Connection Flags

Authentication Modes

Encryption Defaults

TLS encryption is enabled by default, matching modern SQL Server and cloud provider requirements. Override only for trusted local instances:

TUI Keybindings

Key Features

7 MB instead of 1.5 GB

SSMS is a 1.5 GB install that takes 15+ seconds to open. MSSQLTui is a single 7 MB binary that starts in milliseconds. For quick row checks and remote support it's not even a contest.

SSH-friendly with auto-retry

A pure TUI means it runs perfectly over SSH: no X11, no RDP. The connection layer auto-retries on transient failures and the Web UI reconnects on each API call, so a restarted database doesn't kill your session.

Schema-qualified browsing

Tables and views are listed with their schema (dbo.Orders, sales.Invoices), matching how SQL Server actually organizes objects. Row counts are pre-loaded for every object.

T-SQL editor with autocomplete

Autocomplete on T-SQL keywords, table names, and columns, with syntax highlighting for SQL Server-specific syntax. Multi-statement scripts run with per-statement error reporting. One bad query won't hide the rest.

Multi-format export

Export any table or query result as CSV, JSON, or SQL INSERT statements with proper [schema].[name] quoting. Full table or current page, from the TUI or Web UI.

Works with every SQL Server flavor

On-prem SQL Server, Azure SQL Database, Azure SQL Managed Instance, and AWS RDS for SQL Server all speak the same TDS protocol: point -s at the host and connect.

Troubleshooting

Connection refused / port not reachable

Symptom: "connection refused" or a TCP timeout on launch.
Fix: Confirm TCP is enabled on the server (it's off by default on dev installs) and that 1433 is reachable. From a shell:

nc -zv sql.example.com 1433

On-prem: check SQL Server Configuration Manager → Protocols → TCP/IP is Enabled. Azure/RDS: check the firewall/network security group allows your client IP.

Login failed for user

Symptom: "Login failed for user 'sa'" with a known-good password.
Fix: The server is likely in Windows-only auth mode. Switch it to SQL Server and Windows Authentication mode (mixed mode) in SSMS → server properties → Security, then restart the service. Also confirm the sa account is enabled and not locked.

Certificate / TLS errors

Symptom: "The certificate chain was issued by an authority that is not trusted" on connect.
Fix: The server presents a self-signed cert. For a trusted dev box, use --trust-cert. For a local Docker instance with no TLS, use --no-encrypt. Never disable encryption against a production or cloud database.

Azure SQL: "client IP not allowed"

Symptom: Cannot connect to an Azure SQL Database from a new network.
Fix: Azure SQL has a server-level firewall. In the Azure portal → server → Firewalls and virtual networks, add your client IP (shown in the error) to the allowlist, or set a virtual network rule.

Slow on very large tables

Symptom: Opening a table with tens of millions of rows is sluggish.
Fix: Row counts are pre-fetched, which is the cost on huge tables. Use the Query tab with TOP n and a WHERE filter instead of opening the full table. Pagination then streams only the rows you need.

Multi-statement script stops on first error

Symptom: A batch script seems to stop after one statement fails.
Fix: MSSQLTui reports per-statement errors but continues the batch where the server allows it. If a statement is syntactically fatal it aborts the batch. Fix the offending statement (often a missing GO batch separator in DDL) and rerun.

Related Articles

Guides on terminal database browsers and SQL Server workflows.

See also: Postgres CLI Tools vs pgAdmin: When the Terminal Wins

Support

• Email: [email protected]
• Product page: /mssqltui/
• Source: github.com/dzulfikar08/mssqltui

When reporting an issue, include the OS, the SQL Server edition and version (or Azure/RDS), the auth mode, whether TLS is in use, and the exact command and error output.