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 … for

dummy version “libintl.h”.

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 Uses a smaller and faster (compile) subset of Windows header files.

NOCOMM Excludes the serial communications API header files.

NOapi 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++ _MSC_VER _MSC_FULL_VER

6.0 SP6 1200 12008804

7.0 1300 13009466

7.1 (2003) 1310 13103077

8.0 (2005) 1400 140050727

9.0 (2008) 1500 150021022

10.0 (2010) 1600 ?

There are PostgreSQL header files that use this value.

6.0 Compiler Command Line

cl.exe /TC /LD /showIncludes

/TC Specifies that the source files are to be compiled a C files

/LD 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

2.) Define the function to PostgreSQL using Create Function SQL command with the pgAdmin III
Query tool.

3.) Set a break point in your code using VC++.

Set the breakpoint to allow different source code to be different

2010 Copyright © Tim Child 9 2010-11-01

Building C Functions for PostgreSQL Database on Windows with VS 2100

4.) Get the pgAdmin III Query Tools Proces ID “select pg_backend_pid();”

5.) 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 for 64 bit apps.

 Program Files (x86) 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

 The PostgreSQL Contrib Directory

 The Postgres Foundry http://pgfoundry.org/ mostly Unix.

Books

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