This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Table of contents

• Legacy CSV driver
• CSV Files driver connection settings
• Features and capabilities
  • Advanced SQL query capabilities
  • Structuring CSV files with a schema
    • Why use a DDL file
    • How to create a DDL file
  • Folder structure
  • Internal database
  • Additional features

This guide provides instructions on how to set up and use CSV files with DBeaver. The CSV Pro driver allows you to work with CSV data as if it were in a database. You can retrieve data and apply filters, sorting, and other operations, even combining data from multiple files.

Important: When using the CSV Pro driver, all connected CSV files are read-only. To make changes, you need to update the original files outside DBeaver.

Before you start, you need to create a connection in DBeaver and select the CSV Pro driver. If you haven’t done this, see our Database Connection article.

Legacy CSV driver

In the Community Edition, a legacy CSV Basic driver is available. It supports only simple operations.

CSV Files driver connection settings

This section describes how to set up a connection using the CSV Pro driver. The connection settings page requires the following fields:

Field	Description
Connect by (Path/URL)	Choose whether to connect using a local host path or a URL.
File paths	Specify the location of the CSV file(s). Choose an action: - Edit: Modify an existing file or folder selection. - Add: Add a new file or folder. - Remove: Delete a selected file or folder. When Editing or Adding, choose from: - File: Select a single file. - Folder: Choose a directory containing multiple CSV files. For more details, see Folder structure section. - Remote: Access a remote folder via Cloud Storage. This feature is available only in Ultimate and Team Editions.
Driver name	This field will be auto-filled based on your selected driver type.
Driver settings	If there are any specific driver settings, configure them here.

For details on driver properties, see File-based driver properties.

Tip: When using the Folder option, DBeaver scans the directory up to two levels deep for CSV files. For more information, see folder structure. If you select a folder, DBeaver organizes files in schemas based on their directory structure.

Features and capabilities

Advanced SQL query capabilities

The CSV Pro driver supports the full range of SQL queries:

• Simple queries (e.g., SELECT * FROM table): Data is read directly from the CSV file.
• Complex queries (e.g., using WHERE, JOIN, ORDER BY, GROUP BY): When a complex query is executed for the first time, the driver imports the entire CSV file into an internal database to enable advanced SQL functions. Subsequent queries run faster because the data is already imported into internal database.

Structuring CSV files with a schema

CSV files don’t include metadata about their structure, such as column names or data types. To enhance how DBeaver interprets these files, you can define a schema using a DDL (Data Definition Language) file.

Why use a DDL file

A DDL file helps DBeaver interpret your data more accurately by defining:

• Column names
• Data types
• Optional indexes for better performance

How to create a DDL file

1. Create a .ddl file with the same name as your CSV file, placing it in the same directory (e.g., employees.csv and employees.csv.ddl).
2. Write a schema using the CREATE TABLE statement:

CREATE TABLE employees (
  id INTEGER,
  name TEXT NOT NULL,
  age INTEGER,
  department TEXT
  );
  CREATE INDEX idx_employees_id ON employees (id);

You can also use the WITH clause to set a data range - add firstRow and rowCount to your CREATE TABLE statement:

WITH (firstRow = 2, rowCount = 100)

• firstRow - row number to start reading from (default: 1)
• rowCount - maximum number of rows to read

Tip: You can also set firstRow and rowCount in the connection properties. DDL file settings take priority.

Important: If the DDL file contains errors, DBeaver will ignore it. You can still query the file, but column types will be inferred from the data.

Folder structure

When working with a folder containing multiple CSV files, DBeaver organizes them as follows:

Folder structure	Schema in DBeaver
Root files	Default schema
Subfolder files	Schema named after the subfolder
Files in deeper folders	Ignored

If your folder looks like this:

Data/
├── employees.csv
├── sales.csv
└── Reports/
    └── monthly.csv
    └── yearly.csv

DBeaver will create:

• Default schema: employees, sales
• Reports schema: monthly, yearly

Tip: To focus on specific files, consider selecting individual files or folders when configuring the connection.

Internal database

When you execute a complex query (such as WHERE, JOIN, GROUP BY, or ORDER BY.), on an CSV file for the first time, the CSV Pro driver processes the data by importing it into a temporary internal SQLite database.

By default, this internal database stores data temporarily on the disk during your session and is cleared when DBeaver restarts. To speed up queries on the same file in future sessions, you can specify the internalDbFilePath option in the Driver properties tab (e.g., C:\User\database.db) to reuse the processed data.

Additional features

DBeaver provides additional features compatible with CSV Pro driver, but not exclusive to it:

Category	Feature
Data Transfer	Data Export
Data Visualization	Visual Query Builder
	Charts