Config File

We know that writing parameters and flags every time you want to connect to a database can be very tedious, so dblab provides the option to create a YAML file with the configuration to connect to the database. You can define multiple database configurations under the database field; just be sure to use different names for each of them.

For this example, we'll be using a PostgreSQL database, so the driver to use would be postgres. Remember that every driver has different args that we can include in the config YAML.

Single database

In order to connect to a local database hosted at 0.0.0.0:5432, we can just copy and paste the following configuration to a file named .dblab.yaml stored either in the root of your current directory, in your $HOME path ($HOME/.dblab.yaml), or in your $XDG_CONFIG_HOME path ($XDG_CONFIG_HOME/.dblab.yaml).

database:
  - name: "local"
    host: "0.0.0.0"
    port: 5432
    db: "postgres"
    password: "postgres"
    user: "postgres"
    driver: "postgres"
    # optional for postgres and oracle
    # if omitted, all accessible schemas are shown
    # schema: "public"
    # optional: set to true to force a read-only session
    readonly: true
limit: 50

The readonly field is optional. When set to true, dblab forces the database session into read-only mode, preventing any write operations (INSERT, UPDATE, DELETE, etc.). This is useful when you want to safely browse a production database. The same can be achieved via the --readonly CLI flag.

Once created, we can launch dblab with the command:

dblab --config

If you don't specify the name of the database configuration with --cfg-name, then dblab will use the first configuration defined under the database field.

Multiple Databases

But, as we all know, on a daily basis we tend to access multiple databases or the "same" database in different environments. So using the --cfg-name flag can be very handy in these cases.

In the following case we have 3 environments: local, staging, and prod. The YAML file would look like this (but with your own credentials):

database:
  - name: "local"
    host: "<LOCAL HOST ADDRESS>"
    port: 5432
    db: "<DB NAME>"
    password: "<PASSWORD>"
    user: "<USERNAME>"
    schema: "public"
    driver: "postgres"
  - name: "staging"
    host: "<STAGING HOST ADDRESS>"
    port: 5432
    db: "<DB NAME>"
    password: "<PASSWORD>"
    user: "<USERNAME>"
    schema: "public"
    driver: "postgres"
  - name: "prod"
    host: "<PROD HOST ADDRESS>"
    port: 5432
    db: "<DB NAME>"
    password: "<PASSWORD>"
    user: "<USERNAM>"
    schema: "public"
    driver: "postgres"
# should be greater than 0, otherwise the app will error out
limit: 50

And in order to launch a specific environment/configuration we have to use the --cfg-name flag, followed by the name of the database configuration.

dblab --config --cfg-name "prod"

Key bindings

Key bindings can also be configured through the .dblab.yaml file. There is a field called keybindings where you can customize the default shortcuts. By default, the keybindings are not loaded from the config file, so you need to use the --keybindings or -k flag to load them.

The bindings are grouped by the part of the UI they belong to — navigation for moving focus between the three panels, editor for the Vim-style query editor, sidebar for the database tree, and resultset for the result set panel — plus help, quit, history and fullscreen at the top level. Because each panel has its own section, you can rebind, say, the editor's jump-to-top key without touching the sidebar's.

Every field has a default, so you only need to list the ones you want to change. The following example spells out all of them:

database:
  - name: "local"
    host: "0.0.0.0"
    port: 5432
    db: "postgres"
    password: "postgres"
    user: "postgres"
    driver: "postgres"
limit: 50
keybindings:
  help: '?'
  quit: 'ctrl+c'
  history: 'alt+h'
  fullscreen: 'alt+f'
  navigation:
    up: 'ctrl+k'
    down: 'ctrl+j'
    left: 'ctrl+h'
    right: 'ctrl+l'
  editor:
    up: 'k'
    down: 'j'
    left: 'h'
    right: 'l'
    line-start: '0'
    line-end: '$'
    go-top: 'g'
    go-bottom: 'G'
    insert: 'i'
    normal: 'esc'
    execute-query: 'ctrl+e'
    execute-single-query: 'ctrl+r'
  sidebar:
    go-top: 'alt+k'
    go-bottom: 'alt+j'
  resultset:
    next-tab: 'tab'
    prev-tab: 'shift+tab'
    line-start: '0'
    line-end: '$'
    go-top: 'g'
    go-bottom: 'G'

To load the keybindings from the config file, run:

dblab --config --keybindings

Warning

If you wrote your config file before the per-panel sections existed, the top-level next-tab, prev-tab, page-top, page-bottom, end-of-line and beginning-of-line fields are no longer read — move them under resultset, sidebar or editor as shown above. See key bindings configuration for the full mapping from the old names to the new ones.