Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/danvergara/dblab

The database client every command line junkie deserves.
https://github.com/danvergara/dblab

cli client developer-tools development golang mysql postgresql tui

Last synced: 1 day ago
JSON representation

The database client every command line junkie deserves.

Host: GitHub
URL: https://github.com/danvergara/dblab
Owner: danvergara
License: mit
Created: 2021-03-30T05:20:36.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2024-11-19T15:33:55.000Z (24 days ago)
Last Synced: 2024-12-05T03:04:17.886Z (8 days ago)
Topics: cli, client, developer-tools, development, golang, mysql, postgresql, tui
Language: Go
Homepage:
Size: 23.2 MB
Stars: 2,422
Watchers: 14
Forks: 63
Open Issues: 12
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

awesome-repositories - danvergara/dblab - The database client every command line junkie deserves. (Go)
awesome-tools - dblab - The database client every command line junkie deserves. (Databases / Log management / Screen Sharing)
awesome-tuis - dblab
my-awesome - danvergara/dblab - tools,development,golang,mysql,postgresql,tui pushed_at:2024-11 star:2.4k fork:0.1k The database client every command line junkie deserves. (Go)
stars - danvergara/dblab - The database client every command line junkie deserves. (Go)
stars - danvergara/dblab - The database client every command line junkie deserves. (Go)

README

