DBWillow Logo

Creating Your First Connection

Overview

Creating a database connection in DBWillow is simple and secure. This guide will walk you through connecting to your first MySQL database.

Prerequisites

Before creating a connection, you'll need:

  • A MySQL, MySQL 8.0+, or MariaDB server
  • Database credentials (username and password)
  • Host address and port (default is 3306)
  • Database name (optional, you can select it after connecting)

Step-by-Step Guide

Step 1: Open the Connection Dialog

  1. Launch DBWillow
  2. Click the "New Connection" button (or press Ctrl+N / Cmd+N)
  3. The connection dialog will appear

Step 2: Enter Connection Details

Fill in the connection form:

Connection Name:

  • Give your connection a memorable name (e.g., "Local MySQL", "Production DB")
  • This is just a label for your reference

Host:

  • Enter your database server address
  • For local databases: localhost or 127.0.0.1
  • For remote databases: the server's IP address or domain name

Port:

  • Default MySQL port is 3306
  • Change if your server uses a different port

Username:

  • Your MySQL username
  • Common examples: root, admin, or a custom user

Password:

  • Your MySQL password
  • Will be encrypted and stored securely

Database (Optional):

  • Leave empty to connect to all databases
  • Or specify a database name to connect directly

Step 3: Test the Connection

  1. Click the "Test Connection" button
  2. DBWillow will attempt to connect to your database
  3. You'll see a success message if the connection works
  4. If there's an error, check the error message and verify your credentials

Step 4: Save and Connect

  1. Once the test succeeds, click "Save"
  2. Your connection will be saved and encrypted
  3. DBWillow will automatically connect to the database
  4. You'll see the database schema in the sidebar

Connection Types

Standard Connection

For databases accessible directly on your network:

  • Local databases: Use localhost or 127.0.0.1
  • Network databases: Use the server's IP or hostname
  • Cloud databases: Use the provider's connection string

SSH Tunnel Connection

For databases behind a firewall or requiring SSH access:

  1. Check "Use SSH Tunnel" in the connection dialog
  2. Enter SSH connection details:
    • SSH Host
    • SSH Port (usually 22)
    • SSH Username
    • Authentication (password or private key)
  3. Enter MySQL connection details (usually localhost through the tunnel)

See our SSH Tunnel guide for detailed instructions.

Security Features

Encrypted Storage

  • All passwords are encrypted using AES-GCM encryption
  • Credentials are stored locally on your machine
  • Never transmitted to external servers

SSL/TLS Support

  • Enable SSL for secure connections
  • Required for most cloud database providers
  • Configure SSL settings in advanced options

Common Connection Issues

"Access Denied" Error

Possible causes:

  • Incorrect username or password
  • User doesn't have permission to connect from your IP
  • User account is locked or expired

Solutions:

  • Double-check your credentials
  • Verify user permissions in MySQL
  • Check if your IP is allowed in MySQL's user table

"Can't Connect to Server" Error

Possible causes:

  • Incorrect host or port
  • Firewall blocking the connection
  • MySQL server is not running
  • Network connectivity issues

Solutions:

  • Verify the host and port are correct
  • Check if MySQL server is running: systemctl status mysql (Linux)
  • Check firewall settings
  • Test network connectivity: ping <host>

"Connection Timeout" Error

Possible causes:

  • Server is unreachable
  • Firewall blocking the port
  • Network latency issues

Solutions:

  • Check server status
  • Verify firewall rules
  • Try increasing the connection timeout in advanced settings

Advanced Options

Connection Timeout

  • Default: 30 seconds
  • Increase for slow networks
  • Decrease for faster failure detection

Character Set

  • Default: UTF-8
  • Change if your database uses a different character set

SSL Mode

  • Disabled: No encryption (not recommended)
  • Preferred: Use SSL if available
  • Required: SSL must be enabled

Managing Connections

Edit Connection

  1. Right-click on a connection in the sidebar
  2. Select "Edit Connection"
  3. Update the connection details
  4. Click "Save"

Delete Connection

  1. Right-click on a connection
  2. Select "Delete Connection"
  3. Confirm the deletion
  4. Note: This only removes the connection, not the database

Duplicate Connection

  1. Right-click on a connection
  2. Select "Duplicate Connection"
  3. Edit the duplicate with new details
  4. Useful for creating similar connections

Next Steps

Now that you're connected, you can: