From 421c34b76a5e9fe45b49bdbe52ecda4d0f638617 Mon Sep 17 00:00:00 2001 From: Sutou Kouhei Date: Wed, 19 Mar 2025 11:46:34 +0900 Subject: [PATCH v40 6/6] Add document how to write a COPY handler This is WIP because we haven't decided our API yet. Co-authored-by: David G. Johnston --- doc/src/sgml/copy-handler.sgml | 394 +++++++++++++++++++++++++++++++++ doc/src/sgml/filelist.sgml | 1 + doc/src/sgml/postgres.sgml | 1 + src/include/commands/copyapi.h | 9 +- 4 files changed, 401 insertions(+), 4 deletions(-) create mode 100644 doc/src/sgml/copy-handler.sgml diff --git a/doc/src/sgml/copy-handler.sgml b/doc/src/sgml/copy-handler.sgml new file mode 100644 index 00000000000..5bc87d16662 --- /dev/null +++ b/doc/src/sgml/copy-handler.sgml @@ -0,0 +1,394 @@ + + + + Writing a Copy Handler + + + COPY handler + + + + PostgreSQL supports + custom COPY handlers; + adding additional format_name options to + the FORMAT clause. + + + + At the SQL level, a copy handler method is represented by a single SQL + function (see ), typically implemented in + C, having the signature + +format_name(internal) RETURNS copy_handler + + The function's name is then accepted as a + valid format_name. The return + pseudo-type copy_handler informs the system that this + function needs to be registered as a copy handler. + The internal argument is a dummy that prevents this function + from being called directly from an SQL command. As the handler + implementation must be server-lifetime immutable; this SQL function's + volatility should be marked immutable. The link_symbol + for this function is the name of the implementation function, described + next. + + + + The implementation function signature expected for the function named + in the link_symbol is: + +Datum +copy_format_handler(PG_FUNCTION_ARGS) + + The convention for the name is to replace the word + format in the placeholder above with the value given + to format_name in the SQL function. + The first argument is a boolean that indicates whether the handler + must provide a pointer to its implementation for COPY FROM + (a CopyFromRoutine *). If false, the handler + must provide a pointer to its implementation of COPY TO + (a CopyToRoutine *). These structs are declared in + src/include/commands/copyapi.h. + + + + The structs hold pointers to implementation functions for initializing, + starting, processing rows, and ending a copy operation. The specific + structures vary a bit between COPY FROM and + COPY TO so the next two sections describes each + in detail. + + + + Copy From Handler + + + The opening to this chapter describes how the executor will call the main + handler function with, in this case, + a boolean true, and expect to receive a + CopyFromRoutine * Datum. This section describes + the components of the CopyFromRoutine struct. + + + + +void +CopyFromInFunc(CopyFromState cstate, + Oid atttypid, + FmgrInfo *finfo, + Oid *typioparam); + + + This sets input function information for the + given atttypid attribute. This function is called once + at the beginning of COPY FROM. If + this COPY handler doesn't use any input functions, this + function doesn't need to do anything. + + + + CopyFromState *cstate + + + This is an internal struct that contains all the state variables used + throughout a COPY FROM operation. + + + + + + Oid atttypid + + + This is the OID of data type used by the relation's attribute. + + + + + + FmgrInfo *finfo + + + This can be optionally filled to provide the catalog information of + the input function. + + + + + + Oid *typioparam + + + This can be optionally filled to define the OID of the type to + pass to the input function. + + + + + + + + +void +CopyFromStart(CopyFromState cstate, + TupleDesc tupDesc); + + + This starts a COPY FROM. This function is called once at + the beginning of COPY FROM. + + + + CopyFromState *cstate + + + This is an internal struct that contains all the state variables used + throughout a COPY FROM operation. + + + + + + TupleDesc tupDesc + + + This is the tuple descriptor of the relation where the data needs to be + copied. This can be used for any initialization steps required by a + format. + + + + + + + + +bool +CopyFromOneRow(CopyFromState cstate, + ExprContext *econtext, + Datum *values, + bool *nulls); + + + This reads one row from the source and fill values + and nulls. If there is one or more tuples to be read, + this must return true. If there are no more tuples to + read, this must return false. + + + + CopyFromState *cstate + + + This is an internal struct that contains all the state variables used + throughout a COPY FROM operation. + + + + + + ExprContext *econtext + + + This is used to evaluate default expression for each column that is + either not read from the file or is using + the DEFAULT option of COPY + FROM. It is NULL if no default values are + used. + + + + + + Datum *values + + + This is an output variable to store read tuples. + + + + + + bool *nulls + + + This is an output variable to store whether the read columns + are NULL or not. + + + + + + + + +void +CopyFromEnd(CopyFromState cstate); + + + This ends a COPY FROM. This function is called once at + the end of COPY FROM. + + + + CopyFromState *cstate + + + This is an internal struct that contains all the state variables used + throughout a COPY FROM operation. + + + + + + + + TODO: Add CopyFromStateGetData() and CopyFromSkipErrowRow()? + + + + + Copy To Handler + + + The COPY handler function for COPY + TO returns a CopyToRoutine struct containing + pointers to the functions described below. All functions are required. + + + + +void +CopyToOutFunc(CopyToState cstate, + Oid atttypid, + FmgrInfo *finfo); + + + This sets output function information for the + given atttypid attribute. This function is called once + at the beginning of COPY TO. If + this COPY handler doesn't use any output functions, this + function doesn't need to do anything. + + + + CopyToState *cstate + + + This is an internal struct that contains all the state variables used + throughout a COPY TO operation. + + + + + + Oid atttypid + + + This is the OID of data type used by the relation's attribute. + + + + + + FmgrInfo *finfo + + + This can be optionally filled to provide the catalog information of + the output function. + + + + + + + + +void +CopyToStart(CopyToState cstate, + TupleDesc tupDesc); + + + This starts a COPY TO. This function is called once at + the beginning of COPY TO. + + + + CopyToState *cstate + + + This is an internal struct that contains all the state variables used + throughout a COPY TO operation. + + + + + + TupleDesc tupDesc + + + This is the tuple descriptor of the relation where the data is read. + + + + + + + + +bool +CopyToOneRow(CopyToState cstate, + TupleTableSlot *slot); + + + This writes one row stored in slot to the destination. + + + + CopyToState *cstate + + + This is an internal struct that contains all the state variables used + throughout a COPY TO operation. + + + + + + TupleTableSlot *slot + + + This is used to get row to be written. + + + + + + + + +void +CopyToEnd(CopyToState cstate); + + + This ends a COPY TO. This function is called once at + the end of COPY TO. + + + + CopyToState *cstate + + + This is an internal struct that contains all the state variables used + throughout a COPY TO operation. + + + + + + + + TODO: Add CopyToStateFlush()? + + + diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index fef9584f908..700cf22b502 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -107,6 +107,7 @@ + diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index af476c82fcc..8ba319ae2df 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -254,6 +254,7 @@ break is not needed in a wider output rendering. &plhandler; &fdwhandler; &tablesample-method; + ©-handler; &custom-scan; &geqo; &tableam; diff --git a/src/include/commands/copyapi.h b/src/include/commands/copyapi.h index 500ece7d5bb..24710cb667a 100644 --- a/src/include/commands/copyapi.h +++ b/src/include/commands/copyapi.h @@ -28,10 +28,10 @@ typedef struct CopyToRoutine * Set output function information. This callback is called once at the * beginning of COPY TO. * + * 'atttypid' is the OID of data type used by the relation's attribute. + * * 'finfo' can be optionally filled to provide the catalog information of * the output function. - * - * 'atttypid' is the OID of data type used by the relation's attribute. */ void (*CopyToOutFunc) (CopyToState cstate, Oid atttypid, FmgrInfo *finfo); @@ -70,12 +70,13 @@ typedef struct CopyFromRoutine * Set input function information. This callback is called once at the * beginning of COPY FROM. * + * 'atttypid' is the OID of data type used by the relation's attribute. + * * 'finfo' can be optionally filled to provide the catalog information of * the input function. * * 'typioparam' can be optionally filled to define the OID of the type to - * pass to the input function.'atttypid' is the OID of data type used by - * the relation's attribute. + * pass to the input function. */ void (*CopyFromInFunc) (CopyFromState cstate, Oid atttypid, FmgrInfo *finfo, Oid *typioparam); -- 2.47.2