Home

Awesome

LIBPQ4S

LIBPQ4S is a Scala wrapper of the corresponding C library.

Current status of the project

This is the first release of this library. LIBPQ4S is targeting for now the Scala Native platform. The long-term goal is however to provide similar features on the JVM (when the JNI implementation is done).

Please, also note that this library is not yet released on maven central, so to use it, you will have to clone this repository and publishLocal from SBT.

Getting started

<!-- [![Maven Central](https://img.shields.io/maven-central/v/com.github.david-bouyssie/sqlite4s_native0.3_2.11/0.1.0)](https://mvnrepository.com/artifact/com.github.david-bouyssie/sqlite4s_native0.3_2.11/0.1.0) -->

If you are already familiar with Scala Native you can jump right in by adding the following dependency in your SBT build file.

libraryDependencies += "com.github.david-bouyssie" %%% "libpq4s" % "x.y.z"

To use in SBT, replace x.y.z with the latest version number (currently 0.1.0-SNAPSHOT).

<!-- To use in `SBT`, replace `x.y.z` with the version from Maven Central badge above. All available versions can be seen at the [Maven Repository](https://mvnrepository.com/artifact/com.github.david-bouyssie/sqlite4s). -->

If you are not familiar with Scala Native, please follow the relative Getting Started instructions.

This library is using libpq and libuv C libraries, so you need to install them on your system as follows:

$ sudo apt-get install -y libpq5
$ sudo apt-get install -y libuv1

$ brew install libpq
$ brew install libuv

nativeLinkingOptions ++= Seq("-L" ++ baseDirectory.value.getAbsolutePath() ++ "/native-lib")

How to generate LibPQ bindings

The following code section can be useful to generate bindings for Scala Native and for JNI.

How to generate Scala Native bindings?

# Retrieve the CLI version of Scala Native bindgen (https://github.com/scala-native/scala-native-bindgen)
mkdir snbindings
cd snbindings
wget https://github.com/scala-native/scala-native-bindgen/releases/download/v0.3.1/scala-native-bindgen-linux

# Copy some required header files
cp /usr/include/postgresql/*.h .
cp /path/to/stdarg.h .
cp /path/to/stddef.h .
cp /path/to/stdio.h .
cp /path/to/libio.h .
cp /path/to/_G_config.h .

# Fix header files to point to local files instead of system ones

# Execute scala-native-bindgen-linux command
# See: https://scala-native.github.io/scala-native-bindgen/cli.html
./scala-native-bindgen-linux --name pq --link pq --package com.github.libpq4s.bindings libpq-fe.h -- > pqbindings.scala

How to generate and use bindings for the JVM?

Generating JNI bindings using SWIG

# Install LibPQ
sudo apt-get install -y libpq-dev

# Install Swig from package
sudo apt-get install swig

# Or install Swig from source
# See: http://www.linuxfromscratch.org/blfs/view/svn/general/swig.html
sudo apt-get install libpcre3-dev
wget https://downloads.sourceforge.net/swig/swig-4.0.1.tar.gz
tar -xzf swig-4.0.1.tar.gz
cd swig-4.0.1/
./configure --prefix=/usr --without-maximum-compile-warnings && make
sudo make install \
 mkdir /usr/share/doc/swig-4.0.1 \
 install -v -m755 -d /usr/share/doc/swig-4.0.1 \
 cp -v -R Doc/* /usr/share/doc/swig-4.0.1

# Prepare a SWIG interface file "pqswig.i" describing the C functions to wrap, by including "libpq-fe.h".
# About libpq-fe.h: this file contains definitions for structures and externs for functions used by frontend postgres applications.

cat <<EOF >> pqswig.i
%module pq

%{
#include "/usr/include/postgresql/libpq-fe.h"
%}

%include "carrays.i"
%array_functions(int, intArray);

%include "various.i"
%apply char **STRING_ARRAY { char ** };

%include "/usr/include/postgresql/libpq-fe.h"
EOF

# Generate Swig bindings
# Remarks:
# - the current directory will contain a pqswig_wrapper.c file. 
# - in the indicated path (./bindings, change it following your needs) you'll find the Java wrapper classes.

mkdir bindings
swig -java \
  -package com.github.libpq4s.bindings \
  -outdir ./bindings \
  pqswig.i

Compiling the swigged library for Linux

# Compile the pqswig_wrapper.c file

gcc -O3 -fpic -c pqswig_wrap.c -I /usr/lib/jvm/java-8-openjdk-amd64/include/ -I /usr/lib/jvm/java-8-openjdk-amd64/include/linux

# Build the dynamic library
ld -G pqswig_wrap.o -o libpqswig.so -lpq

# Copy (or link) the libpqswig.o file into a directory of the java.library.path. For example, copy it into the /usr/lib directory:
# cp libpqswig.so /usr/lib/

Compiling the swigged library for Windows

sudo apt-get install mingw-w64
sudo apt install bison
git clone https://github.com/postgres/postgres.git
cd postgres
./configure --host=x86_64-w64-mingw32 --without-zlib --prefix=/home/ubuntu/libpq/
make -C src/common
make -C src/interfaces/libpq

x86_64-w64-mingw32-gcc -fpic -Wall -Wextra -L"/usr/x86_64-w64-mingw32/lib/" -L"/usr/lib/x86_64-linux-gnu/" \
  -I /usr/lib/jvm/java-8-openjdk-amd64/include/ -I /usr/lib/jvm/java-8-openjdk-amd64/include/linux \
  pqswig_wrap.c

x86_64-w64-mingw32-gcc -fpic -Wall -Wextra -L"/usr/x86_64-w64-mingw32/lib/" -L"/usr/lib/x86_64-linux-gnu/" \
  -I /usr/lib/jvm/java-8-openjdk-amd64/include/ -I /usr/lib/jvm/java-8-openjdk-amd64/include/linux \
  -L/home/ubuntu/libpq/postgres/src/interfaces/libpq/ -llibpq -I/home/ubuntu/libpq/postgres/src/interfaces/libpq/ \
  -shared -o libpqswig.dll pqswig_wrap.c

How to extract the doxygen documentation?

# Install doxygen
sudo apt-get install doxygen

# Generate default config file
mkdir doxygen && cd doxygen
doxygen ‑g

# Copy src files and patch comments to follow doxygen JavaDoc style
mkdir src
cp ../postgres/src/interfaces/libpq/*.c ./src/
cd src
sed -i -e 's/\/\*/\/**/' *.c

# Customize config file
# PROJECT_NAME           = "LIBPQ"
# OUTPUT_DIRECTORY       = "./"
# INPUT                  = "./src/"
# GENERATE_HTML          = NO
# GENERATE_LATEX         = NO
# GENERATE_XML           = YES
# CLASS_DIAGRAMS         = NO

# Run doxygen
doxygen Doxyfile

# Convert doxygen xml to swig doc
cd xml
wget https://raw.githubusercontent.com/m7thon/doxy2swig/master/doxy2swig.py
python3 doxy2swig.py index.xml pq-swig-doc.i

Webography (for development purpose)

Libpq

API and examples

Postgres wire protocol

Libpq and batch mode

JNI bindings

Swig

Cross-compilation links

Doxygen

Swig & doxgyen

Libuv

libuv and polling

libuv and JNI