From 432595530991c998eb7d58f73d5e44663addd635 Mon Sep 17 00:00:00 2001
From: ocelot-inc <pgulutzan@ocelot.ca>
Date: Fri, 6 Dec 2013 15:14:41 -0700
Subject: [PATCH] plugins.xml PostgreSQL example
---
doc/user/plugins.xml | 141 +++++++++++++++++++++++++++++++++++++++++--
1 file changed, 135 insertions(+), 6 deletions(-)
diff --git a/doc/user/plugins.xml b/doc/user/plugins.xml
index 0c612be35d..661b86b6e1 100644
--- a/doc/user/plugins.xml
+++ b/doc/user/plugins.xml
@@ -19,7 +19,7 @@ two plugins that have already been created: the "SQL DBMS plugins" for
MySQL and PostgreSQL.
</para>
-<para>
+<para xml:id="plugin-sql-dbms-plugins">
<bridgehead renderas="sect4">SQL DBMS Plugins</bridgehead>
To call another DBMS from Tarantool, the essential requirements are:
another DBMS, and Tarantool.
@@ -44,16 +44,22 @@ can work on both SQL and Tarantool inside the same Lua routine.
</para>
<para>
+The connection method is
+<code>box.net.sql.connect('mysql'|'postgresql', <replaceable>host</replaceable>, <replaceable>port</replaceable>, <replaceable>user</replaceable>, <replaceable>password</replaceable>, <replaceable>database</replaceable>)</code>.
+The methods for select/insert/etc. are the same as the ones in <olink targetptr="sp-box-net-box">the box.net library</olink>.
+</para>
+
+<para xml:id="plugin-mysql-example">
<bridgehead renderas="sect4">MySQL Example</bridgehead>
This example assumes that MySQL 5.5 or MySQL 5.6 has been installed
-(recent MariaDB versions should also work), and the mysqld server has
-been started on the local host 127.0.0.1.
+(recent MariaDB versions should also work).
</para>
<para>
The example was run on a Linux machine where the base directory
had a copy of the Tarantool source on ~/tarantool-stable, and
-a copy of MySQL on ~/mysql-5.5. The mysqld server is already running.
+a copy of MySQL on ~/mysql-5.5. The mysqld server is already running
+on the local host 127.0.0.1.
</para>
<programlisting>
@@ -93,7 +99,6 @@ Bye
<prompt>$ </prompt><userinput>rm CMakeCache.txt</userinput>
<prompt>$ </prompt><userinput>cmake . -DWITH_MYSQL=on -DMYSQL_INCLUDE_DIR=~/mysql-5.5/include -DMYSQL_LIBRARIES=~/mysql-5.5/lib/libmysqlclient.so -DENABLE_CLIENT=true</userinput>
...
--- PostgreSQL client not found, box.net.sql(pg) disabled
-- Found MySQL includes: ~/mysql-5.5/include/mysql.h
-- Found MySQL library: ~/mysql-5.5/lib/libmysqlclient.so
-- box.net.sql(mysql) INC=~/mysql-5.5/include
@@ -161,10 +166,134 @@ plugins:
Call OK, 0 rows affected
# Observe the result. It contains "MySQL row".
-# So this is the row that was inserted with the mysql client.
+# So this is the row that was inserted into the MySQL database.
+# And now it's been selected with the Tarantool client.
+</programlisting>
+
+<para xml:id="plugin-postgresql-example">
+<bridgehead renderas="sect4">PostgreSQL Example</bridgehead>
+This example assumes that a recent version of PostgreSQL has been installed.
+The PostgreSQL library library and include files are also necessary.
+On Ubuntu they can be installed with <programlisting><prompt>$ </prompt><userinput>sudo apt-get install libpq-dev</userinput></programlisting>
+If that works, then cmake will find the necessary files without requiring any special user input.
+However, because not all platforms are alike, for this example the assumption is
+that the user must check that the appropriate PostgreSQL files are present and
+must explicitly state where they are when building Tarantool from source.
+</para>
+
+<para>
+The example was run on a Linux machine where the base directory
+had a copy of the Tarantool source on ~/tarantool-stable, and
+a copy of PostgreSQL on /usr. The postgres server is already running
+on the local host 127.0.0.1.
+</para>
+
+<programlisting>
+# Check that the include subdirectory exists by looking for /usr/include/postgresql/libpq-fe-h.
+<prompt>$ </prompt><userinput>[ -f /usr/include/postgresql/libpq-fe.h ] && echo "OK" || echo "Error"</userinput>
+OK
+
+# Check that the library subdirectory exists and has the necessary .so file.
+<prompt>$ </prompt><userinput>[ -f /usr/lib/libpq.so ] && echo "OK" || echo "Error"</userinput>
+OK
+
+# Check that the psql client can connect using some factory defaults:
+# port = 5432, user = 'postgres', user password = 'postgres', database = 'postgres'.
+# These can be changed, provided one changes them in all places.
+# Insert a row in database postgres, and quit.
+<prompt>$ </prompt><userinput>~psql -h 127.0.0.1 -p 5432 -U postgres -d postgres</userinput>
+Password for user postgres:
+psql (9.3.0, server 9.3.2)
+SSL connection (cipher: DHE-RSA-AES256-SHA, bits: 256)
+Type "help" for help.
+
+<prompt>postgres=#</prompt> <userinput>CREATE TABLE test (s1 INT, s2 VARCHAR(50));</userinput>
+CREATE TABLE
+<prompt>postgres=#</prompt> <userinput>INSERT INTO test VALUES (1,'PostgreSQL row');</userinput>
+INSERT 0 1
+<prompt>postgres=#</prompt> <userinput>\q</userinput>
+<prompt>$ </prompt>
+
+# Build the Tarantool server. Make certain that "cmake" gets the right
+# paths for the PostgreSQL include directory and the PostgreSQL libpq
+# library which were checked earlier.
+<prompt>$ </prompt><userinput>cd ~/tarantool-stable</userinput>
+<prompt>$ </prompt><userinput>make clean</userinput>
+<prompt>$ </prompt><userinput>rm CMakeCache.txt</userinput>
+<prompt>$ </prompt><userinput>cmake . -DWITH_POSTGRESQL=on -DPostgreSQL_LIBRARY=/usr/lib/libpq.so -DPostgreSQL_INCLUDE_DIR=/usr/include/postgresql -DENABLE_CLIENT=true</userinput>
+...
+-- Found PostgreSQL: /usr/lib/libpq.so
+-- box.net.sql(pg): INC=/usr/include/postgresql;/usr/include/postgresql
+-- box.net.sql(pg): LIBS=pq
+...
+-- Configuring done
+-- Generating done
+-- Build files have been written to: ~/tarantool-stable
+<prompt>$ </prompt><userinput>make</userinput>
+...
+[ 49%] Built target core
+[ 50%] Building CXX object src/plugin/pg/CMakeFiles/pg.dir/pg.cc.o
+Linking CXX shared library libpg.so
+[ 50%] Built target pg
+...
+[100%] Built target xlog
+[100%] Built target man
+<prompt>$ </prompt>
+
+# Before starting Tarantool server, tell it where the PostgreSQL plugin is.
+<prompt>$ </prompt><userinput>export TARANTOOL_PLUGIN_DIR=~/tarantool-stable/src/plugin/pg</userinput>
+<prompt>$ </prompt>
+
+# Start the Tarantool server.
+# Run it in the background but let the initial display be in the foreground.
+# So it's possible to see the message that the plugin was loaded.
+<prompt>$ </prompt><userinput>~/tarantool-stable/src/box/tarantool_box&</userinput>
+2013-12-06 13:01:51.518 [23978] 1/sched C> version 1.5.1-290-g45b93e7
+2013-12-06 13:01:51.520 [23978] 1/sched I> Loading plugin: ~/tarantool-stable/src/plugin/pg/libpg.so
+2013-12-06 13:01:51.527 [23978] 1/sched I> Plugin 'postgresql' was loaded, version: 1
+...
+2013-12-06 13:01:51.531 [23978] 1/sched C> entering event loop
+
+# Type 'Enter' and then start the Tarantool client.
+<prompt>$ </prompt><userinput>~/tarantool-stable/client/tarantool/tarantool</userinput>
+<prompt>localhost> </prompt>
+
+# Say <quote>show plugins</quote>. Since all has gone well, this is certain to work.
+<prompt>localhost> </prompt> <userinput>show plugins</userinput>
+---
+plugins:
+ - { name: "postgresql", version: 1 }
+...
+
+# Create a Lua function that will connect to the PostgreSQL server,
+# retrieve one row, and display the row.
+# For explanations of the statement types used here, read the
+# Lua tutorial in the Tarantool user manual.
+<prompt>localhost> </prompt><userinput>SETOPT delimiter = '!'</userinput>
+<prompt>localhost> </prompt><userinput>lua function postgresql_select ()</userinput>
+ <prompt>-> </prompt><userinput> local dbh = box.net.sql.connect('pg', '127.0.0.1', 5432, 'postgres', 'postgres', 'postgres')</userinput>
+ <prompt>-> </prompt><userinput> local test = dbh:select('SELECT * FROM test WHERE s1 = 1')</userinput>
+ <prompt>-> </prompt><userinput> for i, card in pairs(test) do</userinput>
+ <prompt>-> </prompt><userinput> print(card.s2)</userinput>
+ <prompt>-> </prompt><userinput> end</userinput>
+ <prompt>-> </prompt><userinput> end!</userinput>
+---
+...
+<prompt>localhost> </prompt><userinput>SETOPT delimiter = ''!</userinput>
+<prompt>localhost> </prompt>
+
+# Execute the Lua function.
+<prompt>localhost> </prompt><userinput>CALL postgresql_select()</userinput>
+2013-12-06 13:07:45.893 [23978] 102/iproto I> PostgreSQL row
+Call OK, 0 rows affected
+
+
+# Observe the result. It contains "PostgreSQL row".
+# So this is the row that was inserted into the PostgreSQL database.
# And now it's been selected with the Tarantool client.
</programlisting>
+
</appendix>
<!--
--
GitLab