diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index 66bc54e6..2b21998e 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/CN/modules/ROOT/nav.adoc @@ -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[大小写转换] diff --git a/CN/modules/ROOT/pages/master/installation_wsl2.adoc b/CN/modules/ROOT/pages/master/installation_wsl2.adoc new file mode 100644 index 00000000..31adb8a4 --- /dev/null +++ b/CN/modules/ROOT/pages/master/installation_wsl2.adoc @@ -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 +---- diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc index a2026117..5360c213 100644 --- a/EN/modules/ROOT/nav.adoc +++ b/EN/modules/ROOT/nav.adoc @@ -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] diff --git a/EN/modules/ROOT/pages/master/installation_wsl2.adoc b/EN/modules/ROOT/pages/master/installation_wsl2.adoc new file mode 100644 index 00000000..a438d8da --- /dev/null +++ b/EN/modules/ROOT/pages/master/installation_wsl2.adoc @@ -0,0 +1,229 @@ + +:sectnums: +:sectnumlevels: 5 + += **Source Build and Verification on Windows(WSL2)** + +== When to Use + +The packages IvorySQL publishes target Linux distributions. Every installation method described in the installation guide (yum, rpm, deb and source) has to run on Linux. On a Windows development machine, the recommended path is to install Ubuntu through WSL2, build, debug and run the regression tests inside the Linux subsystem, and let Windows-side clients reach the instance through `localhost`. + +This page walks through the whole flow. All commands were executed on Windows 11 + WSL2 (Ubuntu 24.04) against the `master` branch of IvorySQL (PostgreSQL 19beta1, IvorySQL 5beta1); the outputs are copied from those runs. + +== Prerequisites + +- Windows 10 version 2004 or later, or Windows 11 +- Virtualization enabled in BIOS (Intel VT-x or AMD-V) +- At least 8GB of RAM and 10GB of free disk space + +== Install WSL2 and Ubuntu + +Run the following in an elevated PowerShell: + +[source,powershell] +---- +wsl --install -d Ubuntu-24.04 +---- + +Reboot the host when the installation finishes. The first start of Ubuntu asks for a Linux user name and password. + +Confirm the distribution runs on WSL 2: + +[source,bash] +---- +$ wsl -l -v + NAME STATE VERSION +* Ubuntu-24.04 Running 2 +---- + +[TIP] +==== +If the distribution fails to start with `WslRegisterDistribution failed with error 0x80370102`, virtualization is disabled in the firmware. Enable VT-x or AMD-V and retry. When the `wsl --install` download stalls, use `wsl --install -d Ubuntu-24.04 --web-download` instead. +==== + +== Install Build Dependencies + +Inside 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 +---- + +== Get the Source + +[source,bash] +---- +git clone --depth 1 https://github.com/IvorySQL/IvorySQL.git +cd IvorySQL +---- + +[CAUTION] +==== +Keep the checkout in the Linux filesystem, for example `~/IvorySQL`, rather than under `/mnt/c`. Compiling across the Windows mount is markedly slower and some scripts fail on the permission differences. +==== + +== Build and Install + +[source,bash] +---- +./configure --prefix=$HOME/ivory --with-uuid=e2fs --enable-debug +make -j$(nproc) +make install +---- + +|==== +| Option | Description +| `--prefix` | Installation directory. Using a directory under `$HOME` avoids `sudo make install` and makes removal a single `rm -rf` +| `--with-uuid` | Required. Accepts `bsd`, `e2fs` or `ossp`. Without it `make` stops in `contrib/uuid-ossp` with `#error "please use configure's --with-uuid switch to select a UUID library"` +| `--enable-debug` | Builds binaries with debug symbols for gdb +|==== + +[NOTE] +==== +`make -j$(nproc)` saturates every CPU core. WSL2 uses at most half of the host memory by default; on a memory-constrained machine use `make -j2` so the compiler is not killed by the OOM handler. +==== + +== Initialize the Cluster + +[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` creates an Oracle-compatible cluster by default, which is what `initdb -m oracle` selects explicitly. For a PostgreSQL-mode cluster use `initdb -D $HOME/ivory/data -m pg`. + +[CAUTION] +==== +`initdb` refuses to run as root. Use the regular user created when the Ubuntu distribution was set up, without `sudo`. +==== + +== Connect and Verify + +Oracle-compatible mode listens on port 1521: + +[source,bash] +---- +$ psql -d ivorysql -p 1521 +psql (19beta1) +Type "help" for help. + +[ORA]ivorysql=# +---- + +[NOTE] +==== +In Oracle-compatible mode the psql prompt carries an `[ORA]` prefix, which distinguishes it from a PostgreSQL-mode prompt. +==== + +Check the Oracle compatibility features: + +[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) +---- + +One cluster listens on both ports, and the port a session connects to decides its compatibility mode: + +[cols="1,2,2"] +|==== +| Port | Mode | compatible_mode +| 1521 | Oracle compatible | oracle +| 5432 | PostgreSQL | pg +|==== + +Connecting on 5432 shows the other mode for the very same statement: + +[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` takes the same argument and returns the same shape in both modes; only the value differs. Oracle-only objects such as `dual` and `sys_context` are available only in a session opened on port 1521. +==== + +== Connect from Windows + +WSL2 forwards local ports by default, so a Windows-side `psql` or GUI client can connect to `localhost` directly: + +[source,powershell] +---- +psql -h 127.0.0.1 -p 1521 -U ivorysql -d ivorysql +---- + +[NOTE] +==== +This relies on `listen_addresses` in `ivorysql.conf` and on the rules in `pg_hba.conf`. If the connection is refused, check the listening address first and then whether `pg_hba.conf` accepts connections from 127.0.0.1. +==== + +== Common Failures + +=== make fails in contrib/uuid-ossp + +[source,text] +---- +error: #error "please use configure's --with-uuid switch to select a UUID library" +---- + +`configure` ran without a UUID library, so `with_uuid=no` and the module is skipped. Install `uuid-dev`, re-run `./configure --with-uuid=e2fs` and rebuild. + +=== initdb: cannot be run as root + +`initdb` refuses to run as a superuser. Run it as a regular user, or create a non-root user inside the container before initializing. + +=== Port 1521 already in use + +An Oracle client installed on Windows or inside WSL may already hold 1521. Change `ivorysql.port` in `ivorysql.conf`, or stop the process that holds the port and restart the instance. + +== Clean Up + +[source,bash] +---- +pg_ctl -D $HOME/ivory/data stop +rm -rf $HOME/IvorySQL $HOME/ivory +---- + +Remove the distribution: + +[source,powershell] +---- +wsl --unregister Ubuntu-24.04 +----