pgdumplib

https://gmr.github.io/pgdumplib/
Admin
pgdumplib is a Python 3 library for reading and writing PostgreSQL pg_dump files created using the...
Tokens:15,269
Snippets:126
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install pgdumplib with pip

Source: https://gmr.github.io/pgdumplib

Install the pgdumplib library using pip. This is the standard installation command for the package.

```bash
pip install pgdumplib

```

--------------------------------

### format property

Source: https://gmr.github.io/pgdumplib/api

Gets or sets the dump format (Custom, Directory, Tar).

```APIDOC
## format property

### Description
Gets or sets the dump format (Custom, Directory, Tar).

### Property
format (writable)

### Return Value
- The dump format (Custom, Directory, Tar).
```

--------------------------------

### Dump.format

Source: https://gmr.github.io/pgdumplib/api

Property that gets or sets the dump format (Custom, Directory, Tar).

```APIDOC
## Dump.format

### Description
Property that gets or sets the dump format (Custom, Directory, Tar).

### Method
Property getter and setter

### Returns
str - The dump format (Custom, Directory, Tar).
```

--------------------------------

### Create a new Dump instance with new()

Source: https://gmr.github.io/pgdumplib/api

The new function initializes a new Dump instance with specified database name, encoding, converter, and Postgres version emulation.

```python
def new(
    dbname: str = 'pgdumplib',
    encoding: str = 'UTF8',
    converter: typing.Any = None,
    appear_as: str = '18.0',
) -> 'dump.Dump':
    """Create a new :py:class:`pgdumplib.dump.Dump` instance

    :param dbname: The database name for the dump (Default: ``pgdumplib``)
    :param encoding: The data encoding (Default: ``UTF8``)
    :param converter: The data converter class to use
        (Default: :py:class:`pgdumplib.converters.DataConverter`)
    :type converter: Converter class or None
    :param appear_as: The version of Postgres to emulate
        (Default: ``18.0``)
    :rtype: pgdumplib.dump.Dump

    """
    from pgdumplib import dump

    return dump.Dump(dbname, encoding, converter, appear_as)
```

--------------------------------

### save(path)

Source: https://gmr.github.io/pgdumplib/api

Save the dump to disk.

```python
def save(self, path: str | os.PathLike) -> None:
    """Save the dump to disk

    :param os.PathLike path: The path to save the dump to

    """
    self._dump.save(str(path))
```

--------------------------------

### new(dbname='pgdumplib', encoding='UTF8', converter=None, appear_as='18.0')

Source: https://gmr.github.io/pgdumplib/api

Create a new Dump instance with configurable database name, encoding, converter, and PostgreSQL version emulation.

```APIDOC
## new(dbname='pgdumplib', encoding='UTF8', converter=None, appear_as='18.0')

### Description
Create a new Dump instance.

### Parameters
- **dbname** (str) - Optional - The database name for the dump. Defaults to 'pgdumplib'.
- **encoding** (str) - Optional - The data encoding. Defaults to 'UTF8'.
- **converter** (Converter class or None) - Optional - The data converter class to use. Defaults to pgdumplib.converters.DataConverter.
- **appear_as** (str) - Optional - The version of Postgres to emulate. Defaults to '18.0'.

### Returns
- **pgdumplib.dump.Dump** - The new dump instance.

### Example
```python
from pgdumplib import new

dump = new(dbname='mydb', encoding='UTF8')
```
```

--------------------------------

### load(path)

Source: https://gmr.github.io/pgdumplib/api

Load the Dumpfile. Loaded dumps are saved without compression by default, regardless of the original compression setting. Use set_compression after loading to specify the desired output compression.

```python
def load(self, path: str | os.PathLike) -> typing.Self:
    """Load the Dumpfile

    .. note::
        Loaded dumps are saved without compression by default,
        regardless of the original compression setting. The
        original compression algorithm is preserved for
        inspection via :attr:`compression_algorithm`. Use
        :meth:`set_compression` after loading to specify the
        desired output compression.

    :param os.PathLike path: The path of the dump to load
    :raises: :py:exc:`RuntimeError`
    :raises: :py:exc:`ValueError`

    """
    path = pathlib.Path(path)
    try:
        if path.is_file():
            self._check_file_format(path)
        self._dump = _pgdumplib.Dump.load(str(path))
    except OSError as err:
        raise ValueError(str(err)) from err

    ver = self._dump.version
    if not constants.MIN_VER <= ver <= constants.MAX_VER:
        raise ValueError(
            'Unsupported backup version: {}.{}.{}'.format(*ver)
        )

    # Preserve original compression for reporting, but save with none
    self._loaded_compression = self._dump.compression
    self._dump.set_compression(constants.COMPRESSION_NONE)

    self._detect_encoding()
    return self
```

--------------------------------

### Create a new database dump

Source: https://gmr.github.io/pgdumplib/examples

Construct a new dump file by adding entries for schemas, extensions, comments, types, and tables, then writing table data and saving the file.

