Perigon.PostgreSQL.Tools 0.3.1

There is a newer version of this package available.
See the version list below for details.
dotnet tool install --global Perigon.PostgreSQL.Tools --version 0.3.1
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local Perigon.PostgreSQL.Tools --version 0.3.1
                    
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=Perigon.PostgreSQL.Tools&version=0.3.1
                    
nuke :add-package Perigon.PostgreSQL.Tools --version 0.3.1
                    

Perigon.PostgreSQL.Tools

Perigon.PostgreSQL.Tools 是 Perigon.PostgreSQL 的 .NET 命令行工具,命令名为 dotnet perigon。它提供两类功能:从 PostgreSQL 数据库反向生成实体和 DbContext,以及为应用项目生成、查看、导出和应用数据库迁移。

安装

需要 .NET 10 SDK 和运行时。全局安装:

dotnet tool install --global Perigon.PostgreSQL.Tools

升级:

dotnet tool update --global Perigon.PostgreSQL.Tools

安装后使用 dotnet perigon。不带有效命令运行时,工具会打印命令用法。

从数据库生成代码

database scaffold 连接现有 PostgreSQL 数据库,生成 DbContext 和实体类:

dotnet perigon database scaffold `
    --connection "Host=localhost;Database=app;Username=postgres;Password=postgres" `
    --context AppDbContext `
    --namespace MyApp.Data `
    --output .\Generated `
    --schema public

命令会在输出目录下生成 AppDbContext/<ContextName>.cs 和 Entity/*.cs。默认包含视图;使用 --no-views 排除视图。

参数 作用 默认值
--connection PostgreSQL 连接字符串,必填 —
--context 生成的 DbContext 名称 DefaultDbContext
--namespace 生成代码的根命名空间 AppDbContext
--output 输出目录 当前目录
--schema 只处理指定 schema,可重复 所有 schema
--table 只处理指定表,可重复 所有表
--no-views 不为视图生成实体 默认包含视图
--force 覆盖同名已存在文件 不覆盖
--dry-run 只打印将生成的文件路径 写入文件

连接字符串也可以从环境变量传入,避免直接写在命令历史中:

$connection = $env:PERIGON_CONNECTION
dotnet perigon database scaffold --connection $connection --output .\Generated

增量迁移

迁移命令会构建 --project 指定的应用项目并加载其中的 DbContext。设计时上下文需要公开的无参构造函数,或接收单个连接字符串的公开构造函数。省略 --context 时,项目必须只有一个 DbContext;多目标框架项目可通过 --framework 选择目标框架,构建配置可通过 --configuration 指定。

生成并检查迁移

模型变化后生成迁移和模型快照:

dotnet perigon migrations add AddUserDisplayName `
    --project .\src\App\App.csproj `
    --context AppDbContext

dotnet perigon migrations list `
    --project .\src\App\App.csproj `
    --context AppDbContext

migrations add 默认将迁移文件和快照写入项目目录下的 Migrations 文件夹,也可以用 --output 指定目录、用 --namespace 指定命名空间。生成的 C# 迁移包含 Up 和 Down。请先检查差异和数据风险提示,必要时手工处理列重命名、数据回填或类型转换,并将迁移文件和快照纳入版本控制。

生成 SQL 脚本

dotnet perigon migrations script `
    --project .\src\App\App.csproj `
    --from 0 `
    --to <migration-id> `
    --idempotent `
    --output .\migration.sql

省略 --from 时从 0(尚未应用迁移)开始;省略 --to 时使用最新迁移。--idempotent 会按迁移 history 状态决定是否执行。将 --from 设为当前迁移、--to 设为较早的迁移可生成回滚脚本。默认 history 表为 public."_PerigonMigrationsHistory";自定义 history 表时,给脚本命令同时传入 --history-schema <schema> 和 --history-table <table>。

应用或回滚迁移

$connection = $env:PERIGON_CONNECTION
dotnet perigon database update `
    --project .\src\App\App.csproj `
    --context AppDbContext `
    --connection $connection

默认应用所有未执行的迁移。通过 --target <migration-id> 指定目标版本;--target 0 回滚所有已应用迁移。每条迁移的 DDL 与 history 记录在同一事务中提交,并使用 PostgreSQL advisory lock 串行化并发迁移。

已有数据库建立基线

如果数据库已经由 EnsureCreated 创建,可在迁移系统中登记初始迁移,而不重复建表:

dotnet perigon database baseline `
    --project .\src\App\App.csproj `
    --context AppDbContext `
    --connection $connection

基线命令会核对初始迁移快照中的受管结构,匹配后写入 history。当前要求项目只注册一个初始迁移。EnsureCreated 用于初始化数据库,不负责应用后续增量迁移;建立基线后使用 database update 管理结构变更。

命令速查

dotnet perigon database scaffold --connection <connection-string> [--context <name>] [--namespace <namespace>] [--output <directory>] [--schema <schema>] [--table <table>] [--force] [--dry-run] [--no-views]
dotnet perigon migrations add <name> --project <project.csproj> [--context <name>] [--output <directory>] [--namespace <namespace>]
dotnet perigon migrations list --project <project.csproj> [--context <name>]
dotnet perigon migrations script --project <project.csproj> [--from <id|0>] [--to <id|0>] [--idempotent] [--output <file>]
dotnet perigon database update --project <project.csproj> --connection <connection-string> [--context <name>] [--target <id|0>]
dotnet perigon database baseline --project <project.csproj> --connection <connection-string> [--context <name>] [--migration <id>]

更多迁移范围和限制见迁移文档。

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last Updated
0.3.8 0 11/20/2026
0.3.1 92 11/12/2026
0.3.0 109 11/1/2026
0.2.2 104 10/30/2026
0.2.1 98 10/30/2026
0.2.0 105 10/29/2026
0.1.8 108 10/26/2026
0.1.7 105 10/23/2026
0.1.6 108 10/23/2026
0.1.5 142 8/10/2026

0.3.1 aligns the migration and scaffolding tool with Perigon.PostgreSQL 0.3.1. See RELEASE_NOTES.md for details.