Maxim

Maxim is a fast, modern terminal user interface (TUI) for working with PostgreSQL databases. Browse tables, view data, and run SQL queries with intelligent autocomplete—all without leaving your terminal.

See the product roadmap for the implementation order, feature priorities, and release criteria.

!Maxim !License !Go

• Fast & Modern TUI - Beautiful, keyboard-driven interface built with Bubble Tea
• Database Management - Create, list, and delete PostgreSQL databases
• Docker DB Creation - Spin up a PostgreSQL database inside a Docker container from the UI
• Table Browser - Browse tables and view data with pagination (100 rows per page)
• SQL Editor - Write SQL queries with syntax-aware autocomplete
• Intelligent Autocomplete - Smart suggestions for SQL keywords, table names, and column names
• Keyboard-Driven - Full keyboard navigation—no mouse required
• Connection Management - Save and reuse database connections securely

Installation

Quick Install (Recommended)

The easiest way to install Maxim is using Go's go install command:

go install github.com/ASHUTOSH-SWAIN-GIT/maxim@latest

Prerequisites:

• Go 1.21 or later installed (download Go)
• $GOPATH/bin or $GOBIN in your PATH (usually already configured)

Verify installation:

maxim --version

Adding to PATH (if command not found):

If the maxim command is not found after installation, you need to add Go's bin directory to your PATH:

Linux/macOS:

For Bash (add to ~/.bashrc):

echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc

For Zsh (add to ~/.zshrc):

echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.zshrc
source ~/.zshrc

For Fish (add to ~/.config/fish/config.fish):

echo 'set -gx PATH $PATH (go env GOPATH)/bin' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

Windows (PowerShell):

# Add to PowerShell profile (run once)
[System.Environment]::SetEnvironmentVariable('Path', $env:Path + ";$env:USERPROFILE\go\bin", 'User')
Or manually add C:\Users\<YourUsername>\go\bin to your PATH environment variable

Windows (Command Prompt):

# Add to PATH permanently (replace <username> with your username)
setx PATH "%PATH%;C:\Users\<username>\go\bin"

After adding to PATH, restart your terminal or run source ~/.bashrc (Linux/macOS) / restart PowerShell (Windows).

Alternative: Download Pre-built Binaries

If you prefer pre-built binaries, download from the Releases page:

1. Download the appropriate archive for your platform
2. Extract and move to your PATH
3. Verify: maxim --version

Requirements

• PostgreSQL server running and accessible (for local/remote DBs)
• Superuser credentials for database management operations (create/delete databases) on local servers
• For Docker-based databases: Docker installed and running

Creating a PostgreSQL Superuser

If you don't already have a PostgreSQL superuser to use with Maxim, create one using one of the options below.

Option A: Using psql

# 1) Switch to the postgres system user (Linux)
sudo -u postgres psql
2) Inside psql, create a login role with superuser privileges
CREATE ROLE maxim_admin WITH LOGIN SUPERUSER PASSWORD 'your-strong-password';
3) Verify
\du
4) Exit psql
\q

Option B: Using createuser

# Linux/macOS
sudo -u postgres createuser --superuser maxim_admin
sudo -u postgres psql -c "ALTER USER maxim_admin WITH PASSWORD 'your-strong-password';"

Notes

• Use a strong password and store it securely.
• If connecting remotely, ensure postgresql.conf and pg_hba.conf allow your host/IP.
• On managed services (RDS, Cloud SQL, Azure), use the platform-provided admin user instead of creating your own superuser.

Quick Start

1. Launch Maxim

maxim start

This will open the main menu with the following options:

• Connect to a DB
• Create a new DB
• List all DBs
• Delete a DB

2. Connect to a Database

Choose "Connect to a DB" from the main menu, or use:

maxim connect

Enter your database credentials:

• Port (default: 5432)
• Username
• Password
• Database Name

When saved connections exist, Maxim shows a connection manager before opening the database. Press Enter to connect, n to add a connection, e to edit, r to rename, or d to delete a saved profile. Maxim asks for the password when connecting and never writes it to the configuration file.

3. Explore Your Database

After connecting, Maxim opens a focused database workspace. Saved connections disappear after selection; the active database stays in the compact header while the main area switches between table data, structure, and the SQL editor.

• Use j/k or the arrow keys and Enter to open a table from the navigator.
• Press b to show or hide the table navigator.
• Use Left/Right to switch between Structure and Data.
• Use n/p to move between 100-row pages.
• Press e to open the SQL editor and Esc to return to the workspace.
• Press c to change connections without restarting Maxim.

Docker Database (Container) Support

Maxim can create PostgreSQL databases inside Docker containers.

Prerequisites

• Docker installed and running

• Permissions to run Docker (on Linux, add your user to the docker group or use sudo)
• An available host port for PostgreSQL (default container port 5432; you choose the host port)

Create a Docker Database