```python
import datetime
import uuid

import pgdumplib
from pgdumplib import constants

dump = pgdumplib.new('example')

schema = dump.add_entry(
    desc=constants.SCHEMA,
    tag='test',
    defn='CREATE SCHEMA test;',
    drop_stmt='DROP SCHEMA test;')

dump.add_entry(
    desc=constants.ACL,
    tag='SCHEMA test',
    defn='GRANT USAGE ON SCHEMA test TO PUBLIC;',
    dependencies=[schema.dump_id])

uuid_ossp = dump.add_entry(
    desc=constants.EXTENSION,
    tag='uuid-ossp',
    defn='CREATE EXTENSION IF NOT EXISTS "uuid-ossp" WITH SCHEMA public;',
    drop_stmt='DROP EXTENSION "uuid-ossp";')

dump.add_entry(
    desc=constants.COMMENT,
    tag='EXTENSION "uuid-ossp"',
    defn="""COMMENT ON EXTENSION "uuid-ossp" IS 'generate universally unique identifiers (UUIDs)'""",
    dependencies=[uuid_ossp.dump_id])

addr_type = dump.add_entry(
    desc=constants.TYPE,
    namespace='test',
    tag='address_type',
    owner='postgres',
    defn="""\
    CREATE TYPE test.address_type AS ENUM ('billing', 'delivery');""",
    drop_stmt='DROP TYPE test.address_type;',
    dependencies=[schema.dump_id])

test_addresses = dump.add_entry(
    desc=constants.TABLE,
    namespace='test',
    tag='addresses',
    owner='postgres',
    defn="""\
    CREATE TABLE addresses (
        id               UUID                     NOT NULL DEFAULT uuid_generate_v4() PRIMARY KEY,
        created_at       TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
        last_modified_at TIMESTAMP WITH TIME ZONE,
        user_id          UUID                     NOT NULL REFERENCES users (id) ON DELETE CASCADE ON UPDATE CASCADE,
        type             address_type             NOT NULL,
        address1         TEXT                     NOT NULL,
        address2         TEXT,
        address3         TEXT,
        locality         TEXT                     NOT NULL,
        region           TEXT,
        postal_code      TEXT                     NOT NULL,
        country          TEXT                     NOT NULL
    );""",
    drop_stmt='DROP TABLE test.addresses;',
    dependencies=[schema.dump_id, addr_type.dump_id, uuid_ossp.dump_id])

example = dump.add_entry(
    constants.TABLE,
    'public', 'example', 'postgres',
    'CREATE TABLE public.example (\
        id UUID NOT NULL PRIMARY KEY,\
        created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,\
        value TEXT NOT NULL);',
    'DROP TABLE public.example')

with dump.table_data_writer(example, ['id', 'created_at', 'value']) as writer:
    writer.append(uuid.uuid4(), datetime.datetime.now(datetime.UTC), 'row1')
    writer.append(uuid.uuid4(), datetime.datetime.now(datetime.UTC), 'row2')
    writer.append(uuid.uuid4(), datetime.datetime.now(datetime.UTC), 'row3')
    writer.append(uuid.uuid4(), datetime.datetime.now(datetime.UTC), 'row4')
    writer.append(uuid.uuid4(), datetime.datetime.now(datetime.UTC), 'row5')

dump.save('custom.dump')
```

--------------------------------

### Create a database dump with pg_dump

Source: https://gmr.github.io/pgdumplib/examples

Use the pg_dump command-line tool to create a database dump in the required custom format.

```bash
pg_dump -Fc -d [YOUR] dump.out
```

--------------------------------

### Dump.__init__

Source: https://gmr.github.io/pgdumplib/api

Creates a new instance of the Dump class. Once created, the instance can be used to read existing dumps or to create new ones.

```APIDOC
## Dump.__init__

### Description
Creates a new instance of the Dump class. Once created, the instance can be used to read existing dumps or to create new ones.

### Method
Constructor

### Signature
Dump(dbname='pgdumplib', encoding='UTF8', converter=None, appear_as='12.0')

### Parameters
- **dbname** (str) - Optional - The database name for the dump. Default: 'pgdumplib'
- **encoding** (str) - Optional - The data encoding. Default: 'UTF8'
- **converter** (converter class) - Optional - The data converter class to use. Default: pgdumplib.converters.DataConverter
- **appear_as** (str) - Optional - The version of Postgres to emulate. Default: '12.0'

### Returns
A new Dump instance.
```

--------------------------------

### server_version property

Source: https://gmr.github.io/pgdumplib/api

Returns the PostgreSQL server version string.

```APIDOC
## server_version property

### Description
Returns the PostgreSQL server version string.

### Property
server_version

### Return Value
- The PostgreSQL server version string.
```

--------------------------------

### lookup_entry(desc, namespace, tag)

Source: https://gmr.github.io/pgdumplib/api

Lookup an entry by description, namespace, and tag.

```python
def lookup_entry(
    self,
    desc: str,
    namespace: str,
    tag: str,
) -> models.Entry | None:
    """Lookup an entry by description, namespace, and tag

    :param str desc: The entry description
    :param str namespace: The namespace
    :param str tag: The tag
    :rtype: pgdumplib.models.Entry or None

    """
    if desc not in constants.SECTION_MAPPING:
        raise ValueError(f'Invalid desc: {desc}')
    entry = self._dump.lookup_entry(desc, namespace, tag)
    if entry is None:
        return None
    return self._to_entry(entry)
```

--------------------------------

### load(filepath, converter=None)

Source: https://gmr.github.io/pgdumplib/api

Load a pg_dump file from disk and return a Dump instance. The filepath can be a string or pathlib.Path, and an optional converter class can be provided.

```APIDOC
## load(filepath, converter=None)

### Description
Load a pg_dump file from disk and return a Dump instance.

### Parameters
- **filepath** (str or pathlib.Path) - Required - The path to the dump to load.
- **converter** (Converter class or None) - Optional - The data converter class to use. Defaults to pgdumplib.converters.DataConverter.

### Returns
- **pgdumplib.dump.Dump** - The loaded dump instance.

### Raises
- **ValueError** - If the file cannot be loaded.

### Example
```python
from pgdumplib import load

dump = load('backup.dump')
```
```

--------------------------------

### Dump.server_version

Source: https://gmr.github.io/pgdumplib/api

Property that returns the PostgreSQL server version string.

```APIDOC
## Dump.server_version

### Description
Property that returns the PostgreSQL server version string.

### Method
Property getter

### Returns
str - The PostgreSQL server version string.
```

--------------------------------

### Dump.load(path)

Source: https://gmr.github.io/pgdumplib/api

Loads a dump file from the given path. Loaded dumps are saved without compression by default, regardless of the original compression setting. The original compression algorithm is preserved for inspection via compression_algorithm.

```APIDOC
## Dump.load(path)

### Description
Loads a dump file from the given path. Loaded dumps are saved without compression by default, regardless of the original compression setting. The original compression algorithm is preserved for inspection via compression_algorithm.

### Method
load(path: str | os.PathLike) -> typing.Self

### Parameters
- **path** (str | os.PathLike) - Required - The path of the dump to load.

### Returns
- **typing.Self** - The Dump instance after loading.

### Raises
- **RuntimeError** - If loading fails.
- **ValueError** - If the path is invalid.
```

--------------------------------

### add_entry(desc, namespace, tag, owner, defn, drop_stmt, copy_stmt, dependencies, tableam, tablespace)

Source: https://gmr.github.io/pgdumplib/api

Adds a new entry to the dump. Returns the entry as a models.Entry object.

```APIDOC
## add_entry(desc, namespace, tag, owner, defn, drop_stmt, copy_stmt, dependencies, tableam, tablespace)

### Description
Adds a new entry to the dump. Returns the entry as a models.Entry object.

### Method
add_entry

### Parameters
- **desc** (str) - Required - The entry description
- **namespace** (str) - Required - The namespace
- **tag** (str) - Required - The tag
- **owner** (str) - Required - The owner
- **defn** (str) - Required - The definition
- **drop_stmt** (str) - Required - The drop statement
- **copy_stmt** (str) - Required - The copy statement
- **dependencies** (list) - Required - The dependencies
- **tableam** (str) - Optional - The table access method
- **tablespace** (str) - Optional - The tablespace

### Returns
- **models.Entry** - The created entry
```

--------------------------------

### save(path)

Source: https://gmr.github.io/pgdumplib/api

Save the dump to disk at the given path.

```APIDOC
## save(path)

### Description
Save the dump to disk.

### Method
save

### Parameters
- **path** (os.PathLike) - Required - The path to save the dump to

### Returns
- **None**
```

--------------------------------

### Dump.add_entry(desc, namespace=None, tag=None, owner=None, defn=None, drop_stmt=None, copy_stmt=None, dependencies=None, tablespace=None, tableam=None, dump_id=None)

Source: https://gmr.github.io/pgdumplib/api

Adds an entry to the dump. Raises ValueError if desc is invalid, if dependencies are not found, or if dump_id is already assigned. Returns an Entry object.

```APIDOC
## Dump.add_entry(desc, namespace=None, tag=None, owner=None, defn=None, drop_stmt=None, copy_stmt=None, dependencies=None, tablespace=None, tableam=None, dump_id=None)

### Description
Adds an entry to the dump. Raises ValueError if desc is not a known value in pgdumplib.constants, if dependencies are not found, or if dump_id is already assigned. Returns an Entry object.

### Method
add_entry

### Parameters
- **desc** (str) - Required - The entry description
- **namespace** (str) - Optional - The namespace of the entry
- **tag** (str) - Optional - The name/table/relation/etc of the entry
- **owner** (str) - Optional - The owner of the object in Postgres
- **defn** (str) - Optional - The DDL definition for the entry
- **drop_stmt** (str) - Optional - A drop statement used to drop the entry
- **copy_stmt** (str) - Optional - A copy statement used when there is a corresponding data section
- **dependencies** (list) - Optional - A list of dump_ids of objects that the entry is dependent upon
- **tablespace** (str) - Optional - The tablespace to use
- **tableam** (str) - Optional - The table access method
- **dump_id** (int) - Optional - The dump id, will be auto-calculated if left empty

### Return Value
pgdumplib.dump.Entry

### Exceptions
- ValueError - If desc is invalid, if dependencies are not found, or if dump_id is already assigned
- NotImplementedError - If a custom dump_id is specified (not yet supported by the Rust backend)

### Notes
- When adding data, use Dump.table_data_writer instead of invoking add_entry directly.
- The creation of ad-hoc blobs is not supported.
- The dump_id will be auto-calculated based upon the existing entries if it is not specified.
```

--------------------------------

### version property

Source: https://gmr.github.io/pgdumplib/api

Returns the archive format version as a tuple.

```APIDOC
## version property

### Description
Returns the archive format version as a tuple.

### Property
version

### Return Value
- The archive format version as a tuple.
```

--------------------------------

### lookup_entry(desc, namespace, tag)

Source: https://gmr.github.io/pgdumplib/api

Lookup an entry by description, namespace, and tag. Returns None if not found.

```APIDOC
## lookup_entry(desc, namespace, tag)

### Description
Lookup an entry by description, namespace, and tag.

### Method
lookup_entry

### Parameters
- **desc** (str) - Required - The entry description
- **namespace** (str) - Required - The namespace
- **tag** (str) - Required - The tag

### Raises
- **ValueError** - If desc is not a valid section mapping

### Returns
- **pgdumplib.models.Entry | None** - The entry if found, otherwise None
```

--------------------------------

### Read data and table definitions

Source: https://gmr.github.io/pgdumplib/examples

Load a dump file and iterate through table rows or look up specific table definitions.

