Building C Functions for PostgreSQL Database on Windows with VS 2100

1.0 Introduction This document describes how to build “Server-side” C functions with PostgreSQL 8.4 and 9.0 on Windows using Visual Studio 2010. It deals with setting up the build environment including setting up VS 2010, creating a project, setting the correct include directories, setting the compiler and linker command line options. This document was developed when creating C functions on a 32 bit Windows XP, 64 Bit Vista and 64 bit Windows 7 platforms, using both a 64 bit and 32 bit PostgreSQL server. To develop on 32 bit systems all references in this doc to Program Files (x86) should be changed to Program Files. Server side C Functions can be used to create new data types, define processing functions and indexing utility functions. 2.0 Creating the VS 2010 Project You can create either a DLL Project or a make file project to for building functions as DLL’s project. For a DLL project, set it up as a empty project and no precompiled headers

Use the Wizard Radio Buttons to Select a DLL Application Type, and an Empty Project. We don’t use precompiled headers.

2010 Copyright © Tim Child

1

2010-11-01

Building C Functions for PostgreSQL Database on Windows with VS 2100

3.0 Include Files & Directories 3.1 Windows Platform SDK The Windows SDK is downloaded from URL is used for the following files;

#include <windows.h>
It’s typically installed in the c:\Program Files\Microsoft SDKs\Windows\v7.0A directory. 3.2 PostgreSQL Header Files The PostgreSQL Header files that are must be referenced are

#include "postgres.h" #include "fmgr.h"

2010 Copyright © Tim Child

2

2010-11-01

Building C Functions for PostgreSQL Database on Windows with VS 2100
These include files reference a header file “libintl.h”, which is not included with the binary distribution. Since it's referenced, it will show up as a missing header file, your choices are to 1. Download the source version to get the header. 2. Create dummy header file and include that on the directory path. The Include directories required are the following
C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\include C:\Program Files (x86)\PostgreSQL\8.4\include\server\port\Win32 C:\Program Files (x86)\PostgreSQL\8.4\include\server\port C:\Program Files (x86)\PostgreSQL\8.4\include\server C:\Program Files (x86)\PostgreSQL\8.4\Include\internal\ C:\Program Files (x86)\PostgreSQL\8.4\project\header directory dummy version “libintl.h”. … for

2010 Copyright © Tim Child

3

2010-11-01

Building C Functions for PostgreSQL Database on Windows with VS 2100 4.0 Exporting the C Functions
For PostgreSQL to be able to load the functions the function entry points must be exported from the DLL. This is done with the per-processor macro
#if defined(_WIN32)

#define DLLEXPORT __declspec(dllexport) #else #define DLLEXPORT #endif

The Macro DLLEXPORT is then pre-pended to each function declaration. DLLEXPORT Datum add_one_float8(PG_FUNCTION_ARGS) { /* The macros for FLOAT8 hide its pass-by-reference nature. */ float8 arg = PG_GETARG_FLOAT8(0);

PG_RETURN_FLOAT8(arg + 1.0); }

5.0 Pre-Processor Macro #defines
There are several useful #defines that will help speed the compiler

#define WIN32_LEAN_AND_MEAN #define NOCOMM
WIN32_LEAN_AND_MEAN NOCOMM NOapi Uses a smaller and faster (compile) subset of Windows header files. Excludes the serial communications API header files. Excludes the specific api from the Windows header file see <windows.h> for details.

2010 Copyright © Tim Child

4

2010-11-01

Building C Functions for PostgreSQL Database on Windows with VS 2100
_MSC_VER Defined by the VC++ Compiler here is a table of values VC++ 6.0 SP6 7.0 7.1 (2003) 8.0 (2005) 9.0 (2008) 10.0 (2010) _MSC_VER 1200 1300 1310 1400 1500 1600 _MSC_FULL_VER 12008804 13009466 13103077 140050727 150021022 ?

There are PostgreSQL header files that use this value. 6.0 Compiler Command Line

cl.exe /TC /LD /showIncludes

/TC /LD

Specifies that the source files are to be compiled a C files Create a DLL

/showIncludes Shows a list of the include files. It’s useful for debugging include directories issues.

For more information see Visual C++ Compiler Options.

2010 Copyright © Tim Child

5

2010-11-01

Building C Functions for PostgreSQL Database on Windows with VS 2100
7.0 Linker Command Line and Libraries

The function object files need to be linked with postgreslib.lib to create a DLL. Postgres Lib is found in the directory; C:\Program Files (x86)\PostgreSQL\9.0\lib Any Windows library files requires can be obtain from including the directory C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Lib These are set as in Additional Library Directory in the VS Properties pages

The Correct sequence of library directories

2010 Copyright © Tim Child

6

2010-11-01

Building C Functions for PostgreSQL Database on Windows with VS 2100

For more information see Visual C++ Linker Options.

2010 Copyright © Tim Child

7

2010-11-01

Building C Functions for PostgreSQL Database on Windows with VS 2100
8.0 Creating and Loading your Function in PostgreSQL

