--- a/doc/dbtables.txt	Tue Mar 10 20:25:15 2026 -0400
+++ b/doc/dbtables.txt	Wed Mar 11 08:53:55 2026 -0400
@@ -1,22 +1,169 @@
-*dbtables.txt*    Simple example Vim plugin
+*dbtables.txt*   Database interaction in Vim
 
 INTRODUCTION                                        *dbtables*
 
-dbtables is a minimal example plugin.
+dbtables is a small plugin to interact with a database from Vim:
+- Browse tables in a dedicated window
+- Execute SQL from the current buffer (normal and visual mode)
+- Open a DB console
+- Manage query history and snippets
+
+It is intended as a lightweight helper for SQL work inside Vim.
+
+INSTALLATION                                       *dbtables-install*
+
+Using vim-plug, add the following to your vimrc/init.vim:
+
+    Plug '/home/lsitas/repos/vim_plugins/dbtables'
+
+Then run:
+
+    :PlugInstall
 
 USAGE                                              *dbtables-usage*
 
-    :DbtablesGreet
-        Echo a greeting message. You can customize it with
-        g:dbtables_greeting:
+The plugin defines the following user commands and mappings.
+
+COMMANDS                                           *dbtables-commands*
+
+                                                    *:DBTables*
+:DBTables
+    Open the database tables window. Selecting a table can show
+	the schema of the table or all the data in the table.
+
+                                                    *:DBConsole*
+:DBConsole
+    Opens a console for interacting with the database. 
+
+                                                    *:ExecuteSQL*
+:ExecuteSQL
+    Execute the SQL query from the current buffer. If there are
+	query parameters included, the user will be prompted to 
+	fill them in. 
+	
+	Example:
+	"""
+	SELECT
+		id,
+		name
+	FROM 
+		my_table
+	WHERE 
+		id > :min_id;
+	"""
+	
+	The user will be prompted for a value for `min_id`
 
-        >   let g:dbtables_greeting = 'Hi there!'
+                                                    *:QueryHistory*
+:QueryHistory
+	Opens the list of recently ran queries. Selecting a query will
+	re-run the query. All parameters are already filled in.
+
+                                                    *:QuerySnippets*
+:QuerySnippets
+	Opens the list of saved query snippets. Selecting a snippet will
+	open the snippet in a new tab for modification or execution.
+
+MAPPINGS                                           *dbtables-mappings*
+
+All mappings use the <Leader> key in normal or visual mode.
+
+In NORMAL mode:
+
+    <Leader>dt
+        Same as |:DBTables|. Open the database tables window.
+
+    <Leader>eq
+        Same as |:ExecuteSQL|. Execute SQL from the current buffer.
+
+    <Leader>db
+        Same as |:DBConsole|. Open an interactive DB console.
+
+    <Leader>qh
+        Same as |:QueryHistory|. Open the query history list.
+
+    <Leader>qs
+        Same as |:QuerySnippets|. Open the query snippets list.
+
+In VISUAL mode:
+
+    <Leader>ev
+        Call dbtables#ExecuteVisualSQLQuery(). Execute only the
+        visually selected SQL text.
+
+CONFIGURATION                                      *dbtables-config*
 
-INSTALLATION                                       *dbtables-install*
+The plugin exposes several global variables you can set in your
+vimrc/init.vim before the plugin is loaded. Each has a default value
+if you do not define it.
+
+                                                    *g:snippets_directory*
+g:snippets_directory
+    Directory where query snippets are stored and loaded from.
+
+    Default:
+        $HOME/.config/heidisql/Snippets
+
+    Example:
+
+        let g:snippets_directory = expand('~/.vim/db_snippets')
+
+                                                    *g:db_user*
+g:db_user
+    Database username used by the plugin when connecting or running
+    queries.
+
+    Default:
+        ''  (empty string; you must set this to actually connect)
+
+    Example:
+
+        let g:db_user = 'myuser'
+
+                                                    *g:db_password*
+g:db_password
+    Database password associated with |g:db_user|.
+
+    Default:
+        ''  (empty string; set this if your DB requires a password)
+
+    Example:
 
-Using vim-plug add the following:
+        let g:db_password = 'mypassword'
+
+                                                    *g:db_name*
+g:db_name
+    Default database/schema name to connect to.
+
+    Default:
+        ''  (empty string; set this to the DB you want to use)
+
+    Example:
+
+        let g:db_name = 'mydatabase'
+
+                                                    *g:db_host*
+g:db_host
+    Hostname or IP address of the database server.
 
-Plug '/home/lsitas/repos/vim_plugins/dbtables'
+    Default:
+        ''  (empty string; set this to your DB host, e.g. 'localhost')
+
+    Example:
+
+        let g:db_host = 'localhost'
+
+NOTES                                              *dbtables-notes*
 
+- All mappings are defined in the plugin by default. If you prefer
+  your own keybindings, you can `:nunmap` or `:xunmap` them and
+  create custom mappings to the same functions
+  (e.g. dbtables#ExecuteSQLQuery()).
+
+- This help file documents only the public interface (commands,
+  mappings, and configuration variables). The internal functions
+  under the dbtables# namespace are intended to be called by these
+  interfaces, but you may also call them directly if you know what
+  you are doing.
 
 *dbtables*      Main help entry for this plugin.