```python
import pgdumplib
from pgdumplib import constants

dump = pgdumplib.load('dump.out')
for row in dump.table_data('public', 'table-name'):
    print(row)
print(dump.lookup_entry(constants.TABLE, 'public', 'table-name').defn)
```

--------------------------------

### load(path)

Source: https://gmr.github.io/pgdumplib/api

Load the Dumpfile from the given path. Raises RuntimeError or ValueError on failure.

```APIDOC
## load(path)

### Description
Load the Dumpfile from the given path. Loaded dumps are saved without compression by default, regardless of the original compression setting. The original compression algorithm is preserved for inspection via compression_algorithm. Use set_compression after loading to specify the desired output compression.

### Method
load

### Parameters
- **path** (os.PathLike) - Required - The path of the dump to load

### Raises
- **RuntimeError** - If the dump cannot be loaded
- **ValueError** - If the path is invalid or the dump version is unsupported

### Returns
- **typing.Self** - The Dump instance
```

--------------------------------

### Dump Class Definition

Source: https://gmr.github.io/pgdumplib/api

The Dump class constructor initializes a new instance for managing database dumps, allowing configuration of the database name, encoding, converter, and PostgreSQL version emulation.

```python
class Dump:
    """Create a new instance of the :py:class:`~pgdumplib.dump.Dump` class

    Once created, the instance of :py:class:`~pgdumplib.dump.Dump` can
    be used to read existing dumps or to create new ones.

    :param str dbname: The database name for the dump
        (Default: ``pgdumplib``)
    :param str encoding: The data encoding (Default: ``UTF8``)
    :param converter: The data converter class to use
        (Default: :py:class:`pgdumplib.converters.DataConverter`)
    :param str appear_as: The version of Postgres to emulate
        (Default: ``12.0``)

    """

    def __init__(
        self,
        dbname: str = 'pgdumplib',
        encoding: str = 'UTF8',
        converter: typing.Any = None,
        appear_as: str = '12.0',
    ):
        self._validate_appear_as(appear_as)
        self._dump = _pgdumplib.Dump(dbname, encoding, appear_as)
        self.encoding = encoding
        self._format = 'Custom'
        self._loaded_compression: str | None = None
        converter = converter or converters.DataConverter
        self._converter: converters.DataConverter = converter()

    def __repr__(self) -> str:
        return (
            f'<Dump format={self.format!r} '
            f'timestamp={self.timestamp.isoformat()!r} '
            f'entry_count={self._dump.entry_count()!r}>'
        )

    @property
    def compression_algorithm(self) -> str:
        """The compression algorithm used in the dump"""
        if self._loaded_compression is not None:
            return self._loaded_compression
        return self._dump.compression

    @property
    def dbname(self) -> str:
        """The database name"""
        return self._dump.dbname

    @property
    def dump_version(self) -> str:
        """The pg_dump version string"""
        return self._dump.dump_version

    @property
    def entries(self) -> list[models.Entry]:
        """The list of entries in the dump"""
        return [self._to_entry(e) for e in self._dump.entries]

    @property
    def format(self) -> str:
        """The dump format (Custom, Directory, Tar)"""
        return self._format

    @format.setter
    def format(self, value: str) -> None:
        self.set_format(value)

    @property
    def server_version(self) -> str:
        """The PostgreSQL server version string"""
        return self._dump.server_version

    @property
    def timestamp(self) -> datetime.datetime:
        """The dump creation timestamp"""
        return self._dump.timestamp
```

--------------------------------

### compression_algorithm property

Source: https://gmr.github.io/pgdumplib/api

Returns the compression algorithm used in the dump.

```APIDOC
## compression_algorithm property

### Description
Returns the compression algorithm used in the dump.

### Property
compression_algorithm

### Return Value
- The compression algorithm used in the dump.
```

--------------------------------

### dbname property

Source: https://gmr.github.io/pgdumplib/api

Returns the database name.

```APIDOC
## dbname property

### Description
Returns the database name.

### Property
dbname

### Return Value
- The database name.
```

--------------------------------

### set_format(fmt) - Set output format

Source: https://gmr.github.io/pgdumplib/api

Sets the output format for the dump. Accepts 'Custom', 'Directory', or 'Tar'. Delegates to the underlying dump object and stores the format locally.

```python
def set_format(self, fmt: str) -> None:
    """Set the output format

    :param str fmt: The output format (Custom, Directory, Tar)

    """
    self._dump.set_format(fmt)
    self._format = fmt

```

--------------------------------

### Dump.dbname

Source: https://gmr.github.io/pgdumplib/api

Property that returns the database name.

```APIDOC
## Dump.dbname

### Description
Property that returns the database name.

### Method
Property getter

### Returns
str - The database name.
```

--------------------------------

### set_compression(algorithm) - Set compression algorithm

Source: https://gmr.github.io/pgdumplib/api

Sets the compression algorithm for the dump. Accepts 'none', 'gzip', 'lz4', or 'zstd'. Resets the loaded compression state before delegating to the underlying dump object.

```python
def set_compression(self, algorithm: str) -> None:
    """Set the compression algorithm

    :param str algorithm: The compression algorithm
        (none, gzip, lz4, zstd)

    """
    self._loaded_compression = None
    self._dump.set_compression(algorithm)

```

--------------------------------

### dump_version property

Source: https://gmr.github.io/pgdumplib/api

Returns the pg_dump version string.

```APIDOC
## dump_version property

### Description
Returns the pg_dump version string.

### Property
dump_version

### Return Value
- The pg_dump version string.
```

--------------------------------

### Convert raw entry to model

