Configuration

vi-sql stores all configuration in ~/.config/vi-sql/config.yaml. The file is created with defaults on first launch. Run vi-sql --paths to print the exact path on your system.

Full example

yaml

log:
  path: /tmp/vi-sql.log
  level: info
  prettyPrint: true
 
editor:
  env: EDITOR
  command: ""
  enabled: false
 
ui:
  vimMode: false
  mouse: true
  schemaPanelWidth: 30
 
styles:
  currentStyle: default.yaml
  nerdFont: true
 
mcp:
  enabled: false
  port: 9741
  allowRead: false
  allowWrite: false
 
security:
  method: keyring
 
showConnectionPage: true
currentConnection: mydb
 
connections:
  - name: mydb
    driver: postgres
    host: localhost
    port: 5432
    database: mydb
    username: user
    password: ""
    sslMode: disable
    timeout: 30
    options:
      alwaysConfirmActions: true
      limit: 1000

`log`

Field	Default	Description
`path`	`/tmp/vi-sql.log`	Path to the log file
`level`	`info`	Log level: `trace`, `debug`, `info`, `warn`, `error`
`prettyPrint`	`true`	Human-readable log output

`editor`

External editor integration for the terminal SQL editor (Ctrl+e).

Field	Default	Description
`env`	`EDITOR`	Environment variable to read the editor command from
`command`	—	Editor command to use directly (takes precedence over `env`)
`enabled`	`false`	Enable `$EDITOR` integration; built-in editor is always available

`ui`

Field	Default	Description
`vimMode`	`false`	Use vim-style keybindings (`hjkl`, `gg`, `dd`, `yy`). See Vim Mode
`mouse`	`true`	Enable mouse support
`schemaPanelWidth`	`30`	Width of the schema tree panel in columns

`styles`

Field	Default	Description
`currentStyle`	`default.yaml`	Theme file name from `~/.config/vi-sql/styles/`. See Themes
`nerdFont`	`true`	Use Nerd Font icons. Set to `false` if your terminal font lacks them

`mcp`

Field	Default	Description
`enabled`	`false`	Start the MCP HTTP server when vi-sql connects to a database
`port`	`9741`	Port the MCP server listens on (`127.0.0.1:<port>`)
`allowRead`	`false`	Permit AI tools to run SELECT / EXPLAIN queries
`allowWrite`	`false`	Permit AI tools to run INSERT / UPDATE / DELETE / DDL (also requires `allowRead: true`)

See MCP Server for setup instructions.

`security`

Controls how connection passwords are encrypted at rest.

Field	Default	Description
`method`	`keyring`	Encryption method — see below

Methods

Method	Description
`keyring`	OS secret service (GNOME Keyring, macOS Keychain, Windows Credential Manager). The key is generated automatically and never stored on disk in plaintext.
`master`	Derive an encryption key from a passphrase via Argon2id. You are prompted for the passphrase on every launch.
`env`	Read the key from the `VI_SQL_SECRET_KEY` environment variable. Useful for scripts and CI.
`off`	Passwords stored in plaintext in `config.yaml`. A warning is shown for each affected connection.

The keyringService and keyringAccount fields under security can be set to override the default keyring entry names, but are normally left unset.

To generate a random key for env mode:

vi-sql --gen-key

To reset a forgotten master password (clears all master-encrypted passwords):

vi-sql --reset-master-password

`connections`

A list of saved database connection profiles.

Field	Description
`name`	Display name — used in the connection picker and with `--connection-name`
`driver`	`postgres` (default), `mysql`, `mariadb`, `cockroachdb`, or `sqlite`
`dsn`	Full connection string. If set, individual fields below are ignored. A value starting with `$` is expanded as an environment variable (e.g. `$DATABASE_URL`)
`host`	Database hostname or IP
`port`	Database port
`database`	Database name
`username`	Username
`password`	Password — encrypted at rest according to `security.method`
`sslMode`	SSL mode (postgres: `disable`/`require`/`verify-ca`/`verify-full`; mysql/mariadb: `true`/`false`)
`timeout`	Connection timeout in seconds
`options.alwaysConfirmActions`	Prompt before executing deletes and updates (default `true`)
`options.limit`	Default row limit for table queries

Environment variable DSN

If your connection string is in an environment variable, set dsn to the variable reference:

yaml

connections:
  - name: prod
    driver: postgres
    dsn: $DATABASE_URL

Other top-level fields

Field	Default	Description
`showConnectionPage`	`true`	Open the connection picker on launch instead of reconnecting to `currentConnection`
`currentConnection`	—	Name of the last-used connection