mariadb-cli
What it is
mariadb-clireads and changes MariaDB databases from the command line- It serves AI agents and people who operate a database from a terminal
- Every invocation is born, does the work, and dies
- There is no background service and no connection reused between invocations
- No state survives the end of the process
How it behaves
One shot
- The process opens the connection, does the work, and closes it
- Interrupting an invocation releases the connection before it ends
- Each class of failure ends in a number of its own
A primary channel carrying only data
- The primary channel carries the result and nothing else, in the published shape
- Diagnostics, warnings and progress leave by the auxiliary channel
- The two never mix, so the output always parses
- The default shape is one JSON document per invocation
- The other shapes are
ndjson,tsvandtext
Defence against accidental change
- Every statement travels to the server as a prepared statement
- The server refuses more than one statement per call
- Classification reads the syntax tree, never the first word
- A conditional comment is expanded before the tree is read, because the server runs its body
- Two further defences do not depend on this tool reading the statement correctly
- The first is a restricted credential, granted on the server
- The second is a read-only block, which the server opens around the work
- Inside that block the server itself refuses every change
- A statement escaping classification would still be refused there
Configuration without environment variables
- Every setting is written and read by the
configcommands - No setting is read from the environment of the process
- A command-line flag beats a stored setting
- A stored setting beats the built-in default
- Turning certificate verification off needs the invocation to say so as well
Nothing in a diagnostic carries a secret
- Every line of the auxiliary channel is scrubbed at its destination
- That covers the screen and the rotated file alike
- It covers lines this product did not write, which is most of them while diagnosing
Installation
- The product is a Rust binary, built from this repository
- The repository is
https://github.com/danilo-aguiar-br/mariadb-cli, declared asrepositoryinCargo.toml - Install the published version with
cargo install mariadb-cli - Install from a clone with
cargo install --path .at the repository root - Every build installs with a Rust toolchain alone and needs no C compiler
- The encrypted channel is on by default, in every published combination of features
- Run
mariadb-cli meta versionto see which crypto provider a binary carries
MSRV
- The minimum supported Rust version is 1.88
- It is declared as
rust-versioninCargo.toml, so cargo refuses an older toolchain by name - Raising it is a breaking change and is never done in a patch release
Usage
Discovering the surface
- Run
mariadb-cli meta commandsfor the command tree - Run
mariadb-cli meta schema --typesfor the type map - Run
mariadb-cli meta manualfor this binary's manual - Run
mariadb-cli meta manual --output mariadb-cli.1to write it to a file
Storing a destination
- Run
mariadb-cli conn add production --host db.example --user reader --password-stdin - The password arrives on standard input, never on the command line
- Run
mariadb-cli conn test productionto open, confirm and close - Run
mariadb-cli conn default productionto elect the default destination
Reading structure and data
- Run
mariadb-cli schema map --database shopfor the compact map - Run
mariadb-cli schema columns --table ordersto describe one table - Run
mariadb-cli query run 'SELECT id, total FROM orders LIMIT 10' - Run
mariadb-cli query sample --table ordersfor the first rows
Trimming the output
- Use
--selectto keep only the columns that matter - Use
--limitto cap the number of rows emitted - Use
--output-format ndjsonto consume one row at a time - Use
--output file.jsonto write the result to disk
The exit numbers
- Read the number before you read the output
0means success2means you used the tool itself incorrectly, and retrying never helps3means validation refused the command, and retrying never helps4means the configuration is missing or invalid, and retrying never helps5means the network was unreachable, and retrying may help6means authentication was refused, and retrying never helps7means the permission was insufficient, and retrying never helps8means the object was not found, and retrying never helps9means a lock conflict, a deadlock or a constraint, and retrying may help10means a size, row or packet limit was reached, and retrying never helps11means the server returned an error, and repeatability depends on its class124means the time limit was reached, and retrying may help130means somebody interrupted the invocation with a signal141means the output channel was closed from the other side- A number outside this table does not exist, and a new one becomes a requirement before it appears
Language
- The interface answers in English and in Brazilian Portuguese
--lang <LANG>fixes the language for one invocationmariadb-cli config set i18n.lang pt-BRstores the choice- With neither, the host locale decides
- The language reaches the messages, never the data: a column name is never translated
Shell completions
- Run
mariadb-cli meta completions bashto generate the script - The supported shells are
bash,zsh,fish,elvishandpowershell - Name yours in place of
bash - Each shell has its own file location and its own loading rule
docs/CROSS_PLATFORM.mdsays what each one expects- Never assume one shell's completion directory applies to another
Where the specification lives
-
The full contract is working material and is not published with the crate
-
Annex A publishes the observable command surface
-
Annex B publishes the global flags
-
Annex C publishes the persisted configuration keys
-
Annex D publishes the exit numbers
-
docs/COMMANDS.mdis the reference: all sixty-three commands and every flag each one takes -
It is generated from the binary by
cargo xtask gen-docs, so it describes this build and not an intention -
llms.txtis the short map of this repository for a reading agent -
llms-full.txtis the same map with the reasoning kept -
The usage guides live in
docs/, each with its.pt-BRmirror -
docs/schemas/carries one JSON Schema per command, generated from the binary -
docs/schemas/README.mdindexes them and states what the envelope carries -
README.pt-BR.mdsays all of this in Portuguese
License
- Distributed under MIT or Apache-2.0, at your option
- The grant travels inside the published archive, because the manifest claims those terms