Source: https://gmr.github.io/pgdumplib/api

Maps a raw _pgdumplib.Entry to a models.Entry object.

```python
    @staticmethod
    def _to_entry(raw: _pgdumplib.Entry) -> models.Entry:
        return models.Entry(
            dump_id=raw.dump_id,
            had_dumper=raw.had_dumper,
            table_oid=raw.table_oid or '0',
            oid=raw.oid or '0',
            tag=raw.tag,
            desc=raw.desc,
            defn=raw.defn,
            drop_stmt=raw.drop_stmt,
            copy_stmt=raw.copy_stmt,
            namespace=raw.namespace,
            tablespace=raw.tablespace,
            tableam=raw.tableam,
            relkind=raw.relkind,
            owner=raw.owner,
            with_oids=raw.with_oids,
            dependencies=raw.dependencies,
            data_state=raw.data_state,
            offset=raw.offset,
        )
```

--------------------------------

### timestamp property

Source: https://gmr.github.io/pgdumplib/api

Returns the dump creation timestamp.

```APIDOC
## timestamp property

### Description
Returns the dump creation timestamp.

### Property
timestamp

### Return Value
- The dump creation timestamp.
```

--------------------------------

### Load a pg_dump file with load()

Source: https://gmr.github.io/pgdumplib/api

The load function reads a pg_dump file from the specified filepath. It accepts an optional converter class to handle data conversion.

```python
def load(
    filepath: str | pathlib.Path,
    converter: typing.Any = None,
) -> 'dump.Dump':
    """Load a pg_dump file from disk

    :param filepath: The path to the dump to load
    :type filepath: str or pathlib.Path
    :param converter: The data converter class to use
        (Default: :py:class:`pgdumplib.converters.DataConverter`)
    :type converter: Converter class or None
    :raises: :py:exc:`ValueError`
    :rtype: pgdumplib.dump.Dump

    """
    from pgdumplib import dump

    return dump.Dump(converter=converter).load(filepath)
```

--------------------------------

### SmartDataConverter.convert static method

Source: https://gmr.github.io/pgdumplib/converters

Static method that splits a tab-separated row string and converts each column using SmartDataConverter._convert_column, returning a tuple of SmartColumn objects. Used as the entry point for converting a row from the dump data.

```python
@staticmethod
def convert(row: str) -> tuple[SmartColumn, ...]:
    """Convert the string based row into a tuple of columns"""
    return tuple(
        SmartDataConverter._convert_column(c) for c in row.split('\t')
    )

```

--------------------------------

### entries property

Source: https://gmr.github.io/pgdumplib/api

Returns the list of entries in the dump.

```APIDOC
## entries property

### Description
Returns the list of entries in the dump.

### Property
entries

### Return Value
- The list of entries in the dump.
```

--------------------------------

### Dump.dump_version

Source: https://gmr.github.io/pgdumplib/api

Property that returns the pg_dump version string.

```APIDOC
## Dump.dump_version

### Description
Property that returns the pg_dump version string.

### Method
Property getter

### Returns
str - The pg_dump version string.
```

--------------------------------

### Dump.compression_algorithm

Source: https://gmr.github.io/pgdumplib/api

Property that returns the compression algorithm used in the dump.

```APIDOC
## Dump.compression_algorithm

### Description
Property that returns the compression algorithm used in the dump.

### Method
Property getter

### Returns
str - The compression algorithm used in the dump.
```

--------------------------------

### Dump.version (property)

Source: https://gmr.github.io/pgdumplib/api

Returns the archive format version as a tuple of three integers. This property provides read-only access to the version information of the dump.

```APIDOC
## Dump.version (property)

### Description
Returns the archive format version as a tuple of three integers.

### Property
`version` -> tuple[int, int, int]

### Returns
- **tuple[int, int, int]** - The archive format version as a tuple.
```

--------------------------------

### Validate appear_as version

Source: https://gmr.github.io/pgdumplib/api

Validates the PostgreSQL version string against supported ranges in constants.K_VERSION_MAP.

```python
    @staticmethod
    def _validate_appear_as(appear_as: str) -> None:
        parts = appear_as.split('.')
        if len(parts) < 2:
            raise ValueError(f'Invalid appear_as version: {appear_as}')
        try:
            major = int(parts[0])
            minor = int(parts[1])
        except ValueError as err:
            raise ValueError(
                f'Invalid appear_as version: {appear_as}'
            ) from err

        for key_range, _value in constants.K_VERSION_MAP.items():
            pg_ver = (major, minor)
            if len(key_range[0]) == 3:
                pg_ver = (
                    major,
                    minor,
                    int(parts[2]) if len(parts) > 2 else 0,
                )
            if key_range[0] <= pg_ver <= key_range[1]:
                return
        raise RuntimeError(f'Unsupported version: {appear_as}')
```

--------------------------------

### Dump.timestamp

Source: https://gmr.github.io/pgdumplib/api

Property that returns the dump creation timestamp.

```APIDOC
## Dump.timestamp

### Description
Property that returns the dump creation timestamp.

### Method
Property getter

### Returns
datetime.datetime - The dump creation timestamp.
```

--------------------------------

### Dump.add_entry(desc, namespace, tag, owner, defn, drop_stmt, copy_stmt, dependencies, tablespace, tableam, dump_id)

Source: https://gmr.github.io/pgdumplib/api

Adds an entry to the dump. Raises ValueError if desc is not a known value in pgdumplib.constants, if dependencies are invalid, or if a specified dump_id is already assigned. When adding data, use table_data_writer instead of invoking add_entry directly.

