# Shovl

A lightweight terminal-based database and S3 client built with Textual.

## Installation

Install Shovle using pip:

```bash
pip install shovl
```

### Database-Specific Dependencies

Shovl requires additional drivers depending on your target database systems. Install the appropriate extras for your use case:

```bash
# Individual database support
pip install shovl[sqlite]        # SQLite support
pip install shovl[postgresql]    # PostgreSQL support
pip install shovl[mysql]         # MySQL support
pip install shovl[mariadb]       # MariaDB support
pip install shovl[oracle]        # Oracle Database support
pip install shovl[snowflake]     # Snowflake support
pip install shovl[duckdb]        # DuckDB support
pip install shovl[ibmdb]         # IBM DB2 support

# General database support (SQLAlchemy only)
pip install shovl[database]

# S3 and cloud storage support
pip install shovl[bucket]

# Complete installation with all features
pip install shovl[all]
```

**Note**: Shovl leverages SQLAlchemy's extensive database support. You may install additional SQLAlchemy-compatible drivers as needed for other database systems.

## Configuration

Shovl uses a hierarchical configuration system to manage connection details and application settings. The configuration file is loaded in the following priority order:

1. Path specified via the `--config` command-line option
2. Local configuration file (`.shovl` in the current directory)
3. Global user configuration file (`~/.shovl` or `%USERPROFILE%\.shovl` on Windows)
4. Default configuration (fallback)

### Generating Configuration Files

Create a sample configuration file:

```bash
# Local configuration
shovl --sample-config > .shovl

# Global configuration
shovl --sample-config > ~/.shovl
```

View the complete configuration schema with detailed parameter descriptions:

```bash
shovl --config-schema
```

### Security Best Practices

**Important**: Never store credentials in plain text within configuration files. Shovl supports environment variable substitution using double curly bracket syntax: `{{VARIABLE_NAME}}`.

Load environment variables from a `.env` file using the `--env` option.

## Usage

### Basic Usage

Launch Shovl with default settings:

```bash
shovl
```

### Advanced Options

Load credentials from an environment file:

```bash
shovl --env .env
```

Specify a custom configuration file:

```bash
shovl --config /path/to/custom/config.json
```

Display all available command-line options:

```bash
shovl --help
```

## System Requirements

- Python 3.12 or higher
- Terminal with Unicode support
- Network connectivity for database and S3 operations

## License

This project is distributed under the terms specified in the LICENSE.md file.

## Contributing

Shovl is an open-source project. For bug reports, feature requests, or contributions, please visit the [project repository](https://codeberg.org/maxbrixner/shovl).

## Support

For issues and support requests, please use the [project's issue tracker](https://codeberg.org/maxbrixner/shovl/issues).
