# Getting Started with SQLife

This guide will help you get up and running with SQLife quickly.

## Table of Contents
- [First Launch](#first-launch)
- [Setting Your Language](#setting-your-language)
- [Creating Your First Connection](#creating-your-first-connection)
- [Understanding the Interface](#understanding-the-interface)
- [Running Your First Query](#running-your-first-query)
- [Browsing Database Objects](#browsing-database-objects)
- [Next Steps](#next-steps)

---

## First Launch

When you launch SQLife for the first time, the application will:

1. **Create application directory** in your home folder (`~/.sqlife/`)
2. **Initialize local database** for storing settings and connections
3. **Show the main window** with the connection manager

### License Activation (Optional)

If this is your first time:
- **Trial Mode:** You can evaluate SQLife for free
- **Licensed Use:** Go to **Help → License** and enter your license key

For now, you can proceed with the trial or skip this step.

---

## Setting Your Language

SQLife supports more than 10 languages. To change the language:

1. Open **Preferences**:
   - **Windows/Linux:** File → Preferences (or press **Ctrl + ,**)
   - **macOS:** SQLife → Preferences (or press **Cmd + ,**)

2. Navigate to **General** section

3. Select your preferred language from the **Language** dropdown

4. Click **OK** or **Apply**

5. **Restart SQLife** for the language change to take effect

---

## Creating Your First Connection

### Oracle Database Connection

1. **Open Connection Manager:**
   - Click the **New Connection** tab, or
   - Press **Cmd/Ctrl + N**

2. **Enter connection details:**
   - **Connection Name:** Give it a meaningful name (e.g., "Development DB")
   - **Database Type:** Oracle
   - **Host:** Database server address (e.g., `localhost` or `192.168.1.100`)
   - **Port:** Default is `1521`
   - **SID/Service Name:** Your database identifier (e.g., `ORCL`)
   - **Username:** Database user (e.g., `SCOTT`)
   - **Password:** User password

> if Oracle database provide service over Service Name, you probably need to add a slash "/" before service name.

3. **Advanced options** (optional):
   - **Role:** NORMAL, SYSDBA, or SYSOPER
   - **Connection Type:** Basic or TNS

4. **Test the connection:**
   - Click **Test Connection** button
   - Wait for the result
   - If successful, you'll see a success message
   - If it fails, check your credentials and network connectivity

5. **Save the connection:**
   - Click **Save** button
   - Your connection appears in the connections list

6. **Connect:**
   - Double-click the connection, or
   - Right-click and select **Connect**

### MySQL Database Connection

1. Open Connection Manager (Cmd/Ctrl + N)

2. Enter connection details:
   - **Connection Name:** (e.g., "MySQL Local")
   - **Database Type:** MySQL
   - **Host:** `localhost` or server address
   - **Port:** Default is `3306`
   - **Database:** Database name (e.g., `myapp`)
   - **Username:** (e.g., `root`)
   - **Password:** User password

3. Test and save as described above

### PostgreSQL Database Connection

1. Open Connection Manager (Cmd/Ctrl + N)

2. Enter connection details:
   - **Connection Name:** (e.g., "Postgres Dev")
   - **Database Type:** PostgreSQL
   - **Host:** `localhost` or server address
   - **Port:** Default is `5432`
   - **Database:** Database name (e.g., `postgres`)
   - **Username:** (e.g., `postgres`)
   - **Password:** User password

3. Test and save as described above

### SQLite Database Connection

1. Open Connection Manager (Cmd/Ctrl + N)

2. Enter connection details:
   - **Connection Name:** (e.g., "Local SQLite")
   - **Database Type:** SQLite
   - **Database File:** Click **Browse** and select your `.db` file

3. Test and save

> Other databases' connection are similar.

---

## Understanding the Interface

Once connected, you'll see the main SQLife interface:

### Main Window Layout

```
┌────────────────────────────────────────────────────────────────────────┐
│ Menu Bar (File, Edit, Database, View, Help)                            │
├────────────────────────────────────────────────────────────────────────┤
│ Toolbar (New, Open, Save, Run, etc.)                                   │
├──────────┬─────────────────────────────────────────────────────────────┤
│          │ Tab Bar (Connection/Workbench Tabs)                         │
│          ├─────────────────────────────────────────────────────────────┤
│ Side     │                                                             │
│ Bar      │  SQL Editor                                                 │
│          │  (Write your queries here)                                  │
│ - Objects│                                                             │
│ - Scripts│─────────────────────────────────────────────────────────────│
│          │  Data View / Results                                        │
│          │  (Query results appear here)                                │
├──────────┴─────────────────────────────────────────────────────────────┤
│ Status Bar (Messages, Position, Encoding, Current Schema, etc.)        │
└────────────────────────────────────────────────────────────────────────┘
```

### Key Areas

1. **Menu Bar:** Access all application features
2. **Toolbar:** Quick access to common operations
3. **Tab Bar:** Multiple workbenches and file tabs
4. **Side Bar (Left):** Navigate database objects and files
   - **Objects Tab:** Browse schemas, tables, views, etc.
   - **Scripts Tab:** Access workspace files and Git repository
5. **SQL Editor:** Write and edit SQL queries
6. **Data View:** View and edit query results
7. **Status Bar:** Shows messages, cursor position, encoding, current schema, etc.

### Side Bar - Objects Tab

The Objects tab shows your database structure:

- **Schema dropdown:** Select which schema to browse
- **Object tree:**
  - 📁 Tables
  - 📁 Views
  - 📁 Procedures
  - 📁 Functions
  - 📁 Indexes
  - 📁 Triggers
  - 📁 Sequences
  - (And more, depending on database type)

**Filter objects:** Type in the filter box to quickly find objects

### Side Bar - Scripts Tab

The Scripts tab shows your workspace:

- **File tree:** Browse local SQL files
- **Filter:** Search for specific files
- **Git integration:** If your workspace is a Git repository, you can view file history

### Side Bar - Outline Tab

The Outline tab displays a **real-time hierarchical tree view** of the SQL blocks in your currently active editor.

- **Automatic parsing:** As you type, SQLife parses your SQL in the background and updates the tree
- **Block types shown:** Procedures `[PROC]`, Functions `[FUNC]`, Packages `[PKG]`, Triggers `[TRIG]`, Views `[VIEW]`, SQL statements `[SQL]`, and anonymous blocks `[BLOCK]`
- **Navigate by click:** Click any block in the tree to jump the editor caret directly to that block's location
- **Popup mode:** Open the outline as a floating window via the keyboard shortcut for quick navigation across large SQL files

### Side Bar - Function Tab

The Function tab provides a **searchable list of built-in database functions and routines** for the connected database type.

- **Search:** Type in the filter box to find functions by name or description
- **Double-click to insert:** Double-click a function to insert its name into the active SQL editor
- **Rich info:** Each entry shows the function name along with its description/comment
- **Auto-loaded:** Functions are loaded from a cached catalog of the connected database's built-in routines after connection

### Side Bar - SFTP Tab

The SFTP tab provides an **embedded remote file browser** for connecting to servers via SSH/SFTP.

- **Connection management:** Select from saved SFTP connections, or add a new one with host, port, user, and authentication (password or key-based)
- **Browse remote files:** View files with name, permissions, size, and modification date; double-click directories to navigate
- **File operations:** Upload, download, create new files/folders, rename, and delete — all from the context menu
- **Open in editor:** Open remote text files (`.sql`, `.xml`, `.json`, `.properties`, etc.) directly in the SQL editor; saving auto-uploads changes back
- **Progress tracking:** Upload and download progress is shown in the file table with a cancel option


---

## Running Your First Query

### Write a Simple Query

1. In the SQL Editor area, type a simple query:

   **For Oracle:**
   ```sql
   SELECT * FROM DUAL;
   ```

   **For MySQL:**
   ```sql
   SELECT 1 + 1 AS result;
   ```

   **For PostgreSQL:**
   ```sql
   SELECT version();
   ```

2. **Execute the query:**
   - Press **Ctrl/Command + Enter**, or
   - Click the **Run** button in the toolbar, or
   - Use menu: **Database → Run**

3. **View results:**
   - Results appear in the Data View below the editor
   - You'll see rows, columns, and values

### Run Selected SQL

If you have multiple statements, you can run just one:

1. Select the SQL statement you want to run
2. Press **Ctrl/Command + Enter** or click **Run**
3. Only the selected SQL is executed

### Run Multiple Statements

To run multiple statements in sequence:

1. Write multiple statements (separated by semicolons for most databases)
2. Make sure **no SQL is selected**
3. Press **Ctrl/Command + Enter** or click **Run**
4. Each statement executes in order
5. Multiple result sets appear in tabs

### Commit and Rollback

SQLife uses **manual commit mode** (autocommit = false):

- **Commit changes:** Press **Cmd/Ctrl + Shift + C** or **Database → Commit**
- **Rollback changes:** Press **Cmd/Ctrl + Shift + R** or **Database → Rollback**

**Important:** Remember to commit INSERT, UPDATE, DELETE statements!

> Some analysis database do not support transaction.
---

## Browsing Database Objects

### Viewing Table Data

1. **Expand the Tables folder** in the Objects tab
2. **Right-click a table**
3. Select **Query Data**
4. The table data loads in the Data View

### Viewing Table Structure

1. **Right-click a table**
2. Select **Property**
3. The table property window opens, showing:
   - Basic information
   - Columns and data types
   - Indexes
   - Constraints
   - Triggers
   - Partitions (if any)

### Viewing Object Definition (DDL)

To see the SQL that creates an object:

1. **Right-click any object** (table, view, procedure, etc.)
2. Select **Object Definition**
3. The DDL appears in a new editor tab

### Editing Table Data

1. **Right-click a table**
2. Select **Edit Data**
3. The data view opens in **edit mode** (unlocked)
4. Click cells to edit values
5. Use the toolbar:
   - **Add Row:** Insert new row
   - **Remove Row:** Delete selected rows
   - **Save:** Commit changes to database
   - **Refresh:** Reload data

**Note:** See [Exploring Objects and Executing SQL](05-explore-objects-and-execute-sql.md) and [Object Explorer](06-object-explorer.md) for detailed editing instructions.

---

## Tips for New Users

### Keyboard Shortcuts

Learn these essential shortcuts:

| Action | Windows/Linux | macOS |
|--------|---------------|-------|
| New File | Ctrl + N | Cmd + N |
| Open File | Ctrl + O | Cmd + O |
| Save File | Ctrl + S | Cmd + S |
| Run Query | Ctrl + Enter | Cmd + Enter |
| Commit | Ctrl + Shift + C | Cmd + Shift + C |
| Rollback | Ctrl + Shift + R | Cmd + Shift + R |
| Format SQL | Ctrl + Shift + F | Cmd + Shift + F |
| Find | Ctrl + F | Cmd + F |
| Replace | Check Key Mapping | Check Key Mapping |
| Comment/Uncomment | Ctrl + / | Cmd + / |
| Trigger Suggestion | Ctrl + Shift + P | Cmd + Shift + P |
| Outline tab | Ctrl + O | Cmd + O |
| Quick Query | Alt + Space | Option + Space |
| Preferences | Ctrl + , | Cmd + , |

Shortcuts are configurable. Check **Preferences -> Key Mapping** for the current assignment.

### SQL Editor Features

- **Syntax highlighting:** SQL keywords are colored
- **Auto-completion:** Press **Ctrl + Space** for suggestions
- **Code formatting:** Press **Ctrl + Shift + F** to format
- **Line numbers:** Visible on the left
- **Error highlighting:** Syntax errors are underlined

### Working with Multiple Tabs

- **New workbench tab:** Click **+** in the tab bar
- **Close tab:** Click **×** on the tab
- **Rename tab:** Double-click the tab title
- **Clone tab:** Right-click and select **Clone**
- **Close others:** Right-click and select **Close Others**

### Saving Your Work

- **SQL files:** Use **File → Save** (Ctrl/Cmd + S)
- **Auto-recovery:** SQLife auto-saves state for crash recovery
- **Connection backup:** Use **File → Backup Connections** regularly

### Getting Help

- Press **F1** or **Help → Help** for online documentation
- Check **Help → About** for version information
- Visit the [FAQ](../faq.md) for common questions

---

## Common First-Time Tasks

### Task 1: Query a Table

```sql
-- Example for Oracle
SELECT employee_id, first_name, last_name, email
FROM employees
WHERE department_id = 10;
```

1. Write the query in the editor
2. Press Ctrl/Command + Enter to execute
3. View results in the Data View

### Task 2: Insert Data

```sql
-- Example
INSERT INTO employees (employee_id, first_name, last_name, email, hire_date)
VALUES (1001, 'John', 'Doe', 'jdoe@company.com', SYSDATE);
```

1. Write the INSERT statement
2. Press Ctrl/Command + Enter to execute
3. **Important:** Press Ctrl/Cmd + Shift + C to commit!

### Task 3: Export Query Results

1. Run a query to get results
2. Click the **Export** button in the Data View toolbar
3. Choose format (Excel, CSV, etc.)
4. Select location and click Export

### Task 4: Import Data from Excel

1. Go to **Database → Import**
2. Select target table
3. Choose Excel file
4. Map columns
5. Click Import

See [Export Objects and Data](07-export-object-and-data.md) and [Import Data](08-import-data.md) for details.

---

## Next Steps

Now that you're familiar with the basics:

1. **Explore more features:**
   - [Connection Management](04-connection-management.md) - Manage multiple connections
   - [Exploring Objects and Executing SQL](05-explore-objects-and-execute-sql.md) - Master the editor features
   - [Object Explorer](06-object-explorer.md) - Navigate database objects
   - [Export Objects and Data](07-export-object-and-data.md) - Export database objects (DDL) and data
   - [Import Data](08-import-data.md) - Import data from Excel, CSV, and TSV files

2. **Customize SQLife:**
   - [Change Preferences](12-change-preferences.md) - Personalize your experience

3. **Try advanced features:**
   - [Execute SQL Script File](09-execute-sql-script-file.md), [Oracle Scheduler](10-oracle-scheduler.md), [Database Document Viewer](11-database-document-viewer.md)

---

**Congratulations!** You're now ready to use SQLife for your database management tasks.

Happy querying! 🐰