COPY-related objects#

The main objects (Copy, AsyncCopy) present the main interface to exchange data during a COPY operations. These objects are normally obtained by the methods Cursor.copy() and AsyncCursor.copy(); however, they can be also created directly, for instance to write to a destination which is not a database (e.g. using a FileWriter).

See Using COPY TO and COPY FROM for details.

Main Copy objects#

class psycopg.Copy#

Manage an asynchronous COPY operation.

Parameters:

cursor – the cursor where the operation is performed.
binary – if True, write binary format.
writer – the object to write to destination. If not specified, write to the cursor connection.

Choosing binary is not necessary if the cursor has executed a COPY operation, because the operation result describes the format too. The parameter is useful when a Copy object is created manually and no operation is performed on the cursor, such as when using writer=FileWriter.

The object is normally returned by with Cursor.copy().

write_row(row: Sequence[Any]) → None#

Write a record to a table after a COPY FROM operation.

The data in the tuple will be converted as configured on the cursor; see Data adaptation configuration for details.

write(buffer: Buffer | str) → None#

Write a block of data to a table after a COPY FROM operation.

If the COPY is in binary format buffer must be bytes. In text mode it can be either bytes or str.

read() → Buffer#

Read an unparsed row after a COPY TO operation.

Return an empty string when the data is finished.

Instead of using read() you can iterate on the Copy object to read its data row by row, using for row in copy: ....

rows() → Iterator[tuple[Any, ...]]#

Iterate on the result of a COPY TO operation record by record.

Note that the records returned will be tuples of unparsed strings or bytes, unless data types are specified using set_types().

Equivalent of iterating on read_row() until it returns None

read_row() → tuple[Any, ...] | None#

Read a parsed row of data from a table after a COPY TO operation.

Return None when the data is finished.

Note that the records returned will be tuples of unparsed strings or bytes, unless data types are specified using set_types().

set_types(types: Sequence[int | str]) → None#

Set the types expected in a COPY operation.

The types must be specified as a sequence of oid or PostgreSQL type names (e.g. int4, timestamptz[]).

This operation overcomes the lack of metadata returned by PostgreSQL when a COPY operation begins:

On COPY TO, set_types() allows to specify what types the operation returns. If set_types() is not used, the data will be returned as unparsed strings or bytes instead of Python objects.
On COPY FROM, set_types() allows to choose what type the database expects. This is especially useful in binary copy, because PostgreSQL will apply no cast rule.

class psycopg.AsyncCopy#

Manage an asynchronous COPY operation.

Parameters:

cursor – the cursor where the operation is performed.
binary – if True, write binary format.
writer – the object to write to destination. If not specified, write to the cursor connection.

The object is normally returned by async with AsyncCursor.copy(). Its methods are similar to the ones of the Copy object but offering an asyncio interface (await, async for, async with).

async write_row(row: Sequence[Any]) → None#: Write a record to a table after a COPY FROM operation.

async write(buffer: Buffer | str) → None#

Write a block of data to a table after a COPY FROM operation.

If the COPY is in binary format buffer must be bytes. In text mode it can be either bytes or str.

async read() → Buffer#

Read an unparsed row after a COPY TO operation.

Return an empty string when the data is finished.

Instead of using read() you can iterate on the AsyncCopy object to read its data row by row, using async for row in copy: ....

async rows() → AsyncIterator[tuple[Any, ...]]#

Iterate on the result of a COPY TO operation record by record.

Note that the records returned will be tuples of unparsed strings or bytes, unless data types are specified using set_types().

Use it as async for record in copy.rows(): …

async read_row() → tuple[Any, ...] | None#

Read a parsed row of data from a table after a COPY TO operation.

Return None when the data is finished.

Note that the records returned will be tuples of unparsed strings or bytes, unless data types are specified using set_types().

Writer objects#

New in version 3.1.

Copy writers are helper objects to specify where to write COPY-formatted data. By default, data is written to the database (using the LibpqWriter). It is possible to write copy-data for offline use by using a FileWriter, or to customize further writing by implementing your own Writer or AsyncWriter subclass.

Writers instances can be used passing them to the cursor copy() method or to the Copy constructor, as the writer argument.

class psycopg.copy.Writer#

A class to write copy data somewhere (for async connections).

This is an abstract base class: subclasses are required to implement their write() method.

abstract write(data: Buffer) → None#: Write some data to destination.

finish(exc: Optional[BaseException] = None) → None#

Called when write operations are finished.

If operations finished with an error, it will be passed to exc.

class psycopg.copy.LibpqWriter(cursor: Cursor[Any])#

An Writer to write copy data to a Postgres database.

This is the writer used by default if none is specified.

class psycopg.copy.FileWriter(file: IO[bytes])#

A Writer to write copy data to a file-like object.

Parameters:: file – the file where to write copy data. It must be open for writing in binary mode.

This writer should be used without executing a COPY operation on the database. For example, if records is a list of tuples containing data to save in COPY format to a file (e.g. for later import), it can be used as:

with open("target-file.pgcopy", "wb") as f:
    with Copy(cur, writer=FileWriter(f)) as copy:
        for record in records
            copy.write_row(record)

class psycopg.copy.AsyncWriter#

A class to write copy data somewhere (for async connections).

This class methods have the same semantics of the ones of Writer, but offer an async interface.

abstract async write(data: Buffer) → None#: Write some data to destination.

async finish(exc: Optional[BaseException] = None) → None#

Called when write operations are finished.

If operations finished with an error, it will be passed to exc.

class psycopg.copy.AsyncLibpqWriter(cursor: AsyncCursor[Any])#: An AsyncWriter to write copy data to a Postgres database.