一介布衣

🧭 快速导航

Sequelize 安装配置详解 - 从零开始搭建开发环境 ​

发布时间：2024-01-08
作者：一介布衣
标签：Sequelize, 安装, 配置, 环境搭建

前言 ​

上一篇文章我们聊了 Sequelize 的基本概念和优势，相信大家对它已经有了初步的了解。今天咱们就来动手实践，从零开始搭建一个 Sequelize 的开发环境。

说实话，第一次配置 Sequelize 的时候，我也踩了不少坑。特别是数据库驱动的选择和版本兼容性问题，让我折腾了好久。今天我就把这些经验分享给大家，让大家少走弯路。

环境准备 ​

在开始之前，确保你的系统已经安装了：

  • Node.js：建议 14.0 以上版本
  • npm 或 yarn：包管理工具
  • 数据库：至少安装一种（MySQL、PostgreSQL、SQLite 等）

检查 Node.js 版本：

bash
node --version
npm --version

如果版本太低，建议先升级到最新的 LTS 版本。

创建项目 ​

首先创建一个新的 Node.js 项目：

bash
mkdir sequelize-demo
cd sequelize-demo
npm init -y

这会创建一个基本的 package.json 文件。

安装 Sequelize ​

核心包安装 ​

bash
npm install sequelize

这是 Sequelize 的核心包，但是光有这个还不够，我们还需要安装对应的数据库驱动。

数据库驱动选择 ​

根据你使用的数据库，选择对应的驱动：

PostgreSQL ​

bash
npm install pg pg-hstore

MySQL ​

bash
npm install mysql2

MariaDB ​

bash
npm install mariadb

SQLite ​

bash
npm install sqlite3

Microsoft SQL Server ​

bash
npm install tedious

Oracle Database ​

bash
npm install oracledb

我的建议：如果你是初学者，推荐先用 SQLite。它不需要额外安装数据库服务器，配置简单，非常适合学习和开发。

开发工具安装 ​

为了更好的开发体验，建议安装以下工具：

bash
# Sequelize CLI - 命令行工具，用于迁移、种子等操作
npm install --save-dev sequelize-cli

# 如果使用 TypeScript
npm install --save-dev @types/node typescript ts-node

# 如果需要环境变量管理
npm install dotenv

项目结构设计 ​

一个典型的 Sequelize 项目结构如下：

sequelize-demo/
├── config/
│   └── database.js          # 数据库配置
├── models/
│   ├── index.js             # 模型入口文件
│   └── user.js              # 用户模型示例
├── migrations/              # 数据库迁移文件
├── seeders/                 # 种子数据文件
├── controllers/             # 控制器（可选）
├── routes/                  # 路由（可选）
└── app.js                   # 应用入口

让我们创建这个结构：

bash
mkdir config models migrations seeders
touch config/database.js models/index.js app.js

基础配置 ​

1. 数据库配置文件 ​

创建 config/database.js：

javascript
const { Sequelize } = require('sequelize');
require('dotenv').config();

// 根据环境选择配置
const config = {
  development: {
    dialect: 'sqlite',
    storage: './database.sqlite',
    logging: console.log, // 开发环境显示 SQL 日志
  },
  test: {
    dialect: 'sqlite',
    storage: ':memory:',
    logging: false, // 测试环境不显示日志
  },
  production: {
    dialect: 'postgres',
    host: process.env.DB_HOST || 'localhost',
    port: process.env.DB_PORT || 5432,
    database: process.env.DB_NAME,
    username: process.env.DB_USER,
    password: process.env.DB_PASS,
    logging: false, // 生产环境不显示日志
    pool: {
      max: 10,
      min: 0,
      acquire: 30000,
      idle: 10000
    }
  }
};

const env = process.env.NODE_ENV || 'development';
const sequelize = new Sequelize(config[env]);

module.exports = sequelize;

2. 环境变量配置 ​

创建 .env 文件（记得加到 .gitignore 中）：