1. Open Maxim: maxim start
2. Choose: Create a new DB
3. Select: Docker
4. Enter the following:

1. Maxim will start a container from postgres:latest, wait until it is ready, and show a success message with connection details (password is not displayed).
2. No auto-connect occurs; use the normal connect flow below.

Connect to a Docker Database

• Host: localhost
• Port: the host port you entered during creation
• Username: the username you entered during creation
• Database: the database name you entered during creation
• Password: the password you entered during creation

List and Delete

• List all DBs includes Docker databases, marked with [Docker].
• Delete a DB will stop and remove the Docker container when a Docker DB is selected.

Notes

• Passwords are never stored; they are masked in any on-screen messages.
• PostgreSQL version is latest by default.

Docker Troubleshooting

• "docker: command not found": Install Docker and ensure it’s in PATH.
• "permission denied": On Linux, add your user to the docker group or run with sudo.
• "port already in use": Choose a different host port (e.g., 5433, 5434...).
• Container not ready: docker logs to inspect startup.
• Manual cleanup:

docker stop <container_name> && docker rm <container_name>

Usage Guide

Main Commands

maxim start      # Launch interactive TUI interface
maxim connect    # Connect to a database
maxim create     # Create a new database and user
maxim list       # List all databases on the server (includes Docker)
maxim delete     # Delete a database (kills Docker container if applicable)
maxim --version  # Show version information
maxim --help     # Show help

SQL Editor

The SQL Editor provides a split-panel interface:

• Left Panel: Type your SQL queries
• Right Panel: View autocomplete suggestions and results

• Ctrl+A - Execute all queries
• Ctrl+X - Cancel the running query
• Ctrl+R - Clear results
• Tab - Cycle through autocomplete suggestions
• Enter - Select highlighted suggestion
• Esc - Return to the database workspace

Viewing Table Data

In the database workspace:

• j/k or Up/Down - Select a table
• Enter - Load the selected table
• b - Show or hide the table navigator
• Tab - Switch between data and structure
• Up/Down or j/k - Select a row in the data grid
• Enter - Peek at every field and the full value for the selected row

• Esc - Return from the row peek to the data grid
• / - Apply a server-side column=value filter
• s - Cycle the sort column
• Shift+S - Reverse the sort direction
• Left/Right - Switch between table structure and row data
• n/p - Load the next or previous page (100 rows)
• e - Open the SQL editor
• c - Return to the saved connection manager
• q - Quit

Configuration

Connection details are stored securely in your system's configuration directory:

• Linux: ~/.config/maxim/config.json
• macOS: ~/Library/Application Support/maxim/config.json
• Windows: %APPDATA%\maxim\config.json

Keyboard Navigation

Maxim is fully keyboard-driven:

• Arrow Keys / j/k - Navigate menus and lists
• Enter - Select/Submit
• Esc / q - Quit/Go back
• Tab - Move to next field (in forms)
• Shift+Tab - Move to previous field

Examples

Create a New Database

maxim create
Follow the prompts to enter:
- Database name
- Username
- Password

List All Databases

maxim list
Shows all databases on the server (includes [Docker] entries)
Press Esc to return to menu

Connect and Query

maxim connect
Enter host, port, username, password, and database name
Open "Editor" to type queries with autocomplete

Troubleshooting

Connection Failed

• Verify PostgreSQL is running: sudo systemctl status postgresql (Linux)
• Check if the port is correct (default: 5432, or your Docker host port)
• Ensure your user has the necessary permissions
• Verify network connectivity to the database server

Permission Denied

• Ensure you're using superuser credentials for database creation/deletion
• Check PostgreSQL user permissions
• Verify database ownership

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development checks

Run the same checks used by CI before opening a pull request:

make ci

This verifies module files and formatting, runs go vet, executes tests with race detection, and builds the Maxim binary. Individual targets such as make test, make test-integration-cli, make fmt, make coverage, and make build are also available. The coverage target enforces the repository's current 15% minimum and should be raised as coverage grows.

make test-integration-db automatically starts and removes a disposable PostgreSQL 17 Docker container. To use an existing disposable database instead, set all of MAXIM_TEST_DB_HOST, MAXIM_TEST_DB_PORT, MAXIM_TEST_DB_USER, MAXIM_TEST_DB_PASSWORD, and MAXIM_TEST_DB_NAME. Docker lifecycle tests require a running Docker daemon and can be run with make test-integration-docker.

CI additionally tests Maxim on Linux, macOS, and Windows, scans for known Go vulnerabilities, exercises Maxim against a real PostgreSQL service and Docker container, and validates the GoReleaser configuration. Version tags in the form v* trigger the release workflow.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Bubble Tea - A powerful TUI framework
• Uses Cobra for CLI commands

Support

For issues, questions, or feature requests, please open an issue on GitHub.

Enjoy working with your databases! 🚀