vivadb-py

A python wrapper around vivadb.

Installation

Install through pip (or your favorite dependency manager):

pip install vivadb-py

Commands

The package comes bundled with the vivadb executable and has all its subcommands.

config - Database Configuration

Configure your PostgreSQL connection settings and save them to environment files.

vivadb config [OPTIONS]

Options:

• --host - PostgreSQL host (default: localhost)
• --port - PostgreSQL port (default: 5432)
• --user - PostgreSQL username
• --password - Password (not recommended for production)
• --password-stdin - Input password securely from stdin
• --dbname - Database name
• --prod - Write to production environment file
• -h, --help - Show help for this command

Examples:

# Configure development database with secure password input
vivadb config --host=localhost --port=5432 --user=myuser --dbname=postgres --password-stdin

# Configure production database
vivadb config --host=prod-server --use= prod_user --dbname=production_db --prod --password-stdin

exec - Execute SQL Queries

Execute SQL queries with production awareness and optional safety checks.

vivadb exec [OPTIONS]

Options:

• -q, --query - SQL query to execute
• -s, --safe - Execute only safe queries
• -p, --prod - Run in production environment
• -h, --help - Show help for this command

Examples:

# Execute a safe query in development
vivadb exec --query="SELECT * FROM users LIMIT 10;" --safe

# Execute query in production (use with caution)
vivadb exec --query="UPDATE users SET status = 'active' WHERE created_at > '2024-01-01';" --prod

new - Create New Project

Create a new project with database integration and optional Docker setup.

vivadb new [OPTIONS]

Options:

• --host - PostgreSQL host
• --port - PostgreSQL port
• --user - PostgreSQL username
• --password - Password (not recommended)
• --password-stdin - Input password securely from stdin
• --dbname - Database name
• --prod - Configure for production
• --docker - Create Docker Compose configuration
• -h, --help - Show help for this command

Examples:

# Create new project with Docker setup
vivadb new --project-name=hello_world --docker --host=localhost --port=5432 --user=myuser --dbname=postgres --password-stdin

migrate - Database Migrations

Update your database schema in a production-aware manner.

vivadb migrate [OPTIONS]

Options:

• --prod - Run migration in production environment
• -h, --help - Show help for this command

Examples:

# Run migrations in development
vivadb migrate

# Run migrations in production
vivadb migrate --prod

Environment Files

vivadb manages separate environment files for development and production:

• Development: .vivadb/.env.local
• Production: .vivadb/.env

This separation helps prevent accidental operations on production databases during development.

Security Best Practices

1. Use --password-stdin: Always use the --password-stdin flag instead of --password to avoid exposing credentials in your shell history.

2. Production flag: Always use the --prod flag when working with production databases to ensure proper environment separation.

3. Safe queries: Use the --safe and/or --prod flag with the exec command when possible to enable additional safety checks.

Project Structure

When using vivadb new, the tool creates a project structure optimized for database-driven applications, including:

• Environment configuration files
• Optional Docker Compose setup for local PostgreSQL
• Project scaffolding with database integration

Here is how a project would look like:

.
├── .gitignore
├── .vivadb
│   ├── .env.local
│   └── compose.yaml
├── README.md
└── schema.v.sql

Contributing

Contributions are more than welcome! Find the contribution guidelines here

License

This project is distributed under an MIT License

Support

For issues and questions, please create an issue in the repository.