env
NODE_ENV=development
DB_HOST=localhost
DB_PORT=5432
DB_NAME=your_database_name
DB_USER=your_username
DB_PASS=your_password

3. 模型入口文件 ​

创建 models/index.js：

javascript
const sequelize = require('../config/database');

// 这里会导入所有模型
const models = {};

// 建立模型关联
Object.keys(models).forEach(modelName => {
  if (models[modelName].associate) {
    models[modelName].associate(models);
  }
});

module.exports = {
  sequelize,
  ...models
};

测试连接 ​

创建 app.js 来测试数据库连接：

javascript
const sequelize = require('./config/database');

async function testConnection() {
  try {
    await sequelize.authenticate();
    console.log('✅ 数据库连接成功！');
    
    // 显示数据库信息
    console.log(`📊 数据库类型: \${sequelize.getDialect()}`);
    console.log(`🔗 连接配置: \${sequelize.config.host || 'SQLite'}`);
    
  } catch (error) {
    console.error('❌ 数据库连接失败:', error.message);
  } finally {
    await sequelize.close();
  }
}

testConnection();

运行测试：

bash
node app.js

如果看到"数据库连接成功"的消息，说明配置正确！

常见问题解决 ​

1. SQLite 权限问题 ​

错误信息：SQLITE_CANTOPEN: unable to open database file

解决方案：

bash
# 确保目录有写权限
chmod 755 .
# 或者指定绝对路径
storage: path.join(__dirname, '../database.sqlite')

2. MySQL 连接被拒绝 ​

错误信息：ER_ACCESS_DENIED_ERROR

解决方案：

  • 检查用户名密码是否正确
  • 确认 MySQL 服务是否启动
  • 检查防火墙设置
bash
# 检查 MySQL 服务状态
sudo systemctl status mysql
# 或者
brew services list | grep mysql

3. PostgreSQL 连接超时 ​

错误信息：connect ETIMEDOUT

解决方案：

  • 检查 PostgreSQL 是否启动
  • 确认端口号是否正确（默认 5432）
  • 检查 pg_hba.conf 配置

4. 版本兼容性问题 ​

错误信息：各种奇怪的错误

解决方案：

bash
# 查看版本兼容性
npm ls sequelize
npm ls mysql2

# 如果有冲突，可以指定版本
npm install sequelize@^6.32.0

性能优化建议 ​

1. 连接池配置 ​

javascript
const sequelize = new Sequelize(database, username, password, {
  host: 'localhost',
  dialect: 'postgres',
  pool: {
    max: 10,        // 最大连接数
    min: 0,         // 最小连接数
    acquire: 30000, // 获取连接超时时间
    idle: 10000     // 连接空闲时间
  }
});

2. 日志配置 ​

javascript
// 开发环境：显示详细日志
logging: (msg) => console.log(`[SQL] \${msg}`)

// 生产环境：使用专业日志库
logging: (msg) => logger.debug(msg)

// 完全关闭日志
logging: false

下一步计划 ​

环境搭建完成后，我们就可以开始真正的开发了。下一篇文章我们将详细介绍：

  1. 如何建立数据库连接
  2. 连接池的配置和优化
  3. 多数据库环境的管理
  4. 连接故障的处理

总结 ​

今天我们完成了 Sequelize 的基础环境搭建，包括：

  • ✅ 安装 Sequelize 和数据库驱动
  • ✅ 设计合理的项目结构
  • ✅ 配置数据库连接
  • ✅ 测试连接是否正常
  • ✅ 解决常见问题

虽然配置过程看起来有点复杂，但是一旦搭建好了，后面的开发就会非常顺畅。建议大家跟着步骤一步步来，遇到问题不要慌，多看看错误信息，基本都能解决。

下一篇文章我们将深入探讨数据库连接的各种场景和最佳实践。记得关注哦！

相关文章推荐：

有问题欢迎留言讨论，我会及时回复大家！