Settings and Files

The Settings window

Cmd/Ctrl+, opens Settings. Changes apply right away.

A second pane, Appearance, sets the theme, the text, and how the grids and the connection bar are drawn. Each change shows in every open window at once, and in the preview under the options: two rows of a table under the bar of a dev connection, drawn as the grid and the bar are. Its rows are made in the app, so it needs no connection and reads no database.

A third pane, Editor, sets how the SQL editor runs and types. Every open SQL editor follows each change at once.

The other keys of the four [editor.…] tables are read and kept now, and take effect in a later version.

On macOS and Windows the Editor pane’s Clear history… deletes the history of every connection, once you say so; a History tab’s own clears its connection’s alone.

A fourth pane, Agents, sets what the [mcp] keys hold, and shows how to connect an agent: Agents is the guide.

On macOS and Windows the window shows where the settings file is, and can reveal it in your file manager, export it, or reset the options of the pane it shows (on the Editor pane, every key of the [editor.…] tables). On the Agents pane, a reset leaves the server’s switch as it is. In the Omarchy look the file is shown beside the options.

The settings file

Settings are kept in settings.toml, which is safe to edit by hand. Tabletist watches the file and applies your edits while it runs. The file holds only what differs from the defaults. Until you change an option there is no file, and one the app writes starts with a header line. Here is every key at its default (group_digits, theme, font, font_size, zebra, keys, line_numbers and keywords have none of their own: they follow the look):

[startup]
on_launch = "restore"
restore_tabs = true

[data]
page_size = 1000
timestamps = "second"
tz = "system"
value_tags = true

[safety]
production_read_only = true
confirm_close_edits = true
idle_disconnect = "30m"

[sidebar]
show_system_schemas = false

[editor.run]
new_tab = "read-only"
limit = 1000
timeout = "30s"
run = "statement"
confirm_unsafe_writes = true

[editor.typing]
indent = 2
autocomplete = "typing"
close_pairs = true
highlight_line = true
wrap = false

[editor.format]
commas = "trailing"

[editor.history]
keep = 1000

[mcp]
enabled = false
log_days = 30
notify = true

[appearance]
interface_size = "default"

[appearance.grid]
row_height = "regular"
column_types = true
table_list = "tree"

[appearance.env]
bar = "tint"

show_system_schemas is set only in the file, and so is a pin by a name or a path other than the Omarchy theme of the moment, and a font by its fontconfig name. The SQL editor’s Limit and Timeout menus set editor.run.limit and editor.run.timeout, which every open SQL editor follows, and the text size keys (Cmd+= Cmd+- Cmd+0 on macOS, Ctrl+= Ctrl+- Ctrl+0 on Windows, ctrl+= ctrl+- in the Omarchy look) set font_size, wherever the keyboard is.

A line that cannot be read is ignored and reported in the Settings window, and its key keeps its last good value: the one it had before the edit, or its default when Tabletist starts. When you change an option in the app, only its key is written: set back to its default, the key is taken out of the file, and otherwise it gets the new value where it is, or goes at the end of its table. Your comments (but not the one beside startup.on_launch, which is Tabletist’s), the order of your keys, the lines that could not be read and keys Tabletist does not know all stay as you wrote them. The one exception is a table written inline (data = { … }) or with dotted keys (data.page_size = 500): a key added to it or taken out of it writes the whole file again, without your comments. Export… saves a copy of the file as it is.

A file an older version wrote holds every key, at the values it had then, the defaults of that time too (page_size = 300, group_digits = false). Those stay until you change them: take a key out of the file, or reset the tab, to have today’s default. An older file’s editor.sql_limit and editor.sql_timeout_secs are read while the file has no editor.run.limit and editor.run.timeout (a timeout over an hour as an hour), and give way to them the first time you set the limit or the timeout.

Files

Tabletist keeps settings and state in two folders.

On Linux, XDG_CONFIG_HOME and XDG_STATE_HOME move the two folders. An administrator’s policy, managed.toml, is in a third place of its own: The administrator’s policy.

