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

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, 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:

# 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 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 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 processes the JSON payload through several stages:

1. Decryption: If a 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 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 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

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

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

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 manages the flow, while dbeaverImport.ts and 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 with an optional 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 and apps/desktop/src/lib/imports/navicatImport.ts respectively.

Where does DBX store imported connections?

After parsing, importConnectionsFromFile in 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 to handle both formats automatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}