pgdumplib 4.0.0

pgdumplib 4.0.0

We're excited to announce pgdumplib 4.0.0, a major release bringing PostgreSQL 16-18 support, Python 3.11-3.14 compatibility, critical bug fixes, and proper handling of PostgreSQL COPY text format escape sequences.

🎯 Highlights

• PostgreSQL 16-18 Support: Full support for dump format versions 1.15.0 and 1.16.0
• Python 3.11-3.14 Support: Expanded Python version compatibility
• COPY Escape Sequences: Proper interpretation of PostgreSQL COPY text format escape sequences
• Critical Bug Fixes: Resolved invalid dump generation and improved error messaging
• Documentation Improvements: Migrated to MkDocs with enhanced contribution guides

✨ New Features

PostgreSQL COPY Text Format Escape Sequences (#7)

The library now properly handles all PostgreSQL COPY text format escape sequences when reading table data:

• Single-character escapes: \b, \f, \n, \r, \t, \v
• Octal escapes: \NNN (1-3 digits)
• Hexadecimal escapes: \xNN (1-2 digits)
• Backslash escape: \\
• Literal fallback: \X → X for unknown sequences

The implementation is based directly on PostgreSQL's canonical source code (CopyReadAttributesText() in copyfromparse.c), ensuring 100% compatibility with how PostgreSQL handles escape sequences.

Impact: Previously, escape sequences were returned as literal strings (e.g., "\\n" as two characters). Now they are properly unescaped to their actual values (e.g., "\n" as a newline character). This matches PostgreSQL's behavior and is the expected behavior for COPY text format.

PostgreSQL 16-18 Support (#13, #15)

Added comprehensive support for PostgreSQL versions 16, 17, and 18:

• Dump format 1.15.0 (PostgreSQL 16): Compression algorithm specification in header
• Dump format 1.16.0 (PostgreSQL 17-18): BLOB METADATA entries, multiple BLOBS support, relkind attribute
• Default version: Updated to PostgreSQL 18.0 emulation in create() function
• K_OFFSET_POS_NOT_SET: Added support for this special offset value introduced in newer PostgreSQL versions

🐛 Bug Fixes

Invalid Dump Generation on Load/Save Cycle (#6, #14)

Fixed a critical bug where loading and saving a dump file would produce an invalid output if the dump included an empty tableam (table access method) field. The issue affected dumps created with PostgreSQL 16+ when tables used default access methods.

Before:

dump = pgdumplib.load('backup.dump')
dump.save('backup-copy.dump')  # ❌ Produces invalid dump

After:

dump = pgdumplib.load('backup.dump')
dump.save('backup-copy.dump')  # ✅ Valid dump

Improved Error Messages (#4, #14)

• Invalid Archive Header: Enhanced error messaging when loading dumps with unsupported format versions. Now provides clear indication of which dump format version was encountered and which versions are supported.
• Documentation Clarity: Fixed incorrect -Fd reference in documentation (should be -Fc for custom format dumps)

📚 Documentation

Migration to MkDocs

The project documentation has been migrated from Sphinx (ReadTheDocs) to MkDocs (GitHub Pages):

• New URL: Documentation now hosted on GitHub Pages
• Improved Navigation: Better organization and discoverability
• Markdown Format: Easier to read and contribute
• Detailed Contribution Guide: Added comprehensive development workflow documentation

README Updates

• Converted from reStructuredText to Markdown for better GitHub integration
• Updated code examples and usage patterns
• Clarified version support matrix

🔧 Infrastructure & Testing

Expanded CI Matrix

Comprehensive testing across Python and PostgreSQL versions:

• Python versions: 3.11, 3.12, 3.13, 3.14
• PostgreSQL versions: 15, 16, 17, 18
• Total test matrix: 32 combinations (4 Python × 8 PostgreSQL versions)

Docker Compose Refactor

Modernized development environment:

• Multi-version PostgreSQL testing via Docker Compose
• Automatic fixture generation for all supported PostgreSQL versions
• Simplified bootstrap process for new contributors

Type Checking

Added comprehensive type checking support:

• mypy: Full type checking with strict configuration
• py.typed: Package now marked as PEP 561 compliant
• Consistent use of typing module across codebase

⚠️ Breaking Changes

Python Version Support

Dropped support for Python 3.9 and 3.10. The minimum supported Python version is now 3.11.

Rationale: Python 3.9 reached end-of-life in October 2025, and Python 3.10 will reach EOL in October 2026. Focusing on actively supported versions allows us to leverage modern Python features and reduce maintenance burden.

Migration Path: Update your Python environment to 3.11 or later before upgrading to pgdumplib 4.0.0.

Escape Sequence Handling

Data converters now properly unescape COPY text format escape sequences. If your code relies on receiving literal escaped strings (e.g., "\\n" instead of "\n"), you'll need to update your logic or use the NoOpConverter:

# If you need raw escaped strings:
dump = pgdumplib.load('backup.dump', converter=pgdumplib.converters.NoOpConverter)

📦 Installation

pip install --upgrade pgdumplib

🙏 Acknowledgments

Special thanks to:

• @monroeclinton for PostgreSQL 16 support contributions (#13)
• @whtsky for CI improvements (#5)
• All community members who reported issues and provided feedback

📊 Statistics

• 82 commits since v3.1.0
• 5 pull requests merged
• 5 issues resolved
• 416 additions and 116 deletions across multiple files
• Test coverage: Maintained at ≥90%

🔗 Resources

• GitHub Repository: https://github.com/gmr/pgdumplib
• Documentation: https://gmr.github.io/pgdumplib
• PyPI Package: https://pypi.org/project/pgdumplib/
• Issue Tracker: https://github.com/gmr/pgdumplib/issues

---

Full Changelog: 3.1.0...4.0.0

3.1.0

Add libffi-dev