# Connection Management

This guide explains how to create, manage, and organize database connections in SQLife.

## Table of Contents
- [Overview](#overview)
- [Creating a New Connection](#creating-a-new-connection)
  - [Server-Based Databases](#server-based-databases)
  - [File-Based Databases](#file-based-databases)
- [Testing Connections](#testing-connections)
- [Saving Connections](#saving-connections)
- [Connecting to a Database](#connecting-to-a-database)
- [Managing Connection Properties](#managing-connection-properties)
- [Organizing Connections with Catalogs](#organizing-connections-with-catalogs)
- [Connection Operations](#connection-operations)
- [Advanced Connection Options](#advanced-connection-options)
- [Troubleshooting](#troubleshooting)

---

## Overview

The Connection Manager is your central hub for managing all database connections in SQLife. It provides:

- **Connection List:** View all saved connections organized by catalogs
- **Connection Form:** Enter and edit connection details
- **Quick Actions:** Test, save, and connect with single clicks
- **Context Menu:** Additional operations like clone, delete, and move

### Opening Connection Manager

Access the Connection Manager by:
- Opening SQLife (Connection Manager appears by default)
- Creating a new connection tab: **File → New** (Ctrl/Cmd + N)
- Clicking the **"New Connection"** tab

### Interface Layout

The Connection Manager has two main sections:

**Left Panel - Connection List:**
- Shows all saved connections organized by catalogs
- Each connection displays:
  - Database icon (Oracle, MySQL, PostgreSQL, etc.)
  - Connection name
  - Connection address (user@host:port/database)
- Double-click to connect

**Right Panel - Connection Form:**
- Database type selector
- Connection details (varies by database type)
- Properties table for advanced JDBC options
- Action buttons: Test, Save, Connect

---

## Creating a New Connection

### Before You Start

Ensure you have:
- Database server address and port
- Valid username and password
- Database name or SID/Service name
- Network access to the database server

### License Limitations

**Free/Trial Version:**
- Limited to 8 saved connections
- Upgrade to licensed version for unlimited connections

---

## Server-Based Databases

Server-based databases include Oracle, MySQL, PostgreSQL, MariaDB, SQL Server, and similar systems that run on a network server.

### Step 1: Start a New Connection

1. Click the **New** button in the Connection Manager
2. The form clears, ready for new connection details
3. Database type defaults to Oracle (you can change it)

### Step 2: Select Database Type

1. Click the **Type** dropdown
2. Select your database type:
   - **Oracle** - Oracle Database
   - **PostgreSQL** - PostgreSQL Database
   - **MySQL** - MySQL Database
   - **MariaDB** - MariaDB Database
   - **SQL Server** - Microsoft SQL Server

3. The port number updates automatically to the database default:
   - Oracle: 1521
   - PostgreSQL: 5432
   - MySQL/MariaDB: 3306
   - SQL Server: 1433

### Step 3: Enter Connection Details

Fill in the required fields:

#### Connection Name
- **Purpose:** A friendly name to identify this connection
- **Example:** "Production Oracle", "Dev MySQL", "HR Database"
- **Required:** Yes
- **Max Length:** 60 characters
- **Tip:** Use descriptive names that indicate environment and purpose

#### Host
- **Purpose:** Database server address
- **Examples:**
  - `localhost` (for local servers)
  - `192.168.1.100` (IP address)
  - `db.company.com` (hostname)
  - `oracle-prod.region.rds.amazonaws.com` (cloud database)
- **Required:** Yes
- **Max Length:** 60 characters

#### Port
- **Purpose:** Database server port number
- **Default:** Auto-filled based on database type
- **Required:** Yes
- **Range:** 0-65535
- **Tip:** Use default unless your DBA specifies otherwise

#### Database/SID
- **Purpose:** Database identifier
- **Label varies by type:**
  - Oracle: "Database" (SID or Service Name)
  - PostgreSQL: "Database" (database name)
  - MySQL/MariaDB: "Database" (database name)
  - SQL Server: "Database" (database name)
- **Examples:**
  - Oracle: `ORCL`, `xe`, `prod.company.com`
  - PostgreSQL: `postgres`, `myapp`
  - MySQL: `employees`, `inventory`
- **Required:** Yes
- **Max Length:** 200 characters

#### Username
- **Purpose:** Database user account
- **Examples:** `SCOTT`, `postgres`, `root`, `admin`
- **Required:** Yes
- **Max Length:** 200 characters
- **Note:** Case-sensitivity depends on database type

#### Password
- **Purpose:** Password for the user account
- **Required:** Yes (for testing and connecting)
- **Max Length:** 60 characters
- **Security:** Optionally save with "Save Password" checkbox

#### Save Password
- **Purpose:** Store password encrypted in SQLife
- **Checked:** Password saved, no need to enter on each connect
- **Unchecked:** Must enter password every time you connect
- **Security Note:** Passwords are encrypted but stored locally
- **Tip:** Don't save passwords for production databases on shared machines

#### Keep Alive
- **Purpose:** Prevent connection timeout by sending periodic pings
- **Value:** Interval in seconds (0 = disabled)
- **Example:** 60 (sends ping every 60 seconds)
- **When to use:**
  - Long-running queries
  - Interactive data editing sessions
  - Databases with short timeout settings
- **Default:** 0 (disabled)

### Step 4: Oracle-Specific Options

If connecting to Oracle, you may need additional settings:

#### Connection Type
In the Properties table, you might find:
- **Connection Type:** Basic or TNS
- **Role:** NORMAL, SYSDBA, or SYSOPER

**Using TNS:**
1. Set connection type to TNS in properties
2. In the Database field, enter TNS alias (e.g., `PROD_DB`)
3. Ensure your `tnsnames.ora` file is configured
4. Or use **File → Import → tnsnames.ora** to import connections

**Using SYSDBA/SYSOPER:**
1. Expand properties table
2. Find "Role" property
3. Change from NORMAL to SYSDBA or SYSOPER
4. Use privileged user credentials (e.g., `sys`)

### Step 5: Example - Oracle Connection

```
Connection Name: Production Oracle
Type: Oracle
Host: oracle-prod.company.com
Port: 1521
Database: ORCL
Username: SCOTT
Password: ••••••••
Save Password: ☑
Keep Alive: 60
```

### Step 6: Example - PostgreSQL Connection

```
Connection Name: Dev PostgreSQL
Type: PostgreSQL
Host: localhost
Port: 5432
Database: myapp_dev
Username: postgres
Password: ••••••••
Save Password: ☑
Keep Alive: 0
```

### Step 7: Example - MySQL Connection

```
Connection Name: Local MySQL
Type: MySQL
Host: 127.0.0.1
Port: 3306
Database: employees
Username: root
Password: ••••••••
Save Password: ☐
Keep Alive: 0
```

---

## File-Based Databases

File-based databases include SQLite, H2 File, Derby File, and HyperSQL File. These databases store data in local files rather than running on a network server.

### Supported File-Based Databases

- **SQLite** - Lightweight, serverless database (`.db`, `.sqlite`, `.sqlite3` files)
- **H2 File** - Java-based database (`.mv.db` files)
- **Derby File** - Apache Derby embedded (folder-based)
- **HyperSQL File** - HSQLDB embedded (`.script` files)

### Step 1: Select File-Based Type

1. Click the **New** button
2. Select database type from dropdown:
   - SQLite
   - H2 File
   - Derby File
   - HyperSQL File

3. The interface changes to **File Mode** showing:
   - File Path field instead of Host/Port
   - Browse button to select database file
   - Optional username/password fields

### Step 2: Enter Connection Details

#### Connection Name
- **Purpose:** Friendly name for this file database
- **Example:** "Local SQLite DB", "H2 Test Database"
- **Required:** Yes
- **Max Length:** 60 characters

#### File Path
- **Purpose:** Full path to database file
- **Required:** Yes
- **Max Length:** 500 characters
- **How to enter:**
  - **Option 1:** Click **Choose File** button and browse
  - **Option 2:** Type or paste the full path

**File Selection by Database Type:**

**SQLite:**
- Extension: `.db`, `.sqlite`, `.sqlite3`
- Example: `/home/user/data/myapp.db`
- Example (Windows): `C:\Users\User\data\myapp.db`

**H2 File:**
- Extension: `.mv.db`
- Example: `/home/user/h2/testdb.mv.db`
- **Important:** H2 appends `.mv.db` automatically, so you can specify just the base name

**Derby File:**
- No specific extension (folder-based)
- Example: `/home/user/derby/mydb`
- Select the Derby database directory

**HyperSQL File:**
- Extension: `.script`
- Example: `/home/user/hsqldb/testdb.script`

#### Database/SID (Optional)
- Usually not needed for file databases
- SQLite: leave blank
- Max Length: 200 characters if used

#### Username (Optional)
- Most file databases don't require authentication
- SQLite: leave blank
- H2/Derby/HyperSQL: may need username if security is enabled
- Max Length: 200 characters

#### Password (Optional)
- SQLite: leave blank (no authentication)
- H2/Derby/HyperSQL: enter if database is password-protected
- Max Length: 60 characters

### Step 3: Example - SQLite Connection

```
Connection Name: Local SQLite
Type: SQLite
File Path: /home/user/Documents/myapp.db
Database: (empty)
Username: (empty)
Password: (empty)
Save Password: ☐
Keep Alive: 0
```

### Step 4: Important Notes for File Databases

**Single Connection Limit:**
- SQLite and other file databases allow only ONE connection at a time
- SQLife enforces this limit to prevent database corruption
- If you try to open a second connection to the same file, you'll see:
  > "Only one connection is allowed for local file database: [path]"

**File Permissions:**
- Ensure you have read/write permissions for the database file
- On Linux/Mac, check file permissions with `ls -l`
- On Windows, check file properties

**Backup Recommendation:**
- File databases can be easily backed up by copying the file
- Regular backups recommended before major operations

---

## Testing Connections

Before saving or connecting, test your connection to verify all details are correct.

### How to Test

1. Fill in all required connection details
2. Click the **Test** button
3. SQLife attempts to connect with provided credentials
4. Wait for the result (may take a few seconds)

### Success

If the test succeeds:
- You'll see: **"Connection test succeeded"**
- Green checkmark or success message in status bar
- Connection details are valid
- You can now save and/or connect

### Failure

If the test fails:
- You'll see: **"Failed to test the connection configuration: [error message]"**
- Red error message in status bar
- Review the error message for clues

### Common Test Failures and Solutions

#### "Connection refused"
- **Cause:** Database server not running or network issue
- **Solution:**
  - Verify database server is running
  - Check host address is correct
  - Verify port number
  - Check firewall settings

#### "Invalid username or password"
- **Cause:** Incorrect credentials
- **Solution:**
  - Double-check username (case-sensitive for some databases)
  - Verify password is correct
  - Ensure account has login permission

#### "Unknown database" or "Database does not exist"
- **Cause:** Database name/SID is incorrect
- **Solution:**
  - Verify database name with DBA
  - For Oracle, confirm SID or Service Name
  - Check database exists on the server

#### "Network error" or "Timeout"
- **Cause:** Cannot reach database server
- **Solution:**
  - Verify network connectivity (ping the server)
  - Check VPN connection if required
  - Verify firewall allows the port
  - Check if behind a proxy (configure in Preferences)

#### File database: "File not found"
- **Cause:** Database file path is incorrect
- **Solution:**
  - Verify file path is correct
  - Use Browse button to locate file
  - Check file exists at specified location

### Testing vs. Connecting

**Test Button:**
- Quick validation of credentials
- Opens and immediately closes connection
- Doesn't open a workbench
- Safe to test multiple times

**Connect Button:**
- Opens full database connection
- Creates new database tab
- Loads database objects
- Ready for queries and operations

**Tip:** Always test before saving to catch errors early.

---

## Saving Connections

Save your connection configuration for future use.

### How to Save

1. Fill in connection details
2. Click the **Save** button
3. If updating existing connection, you'll be prompted:
   > "Are you sure you want to update this connection?"
4. Click **OK** to confirm
5. Connection appears in the list

### When to Save

**Before First Connection:**
- If you enter details and click **Connect**, SQLife asks:
  > "Would you like to save this connection before connecting?"
- Click **OK** to save, or **Cancel** to connect without saving

**After Editing:**
- When you select a saved connection and modify it
- Click **Save** to update the stored configuration
- Confirmation prompt prevents accidental overwrites

**New Connection:**
- If connection name doesn't exist, it's added to the list
- No confirmation needed

### Save Behavior

**What Gets Saved:**
- Connection name
- Database type
- Host/Port (or File Path for file databases)
- Database/SID
- Username
- Password (if "Save Password" is checked)
- Keep Alive interval
- All properties in the Properties table

**Where It's Saved:**
- Local SQLife database in your home folder
- Path: `~/.sqlife/` (Linux/Mac) or `%USERPROFILE%\.sqlife\` (Windows)
- Passwords are encrypted

**Automatic Features:**
- Connections are sorted automatically by type, host, and name
- Last used schema is remembered per connection
- Connection state can be recovered after crash

### Password Security

**Saving Passwords:**
- **Advantage:** Convenient, no need to type password each time
- **Disadvantage:** Password stored on your computer
- **Encryption:** Yes, passwords are encrypted
- **Recommendation:**
  - Save passwords for development/test databases
  - Don't save passwords for production databases on shared machines
  - Use strong passwords always

**Not Saving Passwords:**
- Every time you connect, you must enter the password
- More secure for sensitive databases
- SQLife shows a prompt asking for password

---

## Connecting to a Database

Once your connection is saved (or tested), you can connect to the database.

### Method 1: Connect Button

1. Select connection from list (or enter new details)
2. Click **Connect** button
3. If password isn't saved, you'll be prompted
4. SQLife connects and opens a new database tab

### Method 2: Double-Click

1. **Double-click** a connection in the list
2. Fastest way to connect!
3. Works on any saved connection

### Method 3: Context Menu

1. **Right-click** a connection in the list
2. Select **Connect** from context menu
3. Same as double-click

### Connection Process

When you connect:

1. **Validation:** SQLife validates connection details
2. **Network:** Establishes network connection to database
3. **Authentication:** Logs in with provided credentials
4. **Loading:** Retrieves database metadata and schema list
5. **Ready:** Opens database tab with Objects navigator

**Visual Feedback:**
- Connect button changes to "Cancel" during connection
- Progress indicator may appear
- Status bar shows "Connecting..."

### After Successful Connection

A new database tab opens with:

**Tab Title:** Connection name (e.g., "Production Oracle")

**Main Interface:**
- SQL Editor (top)
- Data View (bottom)
- Objects Navigator (left sidebar)
- Toolbar with query execution buttons

**Objects Navigator:**
- Schema dropdown (select which schema to browse)
- Object tree (Tables, Views, Procedures, Functions, etc.)
- Filter box to search objects

**Next Steps:**
- Browse database objects
- Write and run SQL queries
- Edit table data
- Export/import data

See other guides for details on these features:
- [Exploring Objects and Executing SQL](05-explore-objects-and-execute-sql.md)
- [Object Explorer](06-object-explorer.md)
- [Export Objects and Data](07-export-object-and-data.md)

### Connection Failures

If connection fails:
- Error message displays with details
- Connection tab doesn't open
- Review error message (similar to test failures)
- Fix the issue and try again

### Multiple Connections

**Server Databases:**
- You can open multiple connections to the same server
- Each connection is independent
- Useful for comparing data or working with multiple schemas

**File Databases:**
- Only ONE connection allowed per file database
- Prevents database corruption
- Error if you try to open duplicate connection

**Connection Limit:**
- The practical limit depends on the database, driver, and workstation resources.
- Close unused connections when they are no longer needed.

---

## Managing Connection Properties

The Properties table at the bottom of the connection form shows advanced JDBC connection options.

### Understanding Properties

Properties are organized into folders:

**Common Folders:**
- **Connection:** Basic connection settings
- **Performance:** Query and fetch optimization
- **Security:** SSL, encryption options
- **Advanced:** Database-specific options

**Structure:**
- **Property Name:** JDBC property key
- **Property Value:** Current value (editable)

### Viewing Properties

1. Connect or create a connection
2. Scroll down to the **Properties** section
3. Expand folder nodes to see properties
4. Properties are database-type specific

### Editing Property Values

1. **Double-click** a property value cell
2. Edit the value based on property type:
   - **Text:** Type new value
   - **Dropdown:** Select from options
   - **Checkbox:** Toggle true/false
   - **Number:** Enter numeric value

3. Press **Enter** to confirm
4. Click **Save** or **Test** to apply changes

### Common Properties

#### Oracle
- **Connection Type:** basic, tns, oci
- **Role:** NORMAL, SYSDBA, SYSOPER
- **SSL:** Enable SSL connections

#### PostgreSQL
- **SSL Mode:** disable, require, verify-ca, verify-full
- **Application Name:** Appears in pg_stat_activity

#### MySQL
- **useSSL:** Enable SSL connections
- **serverTimezone:** Set timezone (e.g., UTC)
- **allowPublicKeyRetrieval:** Allow public key retrieval

#### SQL Server
- **Encrypt:** Enable connection encryption
- **TrustServerCertificate:** Trust server certificate

### Restoring Default Properties

If you've changed properties and want to revert:

1. Click the **Restore Options** button
2. Confirmation prompt appears:
   > "Are you sure you want to restore the default options?"
3. Click **OK** to confirm
4. All properties reset to database type defaults

**Note:** This affects the current connection only, not already saved connections.

### When to Modify Properties

**Common Scenarios:**
- **SSL Required:** Enable SSL/encryption for secure connections
- **Connection Timeout:** Increase timeout for slow networks
- **Character Encoding:** Set specific encoding (UTF-8, etc.)
- **Performance Tuning:** Adjust fetch size or buffer settings
- **Oracle Role:** Connect as SYSDBA or SYSOPER

**Caution:**
- Only modify if you understand the property
- Incorrect values may prevent connection
- Test after changing critical properties
- Consult database documentation or DBA

---

## Organizing Connections with Catalogs

Catalogs (also called folders or categories) help organize connections into logical groups.

### Default Catalog

All new connections are added to the **"Uncatalogued"** folder by default.

### Creating a Catalog

Currently, catalogs are managed through the context menu when moving connections:

1. **Right-click** a connection
2. Select **Move To** → **New Catalog**
3. Enter catalog name (e.g., "Production", "Development", "Test")
4. Click **OK**
5. New catalog appears in the list
6. Connection moves to new catalog

### Renaming a Catalog

1. **Right-click** the catalog name
2. Select **Rename Catalog**
3. Enter new name
4. Click **OK**
5. Success message: "Catalog renamed successfully"

### Deleting a Catalog

1. **Right-click** the catalog name
2. Select **Delete Catalog**
3. Confirmation prompt:
   > "Are you sure you want to delete the catalog?"
4. Click **OK**
5. Connections move to "Uncatalogued" folder
6. Catalog is removed

**Note:** Deleting a catalog doesn't delete the connections, only the grouping.

### Moving Connections Between Catalogs

See [Connection Operations](#connection-operations) → [Moving Connections](#moving-connections) below.

### Organizing Tips

**Suggested Catalog Names:**
- **By Environment:** Production, Staging, Development, Test
- **By Project:** ProjectA, ProjectB, ClientX
- **By Database Type:** Oracle, PostgreSQL, MySQL
- **By Team:** Frontend, Backend, Analytics, DBA

**Best Practices:**
- Use clear, descriptive names
- Keep catalog structure simple
- Review and reorganize periodically
- Use consistent naming conventions

---

## Connection Operations

Manage connections through the context menu with right-click operations.

### Context Menu - Connections

Right-click any connection to see:

- **Connect** - Open connection
- **Clone** - Duplicate connection
- **Delete** - Remove connection
- **Move To** - Move to different catalog

### Context Menu - Catalogs

Right-click any catalog to see:

- **Rename Catalog** - Change catalog name
- **Delete Catalog** - Remove catalog (keeps connections)

### Connecting

**Right-Click Method:**
1. Right-click connection
2. Select **Connect**
3. Same as double-click

**Keyboard Method:**
- Select connection
- Press **Enter**

See [Connecting to a Database](#connecting-to-a-database) for details.

### Cloning Connections

Create a copy of an existing connection, useful for:
- Creating test version of production connection
- Setting up similar connections with different credentials
- Backing up connection before modifying

**How to Clone:**
1. Right-click connection
2. Select **Clone**
3. New connection appears with name: "[Original Name] (1)"
4. Select the cloned connection
5. Modify details as needed
6. Click **Save** to save the clone

**What Gets Cloned:**
- All connection details (host, port, database, username)
- Password (if saved)
- Keep Alive setting
- All properties
- Catalog assignment

**After Cloning:**
- Change the connection name to something meaningful
- Update any different details (e.g., change "Production" to "Development")
- Test the cloned connection
- Save

**Success Message:**
- "Connection configuration cloned successfully"

### Deleting Connections

Remove connections you no longer need.

**How to Delete:**
1. Right-click connection
2. Select **Delete**
3. Confirmation prompt:
   > "Are you sure you want to delete this connection?"
4. Click **OK** to confirm
5. Success message: "Connection configuration deleted successfully"
6. Connection removed from list

**Important:**
- Deletion is permanent
- Cannot be undone
- Backup connections regularly (see below)

**Before Deleting:**
- Make sure you won't need the connection
- Consider exporting/backing up connections first
- Note any special properties or settings

### Moving Connections

Organize connections by moving them between catalogs.

**How to Move:**
1. Right-click connection
2. Select **Move To**
3. Submenu shows available catalogs:
   - Existing catalogs (except current one)
   - **New Catalog** option
4. Select destination catalog
5. Success message: "Connection configuration moved successfully"
6. Connection appears in new catalog

**Creating New Catalog While Moving:**
1. Select **Move To** → **New Catalog**
2. Dialog appears: "Enter the new catalog name:"
3. Enter name (e.g., "Production Databases")
4. Click **OK**
5. New catalog created
6. Connection moves to new catalog

**Validation:**
- Cannot move to same catalog
- Catalog names must be unique
- Error if catalog name already exists: "The catalog name already exists"

### Selecting Connections to Edit

**Click once** on a connection to:
- Load its details into the form (right panel)
- View/edit connection properties
- Update username, password, or other fields

**After Selecting:**
- All fields populate with saved values
- Password appears as dots (••••) if saved
- Properties table shows saved property values
- Database type dropdown is disabled (cannot change type)

**To Edit:**
1. Select connection
2. Modify any field
3. Click **Save** to update
4. Confirmation prompt appears

**To Clear and Start New:**
- Click **New** button
- Form clears for new connection
- Database type dropdown enabled again

---

## Advanced Connection Options

### Keep-Alive Configuration

Keep-Alive sends periodic "ping" queries to prevent connection timeout.

**When to Use:**
- Long data editing sessions
- Databases with short idle timeout
- Overnight queries or data loads
- Interactive analysis work

**How to Configure:**
1. Set **Keep Alive** to desired interval (in seconds)
2. Example: 60 = ping every 60 seconds
3. Set to 0 to disable

**Recommended Values:**
- Development: 0 (disabled)
- Production: 60-300 seconds (1-5 minutes)
- Long sessions: 300-600 seconds (5-10 minutes)

**How It Works:**
- SQLife sends a simple query (like `SELECT 1` or `SELECT 1 FROM DUAL`)
- Keeps connection alive without affecting your work
- Invisible to user

**Caution:**
- Uses database resources
- May accumulate connections if many sessions
- Disable when not needed

### Importing TNS Names (Oracle)

If you have an Oracle `tnsnames.ora` file, you can import all entries at once.

**What is tnsnames.ora?**
- Oracle configuration file
- Contains TNS alias definitions
- Usually in `$ORACLE_HOME/network/admin/tnsnames.ora`

**How to Import:**
1. Go to **File → Import → tnsnames.ora**
2. Browse to select `tnsnames.ora` file
3. Click **Open**
4. SQLife parses all entries
5. Creates connection for each TNS alias

**After Import:**
- All TNS entries appear in connection list
- Connection names match TNS aliases
- Default username may be empty (fill in manually)
- No passwords imported (security)
- All added to "Uncatalogued" folder

**Import Details:**
- Success message shows number imported
- Duplicate names automatically renamed (adds number)
- Invalid entries skipped

**Next Steps:**
- Review imported connections
- Add usernames and passwords
- Test each connection
- Organize into catalogs

### Importing Connections from JDBC URL

If you have a JDBC connection URL (e.g., from an application configuration or another tool), you can import it directly:

1. Go to **File → Import → JDBC URL**
2. Paste the JDBC URL (e.g., `jdbc:postgresql://host:5432/dbname`)
3. SQLife parses the URL and fills in host, port, database, and connection properties automatically
4. Enter the username/password, then test and save

### Importing Connections from DBeaver or Navicat

SQLife can import saved connection configurations from other tools:

1. Go to **File → Import → DBeaver** or **File → Import → Navicat**
2. For **DBeaver:** select the `data-sources.json` file
3. For **Navicat:** SQLife reads the Windows registry entries
4. A **preview dialog** shows the connections that will be imported
5. Confirm to import — each entry becomes a connection in the list

### SSH and SFTP Connections

SQLife provides a dedicated SSH/SFTP connection mode. Use it to browse remote files and work with servers that are not directly reachable:

1. Create a new connection and select the SSH/SFTP mode.
2. Enter the SSH server details:
   - **SSH Host:** Server address (e.g., `bastion.company.com`)
   - **SSH Port:** Default `22`
   - **SSH User:** SSH login user
   - **Authentication:** Password or private key
3. Choose password or private-key authentication.
4. Use the SFTP tab to browse, upload, download, rename, and delete remote files.

**Use Cases:**
- Accessing files on private servers
- Editing remote SQL and configuration files
- Using SSH authentication instead of a separate file-transfer client

### Backing Up Connections

Save all connection configurations to a file for backup or transfer.

**How to Backup:**
1. Go to **File → Backup Connections**
2. Choose save location
3. Default filename: `Backup-YYYYMMDD.json`
4. Click **Save**

**What Gets Backed Up:**
- All saved connections
- Connection details (host, port, database, username)
- Saved passwords (encrypted)
- Properties
- Catalog assignments

**Use Cases:**
- Regular backups (weekly/monthly)
- Moving to new computer
- Sharing connections with team (remove passwords first)
- Before major changes

### Restoring Connections

Restore connections from a backup file.

**How to Restore:**
1. Go to **File → Restore Connections**
2. Browse to select backup `.json` file
3. Click **Open**
4. Confirmation prompt:
   > "Are you sure you want to restore connections? All current connections will be replaced."
5. Click **OK** to confirm
6. Success message: "Connections restored successfully"

**Important:**
- **Replaces all existing connections**
- Cannot be undone
- Backup current connections first if needed

**After Restore:**
- All connections from backup file appear
- Test connections to verify
- Passwords restored (if they were saved)
- Catalog structure restored

---

## Troubleshooting

### Connection List is Empty

**Cause:** No saved connections yet, or database issue

**Solutions:**
1. Create your first connection using **New** button
2. Import connections from backup or tnsnames.ora
3. Check if SQLife database is corrupted (reinstall if needed)

### Cannot Save More Than 8 Connections

**Cause:** Free/Trial version limitation

**Solution:**
- Activate license: **Help → License**
- Enter license key
- Restart SQLife
- Unlimited connections now available

### Connection Test Fails But Works in Other Tools

**Possible Causes:**

**Firewall/Network:**
- SQLife blocked by firewall
- Add SQLife to firewall exceptions

**Proxy Required:**
- Configure proxy: **File → Preferences → Proxy Settings**
- Enter proxy host, port, credentials

**SSL Certificate Issues:**
- For SSL connections, certificate may not be trusted
- Import certificate or adjust SSL properties

**JDBC Driver Version:**
- Rare: JDBC driver incompatibility
- Check with SQLife support

### Password Not Saving

**Possible Causes:**

**"Save Password" Not Checked:**
- Ensure checkbox is selected before saving

**File System Permissions:**
- SQLife cannot write to home directory
- Check permissions on `~/.sqlife/` folder

**Encryption Issues:**
- Operating system security policy blocking
- Contact support

### Connection Suddenly Stopped Working

**Possible Causes:**

**Password Changed:**
- Database password was reset
- Update password in connection properties

**Network Change:**
- VPN disconnected
- Database server moved
- Firewall rules changed
- Solution: Verify network and server status

**Database Server Down:**
- Server maintenance or outage
- Contact database administrator

**Account Locked/Expired:**
- Too many failed login attempts
- Password expired (Oracle)
- Contact database administrator

### File Database: "File Locked" Error

**Cause:** Another process has the database file open

**Solutions:**
1. Close other applications using the file
2. Close other SQLife connections to same file
3. Restart SQLife
4. Reboot if file lock persists (rare)

### Connection Extremely Slow

**Possible Causes:**

**Network Latency:**
- High latency to database server
- Test with ping, consider VPN or network optimization

**Large Number of Database Objects:**
- Thousands of tables, views, etc.
- Loading metadata takes time
- Consider using object filter

**Database Server Overloaded:**
- High CPU/memory on database server
- Contact database administrator

**Keep-Alive Too Frequent:**
- Very low keep-alive interval (e.g., 5 seconds)
- Increase interval or disable

---

## Next Steps

Now that you know how to manage connections:

1. **Connect to your database:**
   - Use the techniques in this guide
   - Test before connecting
   - Save for future use

2. **Explore the SQL Editor:**
   - [Exploring Objects and Executing SQL](05-explore-objects-and-execute-sql.md)
   - Write and run queries
   - Format and beautify SQL

3. **Work with database objects:**
   - [Object Explorer](06-object-explorer.md)
   - Browse tables, views, procedures
   - View object definitions

4. **Edit and export data:**
   - [Export Objects and Data](07-export-object-and-data.md)
   - Edit table data
   - Export query results

5. **Customize preferences:**
   - [Change Preferences](12-change-preferences.md)
   - Set default save password option
   - Configure key mappings

---

## Tips and Best Practices

### Connection Organization

- **Use descriptive names:** Include environment and purpose
- **Organize with catalogs:** Group by project, team, or environment
- **Regular cleanup:** Delete unused connections
- **Backup regularly:** Export connections weekly or monthly

### Security

- **Production passwords:** Don't save on shared machines
- **Strong passwords:** Always use strong, unique passwords
- **Review access:** Periodically review who has access to SQLife
- **Encrypt backups:** Store backup files securely

### Performance

- **Close unused connections:** Free up memory
- **Appropriate keep-alive:** Don't set too low
- **Connection pooling:** Not needed (SQLife manages this)

### Maintenance

- **Test connections periodically:** Catch issues early
- **Update after server changes:** When servers migrate or change
- **Document special settings:** Note unusual properties or configurations

---

**You're now ready to effectively manage connections in SQLife!**

For more help, see:
- [Getting Started Guide](03-getting-started.md)

Happy connecting! 🐰