4、数据库环境搭建（PostgreSQL）：PostgreSQL 14/15安装、创建数据库与用户、初始化表结构（schema.sql）、配置数据源连接池

好，咱们继续往下走。上一章我们把 Java 和 IDE 搞定了，现在该轮到数据库了。

ThingsBoard 默认用的是 PostgreSQL，当然它也支持 Cassandra 做时序数据存储，但那是后话。咱们做二次开发，本地调试阶段，PostgreSQL 完全够用。我个人习惯用 14 或 15 版本，稳定，坑少。

4.1 安装 PostgreSQL 14/15

先说安装。不同操作系统方法不一样，我分别说一下。

Windows 用户

去官网下载安装包，选 14 或 15 版本。安装时记得把 pgAdmin 和 Command Line Tools 勾上。密码设一个你能记住的，比如 postgres。嗯，这里要注意：端口默认 5432，别跟别的服务冲突了。

Linux 用户（Ubuntu/Debian）

我个人更推荐 Linux 环境，因为生产环境也跑在 Linux 上。命令如下：

# 导入 GPG 密钥
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

# 添加仓库
echo "deb http://apt.postgresql.org/pub/repos/apt/ $(lsb_release -cs)-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list

# 安装 PostgreSQL 15
sudo apt update
sudo apt install postgresql-15 postgresql-client-15

安装完成后，检查一下服务状态：

sudo systemctl status postgresql

如果显示 active (running)，那就对了。

Mac 用户

用 Homebrew 最简单：

brew install postgresql@15
brew services start postgresql@15
小提示： 我遇到过好几次端口被占用的情况。如果你启动后连不上，先检查一下 5432 端口是不是被别的 PostgreSQL 实例占了。用 lsof -i :5432 看一眼。

4.2 创建数据库与用户

数据库装好了，接下来要创建 ThingsBoard 专用的数据库和用户。说白了，就是给 ThingsBoard 准备一个「家」。

先切换到 postgres 用户：

sudo -i -u postgres
psql

然后执行以下 SQL：

-- 创建用户，密码自己设一个复杂的
CREATE USER thingsboard WITH PASSWORD 'your_strong_password';

-- 创建数据库，指定所有者
CREATE DATABASE thingsboard OWNER thingsboard;

-- 给用户所有权限
GRANT ALL PRIVILEGES ON DATABASE thingsboard TO thingsboard;

这里有个细节：GRANT ALL PRIVILEGES ON DATABASE 只给了数据库级别的权限，但表级别的权限还需要在初始化表结构时赋予。别急，后面会说到。

验证一下：

\l   -- 查看所有数据库
\du  -- 查看所有用户

看到 thingsboard 数据库和用户就对了。

注意： 密码不要用太简单的，比如 123456。我曾经有个同事，图省事设了个弱密码，结果测试环境被扫了，数据被删了一部分。虽然本地环境问题不大，但养成好习惯很重要。

4.3 初始化表结构（schema.sql）

数据库和用户有了，但里面是空的。ThingsBoard 的表结构都在源码里，我们需要跑一下初始化脚本。

找到 ThingsBoard 源码中的 schema.sql 文件。路径大概是：

application/src/main/resources/sql/schema.sql

如果你是从 GitHub 克隆的源码，这个文件就在那里。执行方式很简单：

psql -U thingsboard -d thingsboard -f /path/to/schema.sql

它会提示输入密码，输入你刚才设的那个就行。

执行完成后，看看有没有报错。如果有错误，多半是权限问题。这时候需要给 thingsboard 用户更多权限：

psql -U postgres -d thingsboard -c "GRANT ALL ON SCHEMA public TO thingsboard;"

然后再跑一次 schema.sql。

验证表结构是否创建成功：

psql -U thingsboard -d thingsboard -c "\dt"

你会看到一堆表，比如 admin_settings、device、asset 等等。看到这些表，说明初始化成功了。

核心要点： schema.sql 不仅创建了表，还创建了索引、序列、以及一些默认数据。比如系统管理员账号就是在这里初始化的。所以这一步不能跳过，也不能出错。

4.4 配置数据源连接池

数据库准备好了，接下来要让 ThingsBoard 连上它。连接池用的是 HikariCP，这是 Spring Boot 默认的，性能很好，不用换。

配置文件在 application/src/main/resources/application.properties 里。找到数据库相关的配置项：

# 数据源配置
spring.datasource.url=jdbc:postgresql://localhost:5432/thingsboard
spring.datasource.username=thingsboard
spring.datasource.password=your_strong_password
spring.datasource.driver-class-name=org.postgresql.Driver

# HikariCP 连接池配置
spring.datasource.hikari.maximum-pool-size=16
spring.datasource.hikari.minimum-idle=4
spring.datasource.hikari.idle-timeout=600000
spring.datasource.hikari.connection-timeout=30000
spring.datasource.hikari.max-lifetime=1800000

这些参数什么意思？我简单说一下：

  • maximum-pool-size：最大连接数。本地调试 16 够用了，生产环境可以调大。
  • minimum-idle：最小空闲连接。设 4 个，避免频繁创建连接。
  • idle-timeout：空闲超时。10 分钟没用的连接会被回收。
  • connection-timeout：连接超时。30 秒连不上就报错。
  • max-lifetime：连接最大存活时间。30 分钟强制换新连接，防止连接泄漏。

这里有个坑：max-lifetime 一定要比数据库的 wait_timeout 小。PostgreSQL 默认的 tcp_keepalives_idle 是 2 小时，但有些云数据库会设得更短。我曾经遇到过连接被数据库端断开，但 HikariCP 不知道，还在用旧连接，结果报错。所以 max-lifetime 设 30 分钟是比较安全的。

配置完成后，启动 ThingsBoard 应用，看日志里有没有报错。如果看到类似这样的日志：

HikariPool-1 - Start completed.

那就说明连接池初始化成功了。

调试技巧： 如果启动时报数据库连接失败，先别急着改代码。用 psql -U thingsboard -d thingsboard -h localhost 手动连一下，看看能不能连上。很多时候是密码输错了，或者 PostgreSQL 服务没启动。

4.5 验证数据库环境

最后一步，验证整个数据库环境是否正常工作。我一般会做三件事：

  1. 检查表结构：用 \dt 看看表是否都在。
  2. 检查默认数据：查一下 admin_settings 表，看看有没有默认的系统配置。
  3. 检查连接池：启动 ThingsBoard 后，用 pg_stat_activity 看看有没有活跃连接。

如果这三步都过了，那数据库环境就算搭建完成了。

嗯，到这里，数据库这块就搞定了。下一章我们开始配置 ThingsBoard 的核心服务，包括消息队列和缓存。准备好了吗？

← 上一章 📖 返回目录 下一章 →