mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation

Português

mariadb-cli

crates.io docs.rs 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