```APIDOC
## Dump.add_entry(desc, namespace, tag, owner, defn, drop_stmt, copy_stmt, dependencies, tablespace, tableam, dump_id)

### Description
Adds an entry to the dump. Raises ValueError if desc is not a known value in pgdumplib.constants, if dependencies are invalid, or if a specified dump_id is already assigned. When adding data, use table_data_writer instead of invoking add_entry directly.

### Method
add_entry(desc: str, namespace: str | None = None, tag: str | None = None, owner: str | None = None, defn: str | None = None, drop_stmt: str | None = None, copy_stmt: str | None = None, dependencies: list[int] | None = None, tablespace: str | None = None, tableam: str | None = None, dump_id: int | None = None) -> models.Entry

### Parameters
- **desc** (str) - Required - The entry description. Must be a value known in pgdumplib.constants.
- **namespace** (str | None) - Optional - The namespace of the entry.
- **tag** (str | None) - Optional - The name/table/relation/etc of the entry.
- **owner** (str | None) - Optional - The owner of the object in Postgres.
- **defn** (str | None) - Optional - The DDL definition for the entry.
- **drop_stmt** (str | None) - Optional - A drop statement used to drop the entry.
- **copy_stmt** (str | None) - Optional - A copy statement used when there is a corresponding data section.
- **dependencies** (list[int] | None) - Optional - A list of dump_ids of objects that the entry is dependent upon.
- **tablespace** (str | None) - Optional - The tablespace to use.
- **tableam** (str | None) - Optional - The table access method.
- **dump_id** (int | None) - Optional - The dump id, will be auto-calculated if left empty.

### Returns
- **models.Entry** - The newly added entry.

### Raises
- **ValueError** - If desc is invalid, dump_id is less than 1, dump_id is already assigned, or a dependency dump_id is not found.
- **NotImplementedError** - If a custom dump_id is specified (not yet supported by the Rust backend).
```

--------------------------------

### Dump.entries

Source: https://gmr.github.io/pgdumplib/api

Property that returns the list of entries in the dump.

```APIDOC
## Dump.entries

### Description
Property that returns the list of entries in the dump.

### Method
Property getter

### Returns
list[models.Entry] - The list of entries in the dump.
```

--------------------------------

### add_entry method definition

Source: https://gmr.github.io/pgdumplib/api

The implementation of the add_entry method in pgdumplib/dump.py, which validates input parameters and manages entry dependencies.

```python
def add_entry(
    self,
    desc: str,
    namespace: str | None = None,
    tag: str | None = None,
    owner: str | None = None,
    defn: str | None = None,
    drop_stmt: str | None = None,
    copy_stmt: str | None = None,
    dependencies: list[int] | None = None,
    tablespace: str | None = None,
    tableam: str | None = None,
    dump_id: int | None = None,
) -> models.Entry:
    """Add an entry to the dump

    A :py:exc:`ValueError` will be raised if `desc` is not value that
    is known in :py:module:`pgdumplib.constants`.

    When adding data, use :py:meth:`~Dump.table_data_writer` instead
    of invoking :py:meth:`~Dump.add_entry` directly.

    If ``dependencies`` are specified, they will be validated and if a
    ``dump_id`` is specified and no entry is found with that
    ``dump_id``, a :py:exc:`ValueError` will be raised.

    Other omitted values will be set to the default values specified
    in the :py:class:`pgdumplib.dump.Entry` class.

    The ``dump_id`` will be auto-calculated based upon the existing
    entries if it is not specified.

    .. note:: The creation of ad-hoc blobs is not supported.

    :param str desc: The entry description
    :param str namespace: The namespace of the entry
    :param str tag: The name/table/relation/etc of the entry
    :param str owner: The owner of the object in Postgres
    :param str defn: The DDL definition for the entry
    :param drop_stmt: A drop statement used to drop the entry
    :param copy_stmt: A copy statement used when there is a
        corresponding data section.
    :param list dependencies: A list of dump_ids of objects that
        the entry is dependent upon.
    :param str tablespace: The tablespace to use
    :param str tableam: The table access method
    :param int dump_id: The dump id, will be auto-calculated if
        left empty
    :raises: :py:exc:`ValueError`
    :rtype: pgdumplib.dump.Entry

    """
    if desc not in constants.SECTION_MAPPING:
        raise ValueError(f'Invalid desc: {desc}')

    if dump_id is not None and dump_id < 1:
        raise ValueError('dump_id must be greater than 1')

    # TODO: Pass dump_id through to _dump.add_entry once the Rust
    # backend supports it, then remove this guard.
    if dump_id is not None:
        raise NotImplementedError(
            'Custom dump_id is not yet supported by the Rust backend'
        )

    existing_ids = self._dump.entry_dump_ids()

    if dump_id and dump_id in existing_ids:
        raise ValueError(f'dump_id {dump_id!r} is already assigned')

    for dependency in dependencies or []:
        if dependency not in existing_ids:
            raise ValueError(
                f'Dependency dump_id {dependency!r} not found'
            )
```

--------------------------------

### Dump.blobs()

Source: https://gmr.github.io/pgdumplib/api

Iterator that returns each blob in the dump as a tuple of (int, bytes). Yields blob data sequentially.

```APIDOC
## Dump.blobs()

### Description
Iterator that returns each blob in the dump as a tuple of (int, bytes). Yields blob data sequentially.

### Method
blobs() -> typing.Generator[tuple[int, bytes], None, None]

### Returns
- **typing.Generator[tuple[int, bytes], None, None]** - A generator yielding tuples of (dump_id, blob_bytes).
```

--------------------------------

