⌘+k ctrl+k
1.1.3 (stable)
Search Shortcut cmd + k | ctrl + k
Java JDBC API

Installation

DuckDB Java JDBC API 可以从 Maven Central 安装。详情请参阅 安装页面。

Basic API Usage

DuckDB的JDBC API实现了标准Java数据库连接（JDBC）API 4.1版本的主要部分。描述JDBC超出了本页的范围，详情请参阅官方文档。下面我们重点介绍DuckDB特有的部分。

请参考外部托管的API参考以获取有关我们对JDBC规范的扩展的更多信息，或查看下面的Arrow方法。

Startup & Shutdown

在JDBC中，数据库连接是通过标准的java.sql.DriverManager类创建的。 驱动程序应该自动注册到DriverManager中，如果由于某些原因无法自动注册，您可以使用以下语句强制注册：

Class.forName("org.duckdb.DuckDBDriver");

要创建DuckDB连接，请使用DriverManager并带有jdbc:duckdb: JDBC URL前缀，如下所示：

import java.sql.Connection;
import java.sql.DriverManager;

Connection conn = DriverManager.getConnection("jdbc:duckdb:");

要使用DuckDB特定的功能，例如Appender，将对象转换为DuckDBConnection：

import java.sql.DriverManager;
import org.duckdb.DuckDBConnection;

DuckDBConnection conn = (DuckDBConnection) DriverManager.getConnection("jdbc:duckdb:");

当单独使用jdbc:duckdb: URL时，会创建一个内存数据库。请注意，对于内存数据库，没有数据会持久化到磁盘（即，当你退出Java程序时，所有数据都会丢失）。如果你想访问或创建一个持久化数据库，请在路径后附加其文件名。例如，如果你的数据库存储在/tmp/my_database，使用JDBC URL jdbc:duckdb:/tmp/my_database来创建与它的连接。

可以在只读模式下打开一个DuckDB数据库文件。例如，如果多个Java进程想要同时读取同一个数据库文件，这将非常有用。要以只读模式打开现有的数据库文件，请设置连接属性duckdb.read_only，如下所示：

Properties readOnlyProperty = new Properties();
readOnlyProperty.setProperty("duckdb.read_only", "true");
Connection conn = DriverManager.getConnection("jdbc:duckdb:/tmp/my_database", readOnlyProperty);

可以使用DriverManager创建额外的连接。更高效的机制是调用DuckDBConnection#duplicate()方法：

Connection conn2 = ((DuckDBConnection) conn).duplicate();

允许多个连接，但不支持混合读写连接和只读连接。

配置连接

可以提供配置选项来更改数据库系统的不同设置。请注意，许多这些设置稍后也可以使用PRAGMA语句进行更改。

Properties connectionProperties = new Properties();
connectionProperties.setProperty("temp_directory", "/path/to/temp/dir/");
Connection conn = DriverManager.getConnection("jdbc:duckdb:/tmp/my_database", connectionProperties);

Querying

DuckDB 支持标准的 JDBC 方法来发送查询并检索结果集。首先，需要从 Connection 创建一个 Statement 对象，然后可以使用该对象通过 execute 和 executeQuery 发送查询。execute() 用于不期望返回结果的查询，如 CREATE TABLE 或 UPDATE 等，而 executeQuery() 用于产生结果的查询（例如，SELECT）。以下是两个示例。另请参阅 JDBC Statement 和 ResultSet 文档。

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

Connection conn = DriverManager.getConnection("jdbc:duckdb:");

// create a table
Statement stmt = conn.createStatement();
stmt.execute("CREATE TABLE items (item VARCHAR, value DECIMAL(10, 2), count INTEGER)");
// insert two items into the table
stmt.execute("INSERT INTO items VALUES ('jeans', 20.0, 1), ('hammer', 42.2, 2)");

try (ResultSet rs = stmt.executeQuery("SELECT * FROM items")) {
    while (rs.next()) {
        System.out.println(rs.getString(1));
        System.out.println(rs.getInt(3));
    }
}
stmt.close();

jeans
1
hammer
2

DuckDB 也支持根据 JDBC API 的预处理语句：

import java.sql.PreparedStatement;

try (PreparedStatement stmt = conn.prepareStatement("INSERT INTO items VALUES (?, ?, ?);")) {
    stmt.setString(1, "chainsaw");
    stmt.setDouble(2, 500.0);
    stmt.setInt(3, 42);
    stmt.execute();
    // more calls to execute() possible
}

警告 请不要使用预处理语句将大量数据插入DuckDB。有关更好的选项，请参阅数据导入文档。

Arrow 方法

请参考API参考以获取类型签名

Arrow 导出

以下演示了如何导出箭头流并使用Java箭头绑定来消费它

import org.apache.arrow.memory.RootAllocator;
import org.apache.arrow.vector.ipc.ArrowReader;
import org.duckdb.DuckDBResultSet;

try (var conn = DriverManager.getConnection("jdbc:duckdb:");
    var stmt = conn.prepareStatement("SELECT * FROM generate_series(2000)");
    var resultset = (DuckDBResultSet) stmt.executeQuery();
    var allocator = new RootAllocator()) {
    try (var reader = (ArrowReader) resultset.arrowExportStream(allocator, 256)) {
        while (reader.loadNextBatch()) {
            System.out.println(reader.getVectorSchemaRoot().getVector("generate_series"));
        }
    }
    stmt.close();
}