The runtime folder is /run/user/<your user id>/tabletist on Linux, where the system makes /run/user for you, and ~/.local/state/tabletist where it does not, whatever XDG_STATE_HOME says: an agent may start tabletist mcp without your variables. macOS has none, and uses the state folder, or .tabletist in your home folder when the state folder’s path is too long for a socket. Windows has none either, and uses the state folder: the app listens on a named pipe, whose name is new each time agents are turned on, and writes the name there for tabletist mcp to find.

Passwords are kept in the system keyring, never in these files. Read about passwords.

The connections file

Saved connections are kept in connections.toml, one [[connections]] table for each.

version = 3

[[connections]]
id          = "6a0c1f0e-5a52-4b7b-9c56-3f0c8f2f7a11"
name        = "Bookshop production"
environment = "production"
read_only   = true
password    = "keyring"
ssh_secret  = "ask"
driver      = "postgres"
host        = "db.example.com"
port        = 5432
user        = "app"
database    = "bookshop_production"
tls         = "verify-full"
ca_file     = "/etc/ssl/bookshop-ca.pem"

[connections.ssh]
host = "bastion.example.com"
port = 2222
user = "deploy"
auth = "key-file"
key  = "/home/ada/.ssh/id_ed25519"

[[connections]]
name        = "Bookshop on disk"
environment = "local"
driver      = "sqlite"
sqlite_path = "/home/ada/bookshop.db"

A tunnel is the connection’s [connections.ssh] table: host, and optionally port and user, auth (password, key-file or agent), and with key-file the key to use.

What agents may do on a connection is its [connections.agents] table: access (off or read), rows, the most rows of an answer (1 to 5000), and timeout_secs, how long a statement may run (1 to 60). Without the table, or a key of it, a connection is off, with 500 rows and 10 seconds.

The table can also say which tables agents may not read, with one of two lists:

[connections.agents]
access = "read"
hidden = ["customers", "sales.orders"]

hidden names the tables agents may not read, and every other one they may. only names the tables they may read, and no others, the ones made later included: only = [] hides every table. A name without a schema is that table in every schema, and a name with a dot or a double quote in it is written in double quotes, with the quote doubled: sales."q1.orders". A view over a hidden table is hidden with it, and so are a partition and a child table of one. While anything is hidden, agents may not read the system catalogs either (information_schema, pg_catalog, mysql, sqlite_schema and the rest). If a table that hidden names is renamed or dropped, agents may not use the connection at all until you take the name out of the list or put the right one in.

masked names the columns whose values agents get as •••, every value, an empty one too:

[connections.agents]
access = "read"
masked = ["orders.email", "sales.customers.phone"]

An entry is a table and a column, or a schema, a table and a column, each part written as in hidden. One without a schema is that column of the table of that name in every schema. Agents may select a masked column as it is, and may not filter, join, sort, group or compute on it, nor on any column of the same name in any table. A view that reads one is refused, and so is any view over its table on MySQL. Its partitions and child tables have it masked too, and so does a generated column of its table. If a column that masked names is renamed or dropped, agents may not use the connection at all until you take it out of the list or put the right one in.

A file in which a connection masks a column says version = 6, one in which a connection hides a table and masks none says version = 5, one in which a connection has the table and neither hides nor masks says version = 4, and one in which none has it stays version = 3. Agents use the table only while [mcp] enabled is true in settings.toml. Stop agents here, in a connection’s Agents tab, stops the agents working on it and sets its access to off, so that an agent that connects again does not see it.

Agent access changed outside Tabletist

A change to either file that lets agents do more than Tabletist last showed you is not applied at once: turning [mcp] enabled on, a connection’s access up from off, a connection hiding less (a name taken out of hidden or put into only, or a hidden list made an only one), or a connection masking less: a name taken out of masked, or one that named a column in every schema made to name it in one. Tabletist says what changed in a bar under the top of the window, and until you answer, agents may do what they could before. Keep applies the change. Put back undoes it in the files: it turns [mcp] enabled off, sets the connection’s access back to off, or puts its tables or its masked columns back as they were, and leaves your other settings and connections as they are. While a name taken out of masked is held, a column put into it at the same time is masked at once. A change that lets agents do less applies at once.