### Validate dump format and encoding

Source: https://gmr.github.io/pgdumplib/api

Internal logic to verify file headers and detect encoding from dump entries.

```python
        if not header:
            raise ValueError(
                'Empty file. Use pg_dump -Fc to create a custom format dump.'
            )

        if header[:5] == constants.MAGIC:
            return

        try:
            text = header.decode('utf-8', errors='replace')
            if text.startswith(
                ('--', 'CREATE', 'SET', 'SELECT', 'INSERT', 'ALTER', 'DROP')
            ):
                raise ValueError(
                    'This appears to be a plain SQL text file, '
                    'not a custom format dump. '
                    'Use pg_dump -Fc to create a '
                    'custom format dump.'
                )
        except UnicodeDecodeError:
            pass

        # Allow unknown binary formats (e.g., tar archives) to pass
        # through to the Rust backend for handling

    def _detect_encoding(self) -> None:
        """Detect the encoding from the dump's ENCODING entry"""
        entry = self._dump.get_entry(1)
        if entry and entry.desc == constants.ENCODING and entry.defn:
            match = ENCODING_PATTERN.search(entry.defn)
            if match:
                self.encoding = match.group(1)
```

--------------------------------

### Dump.get_entry(dump_id)

Source: https://gmr.github.io/pgdumplib/api

Returns the entry for the given dump_id. Returns None if no entry exists with that dump_id.

```APIDOC
## Dump.get_entry(dump_id)

### Description
Returns the entry for the given dump_id. Returns None if no entry exists with that dump_id.

### Method
get_entry(dump_id: int) -> models.Entry | None

### Parameters
- **dump_id** (int) - Required - The dump ID of the entry to return.

### Returns
- **models.Entry | None** - The entry with the given dump_id, or None if not found.
```

--------------------------------

### get_entry(dump_id)

Source: https://gmr.github.io/pgdumplib/api

Return the entry for the given dump_id. Returns None if not found.

```APIDOC
## get_entry(dump_id)

### Description
Return the entry for the given dump_id.

### Method
get_entry

### Parameters
- **dump_id** (int) - Required - The dump ID of the entry to return.

### Returns
- **models.Entry | None** - The entry if found, otherwise None
```

--------------------------------

### blobs()

Source: https://gmr.github.io/pgdumplib/api

Iterator that returns each blob in the dump.

```python
def blobs(self) -> typing.Generator[tuple[int, bytes], None, None]:
    """Iterator that returns each blob in the dump

    :rtype: tuple(int, bytes)

    """
    yield from self._dump.blobs()
```

--------------------------------

### get_entry(dump_id)

Source: https://gmr.github.io/pgdumplib/api

Return the entry for the given dump_id.

```python
def get_entry(self, dump_id: int) -> models.Entry | None:
    """Return the entry for the given `dump_id`

    :param int dump_id: The dump ID of the entry to return.

    """
    entry = self._dump.get_entry(dump_id)
    if entry is None:
        return None
    return self._to_entry(entry)
```

--------------------------------

### table_data_writer(entry, columns) - Context manager for writing table data

Source: https://gmr.github.io/pgdumplib/api

Context manager for writing table data. Reuses an existing TABLE DATA entry if present, raising ValueError if columns do not match. Yields a TableData writer and appends the written data to the dump entry.

```python
@contextlib.contextmanager
def table_data_writer(
    self,
    entry: models.Entry,
    columns: abc.Sequence,
) -> typing.Generator[TableData, None, None]:
    """Context manager for writing table data

    :param entry: The entry the data is for
    :param columns: The columns being written
    :rtype: TableData

    """
    copy_stmt = (
        f'COPY {entry.namespace}.{entry.tag}'
        f' ({
```

--------------------------------

### blobs()

Source: https://gmr.github.io/pgdumplib/api

Iterator that returns each blob in the dump as a tuple of (int, bytes).

```APIDOC
## blobs()

### Description
Iterator that returns each blob in the dump.

### Method
blobs

### Returns
- **tuple(int, bytes)** - A tuple containing the blob ID and the blob data
```

--------------------------------

### NoOpConverter.convert static method

Source: https://gmr.github.io/pgdumplib/converters

Returns the row passed in without any conversion.

```python
@staticmethod
def convert(row: str) -> str:
    """Returns the row passed in

    :param str row: The row to convert
    :rtype: str

    """
    return row
```

--------------------------------

### table_data(namespace, table) - Iterate over table data

Source: https://gmr.github.io/pgdumplib/api

Iterates over the data for a specified table, converting each row. Raises EntityNotFoundError if the table is not found and NoDataError if no data is available.

```python
def table_data(
    self,
    namespace: str,
    table: str,
) -> typing.Generator:
    """Iterate over the data for the specified table

    :param str namespace: The namespace/schema
    :param str table: The table name
    :raises: :py:exc:`pgdumplib.exceptions.EntityNotFoundError`
    :raises: :py:exc:`pgdumplib.exceptions.NoDataError`

    """
    for row in self._dump.table_data(namespace, table):
        yield self._converter.convert(row)

```

--------------------------------

### TableData.get_data Method

Source: https://gmr.github.io/pgdumplib/api

Returns the accumulated table data as bytes.

```python
def get_data(self) -> bytes:
    """Return the accumulated data as bytes"""
    return self._buffer.getvalue()
```

--------------------------------

### NoOpConverter class definition

Source: https://gmr.github.io/pgdumplib/converters

Performs no conversion on the row passed in, returning it unchanged.

