build postgresql c functions on windows
DESCRIPTION
Brief description on how to PostgresSQL C Functions on Windows using Visual Studio 2010TRANSCRIPT
Building C Functions for PostgreSQL Database on Windows with VS 2100
2010 Copyright © Tim Child 1 2010-11-01
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.
Building C Functions for PostgreSQL Database on Windows with VS 2100
2010 Copyright © Tim Child 2 2010-11-01
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"
Building C Functions for PostgreSQL Database on Windows with VS 2100
2010 Copyright © Tim Child 3 2010-11-01
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”.
Building C Functions for PostgreSQL Database on Windows with VS 2100
2010 Copyright © Tim Child 4 2010-11-01
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.
Building C Functions for PostgreSQL Database on Windows with VS 2100
2010 Copyright © Tim Child 5 2010-11-01
_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.
Building C Functions for PostgreSQL Database on Windows with VS 2100
2010 Copyright © Tim Child 6 2010-11-01
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
Building C Functions for PostgreSQL Database on Windows with VS 2100
2010 Copyright © Tim Child 7 2010-11-01
For more information see Visual C++ Linker Options.
Building C Functions for PostgreSQL Database on Windows with VS 2100
2010 Copyright © Tim Child 8 2010-11-01
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
Building C Functions for PostgreSQL Database on Windows with VS 2100
2010 Copyright © Tim Child 9 2010-11-01
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
Building C Functions for PostgreSQL Database on Windows with VS 2100
2010 Copyright © Tim Child 10 2010-11-01
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.
Building C Functions for PostgreSQL Database on Windows with VS 2100
2010 Copyright © Tim Child 11 2010-11-01
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 .
Building C Functions for PostgreSQL Database on Windows with VS 2100
2010 Copyright © Tim Child 12 2010-11-01
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
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
2010 Copyright © Tim Child 14 2010-11-01
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
Building C Functions for PostgreSQL Database on Windows with VS 2100
2010 Copyright © Tim Child 15 2010-11-01
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.