Turning agents on in Tabletist itself, with Turn on in a connection’s Agents tab or the switch in Settings › Agents, is never held. Tabletist keeps what it showed you in agents_shown.json. Without that file, the first time a version with this check starts, whatever you turned on by hand is held once.

Edit the file while Tabletist is closed. Tabletist writes the whole file again when you change a connection, so a comment you add is not kept.

Tabletist reads the file strictly. A key it does not know, or a value a key cannot have, is an error and not something it skips: a line such as read_onyl = true must not pass for a connection that may write. When the file cannot be read, Tabletist starts with no connections, says which line is wrong, and keeps the file beside itself as connections.toml.bad (or .bad.1 when that name is taken: the notice says which). Fix the line and rename the file back. When each connection last connected is kept. What Tabletist says of the line never repeats a value written on it.

Until you rename the file back or remove it, every start says that it is there, and loads no connection.

Versions before this one kept the connections in connections.json. Tabletist reads that file once, at the first start that finds no connections.toml, writes the two files above from it, tells you, and leaves it where it is. If the old file itself cannot be read, it is kept aside in the same way and nothing is written for it, so it is read again once it is mended.

At the next start, which finds connections.toml, Tabletist notes in its state folder that the connections have moved (connections.moved). From then on connections.json is not read again, whatever becomes of the new file: the connections of the day they moved do not come back in place of a connections.toml that was kept aside or removed. To have the old file read once more, remove connections.moved as well.

The administrator’s policy

An administrator can set limits that nobody else on the computer can raise, in managed.toml. It is kept where only an administrator can write, and no variable moves it:

The file is a floor under your own settings. Each of its limits is combined with yours, and the stricter one is in force. Nothing in settings.toml or connections.toml can lift it, and nothing of it is written into them: when a rule is removed, you have your own settings back. A coding agent runs as you and can edit your files, so this is the one limit it cannot undo, as long as it cannot act as an administrator.

version = 1

[agents]
allowed = true           # false: agents cannot be turned on
log_days_min = 90        # the log of agents' calls keeps a call at least this long

[[rules]]
name = "Bookshop production"
match = { driver = "postgres", host = "db.example.com", database = "bookshop_*" }
read_only = true
access_max = "read"
rows_max = 500
timeout_max_secs = 10
hidden = ["customers"]
masked = ["orders.email"]

[[rules]]
name = "Analytics replica"
match = { driver = "postgres", host = "replica.example.com" }
visible_only = ["books", "authors", "orders"]

[[rules]]
name = "Shared files"
match = { driver = "sqlite", path = "/srv/shared/*.db" }
access_max = "off"

A rule matches a connection by what it reaches. Each key in match must match, and * in it stands for any run of characters. host is compared without regard to case, and through an SSH tunnel it is the database’s host. path is a SQLite file’s, with ~ read as your home folder. A key the connection has no use for, such as path on PostgreSQL, does not match. Every rule that matches a connection applies.

A rule’s tables and columns apply beside your own. A table is visible to agents only if your Tables setting and every matching rule let it be seen, so two visible_only lists leave the tables both name. A column is masked if you or any matching rule masks it. A view over a hidden table is hidden with it, as with your own.

An entry in hidden or masked that names nothing in the database closes the connection to agents, as yours does: a table that was renamed is hidden by nothing under its new name. A rule may match several databases, and each must have what it names. An entry in visible_only that names nothing hides more, and stops nothing.

When a rule is why an agent is refused, it is told so, with the same code as for your own settings: “customers is hidden for agents by your administrator’s policy.”, or, for a stale entry, “Agents may not use this connection until your administrator’s policy is fixed.”, which names no entry. list_connections gives each rule’s entries apart from yours, under administrator, without the rule’s name.

The file is read when Tabletist starts. The connection editor and Settings show your own settings, not the administrator’s limits.

Tabletist reads the file strictly. A key it does not know, a value a key cannot have, or a version other than 1 makes the whole file unreadable, and then, until it is mended, agents are off and every connection is read-only. Tabletist says so under the top of the window, with the line, and never repeats a value written on it. A file that is not there is no policy.

Command-line options

--help also lists --demo-shot, which saves a picture of the demo’s window to a file, and --demo-size, which sets that window’s size.