Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CN/modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
** xref:master/getting-started/quick_start.adoc[快速开始]
* 安装部署
** xref:master/installation_guide.adoc[安装指南]
** xref:master/installation_wsl2.adoc[Windows(WSL2)源码编译]
** xref:master/cluster_setup.adoc[集群搭建]
* Oracle兼容功能
** xref:master/oracle_compatibility/compat_case_conversion.adoc[大小写转换]
Expand Down
231 changes: 231 additions & 0 deletions CN/modules/ROOT/pages/master/installation_wsl2.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,231 @@

:sectnums:
:sectnumlevels: 5

= **Windows(WSL2)源码编译与验证**

== 适用场景

IvorySQL 官方发布的安装包面向 Linux 发行版,安装指南中的 yum、rpm、deb 与源码安装方式均需要在 Linux 环境执行。开发环境为 Windows 时,推荐使用 WSL2 安装 Ubuntu,在 Linux 子系统中完成源码编译、调试和回归测试;Windows 侧的客户端通过 `localhost` 访问运行在 WSL2 中的实例。

本文覆盖从零到可用的完整流程。文中命令已在 Windows 11 + WSL2(Ubuntu 24.04) + IvorySQL master 分支(PostgreSQL 19beta1、IvorySQL 5beta1)上执行验证,输出均取自实际运行结果。

== 前置条件

- Windows 10 2004 及以上版本,或 Windows 11
- BIOS 中已开启虚拟化(Intel VT-x 或 AMD-V)
- 可用内存 8GB 及以上,磁盘预留 10GB

== 安装WSL2与Ubuntu

以管理员身份打开 PowerShell,执行:

[source,powershell]
----
wsl --install -d Ubuntu-24.04
----

安装完成后重启主机。首次启动 Ubuntu 时按提示设置 Linux 用户名和密码。

确认 WSL 版本为 2:

[source,bash]
----
$ wsl -l -v
NAME STATE VERSION
* Ubuntu-24.04 Running 2
----

[TIP]
====
若提示 `WslRegisterDistribution failed with error 0x80370102`,说明虚拟化未开启,需要在 BIOS 中启用 VT-x 或 AMD-V 后重试。`wsl --install` 下载失败时,可改用 `wsl --install -d Ubuntu-24.04 --web-download`。
====

== 安装编译依赖

在 Ubuntu 中执行:

[source,bash]
----
sudo apt update
sudo apt install -y build-essential bison flex git pkg-config gettext \
libreadline-dev zlib1g-dev libssl-dev libxml2-dev libxslt1-dev \
libicu-dev libperl-dev python3-dev tcl-dev libldap2-dev uuid-dev \
libpam0g-dev libselinux1-dev
----

== 获取源码

[source,bash]
----
git clone --depth 1 https://github.com/IvorySQL/IvorySQL.git
cd IvorySQL
----

[CAUTION]
====
源码应放在 Linux 文件系统(例如 `~/IvorySQL`),不要放在 `/mnt/c` 等 Windows 挂载目录下。跨文件系统编译会明显变慢,且部分脚本会因文件权限差异失败。
====

== 编译与安装

[source,bash]
----
./configure --prefix=$HOME/ivory --with-uuid=e2fs --enable-debug
make -j$(nproc)
make install
----

主要参数说明:

|====
| 参数 | 说明
| `--prefix` | 安装目录。使用用户目录可避免 `sudo make install`,卸载时直接删除目录即可
| `--with-uuid` | 必选参数,取值 `bsd`、`e2fs` 或 `ossp`。省略后 `make` 会在 `contrib/uuid-ossp` 处报 `#error "please use configure's --with-uuid switch to select a UUID library"`
| `--enable-debug` | 生成带调试符号的二进制,便于使用 gdb 调试
|====

[NOTE]
====
`make -j$(nproc)` 会占满所有 CPU 核心。WSL2 默认最多使用主机一半内存,内存紧张时可改用 `make -j2`,避免编译进程被系统终止。
====

== 初始化数据库

[source,bash]
----
export PATH=$HOME/ivory/bin:$PATH

initdb -D $HOME/ivory/data
pg_ctl -D $HOME/ivory/data -l $HOME/ivory/log.txt start
----

`initdb` 默认创建 Oracle 兼容模式的集群,等价于 `initdb -m oracle`;如需 PostgreSQL 模式,使用 `initdb -D $HOME/ivory/data -m pg`。

[CAUTION]
====
`initdb` 不能以 root 身份执行。在 WSL 中使用创建 Ubuntu 时设置的普通用户即可,不要加 `sudo`。
====

== 连接与验证

Oracle 兼容模式监听 1521 端口:

[source,bash]
----
$ psql -d ivorysql -p 1521
psql (19beta1)
Type "help" for help.

[ORA]ivorysql=#
----

[NOTE]
====
Oracle 兼容模式下 psql 提示符带有 `[ORA]` 前缀,与 PostgreSQL 模式的提示符区分。
====

验证 Oracle 兼容特性:

[source,sql]
----
[ORA]ivorysql=# SELECT version();
PostgreSQL 19beta1 (IvorySQL 5beta1) on x86_64-pc-linux-gnu, compiled by gcc
(Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit
(1 row)

[ORA]ivorysql=# SHOW ivorysql.compatible_mode;
ivorysql.compatible_mode
--------------------------
oracle
(1 row)

[ORA]ivorysql=# SELECT 1 FROM dual;
?column?
----------
1
(1 row)

[ORA]ivorysql=# SELECT sys_context('USERENV','DB_NAME');
sys_context
-------------
ivorysql
(1 row)
----

同一个集群同时监听两个端口,连接端口决定会话的兼容模式:

[cols="1,2,2"]
|====
| 端口 | 模式 | compatible_mode
| 1521 | Oracle 兼容模式 | oracle
| 5432 | PostgreSQL 模式 | pg
|====

切换到 5432 端口连接,可以对比两种模式下同一语句的行为:

[source,bash]
----
$ psql -d ivorysql -p 5432
psql (19beta1)
Type "help" for help.

ivorysql=# SHOW ivorysql.compatible_mode;
ivorysql.compatible_mode
--------------------------
pg
(1 row)
----

[NOTE]
====
`SHOW` 的参数名与返回值在两种模式下一致,只有取值不同;`dual` 表、`sys_context` 等 Oracle 专有对象只在 1521 端口的会话中可用。
====

== 从 Windows 连接

WSL2 默认开启本地端口转发,Windows 侧的 `psql` 或图形化客户端可以直接连接 `localhost`:

[source,powershell]
----
psql -h 127.0.0.1 -p 1521 -U ivorysql -d ivorysql
----

[NOTE]
====
该方式依赖 `ivorysql.conf` 中的 `listen_addresses` 与 `pg_hba.conf` 的访问控制。若连接被拒绝,先确认实例监听地址,再检查 `pg_hba.conf` 是否允许来自 127.0.0.1 的连接。
====

== 常见错误

=== make 在 contrib/uuid-ossp 处失败

[source,text]
----
error: #error "please use configure's --with-uuid switch to select a UUID library"
----

原因是 `configure` 未指定 UUID 库(此时 `with_uuid=no`),该模块不会被编译。安装 `uuid-dev` 后重新执行 `./configure --with-uuid=e2fs` 并重新编译。

=== initdb: cannot be run as root

`initdb` 禁止以超级用户执行。改用普通用户运行,或在容器中创建非 root 用户后再初始化。

=== 1521 端口被占用

Windows 或 WSL 中安装了 Oracle 客户端时,1521 可能已被占用。可在 `ivorysql.conf` 中修改 `ivorysql.port`,或停止占用该端口的进程后重启实例。

== 清理

[source,bash]
----
pg_ctl -D $HOME/ivory/data stop
rm -rf $HOME/IvorySQL $HOME/ivory
----

删除 WSL 发行版:

[source,powershell]
----
wsl --unregister Ubuntu-24.04
----
1 change: 1 addition & 0 deletions EN/modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
** xref:master/getting-started/quick_start.adoc[Quick Start]
* Deploy
** xref:master/installation_guide.adoc[Installation]
** xref:master/installation_wsl2.adoc[Source build on Windows(WSL2)]
** xref:master/cluster_setup.adoc[Cluster]
* Oracle Compatibility
** xref:master/oracle_compatibility/compat_case_conversion.adoc[Case conversion]
Expand Down
Loading
Loading