Arrow Import

以下演示了如何使用Java Arrow绑定消费Arrow流。

import org.apache.arrow.memory.RootAllocator;
import org.apache.arrow.vector.ipc.ArrowReader;
import org.duckdb.DuckDBConnection;

// Arrow binding
try (var allocator = new RootAllocator();
     ArrowStreamReader reader = null; // should not be null of course
     var arrow_array_stream = ArrowArrayStream.allocateNew(allocator)) {
    Data.exportArrayStream(allocator, reader, arrow_array_stream);

    // DuckDB setup
    try (var conn = (DuckDBConnection) DriverManager.getConnection("jdbc:duckdb:")) {
        conn.registerArrowStream("asdf", arrow_array_stream);

        // run a query
        try (var stmt = conn.createStatement();
             var rs = (DuckDBResultSet) stmt.executeQuery("SELECT count(*) FROM asdf")) {
            while (rs.next()) {
                System.out.println(rs.getInt(1));
            }
        }
    }
}

流式结果

结果流式传输在JDBC驱动程序中是可选的——通过在运行查询之前将jdbc_stream_results配置设置为true。最简单的方法是在Properties对象中传递它。

Properties props = new Properties();
props.setProperty(DuckDBDriver.JDBC_STREAM_RESULTS, String.valueOf(true));

Connection conn = DriverManager.getConnection("jdbc:duckdb:", props);

Appender

Appender 在 DuckDB JDBC 驱动程序中通过 org.duckdb.DuckDBAppender 类提供。 该类的构造函数需要指定模式名称和所应用的表名称。 当调用 close() 方法时，Appender 会被刷新。

示例：

import java.sql.DriverManager;
import java.sql.Statement;
import org.duckdb.DuckDBConnection;

DuckDBConnection conn = (DuckDBConnection) DriverManager.getConnection("jdbc:duckdb:");
try (var stmt = conn.createStatement()) {
    stmt.execute("CREATE TABLE tbl (x BIGINT, y FLOAT, s VARCHAR)"
);

// using try-with-resources to automatically close the appender at the end of the scope
try (var appender = conn.createAppender(DuckDBConnection.DEFAULT_SCHEMA, "tbl")) {
    appender.beginRow();
    appender.append(10);
    appender.append(3.2);
    appender.append("hello");
    appender.endRow();
    appender.beginRow();
    appender.append(20);
    appender.append(-8.1);
    appender.append("world");
    appender.endRow();
}

Batch Writer

DuckDB JDBC 驱动程序提供了批量写入功能。 批量写入器支持预处理语句，以减少查询解析的开销。

批量插入的首选方法是使用Appender，因为它的性能更高。 然而，当无法使用Appender时，批量写入器可以作为替代方案。

使用预编译语句的批量写入器 

import java.sql.DriverManager;
import java.sql.PreparedStatement;
import org.duckdb.DuckDBConnection;

DuckDBConnection conn = (DuckDBConnection) DriverManager.getConnection("jdbc:duckdb:");
PreparedStatement stmt = conn.prepareStatement("INSERT INTO test (x, y, z) VALUES (?, ?, ?);");

stmt.setObject(1, 1);
stmt.setObject(2, 2);
stmt.setObject(3, 3);
stmt.addBatch();

stmt.setObject(1, 4);
stmt.setObject(2, 5);
stmt.setObject(3, 6);
stmt.addBatch();

stmt.executeBatch();
stmt.close();

使用原生语句的批量写入器

批处理写入器还支持普通的SQL语句：

import java.sql.DriverManager;
import java.sql.Statement;
import org.duckdb.DuckDBConnection;

DuckDBConnection conn = (DuckDBConnection) DriverManager.getConnection("jdbc:duckdb:");
Statement stmt = conn.createStatement();

stmt.execute("CREATE TABLE test (x INTEGER, y INTEGER, z INTEGER)");

stmt.addBatch("INSERT INTO test (x, y, z) VALUES (1, 2, 3);");
stmt.addBatch("INSERT INTO test (x, y, z) VALUES (4, 5, 6);");

stmt.executeBatch();
stmt.close();

Troubleshooting

未找到驱动程序类

如果Java应用程序无法找到DuckDB，它可能会抛出以下错误：

Exception in thread "main" java.sql.SQLException: No suitable driver found for jdbc:duckdb:
    at java.sql/java.sql.DriverManager.getConnection(DriverManager.java:706)
    at java.sql/java.sql.DriverManager.getConnection(DriverManager.java:252)
    ...

当尝试手动加载类时，可能会导致此错误：

Exception in thread "main" java.lang.ClassNotFoundException: org.duckdb.DuckDBDriver
    at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:641)
    at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:188)
    at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:520)
    at java.base/java.lang.Class.forName0(Native Method)
    at java.base/java.lang.Class.forName(Class.java:375)
    ...

这些错误源于未检测到DuckDB Maven/Gradle依赖项。为确保其被检测到，请在您的IDE中强制刷新Maven配置。

关于此页面