[Português](README.pt-BR.md)
# mariadb-cli
[](https://crates.io/crates/mariadb-cli)
[](https://docs.rs/mariadb-cli)
[](#license)
[](#msrv)
## What it is
- `mariadb-cli` reads 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`, `tsv` and `text`
### 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 `config` commands
- 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 as `repository` in `Cargo.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 version` to see which crypto provider a binary carries
## MSRV
- The minimum supported Rust version is 1.88
- It is declared as `rust-version` in `Cargo.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 commands` for the command tree
- Run `mariadb-cli meta schema --types` for the type map
- Run `mariadb-cli meta manual` for this binary's manual
- Run `mariadb-cli meta manual --output mariadb-cli.1` to 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 production` to open, confirm and close
- Run `mariadb-cli conn default production` to elect the default destination
### Reading structure and data
- Run `mariadb-cli schema map --database shop` for the compact map
- Run `mariadb-cli schema columns --table orders` to describe one table
- Run `mariadb-cli query run 'SELECT id, total FROM orders LIMIT 10'`
- Run `mariadb-cli query sample --table orders` for the first rows
### Trimming the output
- Use `--select` to keep only the columns that matter
- Use `--limit` to cap the number of rows emitted
- Use `--output-format ndjson` to consume one row at a time
- Use `--output file.json` to write the result to disk
## The exit numbers
- Read the number before you read the output
- `0` means success
- `2` means you used the tool itself incorrectly, and retrying never helps
- `3` means validation refused the command, and retrying never helps
- `4` means the configuration is missing or invalid, and retrying never helps
- `5` means the network was unreachable, and retrying may help
- `6` means authentication was refused, and retrying never helps
- `7` means the permission was insufficient, and retrying never helps
- `8` means the object was not found, and retrying never helps
- `9` means a lock conflict, a deadlock or a constraint, and retrying may help
- `10` means a size, row or packet limit was reached, and retrying never helps
- `11` means the server returned an error, and repeatability depends on its class
- `124` means the time limit was reached, and retrying may help
- `130` means somebody interrupted the invocation with a signal
- `141` means 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 invocation
- `mariadb-cli config set i18n.lang pt-BR` stores 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 bash` to generate the script
- The supported shells are `bash`, `zsh`, `fish`, `elvish` and `powershell`
- Name yours in place of `bash`
- Each shell has its own file location and its own loading rule
- `docs/CROSS_PLATFORM.md` says 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.md` is 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.txt` is the short map of this repository for a reading agent
- `llms-full.txt` is the same map with the reasoning kept
- The usage guides live in `docs/`, each with its `.pt-BR` mirror
- `docs/schemas/` carries one JSON Schema per command, generated from the binary
- `docs/schemas/README.md` indexes them and states what the envelope carries
- `README.pt-BR.md` says 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