Skip to content
50 changes: 37 additions & 13 deletions README.ja.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,14 @@
# pgdumpx

[![crates.io](https://img.shields.io/crates/v/pgdumpx.svg)](https://crates.io/crates/pgdumpx)
[![docs.rs](https://docs.rs/pgdumpx/badge.svg)](https://docs.rs/pgdumpx/0.2.0/pgdumpx/)
[![CI](https://github.com/tappe9/pgdumpx/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tappe9/pgdumpx/actions/workflows/ci.yml)
[![MSRV](https://img.shields.io/badge/MSRV-1.85.0-blue.svg)](https://www.rust-lang.org/)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE-MIT)

**PostgreSQL Custom Formatをrestoreせず、byte-orientedなrowとして安全にscanするRustライブラリ / CLI。**

> 現在のソースバージョン: `0.2.0`。v0.1のfoundationとv0.2の機能は実装済みです。registry commandを使うには、対象package versionがcrates.ioに存在する必要があります。ソースからのinstallはregistry公開状態に依存しません。
> `pgdumpx 0.2.0`はcrates.ioで公開済みです。再利用可能なRustライブラリと、install可能なCLI packageの両方を提供します。

pgdumpxは、PostgreSQL Custom Format (`pg_dump -Fc`) archiveを、データベースへrestoreせずに検査するread-onlyのRustライブラリ / CLIです。

Expand All @@ -14,8 +20,18 @@ pgdumpxは、PostgreSQL Custom Format (`pg_dump -Fc`) archiveを、データベ

[English README](README.md)

## 公開成果物

| 成果物 | Version | 用途 |
| --- | --- | --- |
| [`pgdumpx`](https://crates.io/crates/pgdumpx/0.2.0) | `0.2.0` | 再利用可能なRustライブラリ |
| [`pgdumpx-cli`](https://crates.io/crates/pgdumpx-cli/0.2.0) | `0.2.0` | `pgdumpx` executableをinstallするCLI package |
| [API documentation](https://docs.rs/pgdumpx/0.2.0/pgdumpx/) | `0.2.0` | 公開済みlibrary rustdoc |
| [GitHub Release](https://github.com/tappe9/pgdumpx/releases/tag/v0.2.0) | `v0.2.0` | source releaseとrelease notes |

## 現在の開発状況

- **v0.2.0公開完了:** library、CLI package、annotated source tag、GitHub Release、API documentationを上記リンクから利用できます。
- **v0.1 foundation完了:** metadata inspection、4種類のcompression backend、bounded raw extraction、COPY row parsing、first-match search、各種limits、fuzz / benchmark / CI evidence、rustdoc、packaging verification。
- **v0.2完了:** file-oriented opening、owned byte-oriented selector、reusable extraction plan、deterministicなsequential multi-table extraction、metadata filtering、exact named-column equality helperを実装済みです。
- **correctness / maintenance follow-up完了:** destination flush failure、aggregate metadata budget、terminal row-reader error、field-count validation、linear duplicate detection、finite CLI scan default、feature matrix test、scheduled fuzz、advisory policy、workflow hardeningを現在のsourceに含みます。
Expand Down Expand Up @@ -112,26 +128,33 @@ unsupported representationはCOPY textとして推測せず、row APIからtyped

## インストール

### crates.io から

crates.ioでpackage versionを確認してからinstallまたはdependency追加を行ってください。次のregistry commandには`0.2.0`がcrates.ioに存在することが必要です。
### crates.ioからCLIをinstall

```bash
cargo info pgdumpx@0.2.0
cargo info pgdumpx-cli@0.2.0
cargo install pgdumpx-cli --version 0.2.0 --locked
pgdumpx --version
pgdumpx --help
```

library consumerは次を追加できます。
package名は`pgdumpx-cli`、installされるexecutable名は`pgdumpx`です。

### crates.ioからlibraryを利用

```toml
[dependencies]
pgdumpx = "0.2.0"
```

公開済みAPI documentationは[docs.rs](https://docs.rs/pgdumpx/0.2.0/pgdumpx/)で確認できます。registry metadataは次のcommandでも確認できます。

```bash
cargo info pgdumpx@0.2.0
cargo info pgdumpx-cli@0.2.0
```

### ソースから

この手順はcrates.ioの公開状態に依存しません。
現在の`main`やlocal変更を試す場合はsource pathを利用します。

```bash
git clone https://github.com/tappe9/pgdumpx.git
Expand Down Expand Up @@ -188,7 +211,7 @@ APIでは次を別のlimitとして扱います。

`Limits::default()`はfiniteなcompatibility-oriented defaultで、`Archive::open_with_limits`ではTOC / string / dependency / row / fieldへより厳しいlimitを指定できます。`ScanLimits::default()`と`ScanLimits::unlimited()`はoperation-levelの2つのoptional budgetを未設定にします。`max_rows = N`では、一致rowを含めて最大`N`件のcomplete rowだけをyield / evaluateできます。decompressed-byte budgetは、field separator、row terminator、escape spelling、消費したCOPY terminatorを含む、parserが消費した物理COPY byteを数えます。logical fieldのdecode後lengthや、decoder / `BufRead`が先読みした未消費byteは数えません。budgetをcrossするrowはyieldもpredicate評価もされず、limit / consumed-work contextを持つtyped resource errorを返します。

詳細は[Public API design](docs/API-DESIGN.md)とcrate rustdocを参照してください。
詳細は[Public API design](docs/API-DESIGN.md)と[公開済みcrate documentation](https://docs.rs/pgdumpx/0.2.0/pgdumpx/)を参照してください。

## CLI

Expand All @@ -204,7 +227,7 @@ pgdumpx find --max-rows 100000 --max-decompressed-bytes 67108864 \
backup.dump public.orders order_number 123456
```

table-oriented commandの`<SCHEMA.TABLE>`はASCIIの`.`をちょうど1個含み、schema / tableの両componentをnon-emptyとします。SQL identifierのquote / escapeや`.`を含むidentifierはv0.1 CLIでは未対応です。CLI境界のquery identifier / valueはUTF-8で、Rust APIはbyte-orientedのままです。
table-oriented commandの`<SCHEMA.TABLE>`はASCIIの`.`をちょうど1個含み、schema / tableの両componentをnon-emptyとします。SQL identifierのquote / escapeや`.`を含むidentifierは現在のCLI grammarでは未対応です。CLI境界のquery identifier / valueはUTF-8で、Rust APIはbyte-orientedのままです。

### `inspect` / `list`

Expand Down Expand Up @@ -306,7 +329,7 @@ v0.1の最終Definition of Done evidence mappingは[docs/V0.1-RELEASE-AUDIT.md](

各documentのprimary responsibilityを分け、重複とdriftを抑えます。

- [README](README.md) / [日本語 README](README.ja.md) — product value、現在の実装/release status、example、high-level scope
- [README](README.md) / [日本語 README](README.ja.md) — product value、公開済みrelease status、example、high-level scope
- [Requirements](docs/REQUIREMENTS.md) — normative v0.1 behaviorとDefinition of Done
- [Architecture](ARCHITECTURE.md) — 実装済みboundaryとdata flow
- [Public API design](docs/API-DESIGN.md) — 実装済みRust API semanticsとownership/resource contract
Expand All @@ -315,9 +338,10 @@ v0.1の最終Definition of Done evidence mappingは[docs/V0.1-RELEASE-AUDIT.md](
- [Compatibility matrix](docs/COMPATIBILITY.md) — targetとfixture-verified supportの区別
- [Bounded raw extraction](docs/RAW-EXTRACTION.md) — raw byte-budget / partial-output semantics
- [`find` scan-budget policy](docs/FIND-SCAN-LIMITS.md) — finite CLI default、根拠、boundary、migration guidance
- [Packaging audit](docs/PACKAGING.md) — package/license/runtime dependency boundary
- [Packaging audit](docs/PACKAGING.md) — package/license/runtime dependency boundaryと公開済みpackage record
- [Release process](docs/RELEASING.md) — release procedureと完了済みrelease record
- [v0.1 release audit](docs/V0.1-RELEASE-AUDIT.md) — 最終DoD-to-evidence mapping
- [Roadmap](ROADMAP.md) — delivered v0.1 / v0.2 work、deferred candidate scope
- [Roadmap](ROADMAP.md) — delivered / published v0.1・v0.2 work、deferred candidate scope
- [Architecture Decision Records](docs/adr/) — accepted / superseded design decisions
- [Contributing](CONTRIBUTING.md) — contribution / document-update policy
- [Security policy](SECURITY.md) — vulnerability reporting / resource-threat model
Expand Down
50 changes: 37 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,14 @@
# pgdumpx

[![crates.io](https://img.shields.io/crates/v/pgdumpx.svg)](https://crates.io/crates/pgdumpx)
[![docs.rs](https://docs.rs/pgdumpx/badge.svg)](https://docs.rs/pgdumpx/0.2.0/pgdumpx/)
[![CI](https://github.com/tappe9/pgdumpx/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tappe9/pgdumpx/actions/workflows/ci.yml)
[![MSRV](https://img.shields.io/badge/MSRV-1.85.0-blue.svg)](https://www.rust-lang.org/)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE-MIT)

**A bounded, byte-oriented row scanner for PostgreSQL custom-format dumps.**

> Current source version: `0.2.0`. The v0.1 foundation and v0.2 functionality are implemented. Registry commands require the exact package version to be available on crates.io; the source installation path works independently of registry publication.
> `pgdumpx 0.2.0` is published on crates.io as both a reusable Rust library and an installable CLI package.

pgdumpx is a read-only Rust library and CLI for inspecting PostgreSQL custom-format (`pg_dump -Fc`) archives without restoring them into a database.

Expand All @@ -14,8 +20,18 @@ A representative use case is:

[日本語 README](README.ja.md)

## Published artifacts

| Artifact | Version | Purpose |
| --- | --- | --- |
| [`pgdumpx`](https://crates.io/crates/pgdumpx/0.2.0) | `0.2.0` | Reusable Rust library |
| [`pgdumpx-cli`](https://crates.io/crates/pgdumpx-cli/0.2.0) | `0.2.0` | Installs the `pgdumpx` executable |
| [API documentation](https://docs.rs/pgdumpx/0.2.0/pgdumpx/) | `0.2.0` | Published library rustdoc |
| [GitHub Release](https://github.com/tappe9/pgdumpx/releases/tag/v0.2.0) | `v0.2.0` | Source release and release notes |

## Current development status

- **v0.2.0 published:** the library, CLI package, annotated source tag, GitHub Release, and API documentation are available from the links above.
- **v0.1 foundation completed:** metadata inspection, four compression backends, bounded raw extraction, COPY row parsing, first-match search, limits, fuzz/benchmark/CI evidence, rustdoc, and packaging verification.
- **v0.2 completed:** file-oriented opening, owned byte-oriented selectors, reusable extraction plans, deterministic sequential multi-table extraction, metadata filtering, and exact named-column equality helpers are implemented.
- **Correctness and maintenance follow-ups completed:** destination flush failures, aggregate metadata budgets, terminal row-reader errors, field-count validation, linear duplicate detection, finite CLI scan defaults, feature-matrix testing, scheduled fuzzing, advisory policy, and workflow hardening are included in the current source.
Expand Down Expand Up @@ -112,26 +128,33 @@ All row searches remain sequential scans. The helpers add reusable selection pol

## Installation

### From crates.io

Registry commands require `0.2.0` to be available on crates.io. Check the exact versions before installing or adding the dependency:
### CLI from crates.io

```bash
cargo info pgdumpx@0.2.0
cargo info pgdumpx-cli@0.2.0
cargo install pgdumpx-cli --version 0.2.0 --locked
pgdumpx --version
pgdumpx --help
```

Library consumers can add:
The package name is `pgdumpx-cli`; the installed executable is named `pgdumpx`.

### Library from crates.io

```toml
[dependencies]
pgdumpx = "0.2.0"
```

Published API documentation is available on [docs.rs](https://docs.rs/pgdumpx/0.2.0/pgdumpx/). Registry metadata can also be inspected with:

```bash
cargo info pgdumpx@0.2.0
cargo info pgdumpx-cli@0.2.0
```

### From source

This path works independently of crates.io publication:
Use the source path to test the current `main` branch or local changes:

```bash
git clone https://github.com/tappe9/pgdumpx.git
Expand Down Expand Up @@ -188,7 +211,7 @@ The API keeps three resource concepts separate:

`Limits::default()` is finite and compatibility-oriented, and `Archive::open_with_limits` accepts stricter caller-selected TOC/string/dependency/row/field bounds. `ScanLimits::default()` and `ScanLimits::unlimited()` leave both operation-level budgets unset. `max_rows = N` permits at most `N` complete rows to be yielded or evaluated, including a matching row. The decompressed-byte scan budget counts physical COPY bytes consumed by the parser—including field separators, row terminators, escape spellings, and the COPY terminator when consumed—not logical decoded field length or unread decoder/`BufRead` lookahead. A crossing row is not yielded or passed to the predicate, and exhaustion is returned as a typed resource error with limit and consumed-work context.

See [Public API design](docs/API-DESIGN.md) and the crate rustdoc for the complete public contract.
See [Public API design](docs/API-DESIGN.md) and the [published crate documentation](https://docs.rs/pgdumpx/0.2.0/pgdumpx/) for the complete public contract.

## CLI

Expand All @@ -204,7 +227,7 @@ pgdumpx find --max-rows 100000 --max-decompressed-bytes 67108864 \
backup.dump public.orders order_number 123456
```

For table-oriented commands, `<SCHEMA.TABLE>` contains exactly one ASCII `.` separator and non-empty schema and table components. SQL identifier quoting/escaping and identifiers containing `.` are not supported by the v0.1 CLI. Query identifiers/values at the CLI boundary are UTF-8; the Rust API remains byte-oriented.
For table-oriented commands, `<SCHEMA.TABLE>` contains exactly one ASCII `.` separator and non-empty schema and table components. SQL identifier quoting/escaping and identifiers containing `.` are not supported by the current CLI grammar. Query identifiers/values at the CLI boundary are UTF-8; the Rust API remains byte-oriented.

### `inspect` / `list`

Expand Down Expand Up @@ -306,7 +329,7 @@ These projects cover adjacent PostgreSQL dump use cases. pgdumpx keeps a deliber

Each document has one primary responsibility to reduce duplication and drift:

- [README](README.md) / [日本語 README](README.ja.md) — product value, current implementation/release status, examples, and high-level scope;
- [README](README.md) / [日本語 README](README.ja.md) — product value, published release status, examples, and high-level scope;
- [Requirements](docs/REQUIREMENTS.md) — normative v0.1 behavior and Definition of Done;
- [Architecture](ARCHITECTURE.md) — implemented boundaries and data flow;
- [Public API design](docs/API-DESIGN.md) — implemented Rust API semantics and ownership/resource contracts;
Expand All @@ -315,9 +338,10 @@ Each document has one primary responsibility to reduce duplication and drift:
- [Compatibility matrix](docs/COMPATIBILITY.md) — target versus fixture-verified support;
- [Bounded raw extraction](docs/RAW-EXTRACTION.md) — raw byte-budget and partial-output semantics;
- [`find` scan-budget policy](docs/FIND-SCAN-LIMITS.md) — finite CLI defaults, evidence, boundary semantics, and migration guidance;
- [Packaging audit](docs/PACKAGING.md) — package/license/runtime dependency boundary;
- [Packaging audit](docs/PACKAGING.md) — package/license/runtime dependency boundary and published package record;
- [Release process](docs/RELEASING.md) — release procedure and completed release record;
- [v0.1 release audit](docs/V0.1-RELEASE-AUDIT.md) — final DoD-to-evidence mapping;
- [Roadmap](ROADMAP.md) — delivered v0.1/v0.2 work and deferred candidate scope;
- [Roadmap](ROADMAP.md) — delivered and published v0.1/v0.2 work plus deferred candidate scope;
- [Architecture Decision Records](docs/adr/) — accepted and superseded design decisions;
- [Contributing](CONTRIBUTING.md) — contribution and document-update policy;
- [Security policy](SECURITY.md) — vulnerability reporting and resource-threat model.
Expand Down
16 changes: 12 additions & 4 deletions ROADMAP.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# pgdumpx Roadmap

Status: **v0.1 foundation complete; v0.2 implementation complete; the 0.2.0 publication process is tracked separately from source delivery.**
Status: **v0.2.0 released; v0.1 foundation and v0.2 implementation complete; v0.3+ candidates remain deferred.**

This roadmap records completed v0.1/v0.2 work and explicitly deferred candidates. The normative v0.1 contract remains in `docs/REQUIREMENTS.md`, final v0.1 evidence is mapped in `docs/V0.1-RELEASE-AUDIT.md`, GitHub Tracking Issue #30 records the v0.1 sequence, and [Tracking Issue #56](https://github.com/tappe9/pgdumpx/issues/56) records the completed v0.2 sequence.
This roadmap records completed v0.1/v0.2 work, the published `0.2.0` release, and explicitly deferred candidates. The normative v0.1 contract remains in `docs/REQUIREMENTS.md`, final v0.1 evidence is mapped in `docs/V0.1-RELEASE-AUDIT.md`, GitHub Tracking Issue #30 records the v0.1 sequence, and [Tracking Issue #56](https://github.com/tappe9/pgdumpx/issues/56) records the completed v0.2 sequence.

## v0.1 — Bounded row scanning for Custom Format archives

Expand Down Expand Up @@ -179,7 +179,7 @@ Stable exit behavior:

No-match remains distinct from failure.

## v0.2 — Completed
## v0.2 — Completed and released

The v0.2 implementation builds on the v0.1 `Read + Seek`, validated-entry, decompression, row-parser, and raw-output paths. It preserves the single mutable seekable-source invariant and does not add parallel or indexed alternatives.

Expand All @@ -190,7 +190,15 @@ The v0.2 implementation builds on the v0.1 `Read + Seek`, validated-entry, decom
- [#89](https://github.com/tappe9/pgdumpx/issues/89) hardened GitHub Actions with pinned dependencies, bounded execution, least-privilege permissions, and cancellation policy.
- [#92](https://github.com/tappe9/pgdumpx/issues/92) prepared reproducible `pgdumpx 0.2.0` and `pgdumpx-cli 0.2.0` package metadata, changelog, release notes, packaging verification, and staged release instructions.

The `0.2.0` source and package contract is complete. Registry publication, the annotated tag, and the GitHub Release follow the independently verified process in `docs/RELEASING.md`; this roadmap does not infer their live state.
### Published artifacts

- Library: <https://crates.io/crates/pgdumpx/0.2.0>
- CLI: <https://crates.io/crates/pgdumpx-cli/0.2.0>
- Library API documentation: <https://docs.rs/pgdumpx/0.2.0/pgdumpx/>
- GitHub Release: <https://github.com/tappe9/pgdumpx/releases/tag/v0.2.0>
- Release commit: `aaae67749e3f389bdde5c28f555436508e219fc8`

The library and CLI packages were published on 2026-09-01 UTC in dependency order and remain non-yanked. The annotated `v0.2.0` tag and GitHub Release point to the verified release commit. See `docs/RELEASING.md` for the completed release record and reusable staged procedure.

## v0.3+ — Deferred candidates

Expand Down
Loading