dblab ![integration tests](https://github.com/danvergara/dblab/actions/workflows/ci.yaml/badge.svg) ![unit tests](https://github.com/danvergara/dblab/actions/workflows/test.yaml/badge.svg) [![Release](https://img.shields.io/github/release/danvergara/dblab.svg?label=Release)](https://github.com/danvergara/dblab/releases)
===============

dblab logo

__Interactive client for PostgreSQL, MySQL, SQLite3, Oracle and SQL Server.__

---

**Documentation**: https://dblab.danvergara.com

---

## Table of contents

- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Homebrew](#homebrew)
- [Binary Release](#binary-release-linuxosxwindows)
- [Automated installation/update](#automated-installationupdate)
- [Help Command](#help)
- [Usage](#usage)
- [Configuration](#configuration)
- [Navigation](#navigation)
- [Key Bindings](#key-bindings)
- [Contribute](#contribute)
- [License](#license)

## Overview

dblab is a fast and lightweight interactive terminal based UI application for PostgreSQL, MySQL and SQLite3,
written in Go and works on OSX, Linux and Windows machines. Main idea behind using Go for backend development
is to utilize ability of the compiler to produce zero-dependency binaries for
multiple platforms. dblab was created as an attempt to build very simple and portable
application to work with local or remote PostgreSQL/MySQL/SQLite3/Oracle/SQL Server databases.

## Features

- Cross-platform support OSX/Linux/Windows 32/64-bit
- Simple installation (distributed as a single binary)
- Zero dependencies.

## Installation

> ~~if you need to work with SQLite3, install the CGO enabled binary using the proper bash script listed below.~~
> The above comment is deprecated and CGO is not needed anymore. There will be a single binary capable to deal with all supported clients.

### Homebrew

It works with Linux, too.

```
$ brew install danvergara/tools/dblab
```

```
$ brew tap danvergara/tools
$ brew install dblab
```

### Binary Release (Linux/OSX/Windows)
You can manually download a binary release from [the release page](https://github.com/danvergara/dblab/releases).

## Automated installation/update
> Don't forget to always verify what you're piping into bash

Install the binarry using our bash script:

```sh
curl https://raw.githubusercontent.com/danvergara/dblab/master/scripts/install_update_linux.sh | bash
```

## Help

```
dblab is a terminal UI based interactive database client for Postgres, MySQL and SQLite3.

Usage:
dblab [flags]
dblab [command]

Available Commands:
help Help about any command
version The version of the project

Flags:
--cfg-name string Database config name section
--config Get the connection data from a config file (default locations are: current directory, $HOME/.dblab.yaml or $XDG_CONFIG_HOME/.dblab.yaml)
--db string Database name (optional)
--driver string Database driver
--encrypt string [strict|disable|false|true] data sent between client and server is encrypted or not
-h, --help help for dblab
--host string Server host name or IP
--limit uint Size of the result set from the table content query (should be greater than zero, otherwise the app will error out) (default 100)
--pass string Password for user
--port string Server port
--schema string Database schema (postgres only)
--socket string Path to a Unix socket file
--ssl string SSL mode
--ssl-verify string [enable|disable] or [true|false] enable ssl verify for the server
--sslcert string This parameter specifies the file name of the client SSL certificate, replacing the default ~/.postgresql/postgresql.crt
--sslkey string This parameter specifies the location for the secret key used for the client certificate. It can either specify a file name that will be used instead of the default ~/.postgresql/postgresql.key, or it can specify a key obtained from an external “engine”
--sslpassword string This parameter specifies the password for the secret key specified in sslkey
--sslrootcert string This parameter specifies the name of a file containing SSL certificate authority (CA) certificate(s) The default is ~/.postgresql/root.crt
--timeout string in seconds (default is 0 for no timeout), set to 0 for no timeout. Recommended to set to 0 and use context to manage query and connection timeouts
--trace-file string File name for trace log
--trust-server-certificate string [false|true] server certificate is checked or not
-u, --url string Database connection string
--user string Database user
-v, --version version for dblab
--wallet string Path for auto-login oracle wallet

Use "dblab [command] --help" for more information about a command.
```

## Usage

You can start the app passing no flags or parameters, you'll be asked for connection data instead.
![dblab-demo](screenshots/dblab-demo.gif)

```sh
$ dblab --host localhost --user myuser --db users --pass password --ssl disable --port 5432 --driver postgres --limit 50
$ dblab --db path/to/file.sqlite3 --driver sqlite
$ dblab --host localhost --user system --db FREEPDB1 --pass password --port 1521 --driver oracle --limit 50
$ dblab --host localhost --user SA --db msdb --pass '5@klkbN#ABC' --port 1433 --driver sqlserver --limit 50
```

Connection URL scheme is also supported:

```sh
$ dblab --url 'postgres://user:password@host:port/database?sslmode=[mode]'
$ dblab --url 'mysql://user:password@tcp(host:port)/db'
$ dblab --url 'file:test.db?_pragma=foreign_keys(1)&_time_format=sqlite'
$ dblab --url 'oracle://user:password@localhost:1521/db'
$ dblab --url 'sqlserver://SA:myStrong(!)Password@localhost:1433?database=tempdb&encrypt=true&trustservercertificate=false&connection+timeout=30'
```

if you're using PostgreSQL, you have the option to define the schema you want to work with, the default value is `public`.

```sh
$ dblab --host localhost --user myuser --db users --pass password --schema myschema --ssl disable --port 5432 --driver postgres --limit 50
$ dblab --url postgres://user:password@host:port/database?sslmode=[mode] --schema myschema
```

As a request made in [#125](https://github.com/danvergara/dblab/issues/125), support for MySQL/MariaDB sockets was integrated.

```sh
$ dblab --url "mysql://user:password@unix(/path/to/socket/mysql.sock)/dbname?charset=utf8"
$ dblab --socket /path/to/socket/mysql.sock --user user --db dbname --pass password --ssl disable --port 5432 --driver mysql --limit 50
```

Postgres connection through Unix sockets:

```sh
$ dblab --url "postgres://user:password@/dbname?host=/path/to/socket"
$ dblab --socket /path/to/socket --user user --db dbname --pass password --ssl disable --port 5432 --driver postgres --limit 50
```

Now, it is possible to ensure SSL connections with `PostgreSQL` databases. SSL related parameters has been added, such as `--sslcert`, `--sslkey`, `--sslpassword`, `--sslrootcert`. More information on how to use such connection flags can be found [here](https://www.postgresql.org/docs/current/libpq-connect.html).

```{ .sh .copy }
dblab --host db-postgresql-nyc3-56456-do-user-foo-0.fake.db.ondigitalocean.com --user myuser --db users --pass password --schema myschema --port 5432 --driver postgres --limit 50 --ssl require --sslrootcert ~/Downloads/foo.crt
```

### Configuration

Enter previous flags every time is tedious, so `dblab` provides a couple of flags to help with it: `--config` and `--cfg-name`.

`dblab` is going to look for a file called `.dblab.yaml`. Currently, there are three places where you can drop a config file:

- $XDG_CONFIG_HOME ($XDG_CONFIG_HOME/.dblab.yaml)
- $HOME ($HOME/.dblab.yaml)
- . (the current directory where you run the command line tool)

If you want to use this feature, `--config` is mandatory and `--cfg-name` may be omitted. The config file can store one or multiple database connection sections under the `database` field. `database` is an array, previously was an object only able to store a single connection section at a time.

We strongly encourgae you to adopt the new format as of `v0.18.0`. `--cfg-name` takes the name of the desired database section to connect with. It can be omitted and its default values will be the first item on the array.

As of `v0.21.0`, ssl connections options are supported in the config file.

```sh
# default: test
$ dblab --config

$ dblab --config --cfg-name "prod"
```

`.dblab.yaml` example:

```yaml
database:
- name: "test"
host: "localhost"
port: 5432
db: "users"
password: "password"
user: "postgres"
driver: "postgres"
# optional
# postgres only
# default value: public
schema: "myschema"
- name: "prod"
# example endpoint
host: "mydb.123456789012.us-east-1.rds.amazonaws.com"
port: 5432
db: "users"
password: "password"
user: "postgres"
schema: "public"
driver: "postgres"
ssl: "require"
sslrootcert: "~/.postgresql/root.crt."
- name: "oracle"
host: "localhost"
port: 1521
db: "FREEPDB1 "
password: "password"
user: "system"
driver: "oracle"
ssl: "enable"
wallet: "path/to/wallet"
ssl-verify: true
- name: "sqlserver"
driver: "sqlserver"
host: "localhost"
port: 1433
db: "msdb"
password: "5@klkbN#ABC"
user: "SA"
# should be greater than 0, otherwise the app will error out
limit: 50
```

Or for sqlite:

```yaml
database:
- name: "prod"
db: "path/to/file.sqlite3"
driver: "sqlite"
```

Only the `host` and `ssl` fields are optionals. `127.0.0.1` and `disable`, respectively.

## Navigation

If the query panel is active, type the desired query and press Ctrl+Space to see the results on the rows panel below.
Otherwise, you might me located at the tables panel, then you can navigate by using the arrows Up and Down (or the keys k and j respectively). If you want to see the rows of a table, press Enter. To see the the schema of a table, locate yourself on the `rows` panel and press Ctrl+S to switch to the `structure` panel, then switch Ctrl+S to switch back.
The same can be achieved for the `constraints` view by pressing Ctrl+F to go back and forth between the `rows` and the `constraints` panels.

Now, there's a menu to navigate between hidden views by just clicking on the desired options:

~~As you may have noticed, navigation has already been added, so every time you query the content of a listed table, the result set is going to be paginated. This allows to the user dealing with large tables, optimizing resources.
Just hit the `BACK` and `NEXT` buttons to go back and forth.~~

The navigation buttons were removed since they are too slow to really navigate the content of a table. The user is better off typing a `SELECT` statement with proper `OFFSET` and `LIMIT`.

The `--db` flag is now optional (except for Oracle), meaning that the user will be able to see the list of databases they have access to. The regular list of tables will be replaced with a tree structure showing a list of databases and their respective list of tables, branching off each database. Due to the nature of the vast majority of DBMSs that don't allow cross-database queries, dblab has to open an independent connection for each database. The side effect of this decision, is that the user has to press `Enter` on the specific database of interest. An indicator showing the current active database will appear at the bottom-right of the screen. To change the focus, just hit enter on another database. Once a database is selected, the usual behavior of inspecting tables remains the same.

### Key Bindings
| Key
|-----------------
|Ctrl+Space
|Enter
|Ctrl+S
|Ctrl+T
|Ctrl+I
|Ctrl+H
|Ctrl+J
|Ctrl+K
|Ctrl+L
|Arrow Up
|k
|Arrow Down
|j
|Arrow Right
|l
|Arrow Left
|h
|g
|G
|Ctrl-F
|Ctrl-B
|Ctrl+c | Description | -----------------------|----------------------------------------| | If the query panel is active, execute the query | | If the tables panel is active, list all the rows as a result set on the rows panel and display the structure of the table on the structure panel | | If the rows panel is active, switch to the schema panel. The opposite is true | | If the rows panel is active, switch to the constraints view. The opposite is true | | If the rows panel is active, switch to the indexes view. The opposite is true | | Toggle to the panel on the left | | Toggle to the panel below | | Toggle to the panel above | | Toggle to the panel on the right | | Vertical scrolling on the panel. Views: rows, table, constraints, structure and indexes | | Vertical scrolling on the panel. Views: rows, table, constraints, structure and indexes | | Vertical on the panel. Views: rows, table, constraints, structure and indexes | | Vertical on the panel. Views: rows, table, constraints, structure and indexes | | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes | | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes | | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes | | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes | | Move cursor to the top of the panel's dataset. Views: rows, constraints, structure and indexes | | Move cursor to the bottom of the panel's dataset. Views: rows, constraints, structure and indexes | | Move down by one page. Views: rows, constraints, structure and indexes | | Move up by one page. Views: rows, constraints, structure and indexes | | Quit |

## Contribute

- Fork this repository
- Create a new feature branch for a new functionality or bugfix
- Commit your changes
- Execute test suite
- Push your code and open a new pull request
- Use [issues](https://github.com/danvergara/dblab/issues) for any questions
- Check [wiki](https://github.com/danvergara/dblab/wiki) for extra documentation

## License
The MIT License (MIT). See [LICENSE](LICENSE) file for more details.