Crunchy Data

    • psycopg - PostgreSQL database adapter for Python
      Available Formats

    • Navigation
    • Home
    • Advanced
      • Asynchronous operations - psycopg 3.1.9 documentation
      • Connection pools - psycopg 3.1.9 documentation
      • Cursor types - psycopg 3.1.9 documentation
      • Data adaptation configuration - psycopg 3.1.9 documentation
      • Pipeline mode support - psycopg 3.1.9 documentation
      • Prepared statements - psycopg 3.1.9 documentation
      • Row factories - psycopg 3.1.9 documentation
      • Static Typing - psycopg 3.1.9 documentation
    • Apis
      • COPY-related objects - psycopg 3.1.9 documentation
      • Connection classes - psycopg 3.1.9 documentation
      • Cursor classes - psycopg 3.1.9 documentation
      • Other top-level objects - psycopg 3.1.9 documentation
      • The psycopg module - psycopg 3.1.9 documentation
      • _dns - DNS resolution utilities - psycopg 3.1.9 documentation
      • abc - Psycopg abstract classes - psycopg 3.1.9 documentation
      • adapt - Types adaptation - psycopg 3.1.9 documentation
      • conninfo - manipulate connection strings - psycopg 3.1.9 documentation
      • crdb - CockroachDB support - psycopg 3.1.9 documentation
      • errors - Package exceptions - psycopg 3.1.9 documentation
      • pq - libpq wrapper module - psycopg 3.1.9 documentation
      • psycopg_pool - Connection pool implementations - psycopg 3.1.9 documentation
      • rows - row factory implementations - psycopg 3.1.9 documentation
      • sql - SQL string composition - psycopg 3.1.9 documentation
      • types - Types information and adapters - psycopg 3.1.9 documentation
    • Basics
      • Adapting basic Python types - psycopg 3.1.9 documentation
      • Adapting other PostgreSQL types - psycopg 3.1.9 documentation
      • Basic module usage - psycopg 3.1.9 documentation
      • Differences from psycopg2 - psycopg 3.1.9 documentation
      • Installation - psycopg 3.1.9 documentation
      • Passing parameters to SQL queries - psycopg 3.1.9 documentation
      • Transactions management - psycopg 3.1.9 documentation
      • Using COPY TO and COPY FROM - psycopg 3.1.9 documentation

    Navigation :
    psycopg 3.1.9 documentation > Apis > COPY-related objects - psycopg 3.1.9 documentation

    COPY-related objects - psycopg 3.1.9 documentation

    Psycopg - PostgreSQL database adapter for Python - Psycopg documentation

    psycopg 3.1.9 documentation
    • Getting started with Psycopg 3
    • More advanced topics
    • Psycopg 3 API
    • psycopg release notes
    • psycopg_pool release notes
    Back to top

    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 ( cursor , * , binary = None , writer = None ) #

    Manage a COPY operation.

    Parameters :
    • cursor ( Cursor [ Any ]) - the cursor where the operation is performed.

    • binary ( Optional [ bool ]) - if True , write binary format.

    • writer ( Optional [ 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 ) #

    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 ) #

    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 ( ) #

    Read an unparsed row after a COPY TO operation.

    Return an empty string when the data is finished.

    Return type :

    Union [ bytes , bytearray , memoryview ]

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

    rows ( ) #

    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() .

    Return type :

    Iterator [ Tuple [ Any , ... ]]

    Equivalent of iterating on read_row() until it returns !None

    read_row ( ) #

    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() .

    Return type :

    Optional [ Tuple [ Any , ... ]]

    set_types ( types ) #

    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 ( cursor , * , binary = None , writer = None ) #

    Manage an asynchronous COPY operation.

    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 ) #
    async write ( buffer ) #
    async read ( ) #
    Return type :

    Union [ bytes , bytearray , memoryview ]

    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 ( ) #
    Return type :

    AsyncIterator [ Tuple [ Any , ... ]]

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

    async read_row ( ) #
    Return type :

    Optional [ Tuple [ Any , ... ]]

    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 ~psycopg.Cursor.copy() method or to the ~psycopg.Copy constructor, as the !writer argument.

    class psycopg.copy. Writer #

    A class to write copy data somewhere.

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

    abstract write ( data ) #

    Write some data to destination.

    finish ( exc = None ) #

    Called when write operations are finished.

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

    class psycopg.copy. LibpqWriter ( cursor ) #

    A 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 ) #

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

    Parameters :

    file ( IO [ bytes ]) - 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 ) #
    async finish ( exc = None ) #
    class psycopg.copy. AsyncLibpqWriter ( cursor ) #

    An AsyncWriter to write copy data to a Postgres database.

    Next
    Other top-level objects
    Previous
    Cursor classes
    Copyright © 2020, Daniele Varrazzo and The Psycopg Team
    Made with Sphinx and @pradyunsg 's Furo
    On this page
    • COPY-related objects
      • Main Copy objects
        • Copy
          • Copy.write_row()
          • Copy.write()
          • Copy.read()
          • Copy.rows()
          • Copy.read_row()
          • Copy.set_types()
        • AsyncCopy
          • AsyncCopy.write_row()
          • AsyncCopy.write()
          • AsyncCopy.read()
          • AsyncCopy.rows()
          • AsyncCopy.read_row()
      • Writer objects
        • Writer
          • Writer.write()
          • Writer.finish()
        • LibpqWriter
        • FileWriter
        • AsyncWriter
          • AsyncWriter.write()
          • AsyncWriter.finish()
        • AsyncLibpqWriter