This project is heavily inspired by Lazygit, which I think is the best TUI client for Git.

I wanted to have a tool like that, but for SQL. I didn't find one that fits my needs, so I created one myself.

I live in the terminal, so if you are like me, this tool can become handy for you too.

This is my first Open Source project, also, this is my first Go project. I am not a brilliant programmer. I am just a typical JavaScript developer that wanted to learn a new language, I also wanted a TUI SQL Client, so blanca y en botella, leche! (white and bottled).

This project is in ALPHA stage, please feel free to complain about my spaghetti code.

I use Lazysql daily in my full-time job as a full-stack javascript developer in its current (buggy xD) state. So, the plan is to improve and fix my little boy as a side-project in my free time.

• Cross-platform (macOS, Windows, Linux)
• Vim Keybindings
• Can manage multiple connections (Backspace)
• Tabs
• SQL Editor (CTRL + e)

$ brew install lazysql

go install github.com/jorgerojas26/lazysql@latest

For Windows, macOS or Linux, you can download a binary release here

Arch Linux users can install it from the AUR with:

paru -S lazysql

or

yay -S lazysql

or install it manual with:

git clone https://aur.archlinux.org/lazysql.git
cd lazysql
makepkg -si

(back to top)

If the XDG_CONFIG_HOME environment variable is set, the configuration file will be located at:

• ${XDG_CONFIG_HOME}/lazysql/config.toml

If not, the configuration file will be located at:

• Windows: %APPDATA%\lazysql\config.toml
• macOS: ~/Library/Application Support/lazysql/config.toml
• Linux: ~/.config/lazysql/config.toml

The configuration file is a TOML file and can be used to define multiple connections.

[[database]]
Name = 'Production database'
Provider = 'postgres'
DBName = 'foo'
URL = 'postgres://${user}:urlencodedpassword@localhost:${port}/foo'
ReadOnly = true
Commands = [
  { Command = 'ssh -tt remote-bastion -L ${port}:localhost:5432', WaitForPort = '${port}' },
  { Command = 'whoami', SaveOutputTo = 'user' },
]
[[database]]
Name = 'Development database'
Provider = 'postgres'
DBName = 'foo'
URL = 'postgres://postgres:urlencodedpassword@localhost:5432/foo'
[application]
DefaultPageSize = 300
DisableSidebar = false
SidebarOverlay = false

The ReadOnly field (optional, defaults to false) can be set to true to enable read-only mode for a connection. When enabled, all mutation queries (INSERT, UPDATE, DELETE, DROP, etc.) will be blocked.

The [application] section is used to define some app settings. Not all settings are available yet, this is a work in progress.

For a list of keyboard shortcuts press ?

Open the TUI with:

$ lazysql

To launch lazysql with the ability to pick from the saved connections.

$ lazysql [connection_url]

To launch lazysql and connect to database at [connection_url].

$ lazysql --read-only [connection_url]

To launch lazysql in read-only mode.

1. Start lazysql
2. Create a new connection (press n)
3. Provide a name for the connection as well as the URL to connect to (see example connection URL)
4. Connect to the DB (press <Enter>)

If you already have a connection set up:

1. Start lazysql
2. Select the right connection (press j and h for navigation)
3. Connect to the DB (press c or <Enter>)

There is currently no way to create a table from the TUI. However you can run the query to create the table as a SQL-Query, inside the SQL Editor.

You can update the tree by pressing R, so you can see your newly created table.

1. Press <Ctrl+E> to open the built-in SQL Editor
2. Write the SQL query
3. Press <Ctrl+R> to execute the SQL query

To switch back to the table-tree press H

After executing a SELECT-query a table will be displayed under the SQL-Editor with the query-result.
To switch focus back to SQL-Editor press /

1. Expand the table-tree by pressing e or <Enter>
2. Select the table you want to view
   • next node j
   • previous node k
   • last node G
   • first node g
3. Press <Enter> to open the table

To switch back to the table-tree press H
To switch back to the table press L

1. Open a table
2. Press / to focus the filter input
3. Write a WHERE-clause to filter the table
4. Press <Enter> to submit your filter

To remove the filter, focus the filter input (press /) and press <Esc>.

1. Open a table
2. Press 1 to switch to the record tab
3. Press o to insert a new row
4. Fill out all columns
5. Press <Ctrl+S> to save the changes

1. Open a table
2. Press 1 to switch to the record tab
3. Move to the column you want to edit
4. Press c to edit, Press <Enter> to submit
5. Press <Ctrl+S> to save the changes

1. Open a table
2. Apply filters or sorting as needed
3. Press E to open the export dialog
4. Optionally modify the file path and batch size
5. Select export scope:
   • Export Current Page: Export only the currently displayed rows
   • Export All Records: Fetch and export all records from the table

Batch size (default: 10000): When exporting all records, data is fetched in batches to avoid timeout or memory issues with large tables. Increase for faster exports, decrease if you encounter any errors.

The default file path is ~/Downloads/{database}_{table}_{timestamp}.csv.

1. Execute a SQL query
2. Press E to open the export dialog
3. Optionally modify the file path
4. Select Export to save all query results

(back to top)

• MySQL
• PostgreSQL
• SQLite
• MSSQL
• MongoDB

Support for multiple RDBMS is a work in progress.

In some cases, mostly when connecting to remote databases, it might be necessary to run a custom command before being able to connect to the database. For example when you can only access the database through a remote bastion, you would probably first need to open an SSH tunnel by running the following command in a separate terminal:

ssh remote-bastion -L 5432:localhost:5432

In order to make it easier to run these commands, lazysql supports running custom commands before connecting to the database. You can define these commands in the configuration file like this:

[[database]]
Name = 'server'
Provider = 'postgres'
DBName = 'foo'
URL = 'postgres://${user}:password@localhost:${port}/foo'
Commands = [
  { Command = 'ssh -tt remote-bastion -L ${port}:localhost:5432', WaitForPort = '${port}' },
  { Command = 'whoami', SaveOutputTo = 'user' },
]

The Command field is required and can contain any command that you would normally run in your terminal. The WaitForPort field is optional and can be used to wait for a specific port to be open before continuing. The SaveOutputTo field is optional and can be used to make user-defined variables. The output (stdout) from the command will be saved into the variable, and the variable can be used in the URL or future commands via the ${VARIABLE} syntax.

When you define the ${port} variable in the URL field, lazysql will automatically replace it with a random free port number. This port number will then be used in the connection URL and is available in the Commands field so that you can use it to configure the command.

You can even chain commands to, for example, connect to a remote server and then to a postgres container running in a remote k8s cluster:

[[database]]
Name = 'container'
Provider = 'postgres'
DBName = 'foo'
URL = 'postgres://postgres:password@localhost:${port}/foo'
Commands = [
  { Command = 'ssh -tt remote-bastion -L 6443:localhost:6443', WaitForPort = '6443' },
  { Command = 'kubectl port-forward service/postgres ${port}:5432 --kubeconfig /path/to/kube.conf', WaitForPort = '${port}' }
]

You can use environment variables in the configuration file using the ${env:VAR_NAME} syntax. This is useful for keeping sensitive information like passwords out of the configuration file.

[[database]]
Name = 'Production'
Provider = 'postgres'
URL = 'postgres://${env:DB_USER}:${env:DB_PASSWORD}@localhost:5432/mydb'

export DB_USER=admin
export DB_PASSWORD=secret
lazysql

Note: Undefined environment variables will be replaced with an empty string.

You can customize keybindings by adding a [keymap.<Group>] section to your config.toml file. Each entry maps a command name to a key.

[keymap.Home]
SwitchToEditorView = "i"
Quit = "Esc"

[keymap.Tree]
GotoTop = "t"
Search = "Ctrl-F"

For single character keys, use the character directly (e.g., "q", "G", "1", "/"). For special keys, use the tcell key name (e.g., "Enter", "Esc", "Ctrl-S"). Only key names defined in tcell are supported.

Group names are case-insensitive (Home, home, and HOME all work).

Available groups: Home, Connection, Tree, TreeFilter, Table, Editor, Sidebar, QueryPreview, QueryHistory, JSONViewer.

Specific editor for lazysql can be set by $SQL_EDITOR.

Specific terminal for opening editor can be set by $SQL_TERMINAL

postgres://user:pass@localhost/dbname
pg://user:pass@localhost/dbname?sslmode=disable
mysql://user:pass@localhost/dbname
mysql:/var/run/mysqld/mysqld.sock
sqlserver://user:[email protected]/dbname
mssql://user:[email protected]/instance/dbname
ms://user:[email protected]:port/instance/dbname?keepAlive=10
oracle://user:[email protected]/sid
sap://user:pass@localhost/dbname
file:myfile.sqlite3?loc=auto
/path/to/sqlite/file/test.db
odbc+postgres://user:pass@localhost:port/dbname?option1=

• Support for NoSQL databases
• Columns and indexes creation through TUI
• Table tree input filter
• Custom keybindings
• Show keybindings on a modal
• Rewrite row create, update and delete logic

See the open issues for a full list of proposed features (and known issues).

(back to top)

We use atotto/clipboard to copy to clipboard.

Platforms:

• OSX
• Windows 7 (probably work on other Windows)
• Linux, Unix (requires 'xclip' or 'xsel' command to be installed)

Contributions, issues, and pull requests are welcome!

(back to top)

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Jorge Rojas - LinkedIn - [email protected]

(back to top)

• Mitzasql
• Gobang

(back to top)