# How to Import Connections from DBeaver or Navicat into DBX: A Complete Guide

> Easily import DBeaver or Navicat connections into DBX. Follow this guide to use the Import Connections dialog and convert your existing database configurations into DBX's unified ConnectionConfig objects.

- Repository: [skyler/dbx](https://github.com/t8y2/dbx)
- Tags: how-to-guide
- Published: 2026-07-10

---

**You can import connections from DBeaver or Navicat into DBX using the Settings → Import Connections dialog, which parses DBeaver's JSON exports or Navicat's NCX files and converts them into DBX's unified `ConnectionConfig` objects.**

DBX is an open-source database management tool that provides a seamless migration path from popular clients like DBeaver and Navicat. Whether you are transitioning teams or consolidating your database workflow, you can import connections from DBeaver or Navicat into DBX without manually recreating each configuration.

## Understanding the Import Architecture

The import system in the `t8y2/dbx` repository follows a modular architecture that separates UI concerns from parsing logic.

### The User Interface Entry Point

The import flow begins in **Settings → Import Connections** (also accessible via the sidebar context menu). According to [`apps/desktop/src/stores/connectionStore.ts`](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/stores/connectionStore.ts), the `readImportFile` method opens a file picker filtered for specific formats:

- **DBeaver**: `.json` data-source files with optional companion credentials files
- **Navicat**: `.ncx` or `.xml` export files

### Parser Modules and Normalization

Once selected, the file content is normalized into a payload structure. **DBeaver** imports wrap the data in `{ format: "dbeaver-import", dataSources, credentialsBase64 }`, while **Navicat** imports pass raw XML directly to the parser.

## Step-by-Step Import Process

Migrating your existing connections requires locating the source files and running them through DBX's import pipeline.

### Locating Your Source Files

For **DBeaver**, connection definitions reside in your workspace directory:

```bash

# Linux/macOS

~/.local/share/DBeaverData/workspace*/General/.dbeaver/data-sources.json

# Windows

%USERPROFILE%\AppData\Roaming\DBeaverData\workspace*\General\.dbeaver\data-sources.json

```

You may also find a [`credentials-config.json`](https://github.com/t8y2/dbx/blob/main/credentials-config.json) file in the same directory if passwords were saved.

For **Navicat**, open the application and select **File → Export Connections** to generate a `.ncx` file.

### Running the Import in DBX

1. Open **Settings → Import Connections** in the DBX desktop application.
2. Select your source tool (DBeaver or Navicat) from the dropdown.
3. Choose the exported file when prompted.
4. Review the summary toast that displays the number of connections parsed.

### Post-Import Configuration

After `importConnectionsFromFile` in [`connectionStore.ts`](https://github.com/t8y2/dbx/blob/main/connectionStore.ts) aggregates the results into the sidebar state, you must manually enter any missing passwords. Encrypted passwords from the source tools cannot be recovered during the import process.

## Technical Implementation Details

The import functionality relies on specialized parsers that handle format-specific encryption and schema mapping.

### How DBeaver Imports Work

The `parseDbeaverConnections` function in [`apps/desktop/src/lib/imports/dbeaverImport.ts`](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/lib/imports/dbeaverImport.ts) processes the JSON payload through several stages:

1. **Decryption**: If a [`credentials-config.json`](https://github.com/t8y2/dbx/blob/main/credentials-config.json) is provided, the parser decrypts it using AES-CBC with a hard-coded key.
2. **Extraction**: Each connection entry is extracted and deduplicated using a composite key.
3. **Mapping**: The function infers the database type from driver/provider strings and constructs a unified `ConnectionConfig` object.

### How Navicat Imports Work

The `parseNavicatConnections` function in [`apps/desktop/src/lib/imports/navicatImport.ts`](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/lib/imports/navicatImport.ts) handles XML parsing:

1. **XML Parsing**: Uses `DOMParser` to walk the NCX XML structure.
2. **Profile Inference**: Normalizes attribute names and infers the database profile from `connType`, `driver`, or numeric codes.
3. **Password Decryption**: Decrypts passwords using AES-CBC with the static vectors "libcckey" and "libcciv".
4. **Object Creation**: Generates `ConnectionConfig` objects compatible with DBX's internal state.

### The Integration Layer

The `importConnectionsFromFile` function in [`connectionStore.ts`](https://github.com/t8y2/dbx/blob/main/connectionStore.ts) acts as the dispatcher. It inspects the payload shape to determine which parser to invoke, aggregates the resulting `ConnectionConfig[]` array, and updates the sidebar state. After successful import, the UI displays a success toast indicating the count of imported connections.

## Programmatic Import Examples

You can also trigger imports programmatically using the internal parser modules.

### Importing Navicat Connections via Code

```typescript
import { parseNavicatConnections } from '@/lib/imports/navicatImport';
import { readFile } from 'fs/promises';

async function importNavicat(path: string) {
  const xml = await readFile(path, 'utf8');
  const connections = await parseNavicatConnections(xml);
  console.log(`Parsed ${connections.length} Navicat connections`);
  // Insert `connections` into DBX state or export as DBX JSON
}

```

### Importing DBeaver Connections via Code

```typescript
import { parseDbeaverConnections } from '@/lib/imports/dbeaverImport';
import { readFile } from 'fs/promises';

async function importDbeaver(dataSourcesPath: string, credentialsPath?: string) {
  const dataSources = await readFile(dataSourcesPath, 'utf8');
  const credentialsBase64 = credentialsPath
    ? Buffer.from(await readFile(credentialsPath)).toString('base64')
    : '';

  const payload = JSON.stringify({
    format: 'dbeaver-import',
    dataSources,
    credentialsBase64,
  });

  const connections = await parseDbeaverConnections(payload);
  console.log(`Parsed ${connections.length} DBeaver connections`);
}

```

### Using the High-Level Store Helper

```typescript
import { importConnectionsFromFile } from '@/stores/connectionStore';

// `content` is the raw file text the user selected; `passphrase` is null for plain imports
const result = await importConnectionsFromFile(fileContent, null);
console.log(`Imported ${result.count} connections`);

```

## Limitations and Considerations

While DBX handles most connection metadata automatically, certain limitations exist:

- **Encrypted passwords** from DBeaver or Navicat cannot be recovered during import. You must re-enter these manually in the DBX connection editor.
- **Custom JDBC drivers** or proprietary connection extensions may not map cleanly to DBX's supported database profiles.
- **SSH tunnel configurations** from external tools require verification after import to ensure key paths and authentication methods align with DBX's implementation.

## Summary

- **Import Entry Point**: Access via **Settings → Import Connections** in the DBX desktop UI.
- **Supported Formats**: DBeaver `.json` data-sources (with optional credentials) and Navicat `.ncx` XML exports.
- **Key Files**: [`connectionStore.ts`](https://github.com/t8y2/dbx/blob/main/connectionStore.ts) manages the flow, while [`dbeaverImport.ts`](https://github.com/t8y2/dbx/blob/main/dbeaverImport.ts) and [`navicatImport.ts`](https://github.com/t8y2/dbx/blob/main/navicatImport.ts) handle format-specific parsing.
- **Password Handling**: Encrypted passwords cannot be migrated; plan to re-enter authentication credentials after import.
- **Programmatic Access**: Use `parseDbeaverConnections`, `parseNavicatConnections`, or `importConnectionsFromFile` for automated workflows.

## Frequently Asked Questions

### Can I import encrypted passwords from DBeaver or Navicat?

No. While DBX attempts to decrypt credential files using AES-CBC algorithms (with hard-coded keys for DBeaver and static vectors "libcckey"/"libcciv" for Navicat), successful decryption depends on specific legacy formats. In most cases, you will need to re-enter passwords manually after the import completes.

### What file formats does DBX support for importing connections?

DBX supports **DBeaver** `.json` data-source files (typically named [`data-sources.json`](https://github.com/t8y2/dbx/blob/main/data-sources.json) with an optional [`credentials-config.json`](https://github.com/t8y2/dbx/blob/main/credentials-config.json) companion) and **Navicat** `.ncx` or `.xml` export files. These formats are parsed by dedicated modules in [`apps/desktop/src/lib/imports/dbeaverImport.ts`](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/lib/imports/dbeaverImport.ts) and [`apps/desktop/src/lib/imports/navicatImport.ts`](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/lib/imports/navicatImport.ts) respectively.

### Where does DBX store imported connections?

After parsing, `importConnectionsFromFile` in [`apps/desktop/src/stores/connectionStore.ts`](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/stores/connectionStore.ts) aggregates the connections into DBX's reactive sidebar state. The configurations are persisted as `ConnectionConfig` objects within the application's internal storage, not as separate files in the source format.

### Can I automate the import process without using the GUI?

Yes. You can programmatically import connections using the internal parser modules. Import `parseDbeaverConnections` or `parseNavicatConnections` from their respective files in `apps/desktop/src/lib/imports/`, or use the high-level `importConnectionsFromFile` helper from [`connectionStore.ts`](https://github.com/t8y2/dbx/blob/main/connectionStore.ts) to handle both formats automatically.