Merge pull request #158 from valerybriz/main

Add initial documentation site for dblab
danvergara · May 11, 2023 · 994fb50 · 994fb50
2 parents e9b3844 + e7148d4
commit 994fb50
Show file tree

Hide file tree

Showing 10 changed files with 436 additions and 0 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,24 @@
+name: Deploy github pages with docs
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ github.ref }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force
diff --git a/.gitignore b/.gitignore
@@ -23,3 +23,6 @@ dblab-build
 
 # Dev binary
 dblab
+
+
+.idea/
diff --git a/docs/contribute.md b/docs/contribute.md
@@ -0,0 +1,7 @@
+- Fork this repository
+- Create a new feature branch for a new functionality or bugfix
+- Commit your changes
+- Execute test suite
+- Push your code and open a new pull request
+- Use [issues](https://github.com/danvergara/dblab/issues) for any questions
+- Check [wiki](https://github.com/danvergara/dblab/wiki) for extra documentation
diff --git a/docs/css/extra.css b/docs/css/extra.css
@@ -0,0 +1,4 @@
+.center {
+    display: block;
+    margin: 0 auto;
+}
diff --git a/docs/features.md b/docs/features.md
@@ -0,0 +1,5 @@
+The key features are:
+
+  * Cross-platform support OSX/Linux/Windows 32/64-bit  
+  * Simple installation (distributed as a single binary)  
+  * Zero dependencies.  
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,69 @@
+# Welcome to **dblab**
+
+![dblab](https://raw.githubusercontent.com/danvergara/dblab/main/assets/gopher-dblab.png){ width="300" : .center }
+
+Cross-platform, zero dependencies, terminal based UI application for your Data Bases.  
+
+![integration tests](https://github.com/danvergara/dblab/actions/workflows/ci.yaml/badge.svg)  ![unit tests](https://github.com/danvergara/dblab/actions/workflows/test.yaml/badge.svg)  [![Release](https://img.shields.io/github/release/danvergara/dblab.svg?label=Release)](https://github.com/danvergara/dblab/releases)
+
+---
+
+**Documentation**: <a href="https://dblab.danvergara.com" target="_blank">https://dblab.danvergara.com</a>
+
+**Source Code**: <a href="https://github.com/danvergara/dblab" target="_blank">https://github.com/danvergara/dblab</a>
+
+---
+
+## Overview
+
+**dblab** is a fast and lightweight interactive terminal based UI application for PostgreSQL, MySQL and SQLite3, written in Go and works on OSX, Linux and Windows machines.   
+
+The main idea behind using Go for backend development is to utilize the ability of the compiler to produce zero-dependency binaries for multiple platforms. 
+
+dblab was created as an attempt to build a very simple and portable application to interact with local or remote PostgreSQL/MySQL/SQLite3 databases.  
+
+The key features are:
+
+  * Cross-platform support OSX/Linux/Windows 32/64-bit  
+  * Simple installation (distributed as a single binary)  
+  * Zero dependencies.  
+
+## Installation
+
+{--if you need to work with SQLite3, install the CGO enabled binary using the proper bash script listed below.--}
+
+{==
+
+The above comment is deprecated and CGO is not needed anymore.   
+There will be a single binary capable to deal with all supported clients.
+
+==}
+
+### Homebrew installation
+
+It works with Linux too.
+
+```
+$ brew install danvergara/tools/dblab
+```
+
+Or
+
+```
+$ brew tap danvergara/tools
+$ brew install dblab
+```
+
+### Manual Binary Installation
+The binaries are compatible with Linux, OSX and Windows.  
+You can manually download and install the binary release from [the release page](https://github.com/danvergara/dblab/releases).
+
+### Automated installation/update
+> Don't forget to always verify what you're piping into bash
+
+Install the binary using our bash script:
+
+```sh
+curl https://raw.githubusercontent.com/danvergara/dblab/master/scripts/install_update_linux.sh | bash
+```
+
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -0,0 +1,85 @@
+### Using flags
+
+You can start the app without passing flags or parameters, so then an interactive command prompt will ask for the connection details.  
+
+![Alt Text](https://raw.githubusercontent.com/danvergara/dblab/main/screenshots/dblab-default-form.gif){ width="500" : .center }
+
+Otherwise, you can explicitly include the connection details using multiple parameters:
+
+```sh
+$ dblab --host localhost --user myuser --db users --pass password --ssl disable --port 5432 --driver postgres --limit 50
+$ dblab --db path/to/file.sqlite3 --driver sqlite
+```
+
+Connection URL scheme is also supported:
+
+```sh
+$ dblab --url postgres://user:password@host:port/database?sslmode=[mode]
+$ dblab --url mysql://user:password@tcp(host:port)/db
+$ dblab --url file:test.db?cache=shared&mode=memory
+```
+
+if you're using PostgreSQL, you have the option to define the schema you want to work with, the default value is `public`.
+
+```sh
+$ dblab --host localhost --user myuser --db users --pass password --schema myschema --ssl disable --port 5432 --driver postgres --limit 50
+$ dblab --url postgres://user:password@host:port/database?sslmode=[mode] --schema myschema
+```
+
+As a request made in [#125](https://github.com/danvergara/dblab/issues/125), support for MySQL/MariaDB sockets was integrated.
+
+```sh
+$ dblab --url "mysql://user:pasword@unix(/path/to/socket/mysql.sock)/dbname?charset=utf8"
+$ dblab --socket /path/to/socket/mysql.sock --user user --db dbname --pass password --ssl disable --port 5432 --driver mysql --limit 50
+```
+
+For more information about the available flags check the [Usage section](https://dblab.danvergara.com/usage/#usage).
+
+### Using a config file
+
+
+```sh
+# default: test
+$ dbladb --config
+
+$ dblab --config --cfg-name "prod"
+```
+
+`.dblab.yaml` example:
+
+```yaml
+database:
+  - name: "test"
+    host: "localhost"
+    port: 5432
+    db: "users"
+    password: "password"
+    user: "postgres"
+    driver: "postgres"
+    # optional
+    # postgres only
+    # default value: public
+    schema: "myschema"
+  - name: "prod"
+    # example endpoint
+    host: "mydb.123456789012.us-east-1.rds.amazonaws.com"
+    port: 5432
+    db: "users"
+    password: "password"
+    user: "postgres"
+    schema: "public"
+    driver: "postgres"
+# should be greater than 0, otherwise the app will error out
+limit: 50
+```
+
+Or for sqlite:
+
+```yaml
+database:
+  - name: "prod"
+    db: "path/to/file.sqlite3"
+    driver: "sqlite"
+```
+
+Only the `host` and `ssl` fields are optionals. `127.0.0.1` and `disable`, respectively.
diff --git a/docs/release-notes.md b/docs/release-notes.md
@@ -0,0 +1,3 @@
+You can find the updated release notes in the following link:  
+
+[https://github.com/danvergara/dblab/releases](https://github.com/danvergara/dblab/releases)
diff --git a/docs/usage.md b/docs/usage.md
@@ -0,0 +1,177 @@
+You can get started by using the connection flags or by using a configuration file with the connection params.
+
+```sh
+$ dblab [flags] 
+
+```
+
+or
+
+```sh
+$ dblab [command]
+
+```
+
+### Available Commands                               
+
+|         `help`         |    Help about any command    | 
+|:----------------------:|:----------------------------:|
+|       `version`        |  The version of the project  |
+
+### Flags
+
+|       Flag       |    Type     | Description                                                                                                                       |
+|:----------------:|:-----------:|:----------------------------------------------------------------------------------------------------------------------------------|
+|   `--cfg-name`   |  `string`   | Database config name section                                                                                                      |
+|    `--config`    |             | Get the connection data from a config file (default is $HOME/.dblab.yaml or the current directory)                                |
+|      `--db`      |  `string`   | Database name                                                                                                                     |
+|    `--driver`    |  `string`   | Database driver                                                                                                                   |
+|   `-h, --help`   |             | help for dblab                                                                                                                    |
+|     `--host`     |  `string`   | Server host name or IP                                                                                                            |
+|    `--limit`     |    `int`    | Size of the result set from the table content query (should be greater than zero, otherwise the app will error out) (default 100) |
+|     `--pass`     |  `string`   | Password for user                                                                                                                 |
+|     `--port`     |  `string`   | Server port                                                                                                                       |
+|    `--schema`    |  `string`   | Database schema (postgres only)                                                                                                   |
+|    `--socket`    |  `string `  | Path to a Unix socket file                                                                                                        |
+|     `--ssl`      |  `string`   | SSL mode                                                                                                                          |
+|   `-u, --url`    |  `string`   | Database connection string                                                                                                        |
+|     `--user`     |  `string`   | Database user                                                                                                                     |
+
+Use `dblab [command] --help` for more information about a command.
+
+
+## Navigation
+
+If the query panel is active, type the desired query and press <kbd>Ctrl+Space</kbd> to see the results on the rows panel below.
+Otherwise, you might me located at the tables panel, then you can navigate by using the arrows <kbd>Up</kbd> and <kbd>Down</kbd> (or the keys <kbd>k</kbd> and <kbd>j</kbd> respectively).  
+
+If you want to see the rows of a table, press <kbd>Enter</kbd>.  
+
+To see the schema of a table, locate yourself on the `rows` panel and press <kbd>Ctrl+S</kbd> to switch to the `structure` panel, then switch <kbd>Ctrl+S</kbd> to switch back.  
+
+The same can be achieved for the `constraints` view by pressing <kbd>Ctrl+F</kbd> to go back and forth between the `rows` and the `constraints` panels.
+
+Now, there's a menu to navigate between hidden views by just clicking on the desired options:
+
+![Alt Text](https://raw.githubusercontent.com/danvergara/dblab/main/screenshots/rows-view.png){ width="700" : .center }
+![Alt Text](https://raw.githubusercontent.com/danvergara/dblab/main/screenshots/structure-view.png){ width="700" : .center }
+![Alt Text](https://raw.githubusercontent.com/danvergara/dblab/main/screenshots/constraints-view.png){ width="700" : .center }
+![Alt Text](https://raw.githubusercontent.com/danvergara/dblab/main/screenshots/indexes-view.png){ width="700" : .center }
+
+As you may have noticed, navigation has already been added, so every time you query the content of a listed table, the result set is going to be paginated. This allows to the user dealing with large tables, optimizing resources.
+Just hit the `BACK` and `NEXT` buttons to go back and forth.
+
+### Key Bindings
+Key                                     | Description
+----------------------------------------|---------------------------------------
+<kbd>Ctrl+Space</kbd>                   | If the query panel is active, execute the query
+<kbd>Enter</kbd>                        | If the tables panel is active, list all the rows as a result set on the rows panel and display the structure of the table on the structure panel
+<kbd>Ctrl+S</kbd>                       | If the rows panel is active, switch to the schema panel. The opposite is true
+<kbd>Ctrl+F</kbd>                       | If the rows panel is active, switch to the constraints view. The opposite is true
+<kbd>Ctrl+I</kbd>                       | If the rows panel is active, switch to the indexes view. The opposite is true
+<kbd>Ctrl+H</kbd>                       | Toggle to the panel on the left
+<kbd>Ctrl+J</kbd>                       | Toggle to the panel below
+<kbd>Ctrl+K</kbd>                       | Toggle to the panel above
+<kbd>Ctrl+L</kbd>                       | Toggle to the panel on the right
+<kbd>Arrow Up</kbd>                     | Next row of the result set on the panel. Views: rows, table, constraints, structure and indexes
+<kbd>k</kbd>                            | Next row of the result set on the panel. Views: rows, table, constraints, structure and indexes
+<kbd>Arrow Down</kbd>                   | Previous row of the result set on the panel. Views: rows, table, constraints, structure and indexes
+<kbd>j</kbd>                            | Previous row of the result set on the panel. Views: rows, table, constraints, structure and indexes
+<kbd>Arrow Right</kbd>                  | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes
+<kbd>l</kbd>                            | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes
+<kbd>Arrow Left</kbd>                   | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes
+<kbd>h</kbd>                            | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes
+<kbd>Ctrl+c</kbd>                       | Quit
+
+
+## Connection Examples
+
+You can start the app without passing flags or parameters, so then an interactive command prompt will ask for the connection details.  
+
+![Alt Text](https://raw.githubusercontent.com/danvergara/dblab/main/screenshots/dblab-default-form.gif){ width="500" : .center }
+
+Otherwise, you can explicitly include the connection details using multiple parameters:
+
+```sh
+$ dblab --host localhost --user myuser --db users --pass password --ssl disable --port 5432 --driver postgres --limit 50
+$ dblab --db path/to/file.sqlite3 --driver sqlite
+```
+
+Connection URL scheme is also supported:
+
+```sh
+$ dblab --url postgres://user:password@host:port/database?sslmode=[mode]
+$ dblab --url mysql://user:password@tcp(host:port)/db
+$ dblab --url file:test.db?cache=shared&mode=memory
+```
+
+if you're using PostgreSQL, you have the option to define the schema you want to work with, the default value is `public`.
+
+```sh
+$ dblab --host localhost --user myuser --db users --pass password --schema myschema --ssl disable --port 5432 --driver postgres --limit 50
+$ dblab --url postgres://user:password@host:port/database?sslmode=[mode] --schema myschema
+```
+
+As a request made in [#125](https://github.com/danvergara/dblab/issues/125), support for MySQL/MariaDB sockets was integrated.
+
+```sh
+$ dblab --url "mysql://user:pasword@unix(/path/to/socket/mysql.sock)/dbname?charset=utf8"
+$ dblab --socket /path/to/socket/mysql.sock --user user --db dbname --pass password --ssl disable --port 5432 --driver mysql --limit 50
+```
+
+### Configuration
+
+Entering the parameters and flags every time you want to use it is tedious, 
+so `dblab` provides a couple of flags to help with it: `--config` and `--cfg-name`.
+
+`dblab` is going to look for a file called `.dblab.yaml`. For now, the only two places where you can drop a config file are $HOME ($HOME/.dblab.yaml) and the current directory where you run the command line tool.  
+
+If you want to use this feature, `--config` is mandatory and `--cfg-name` may be omitted. The config file can store one or multiple database connection sections under the `database` field. `database` is an array, previously was an object only able to store a single connection section at a time. 
+
+We strongly encourgae you to adopt the new format as of `v0.18.0`. `--cfg-name` takes the name of the desired database section to connect with. It can be omitted and its default values will be the first item on the array.
+
+```sh
+# default: test
+$ dbladb --config
+
+$ dblab --config --cfg-name "prod"
+```
+
+`.dblab.yaml` example:
+
+```yaml
+database:
+  - name: "test"
+    host: "localhost"
+    port: 5432
+    db: "users"
+    password: "password"
+    user: "postgres"
+    driver: "postgres"
+    # optional
+    # postgres only
+    # default value: public
+    schema: "myschema"
+  - name: "prod"
+    # example endpoint
+    host: "mydb.123456789012.us-east-1.rds.amazonaws.com"
+    port: 5432
+    db: "users"
+    password: "password"
+    user: "postgres"
+    schema: "public"
+    driver: "postgres"
+# should be greater than 0, otherwise the app will error out
+limit: 50
+```
+
+Or for sqlite:
+
+```yaml
+database:
+  - name: "prod"
+    db: "path/to/file.sqlite3"
+    driver: "sqlite"
+```
+
+Only the `host` and `ssl` fields are optionals. `127.0.0.1` and `disable`, respectively.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -23,3 +23,6 @@ dblab-build

		# Dev binary
		dblab


		.idea/
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		You can find the updated release notes in the following link:

		[https://github.com/danvergara/dblab/releases](https://github.com/danvergara/dblab/releases)