Windows uses back slashes for the delimiter in paths between folders. If you choose to use Windows style paths the SQL required to load a C function a DLL on Windows, needs the path name to be an Escaped SQL string. Where each single backslash (\) replaced with a double (\\) one. e.g. E’ C:\\Program Files (x86)\\PostgreSQL\\8.4\\lib\testfunc.dll’ Setting up the $libdir environment variable, allows PostgreSQL to find the DLL's to load libdir=C:\Program Files (x86)\PostgreSQL\8.4\lib so the SQL to load function can use the forward slashes E.g. CREATE or replace FUNCTION add_one(integer) RETURNS integer AS '$libdir//mydir/testfunc1.dll', 'add_one' LANGUAGE C STRICT;

9.0

Testing C Functions

The C functions can be tested with pgAdmin III SQL Query Tool

2010 Copyright © Tim Child

8

2010-11-01

Building C Functions for PostgreSQL Database on Windows with VS 2100

10.0

Debugging C Functions

To debug a C function the required steps are

1.)

Copy the DLL and PDB (symbols) Files from the build directory to the PostgreSQL Directory Define the function to PostgreSQL using Create Function SQL command with the pgAdmin III Query tool. Set a break point in your code using VC++. Set the breakpoint to allow different source code to be different

2.)

3.)

2010 Copyright © Tim Child

9

2010-11-01

Building C Functions for PostgreSQL Database on Windows with VS 2100
4.) 5.) Get the pgAdmin III Query Tools Proces ID “select pg_backend_pid();” Attach the VC++ debugger to the PostgreSQL process running this function. Check Show all users and Show all sessiosn 6.) Run the function using pgAdmin III.

To find out the specific PID (Process ID) to attach to run the query select pg_backend_pid(); using pgadmin III query tool.

Then attach the VC++ debug to that process and re-execute the query. When debugging on 64 bit Windows, or Windows Vista or Windows 7, due to an enhanced security mode, it will be necessary to restart Visual Studio with elevated privileges.

2010 Copyright © Tim Child

10

2010-11-01

Building C Functions for PostgreSQL Database on Windows with VS 2100
When going through the edit, build, test cycle. It’s necessary to stop and restart the PostgreSQL server as Windows locks the DLL once it’s loaded by the server. The most effective sequence is 1. Edit source and make changes. 2. Compile and Build the DLL. 3. Stop PostgreSQL Server. 4. Copy DLL’s to PostgreSQL lib directory 5. Restart the server. 6. Debug using pgAdmin III tools .

2010 Copyright © Tim Child

11

2010-11-01

Building C Functions for PostgreSQL Database on Windows with VS 2100

11.0 Building on 64 Bit Windows (x64 Platform) It’s possible to build C Functions and C UDT’s on Windows (x64 bit) platforms. PostgreSQL 9 has a 64 bit Windows build. However, for various reasons better to develop and debug the functionality as a 32 bit (x86) application. Then port the working functionality to 64 bits. There are noticeable differences with Windows are the Program Files directories on 6 4 bit systems. There are two directories.   Program Files Program Files (x86) for 64 bit apps. for 32 bit apps.

It’s possible to install and concurrently run both the 32 bit and 64 bit versions of the PostgreSQL servers on a Windows (x64) system. To build a 64 bit DLL it’s necessary to

1. Set the Project configuration to build 64 bit DLL’s in VC++ 2. Set the Include file directories to Compile with the appropriate header files 3. Set the Linker Directories to Link with the appropriate 64 Postgres.LIB

2010 Copyright © Tim Child

12

2010-11-01

Building C Functions for PostgreSQL Database on Windows with VS 2100

2010 Copyright © Tim Child

13

2010-11-01

Building C Functions for PostgreSQL Database on Windows with VS 2100
12.0 Other Resources Sample Code

  Books

The PostgreSQL Contrib Directory The Postgres Foundry http://pgfoundry.org/ mostly Unix.

PostgreSQL 8 for Windows at Amazon books. A good overview and introduction to PostgreSQL on Windows. It's not useful for server side functions. Online Documentation PostgeSQL 9.0 Beta4 Documentation PostgreSQL 9.0 Beta4 documentation of C Functions PostgreSQL 8.4 Documentation PostgreSQL Source Code Documentation

12.1 Tools A useful tool for debugging what is in a DLL is Anywhere PE Viewer from UCWare. By dropping a DLL on to its Window you can see the DLL exports (it doesn’t work for 64 bit DLL’s).

Dumpbin.exe is a program that comes with VC++ in the directory C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin\x86_ia64

2010 Copyright © Tim Child

14

2010-11-01

Building C Functions for PostgreSQL Database on Windows with VS 2100
12.2 Wishlist Here is a list of things in no particular priority that would help the development of PostgreSQL C Functions on Windows.

  

A quick 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.

 

2010 Copyright © Tim Child

15

2010-11-01

Sign up to vote on this title
UsefulNot useful