启动HSQL Database Engine Server模式出现Connection Refused错误如何解决

连接错误SQLTransientConnectionException: Connection Refused排查步骤 #

• 确认服务端启动参数合规
  正确的Server模式启动命令参考如下：

  java -cp hsqldb.jar org.hsqldb.server.Server --database.0 file:./mydb --dbname.0 mydb --address 0.0.0.0 --port 9001
  

  重点校验参数：
  • --address：如果仅本机访问可设为127.0.0.1，如果需要其他机器访问必须设为0.0.0.0，错误绑定到无对应网卡的地址会直接导致连接被拒
  • --port：默认端口为9001，确保该端口未被其他进程占用
    启动后观察控制台输出，确认有Server[#]: Startup completed in X ms提示后再尝试连接，若启动过程有报错先解决启动异常问题。
• 校验端口监听与防火墙规则
  服务启动后执行端口检查命令：
  • Windows：netstat -ano | findstr 9001
  • Linux/macOS：ss -tulpn | grep 9001
    确认HSQLDB进程正在监听对应端口后，检查本机防火墙是否放行对应端口的入站连接，避免防火墙拦截请求导致连接被拒。
• 确认客户端连接串配置正确
  Server模式的JDBC连接串标准格式为：jdbc:hsqldb:hsql://[服务端IP]:[端口]/[dbname]，例如本地启动的服务连接串为jdbc:hsqldb:hsql://127.0.0.1:9001/mydb
  校验点：
  • IP、端口与服务端启动参数完全一致
  • dbname与启动时--dbname.0后的参数完全匹配，不要误写为数据库文件名称
  • 账号密码默认是sa/空，自定义过账号密码的要对应配置

多客户端同时连接注意事项 #

要实现Java应用、DBeaver同时连接同一个HSQL实例，需满足以下要求：

• 严禁使用文件模式（jdbc:hsqldb:file:开头的连接串）启动实例，该模式默认加排他锁，仅允许一个客户端连接
• 服务启动时可添加--readonly false参数，确保所有客户端都有写入权限
• 连接串末尾可追加;hsqldb.write_delay=false参数，关闭写入延迟，避免DBeaver无法实时查询到Java应用刚写入的数据
• 确保服务启动时--database.0指定的数据库文件路径有读写权限，避免数据持久化失败导致服务异常

内容的提问来源于stack exchange，提问作者sabasedigh