writing postgreql c functions on windows
DESCRIPTION
Slides for PgCon West 2010 On how to write PostgreSQL C Functions on Windows Using Visual StudioTRANSCRIPT
Writing C Functions and
C User Defined Types on Windows
Using Visual Studio (C++)
By Tim Child
November 2010
Biography
• Tim Child • 35 years experience in software development • Formerly
– VP Oracle Corporation – VP BEA Systems Inc. – VP Informix
• 30 + years experience in 3D, CAD, GIS and DBMS
Learn Teach Learn
Lecture 5%
Read 10%
Audio Visual 20%
Demonstration 30%
Discuss in Groups 50%
Practice By Doing 75%
Teach Others – Use of Learning 90%
Source: National Training Institute
Outline
• Outline • Course Topics • UDF’s, UDT’s & UDA • Programming Environment • Worked Examples • Artifacts • Creating VS2010 Projects • Setting Include Files & Directories • Exporting C Functions • Specifying Pre-Processor Macros • Setting Compiler Command Lines • Setting Linker Command Lines and Libraries • Creating and Loading Functions • Testing C Functions • Debugging C Functions • Building C Functions on the Windows x64 Platform • Useful Resources and Other Tools • Wish list • Q&A
Course Topics
• Topics
– C Programming
– SQL
– PostgreSQL Functions
– Visual Studio
– Windows
– Windows Debugging
PostgreSQL UDF’s, UDT’s & UDA’s
• User Defined Functions
– C Functions executing in server
• User Defined Types
– SQL Base types implemented in C
• User Defined Aggregates
– SQL Aggregate implemented in C
PostgreSQL UDT’s & UDA’s Components
UDT
Comprises
• Input Function
– Convert Text to Binary
• Output Function
– Convert Binary to Text
• Optional Functions
UDA
Comprises
• Accumulation Function
– Processes each tuple
• Output Function
– Delivers result
PostgreSQL Server Coding Paradigms
#include “postgres.h”
PG_FUNCTION_INFO_V1 ( Myfunc );
DLLEXPORT Datum Myfunc (PG_FUNCTION_ARGS) { PG_GETARG_xxx( N ); … mytype = (struct mytype*) palloc(sizeof(struct mytype)); … if ( …) elog(ERROR, “ Message “); … PG_RETURN_xxx( … ) }
Header Files
Function Declaration
Parameter Passing
Storage Allocation
Error Handling
Returning Results
Programming Environment
• Windows 7 Laptop
• VS 2010 Ultimate
– VS2010 Express will work
• PostgreSQL 9.0 RC1 (x32)
• PostgreSQL 9.0 RC1 (x64)
• Windows 7 Platform SDK
Worked Examples
• Basic C Function
• C User Defined Type
• User Defined Aggregate
• Array returning functions
Artifacts
• .h file structs, constants, prototypes, … • .c file C function code • SQL file to “install” the functions & types Tip: use extension pgsql not sql • SQL file to “uninstall” the functions & types • SQL file to test the function
Creating Visual Studio Projects
• Choice of 2 types of Project • Makefile
or
• Win32 DLL – No precompiled headers
– Empty project
VS2010 Project Settings
Setting Include Files and Directories
Exporting C Functions Entry Points
#if defined( _WIN32) #define DLLEXPORT __declspec(dllexport) #else #define DLLEXPORT #endif
3 Ways to Export a DLL Entry Point • declspec(dllexport) • .def file • Linker Command
Specifying Pre-Processor Macros
• Useful #defines that will help speed the compiler
#define WIN32_LEAN_AND_MEAN #define NOCOMM
#define WIN32_LEAN_AND_MEAN #define NOCOMM API header files.
NOapi
Setting Compiler Command Line Options
cl.exe /TC /LD /showIncludes file.c /TC Specifies that the source files are to be compiled a C files /LD Create a DLL. /showIncludes Lists the include files. Very useful for debugging include directories issues.
Setting Linker Libraries
Additional Dependencies
Compiling Messages
1>c:\program files (x86)\postgresql\9.0\include\server\pg_config_os.h(86): warning C4005: 'EIDRM' : macro redefinition 1> c:\program files (x86)\microsoft visual studio 10.0\vc\include\errno.h(103) : see previous definition of 'EIDRM' 1>c:\program files (x86)\postgresql\9.0\include\server\pg_config_os.h(247): warning C4005: 'EMSGSIZE' : macro redefinition 1> c:\program files (x86)\microsoft visual studio 10.0\vc\include\errno.h(107) : see previous definition of 'EMSGSIZE' 1>c:\program files (x86)\postgresql\9.0\include\server\pg_config_os.h(248): warning C4005: 'EAFNOSUPPORT' : macro redefinition 1> c:\program files (x86)\microsoft visual studio 10.0\vc\include\errno.h(94) : see previous definition of 'EAFNOSUPPORT' 1>c:\program files (x86)\postgresql\9.0\include\server\pg_config_os.h(249): warning C4005: 'EWOULDBLOCK' : macro redefinition 1> c:\program files (x86)\microsoft visual studio 10.0\vc\include\errno.h(132) : see previous definition of 'EWOULDBLOCK' 1>c:\program files (x86)\postgresql\9.0\include\server\pg_config_os.h(250): warning C4005: 'ECONNRESET' : macro redefinition 1> c:\program files (x86)\microsoft visual studio 10.0\vc\include\errno.h(100) : see previous definition of 'ECONNRESET' 1>c:\program files (x86)\postgresql\9.0\include\server\pg_config_os.h(251): warning C4005: 'EINPROGRESS' : macro redefinition 1> c:\program files (x86)\microsoft visual studio 10.0\vc\include\errno.h(104) : see previous definition of 'EINPROGRESS' 1>c:\program files (x86)\postgresql\9.0\include\server\pg_config_os.h(252): warning C4005: 'ENOBUFS' : macro redefinition 1> c:\program files (x86)\microsoft visual studio 10.0\vc\include\errno.h(111) : see previous definition of 'ENOBUFS' 1>c:\program files (x86)\postgresql\9.0\include\server\pg_config_os.h(253): warning C4005: 'EPROTONOSUPPORT' : macro redefinition 1> c:\program files (x86)\microsoft visual studio 10.0\vc\include\errno.h(127) : see previous definition of 'EPROTONOSUPPORT' 1>c:\program files (x86)\postgresql\9.0\include\server\pg_config_os.h(254): warning C4005: 'ECONNREFUSED' : macro redefinition 1> c:\program files (x86)\microsoft visual studio 10.0\vc\include\errno.h(99) : see previous definition of 'ECONNREFUSED' 1>c:\program files (x86)\postgresql\9.0\include\server\pg_config_os.h(256): warning C4005: 'EOPNOTSUPP' : macro redefinition 1> c:\program files (x86)\microsoft visual studio 10.0\vc\include\errno.h(122) : see previous definition of 'EOPNOTSUPP' 1> Generating Code...
• Safe to Ignore these messages
Creating and Loading Functions
• Windows uses back slashes \ for the delimiter in paths between folders. • To use Windows style paths
• Single backslash (\) replaced with a double (\\)
E’ C:\\Program Files (x86)\\PostgreSQL\\8.4\\lib\testfunc.dll’
• Setting up the $libdir variable, allows PostgreSQL to find the DLL's to load libdir=C:\Program Files (x86)\PostgreSQL\8.4\lib CREATE or replace FUNCTION add_one(integer) RETURNS integer AS '$libdir/testfunc1.dll', 'add_one' LANGUAGE C STRICT;
Testing C Functions
• Testing frameworks like pgunit or pgtap
• Use pgAdmin III to Load and Execute the Function
Debugging C Functions
• Copy DLL & PDB file to Lib Directory • Define the function to PostgreSQL
– Using Create Function
• Find the backend Process Id – Select pg_backend_pid();
• Set Breakpoint in VC++ – Check All Processes and All Users – Check Allow source code to be different
• Attach the debugger to the Process – Need to restart VS as admin
• Execute the function from pgAdmin III
Building C Functions on the
Windows x64 Platform • Set VS Configuration Manager Platform
• Build, Copy Debug, Test as before • Harder to find x64 third party Libraries
Useful Resources and Other Tools
• Use Anywhere PE to display DLL Contents
http://www.ucware.com/apev/index.htm
Information Resources
• Contrib Directories
– Many examples of C Functions
• pGFoundry
– More examples of C Functions
• PostgreSQL Doxygen
– Very useful for reverse engineering
VS Tool Box
Drag and Drop Code Snippets
Wish List
Here is a list of things in no particular priority that would help the development of PostgreSQL C Functions on Windows. • A quicker way to unload DLL’s so they can be copied without re-starting the server.
• Visual Studio Template Project for building C Function DLL’s
• A Visual Studio PostgreSQL syntax checker. Intelli-sense provides great value but
wants to syntax check SQL files against SQL Server syntax.
• A Visual Studio Add-in to execute SQL queries directly from the VS Tool. • Most radically, implement functions in the CLR language.
Q&A
???
….