```python
class NoOpConverter:
    """Performs no conversion on the row passed in"""

    @staticmethod
    def convert(row: str) -> str:
        """Returns the row passed in

        :param str row: The row to convert
        :rtype: str

        """
        return row
```

--------------------------------

### TableData.append(*args)

Source: https://gmr.github.io/pgdumplib/api

Appends a row to the table data. The column order must match the order specified when Dump.table_data_writer was invoked. All columns are coerced to strings, with None converted to the null marker and datetime objects formatted according to pg_dump timestamp format.

```APIDOC
## TableData.append(*args)

### Description
Append a row to the table data, passing columns in as args. Column order must match the order specified when Dump.table_data_writer was invoked. All columns will be coerced to a string with special attention paid to None, converting it to the null marker (\N) and datetime.datetime objects, which will have the proper pg_dump timestamp format applied to them.

### Method
append(*args)

### Parameters
- *args (any) - Required - The column values for the row, in the order specified when Dump.table_data_writer was invoked.

### Returns
None

### Example
```python
table_data.append('value1', 'value2', None, datetime.datetime.now())
```
```

--------------------------------

### SmartDataConverter class with convert and _convert_column methods

Source: https://gmr.github.io/pgdumplib/converters

Converts string-based row/column data into native Python types (int, datetime, Decimal, IP addresses, UUID, etc.) for use with the pgdumplib Dump.read_data iterator. Handles NULL markers and unescapes copy text before conversion, falling back to the original string if no type matches.

```python
class SmartDataConverter(DataConverter):
    """Attempts to convert columns to native Python data types

    Used for converting row/column data with the
    :meth:`pgdumplib.dump.Dump.read_data` iterator.

    Possible conversion types:

        - :py:class:`int`
        - :py:class:`datetime.datetime`
        - :py:class:`decimal.Decimal`
        - :py:class:`ipaddress.IPv4Address`
        - :py:class:`ipaddress.IPv4Network`
        - :py:class:`ipaddress.IPv6Address`
        - :py:class:`ipaddress.IPv6Network`
        - :py:const:`None`
        - :py:class:`str`
        - :py:class:`uuid.UUID`

    """

    @staticmethod
    def convert(row: str) -> tuple[SmartColumn, ...]:
        """Convert the string based row into a tuple of columns"""
        return tuple(
            SmartDataConverter._convert_column(c) for c in row.split('\t')
        )

    @staticmethod
    def _convert_column(column: str) -> SmartColumn:
        """Attempt to convert the column from a string if appropriate"""
        # Check for NULL before unescaping (PostgreSQL does this)
        if column == '\\N':
            return None
        # Unescape the column data
        column = unescape_copy_text(column)
        if column.strip('-').isnumeric():
            return int(column)
        elif column.strip('-').replace('.', '').isnumeric():
            try:
                return decimal.Decimal(column)
            except (ValueError, decimal.InvalidOperation):
                pass
        try:
            return ipaddress.ip_address(column)
        except ValueError:
            pass
        try:
            return ipaddress.ip_network(column)
        except ValueError:
            pass
        try:
            return uuid.UUID(column)
        except ValueError:
            pass
        for tz_fmt in {'Z', 'ZZ', 'z', 'zz'}:
            for micro_fmt in {'.SSSSSS', ''}:
                try:
                    pdt = pendulum.from_format(
                        column, f'YYYY-MM-DD HH:mm:ss{micro_fmt} {tz_fmt}'
                    )
                    # Convert pendulum DateTime to datetime.datetime
                    return datetime.datetime.fromisoformat(pdt.isoformat())
                except ValueError:
                    pass
        return column

```

--------------------------------

### DataConverter.convert static method

Source: https://gmr.github.io/pgdumplib/converters

Converts a string row into a tuple of columns, replacing '\N' with None and unescaping other escape sequences.

```python
@staticmethod
def convert(row: str) -> tuple[typing.Any, ...]:
    """Convert the string based row into a tuple of columns.

    :param str row: The row to convert
    :rtype: tuple

    """
    return tuple(
        None if e == '\\N' else unescape_copy_text(e)
        for e in row.split('\t')
    )
```

--------------------------------

### TableData.get_data()

Source: https://gmr.github.io/pgdumplib/api

Returns the accumulated table data as bytes. This method is used to retrieve the buffered data after appending rows.

```APIDOC
## TableData.get_data()

### Description
Return the accumulated data as bytes.

### Method
get_data()

### Parameters
None

### Returns
bytes - The accumulated data as bytes.

### Example
```python
data = table_data.get_data()
```
```

--------------------------------

### TableData.append Method

Source: https://gmr.github.io/pgdumplib/api

Appends a row to the table data. Column order must match the order specified when table_data_writer was invoked.

```python
def append(self, *args) -> None:
    """Append a row to the table data, passing columns in as args

    Column order must match the order specified when
    :py:meth:`~pgdumplib.dump.Dump.table_data_writer` was invoked.

    All columns will be coerced to a string with special attention
    paid to ``None``, converting it to the null marker (``\\N``) and
    :py:class:`datetime.datetime` objects, which will have the proper
    pg_dump timestamp format applied to them.

    """
    row = '\t'.join([self._convert(c) for c in args])
    self._buffer.write(f'{row}\n'.encode(self._encoding))
```

--------------------------------

### TableData.size (property)

Source: https://gmr.github.io/pgdumplib/api

Returns the current size of the buffered data. This property provides the number of bytes currently stored in the buffer.

```APIDOC
## TableData.size (property)

### Description
Return the current size of the buffered data.

### Property
size

### Returns
int - The current size of the buffered data in bytes.

### Example
```python
size = table_data.size
```
```
Tokens:
Raw