From 1a8f48201c99c8bee514d9909e5f6a784bf11b35 Mon Sep 17 00:00:00 2001 From: Thomas Roten Date: Fri, 22 Dec 2017 21:03:27 -0600 Subject: [PATCH 1/3] Add commands and prompt pages. --- content/pages/3.docs.md | 13 ++- content/pages/commands.md | 170 ++++++++++++++++++++++++++++++++++++++ content/pages/prompt.md | 39 +++++++++ 3 files changed, 220 insertions(+), 2 deletions(-) create mode 100644 content/pages/commands.md create mode 100644 content/pages/prompt.md diff --git a/content/pages/3.docs.md b/content/pages/3.docs.md index 42e1197..1e1fa5f 100644 --- a/content/pages/3.docs.md +++ b/content/pages/3.docs.md @@ -21,6 +21,11 @@ Showcase of various color themes: [Gallery]({filename}/pages/syntax.md) +## [Commands]({filename}/pages/commands.md) + +Mycli has an assortment of commands to help you as you interact with a +database. + ## [Keybindings]({filename}/pages/keybindings.md) There are two types of keybindings available. Emacs mode and Vi mode. The keybindings can be changed via the config file (~/.myclirc) or toggled via F4 key. @@ -47,7 +52,7 @@ Use the `\e` command in the prompt, to launch the default editor. ## [Multi-line mode]({filename}/pages/multi-line.md) -`Mycli` doesn't expect a semi-colon at the end of a line to execute the query. But this can be changed by setting the multi-line mode. +Mycli doesn't expect a semi-colon at the end of a line to execute the query. But this can be changed by setting the multi-line mode. [Read more...]({filename}/pages/multi-line.md) @@ -70,5 +75,9 @@ When working with multiple servers, it is possible to store their connection par ## [Pager Output]({filename}/pages/pager.md) -`Mycli` uses pager programs to make it easier to view large result sets. This +Mycli uses pager programs to make it easier to view large result sets. This can be configured or disabled. + +## [Prompt]({filename}/pages/prompt.md) + +Mycli has a configurable prompt. diff --git a/content/pages/commands.md b/content/pages/commands.md new file mode 100644 index 0000000..646b159 --- /dev/null +++ b/content/pages/commands.md @@ -0,0 +1,170 @@ +Title: Commands +Slug: commands +status: hidden + +## Introduction + +Mycli sends most input you enter to the MySQL server as a SQL statement. There +is also a set of commands that mycli will accept. To see these, type `help` or +`\?` at the prompt: + +``` +mycli> help ++-------------+----------------------------+------------------------------------------------------------+ +| Command | Shortcut | Description | ++-------------+----------------------------+------------------------------------------------------------+ +| \G | \G | Display current query results vertically. | +| \dt | \dt[+] [table] | List or describe tables. | +| \e | \e | Edit command with editor (uses $EDITOR). | +| \f | \f [name [args..]] | List or execute favorite queries. | +| \fd | \fd [name] | Delete a favorite query. | +| \fs | \fs name query | Save a favorite query. | +| \l | \l | List databases. | +| \once | \o [-o] filename | Append next result to an output file (overwrite using -o). | +| \timing | \t | Toggle timing of commands. | +| connect | \r | Reconnect to the database. Optional database argument. | +| exit | \q | Exit. | +| help | \? | Show this help. | +| nopager | \n | Disable pager, print to stdout. | +| notee | notee | Stop writing results to an output file. | +| pager | \P [command] | Set PAGER. Print the query results via PAGER. | +| prompt | \R | Change prompt format. | +| quit | \q | Quit. | +| rehash | \# | Refresh auto-completions. | +| source | \. filename | Execute commands from file. | +| status | \s | Get status information from the server. | +| system | system [command] | Execute a system shell commmand. | +| tableformat | \T | Change the table format used to output results. | +| tee | tee [-o] filename | Append all results to an output file (overwrite using -o). | +| use | \u | Change to a new database. | +| watch | watch [seconds] [-c] query | Executes the query every [seconds] seconds (by default 5). | ++-------------+----------------------------+------------------------------------------------------------+ +``` + +Most commands have a long and short form. Most of the commands are +case sensitive. Commands may be followed by an optional semicolon. + +* `\G` + + Send the current statement to the server and display the results vertically. + This is used instead of a semicolon terminator, e.g. `select 1\G`. + +* `\dt`, `\dt[+] [table]` + + List the tables in the default database (when used without any parameters). + Describe a table (when passed a parameter). + + The optional `+` verbose indicator can be used to toggle whether or not the `CREATE TABLE` statement for the table is shown. + + The `\dt` commands are equivalent to running `SHOW TABLES`, `SHOW COLUMNS FROM + [table_name]`, and `SHOW CREATE TABLE [table_name]`. + +* `\e` + + Edit the current statement with an editor (uses the environment variable `$EDITOR`). + If this is entered without a current query, it will populate the editor + with the previous query. + +* `\f`, `\f [name] [args..]` + + List or execute favorite queries. If the favorite query requires parameters, + they can be passed to the query after the name, e.g., `\f users_by_name + "Teddy Roosevelt"`. See [Favorite Queries]({filename}/pages/favorites.md) for more information. + +* `\fd [name]` + + Delete a favorite query. + +* `\fs [name] [query]` + + Save a favorite query. Favorite queries support shell-style parameter + substitution. See [Favorite Queries]({filename}/pages/favorites.md) for more information. + +* `\l` + + List the databases on the MySQL server host. This is equivalent to running + `SHOW DATABASES`. + +* `once`, `\o [-o] filename` + + Output the next query's results to an output file. Defaults to + append mode. Use `-o` to overwrite any existing file content. + +* `timing`, `\t` + + Toggle whether or not the time it takes to execute a statement is displayed + below the results. + +* `connect`, `\r` + + Reconnect to the server. You can optionally supply a database name that + will be set as the default database for your connection. + +* `quit`, `exit`, `\q` + + Exit mycli. + +* `help`, `\?`, `?` + + Display a help message listing mycli's commands. + +* `nopager`, `\n` + + Disable the use of pager software for outputting query results. For more + information see the [pager section]({filename}/pages/pager.md) of the + documentation. + +* `notee` + + Disables the output to the tee file. For more information, see the + [`tee` command](#tee). + +* `pager`, `\P [command]` + + Enable the use of a pager for outputting query results. Optionally, + specify a command that will be used as the pager. For more information + see the [pager section]({filename}/pages/pager.md) of the documentation. + +* `prompt`, `\R [format]` + + Change the prompt format. The default is `\t \u@\h:\d> `. See the + [prompt page]({filename}/pages/prompt.md) of the documentation + for more information. + +* `rehash`, `\#` + + Refreshes the cached auto-completion data. This is the list of databases, + tables, columns that auto-complete when you are typing. + +* `source`, `\. [filename]` + + Executes the SQL commands from the named file. + +* `status`, `\s` + + Displays status information about the client machine, server, and + connection you are using. + +* `system`, `system [command]` + + Executes a shell command and outputs the results. + +* `tableformat`, `\T [format]` + + Change the output format. Run the command without specifying a format to + see the possible values. + +* `tee`, `tee [-o] filename` + + Log all queries/commands and their output to `filename`. Defaults to + append mode. Use `-o` to overwrite any existing file content. To disable + this, see the [`notee` command](#notee). + +* `use [db_name]`, `\u [db_name]` + + Use `db_name` as the default database. + +* `watch`, `watch [seconds] [-c] query` + + Repeatedly execute a query every `N` seconds. The default interval is `5` + seconds. `-c` can be used to clear the screen after every iteration. diff --git a/content/pages/prompt.md b/content/pages/prompt.md new file mode 100644 index 0000000..0232c0f --- /dev/null +++ b/content/pages/prompt.md @@ -0,0 +1,39 @@ +Title: Prompt +Slug: prompt +status: hidden + +Mycli provides a configurable prompt. When mycli starts up, +it will use the prompt configuration found in its +[config file]({filename}/pages/config.md). Once mycli is running +up, you can interactively change the prompt by using the +[`prompt` command]({filename}/pages/commands.md#prompt). + +The default prompt looks something like this: `mysql user@localhost:db_name> `. +It is formatted using the following character sequences. +The default format string is `\t \u@\h:\d> `. + +* `\D` - the full current date, e.g. `Fri Dec 20 20:51:56 2015` +* `\d` - database name +* `\h` - hostname of the server +* `\m` - minutes of the current time +* `\n` - a newline +* `\P` - AM/PM +* `\p` - the connetion port +* `\R` - the current time, in 24-hour time (0–23) +* `\r` - the current time, standard 12-hour time (1–12) +* `\s` - seconds of the current time +* `\t` - database type (e.g. Percona, MySQL, MariaDB) +* `\u` - username + +## Additional Configuration + +Mycli's configuration file has an additional prompt-related option +called `prompt_continuation`. This default to `-> `. This means that +when a query spans more than one line, subsequent lines start with +`->`: + +``` +mysql user@localhost:db > SELECT first_name, last_name, date_of_birth + -> FROM users + -> WHERE +``` From ac1417843dee08370ab00535a3a627f56f1ad102 Mon Sep 17 00:00:00 2001 From: Thomas Roten Date: Fri, 22 Dec 2017 21:03:44 -0600 Subject: [PATCH 2/3] Fix python versions. --- content/pages/1.install.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/pages/1.install.md b/content/pages/1.install.md index aa5f7f0..48c1226 100644 --- a/content/pages/1.install.md +++ b/content/pages/1.install.md @@ -3,7 +3,7 @@ Slug: install # Compatibility: -Tested on macOS and Linux. Runs on Python 2.7, 3.3, 3.4, 3.5, and 3.6. +Mycli is tested on macOS and Linux. It runs on Python 2.7 and 3.4+. Works well with unicode input/output. @@ -11,6 +11,7 @@ Works well with unicode input/output. Python 2.6, you'll want to install mycli 1.8.1. + # Python Package: If you already know how to install python packages, then you can do: From 319f48b3f4ff252cc92269db2fd3bee044cf9178 Mon Sep 17 00:00:00 2001 From: Thomas Roten Date: Fri, 22 Dec 2017 21:03:56 -0600 Subject: [PATCH 3/3] Add a v1.14.0 release blog post. --- content/release_1.14.0.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 content/release_1.14.0.md diff --git a/content/release_1.14.0.md b/content/release_1.14.0.md new file mode 100644 index 0000000..5eb1158 --- /dev/null +++ b/content/release_1.14.0.md @@ -0,0 +1,36 @@ +Title: Release v1.14.0 +Date: 2017-12-22 +Category: Blog +Author: Thomas Roten +Tags: python, release, changelog, mysql +Slug: v1.14.0 + +`mycli` is a command line interface for MySQL that includes +auto-completion and syntax highlighting. [Read the install instructions]({filename}/pages/1.install.md) to find out how to get the latest version. + +Mycli 1.14.0 was released on December 22, 2017 and includes these changes: + +## Features + +* Add a [`watch` command]({filename}/pages/commands.md#watch) to repeat a query every `N` seconds (defaults to 5) + (Thanks: [David Caro]). +* Default to unix socket connection if host and port are unspecified. This + simplifies authentication on some systems and matches mysql behaviour. See + the [config documentation]({filename}/pages/config.md) for more information on + specifying connection information. +* Add [positional parameters]({filename}/pages/favorites.md) to favorite queries (Thanks: [Scrappy Soft]). + +## Bug Fixes + +* Fix source command for script in current working directory. (Thanks: [Dick Marinus]). +* Fix issue where the `tee` command did not work on Python 2.7 (Thanks: [Thomas Roten]). + +## Internal changes + +* Drop support for Python 3.3 (Thanks: [Thomas Roten]). +* Merge `_on_completions_refreshed` and `_swap_completer_objects` functions (Thanks: [Dick Marinus]). + +[Thomas Roten]: https://github.com/tsroten +[Scrappy Soft]: https://github.com/scrappysoft +[Dick Marinus]: https://github.com/meeuw +[David Caro]: https://github.com/Terseus