如何在 Java 中正确连接 Apache Derby 数据库

本文详解解决 java 连接 derby 时出现 `classnotfoundexception: org.apache.derby.jdbc.clientdriver` 的根本原因与完整配置方案，涵盖 netbeans ide 配置、maven/gradle 依赖管理及命令行运行方式。

Apache Derby 是一个纯 Java 编写的轻量级嵌入式/网络数据库，常用于教学、原型开发和测试环境。但在 Java 项目中首次集成 Derby 时，开发者常遇到如下运行时异常：

java.lang.ClassNotFoundException: org.apache.derby.jdbc.ClientDriver

该错误并非代码逻辑错误，而是类路径（Classpath）缺失导致的典型部署问题：JVM 在运行时无法加载 Derby 提供的 JDBC 驱动类。ClientDriver 是 Derby 网络客户端模式（即通过 jdbc:derby:// URL 连接远程或独立 Derby Network Server）所需的驱动类；若使用嵌入式模式（jdbc:derby:），则应使用 org.apache.derby.jdbc.EmbeddedDriver —— 但无论哪种模式，驱动 JAR 文件都必须显式加入类路径。

✅ 正确配置步骤（三选一）

1. NetBeans IDE 中添加 Derby JAR（推荐新手）

• 下载对应版本的 Derby 发行包（如 Derby 10.16.1.1），解压后定位到 lib/ 目录；
• 关键 JAR 文件说明：
  • derbyclient.jar → 用于 Client/Server 模式（需启动 Network Server）；
  • derby.jar → 用于 Embedded 模式（无需服务端，数据库直接内嵌于 JVM）；
  • derbytools.jar → 可选，含 ij 工具等（非必需）。
• 在 NetBeans 中右键项目 → Properties → Libraries → Add JAR/Folder → 选择 derbyclient.jar（网络模式）或 derby.jar（嵌入模式）→ 点击 OK。

⚠️ 注意：NetBeans 自带的“Derby Database”服务仅用于 IDE 内部管理，不会自动将驱动注入你的项目 classpath，必须手动添加。

2. Maven 项目（pom.xml）

根据使用场景选择依赖（推荐 derbyclient 以支持标准 JDBC URL）：

    org.apache.derby
    derbyclient
    10.16.1.1

如需嵌入式模式，改用：

    org.apache.derby
    derby
    10.16.1.1

Maven 会自动解析并加入运行时 classpath，无需额外配置。

3. 命令行运行（无构建工具）

确保 derbyclient.jar（或 derby.jar）与你的 .class 文件

同处可访问路径，并在执行时显式指定：

# Linux/macOS
java -cp ".:./lib/derbyclient.jar" com.example.DerbyConnectionDemo

# Windows（注意分号）
java -cp ".;.\lib\derbyclient.jar" com.example.DerbyConnectionDemo

✅ 连接代码示例（Client Mode）

确认驱动就位后，即可安全调用：

import java.sql.*;

public class DerbyConnectionDemo {
    public static void main(String[] args) {
        String url = "jdbc:derby://localhost:1527/mydb;create=true";
        try {
            // 显式加载驱动（Java 6+ 可省略，但显式调用更清晰）
            Class.forName("org.apache.derby.jdbc.ClientDriver");

            Connection conn = DriverManager.getConnection(url, "username", "password");
            System.out.println("✅ 成功连接 Derby 数据库！");
            conn.close();
        } catch (ClassNotFoundException e) {
            System.err.println("❌ 驱动类未找到：请检查 derbyclient.jar 是否在 classpath 中");
            e.printStackTrace();
        } catch (SQLException e) {
            System.err.println("❌ 数据库连接失败：" + e.getMessage());
            e.printStackTrace();
        }
    }
}

? 补充说明与最佳实践

• 版本一致性至关重要：derbyclient.jar 与 derby.jar（服务端）版本必须严格一致，否则可能引发 IncompatibleVersionException；
• 嵌入式 vs 网络模式选择：
  • 嵌入式（EmbeddedDriver + derby.jar）：单应用、无并发写入需求、零配置启动；
  • 网络模式（ClientDriver + derbyclient.jar + 启动 NetworkServer）：支持多客户端、JDBC 标准兼容性更好；
• 启动 Derby Network Server（如需）：

  java -jar $DERBY_HOME/lib/derbynet.jar start

• 推荐查阅官方最新文档：Apache Derby Getting Started Guide

只要确保驱动 JAR 正确引入 classpath，并匹配使用模式（Client/Embedded），ClassNotFoundException 即可彻底消除——这是 Derby 集成中最常见也最易解决的“第一步障碍”。