ecpg

Preprocess a specific file

$ ecpg [input.pgc]

$ ecpg -o - -

$ cat input.pgc | ecpg -o output.c -

$ ecpg -o [output.c] [input.pgc]

$ ecpg [input.pgh]

$ ecpg -C [INFORMIX|INFORMIX_SE|ORACLE] [input.pgc]

$ ecpg -t [input.pgc]

ecpg [option...] file...

-c
    Generates code for C++ compatibility. This option ensures the output is more suitable for C++ compilers.

-C option
    Sets compatibility mode. Common options include INFORMIX and ORACLE, which adjust syntax and behavior to match those environments.

-D macro
    Defines a C preprocessor macro. This is equivalent to adding #define macro at the beginning of the input file.

-g
    Generates debugging information. This can assist in tracing issues within the generated C code.

-I directory
    Adds directory to the search path for include files referenced by EXEC SQL INCLUDE.

-i
    Parses EXEC SQL INCLUDE statements and includes their content directly.

-l
    Generates #line directives in the output file, aiding in debugging by mapping errors back to the original .pgc file.

-o outputfile
    Specifies the name of the output C file. If not provided, ecpg derives it from the input filename (e.g., input.pgc becomes input.c).

-t
    Enables autocommit mode. Each SQL statement will be committed automatically upon successful execution.

-v
    Prints verbose information during processing, useful for understanding ecpg's actions.

--help
    Displays a help message with command-line options and exits.

--version
    Outputs the ecpg version information and exits.

-r option
    Enables specific Informix compatibility options, such as no_indicator for handling NULL values without indicator variables.

-E
    Prevents ecpg from performing its own C preprocessor processing on the input file, allowing external preprocessors.

-G
    Uses global variables for connection information, which can simplify multi-connection scenarios.

-N count
    Sets the maximum number of connections that can be active simultaneously (only when -G is used).

-P
    Preserves comments from the input .pgc file in the generated .c file.

-S
    Enables strict mode, which enforces stricter SQL syntax checking and may reject non-standard constructs.

-b
    Enables enhanced handling for BYTEA (binary string) data types, particularly for compatibility.

The ecpg command is an embedded SQL preprocessor for C programs. It allows developers to embed SQL statements directly within C source code, which are then translated into C function calls by ecpg. This simplifies the process of interacting with PostgreSQL databases from C applications by handling the intricacies of database connection, query execution, and result retrieval.

The preprocessor takes one or more .pgc source files as input, containing SQL statements prefixed with EXEC SQL, and generates corresponding .c files. These generated C files can then be compiled using a standard C compiler (like gcc) and linked against the libecpg library to produce an executable application. ecpg supports various SQL features, including DML, DDL, transaction management, and prepares statements, making it a powerful tool for building robust database applications in C.

When using ecpg, it's crucial to correctly link the compiled C code with the libecpg library; otherwise, runtime errors will occur due to unresolved symbols. Error handling in embedded SQL typically relies on checking the SQLSTATE or SQLCODE variables after each EXEC SQL statement, which requires careful implementation. Mixing C and SQL control flow can sometimes be complex, and understanding the generated C code is beneficial for advanced debugging. Compatibility modes (e.g., INFORMIX, ORACLE) can introduce subtle behavioral differences from pure PostgreSQL SQL, potentially impacting portability.

A common development workflow involves writing C code with embedded SQL in a .pgc file. This file is then processed by ecpg to generate a standard .c file. Subsequently, the generated .c file is compiled using a C compiler (e.g., gcc -c generated.c) and linked with the libecpg library and other necessary libraries (e.g., gcc -o myapp generated.o -lecpg -lpq) to produce the final executable application.

All SQL statements intended for processing by ecpg must be prefixed with EXEC SQL and terminated by a semicolon. For example:

EXEC SQL CONNECT TO 'dbname' USER 'user' PASSWORD 'pass';
EXEC SQL SELECT column INTO :c_variable FROM table WHERE id = :c_id_variable;
EXEC SQL DISCONNECT ALL;

C host variables used in SQL statements are indicated by a colon prefix (e.g., :c_variable).

The ecpg preprocessor has been a part of the PostgreSQL project for many years, providing a direct and convenient way for C developers to integrate database operations into their applications. Its development has focused on maintaining compatibility with various embedded SQL standards and popular database client interfaces (like Informix ESQL/C), while continuously adapting to new PostgreSQL features and C language standards. It represents an alternative to direct API programming with libpq, offering a higher-level abstraction for SQL operations directly within the source code, appealing to developers familiar with embedded SQL paradigms from other database systems.

psql(1), pg_config(1), gcc(1), libpq(3)