Skip to main content

When to Use Manual Installation

Manual installation using a VSIX file is useful when:
  • Your organization blocks VS Code Marketplace access
  • You need to install a specific version
  • You’re testing a pre-release version
  • You’re in an air-gapped environment
  • You want to distribute the extension internally

Obtaining the VSIX File

Download from Publisher

Contact BTSS Corp for the VSIX file:

Building from Source

If you have access to the source code:
# Clone the repository
git clone [repository-url]
cd koala-data-explorer-ext

# Install dependencies
npm install

# Build the extension
npm run vscode:prepublish

# Package the extension
npx vsce package
This creates a .vsix file in the project directory.

Installation Methods

Method 1: Using VS Code UI

  1. Open VS Code
  2. Go to Extensions view (Ctrl+Shift+X)
  3. Click the menu at the top of Extensions view
  4. Select Install from VSIX…
  5. Browse to your .vsix file
  6. Select the file and click Install
  7. Reload VS Code when prompted

Method 2: Using Command Palette

  1. Open Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
  2. Type: Extensions: Install from VSIX…
  3. Select the command
  4. Browse to your .vsix file
  5. Confirm installation

Method 3: Using Command Line

# Basic installation
code --install-extension koala-data-explorer-1.1.0.vsix

# Force installation (overwrites existing)
code --install-extension koala-data-explorer-1.1.0.vsix --force

# Install for VS Code Insiders
code-insiders --install-extension koala-data-explorer-1.1.0.vsix

Method 4: Manual Copy (Advanced)

For system-wide installation or automation:
# Windows
copy koala-data-explorer-1.1.0.vsix "%USERPROFILE%\.vscode\extensions\"
cd "%USERPROFILE%\.vscode\extensions\"
tar -xf koala-data-explorer-1.1.0.vsix

# macOS/Linux
cp koala-data-explorer-1.1.0.vsix ~/.vscode/extensions/
cd ~/.vscode/extensions/
unzip koala-data-explorer-1.1.0.vsix -d btss-corp.koala-data-explorer-1.1.0

Verification

After installation, verify the extension:

Check Extension List

  1. Open Extensions view (Ctrl+Shift+X)
  2. Search for “Koala”
  3. Verify “Koala Data Explorer” appears with correct version

Test Command Availability

  1. Open Command Palette (Ctrl+Shift+P)
  2. Type: “Koala”
  3. Verify you see “Koala Data Explorer: Open SQL Query Editor”

Check Installation Directory

# List installed extensions
code --list-extensions

# Should include:
# btss-corp.koala-data-explorer

Offline Installation

For completely offline environments:

1. Prepare Installation Package

On a machine with internet access:
# Download extension and dependencies
code --install-extension btss-corp.koala-data-explorer
cd ~/.vscode/extensions/
tar -czf koala-complete.tar.gz btss-corp.koala-data-explorer-*

2. Transfer and Install

On the offline machine:
# Extract to extensions folder
cd ~/.vscode/extensions/
tar -xzf koala-complete.tar.gz

# Restart VS Code

Managing Multiple Versions

Installing Specific Versions

Keep multiple VSIX files with version numbers:
koala-data-explorer-1.0.0.vsix
koala-data-explorer-1.0.1.vsix
koala-data-explorer-1.1.0.vsix

Switching Versions

  1. Uninstall current version
  2. Install desired version from VSIX
  3. Reload VS Code

Version Downgrade

# Uninstall current version
code --uninstall-extension btss-corp.koala-data-explorer

# Install older version
code --install-extension koala-data-explorer-1.0.0.vsix --force

Troubleshooting Manual Installation

VSIX File Not Recognized

If VS Code doesn’t recognize the VSIX file:
  • Ensure file extension is .vsix (not .zip)
  • Check file isn’t corrupted (try re-downloading)
  • Verify file permissions allow reading

Installation Permissions Error

On Windows:
# Run VS Code as Administrator
Start-Process code -Verb RunAs
On macOS/Linux:
# Fix permissions
chmod 644 koala-data-explorer-1.1.0.vsix

Extension Not Loading After Install

  1. Fully restart VS Code (not just reload)
  2. Check for conflicts with other extensions
  3. Review errors in Help → Toggle Developer Tools
  4. Clear extension cache:
    rm -rf ~/.vscode/extensions/.obsolete
    

Dependency Issues

If the extension fails due to missing dependencies:
  1. Ensure VS Code version >= 1.74.0
  2. Install Visual C++ Redistributable (Windows)
  3. Check Node.js native modules are compatible

Deployment Automation

For IT Administrators

Deploy to multiple machines using scripts: PowerShell (Windows):
# Deploy to all users
$vsixPath = "\\server\share\koala-data-explorer-1.1.0.vsix"
$users = Get-ChildItem "C:\Users" -Directory

foreach ($user in $users) {
    $codePath = Join-Path $user.FullName ".vscode\extensions"
    if (Test-Path $codePath) {
        code --install-extension $vsixPath --force
    }
}
Bash (macOS/Linux):
#!/bin/bash
# Deploy to current user
VSIX_PATH="/path/to/koala-data-explorer-1.1.0.vsix"

for user in /home/*; do
    if [ -d "$user/.vscode" ]; then
        sudo -u $(basename "$user") code --install-extension "$VSIX_PATH"
    fi
done

Using Configuration Management

Ansible Playbook:
- name: Install Koala Data Explorer
  hosts: workstations
  tasks:
    - name: Copy VSIX file
      copy:
        src: koala-data-explorer-1.1.0.vsix
        dest: /tmp/
    
    - name: Install extension
      shell: code --install-extension /tmp/koala-data-explorer-1.1.0.vsix
      become_user: "{{ ansible_user }}"

Post-Installation Configuration

After manual installation:
  1. Verify Installation: Check extension appears in list
  2. Configure Settings: Adjust timeout, logging, etc.
  3. Set Up Connection: Add Oracle Fusion credentials
  4. Activate License: Enter license key if you have one

Security Considerations

When installing manually:
Only install VSIX files from trusted sources. Verify the publisher and file integrity before installation.

Verify File Integrity

Check SHA256 hash if provided:
# Windows
certutil -hashfile koala-data-explorer-1.1.0.vsix SHA256

# macOS/Linux
sha256sum koala-data-explorer-1.1.0.vsix

Scan for Malware

Run security scans before installation:
# Example with ClamAV
clamscan koala-data-explorer-1.1.0.vsix

Next Steps

After successful manual installation: