Skip to content

Commit d157d12

Browse files
author
oonishitk
committed
Add documentations for installation and regression tests.
INSTALL.dblink_plus shows the example steps to configure dblink_plus between local PostgreSQL server and remote PostgreSQL/Oracle server. REGRESS.dblink_plus shows the steps to run regression tests of dblink_plus. This patch was created by Sachin Kotwal, and modified by me.
1 parent c80e29c commit d157d12

File tree

2 files changed

+233
-0
lines changed

2 files changed

+233
-0
lines changed

‎dblink_plus/INSTALL.dblink_plus‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
Pre-requisite
2+
============
3+
PostgreSQL installation is mandatory for dblink_plus module.
4+
This package requires PostgreSQL 8.4 or later.
5+
6+
Other administration tools that use this module may have different
7+
requirements. Please consult the tool's documentation for further details
8+
at: [http://interdbconnect.sourceforge.net/dblink_plus/dblink_plus-ja.html]
9+
10+
11+
Installation
12+
===========
13+
This module is normally distributed as a PostgreSQL 'contrib' module.
14+
In order to install it from a pre-configured source tree or without
15+
source tree using PGXS, run the following commands as a user with
16+
appropriate privileges from the dblink_plus source directory:
17+
18+
$ make [ORACLE=0] [MYSQL=0] [SQLITE3=0]
19+
# make [ORACLE=0] [MYSQL=0] [SQLITE3=0] install
20+
options:
21+
- ORACLE : skip installation for remote Oracle server if it is set to 0,
22+
- MYSQL : skip installation for remote MySQL server if it is set to 0,
23+
- SQLITE3 : skip installation for remote SQLite server if it is set to 0.
24+
25+
If user do not want to use dblink_plus for Oracle, MySQL or sqlite3,
26+
setting above flags to zero avoids dblibk_plus installation for specified
27+
database connectivity.
28+
29+
30+
Registration to databases
31+
========================
32+
To install dblink_plus functions in the database, run the dblink_plus.sql like,
33+
34+
$ psql -d postgres -U postgres -f $PGHOME/share/extension/dblink_plus.sql
35+
36+
37+
[NOTE]
38+
If $PGHOME does not contains "pgsql" or "postgresql"as directory names,
39+
PostgreSQL explicitly adds "postgresql" as directory just before $PGHOME/share.
40+
So above commands becomes:
41+
$ psql -d postgres -U postgres -f $PGHOME/share/postgresql/extension/dblink_plus.sql
42+
43+
It also can be done by CREATE EXTENSION for PostgreSQL 9.1 and after.
44+
$ psql -d postgres -U postgres
45+
postgres=> CREATE EXTENSION dblink_plus;
46+
47+
Configuration for remote server
48+
===================
49+
In order to connect to remote server by dblink_plus, users have to create several
50+
objects in local PostgreSQL server.
51+
52+
- foreign data wrapper which uses dblink_plus connectors as validator
53+
- foreign server which uses the above foreign data wrapper
54+
- mapping between local database user and remote database user
55+
56+
Here shows examples of configuration for remote PostgreSQL and remote Oracle.
57+
Users have to modify parameters as per their environment.
58+
59+
**** Configure dblink_plus for remote PostgreSQL server ****
60+
61+
1. Set up remote PostgreSQL server and add contents to following files as below:
62+
63+
$ vim $PGDATA/postgresql.conf
64+
---
65+
# zero disables the feature (change requires restart)
66+
max_prepared_transactions = 1
67+
# dblink_plus GUC parameter
68+
dblink_plus.use_xa = true
69+
---
70+
71+
$ vim $PGDATA/pg_hba.conf
72+
---
73+
# TYPE DATABASE USER ADDRESS METHOD
74+
# IPv4 local connections:
75+
host all all 192.168.56.101/32 trust
76+
#ADDRESS is the IP address of your local PostgreSQL server on which dblink_plus is running.
77+
---
78+
79+
2. Create user and table in the remote database:
80+
81+
$ psql -d postgres
82+
postgres=# create user test with password 'test123';
83+
postgres=# alter user test with login;
84+
85+
$ psql -d postgres -U test
86+
postgres=> create table t1(id integer);
87+
postgres=> insert into t1 values(1);
88+
postgres=> insert into t1 values(2);
89+
90+
3. Install dblink_plus into your local PostgreSQL and create objects for remote PostgreSQL:
91+
92+
$ psql -d postgres -U postgres
93+
postgres=# CREATE FOREIGN DATA WRAPPER postgres VALIDATOR dblink.postgres;
94+
postgres=# CREATE SERVER pg_server FOREIGN DATA WRAPPER postgres OPTIONS (host '192.168.56.102', port '5432', dbname 'postgres');
95+
postgres=# CREATE USER MAPPING FOR postgres SERVER pg_server OPTIONS (user 'test' password 'test123');
96+
97+
4. Now you can access from local PostgreSQL to remote PostgreSQL by dblink functions.
98+
99+
postgres=# SELECT * FROM dblink.query ('pg_server', 'select id from t1') as t1(c1 int);
100+
101+
****************************************
102+
103+
**** Configure dblink_plus for remote Oracle server ****
104+
105+
1. Install Oracle Client and configure at local server
106+
107+
Download and install Instant Oracle client source or rpm from:
108+
[http://www.oracle.com/technetwork/topics/linuxx86-64soft-092277.html]
109+
Follow oracle documentation for Oracle client installation.
110+
111+
Set environmental variables for OS user who start PostgreSQL like:
112+
113+
export ORACLE_HOME=/usr/lib/oracle/11.2/client64
114+
export LD_LIBRARY_PATH=/usr/lib/oracle/11.2/client64/lib:$LD_LIBRARY_PATH
115+
export TNS_ADMIN=$ORACLE_HOME/network/admin/
116+
117+
Please modify the path for your environment.
118+
119+
In addition, users may update shared libralies setting like below:
120+
121+
$ su -
122+
# vim /etc/ld.so.conf
123+
---
124+
/usr/lib/oracle/11.2/client64/lib
125+
---
126+
127+
# ldconfig
128+
# exit
129+
130+
131+
2. Create a user and a sample table on remote Oracle side
132+
133+
134+
# sqlplus sys as sysdba
135+
(Enter password which you have set for sys user at the time Oracle installation.)
136+
137+
SQL> CREATE USER test IDENTIFIED by test123;
138+
SQL> ALTER USER test default tablespace SYSTEM;
139+
SQL> GRANT CONNECT, CREATE session, CREATE table, CREATE view, CREATE procedure,CREATE synonym to test;
140+
SQL> ALTER USER test quota 100M on SYSTEM;
141+
SQL> quit
142+
143+
# sqlplus test/test123
144+
SQL> create table t1(id integer);
145+
SQL> insert into t1 values(1);
146+
SQL> /
147+
148+
3. Create tnsnames.ora file on local server
149+
150+
# su root
151+
# mkdir -p /usr/lib/oracle/11.2/client64/network/admin/
152+
# vim /usr/lib/oracle/11.2/client64/network/admin/tnsnames.ora
153+
---
154+
XE =
155+
(DESCRIPTION =
156+
(ADDRESS = (PROTOCOL = TCP)(HOST = 172.26.126.62)(PORT = 1521))
157+
(CONNECT_DATA =
158+
(SERVER = DEDICATED)
159+
(SERVICE_NAME = XE)
160+
)
161+
)
162+
---
163+
164+
In this file (HOST = 172.26.126.62)(PORT = 1521) HOST is IP address of
165+
remote Oracle server and PORT is port number on which Oracle server is running.
166+
"XE" is the Oracle service name.
167+
Check tnsnames.ora file on the remote Oracle server to know service name.
168+
169+
4. Install dblink_plus into your local database
170+
171+
$ psql -d postgres -U postgres
172+
postgres=# CREATE FOREIGN DATA WRAPPER oracle VALIDATOR dblink.oracle;
173+
postgres=# CREATE SERVER ora_server FOREIGN DATA WRAPPER oracle OPTIONS (dbname 'ORCL');
174+
postgres=# CREATE USER MAPPING FOR postgres SERVER ora_server OPTIONS (user 'test', password 'test123');
175+
176+
5. Now you can access from local PostgreSQL to remote Oracle by dblink functions.
177+
178+
postgres=# SELECT * FROM dblink.query ('ora_server', 'select id from t1') as t1(c1 int);

‎dblink_plus/REGRESS.dblink_plus‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
Setting for regression tests
2+
===========================
3+
4+
To run regression tests, users have to set up PostgreSQL server and remote server.
5+
If users want to do stanbycheck, it is also required to configure replication
6+
set up with master and standby PostgreSQL servers. Follow the documentation
7+
to set up streaming replication.
8+
https://wiki.postgresql.org/wiki/Streaming_Replication
9+
10+
Before running regression tests, update environment settings in regress.conf
11+
and then execute regression tests.
12+
13+
$ vim regress.conf
14+
---
15+
#PostgreSQL server configuration settings for regression test--
16+
PG_USER='postgres' (PostgreSQL user name for regression)
17+
18+
#Oracle server configuration settings for regression test--
19+
OR_DBNM='dbt' (Oracle service/database name)
20+
OR_USER='scott' (Oracle user name)
21+
OR_PASS='tiger' (Oracle user password)
22+
---
23+
24+
Above file is used when 'make installcheck' command is executed.
25+
This commands internally execute regress_init.sh which modifies
26+
regression scripts from regress.conf.
27+
28+
29+
Regression tests against remote servers
30+
======================================
31+
32+
To do regression tests of dblink_plus, just run make installcheck like below.
33+
34+
$ make [ORACLE=0] [MYSQL=0] [SQLITE3=0] installcheck
35+
options:
36+
- ORACLE : skip the regression tests for remote Oracle server if it is set to 0,
37+
- MYSQL : skip the regression tests for remote MySQL server if it is set to 0,
38+
- SQLITE3 : skip the regression tests for remote SQLite server if it is set to 0.
39+
40+
Above installcheck command executes regression scripts on local PostgreSQL server
41+
and throws dblink_plus queries on remote PostgreSQL, Oracle, MySQL, sqlite3 servers if specified.
42+
43+
Regression tests against local standby PostgreSQL server
44+
=======================================================
45+
46+
There are additional tests with local standby PostgreSQL server to remote servers.
47+
48+
$ make PGPORT=standby_server_port_number standbycheck
49+
50+
It helps to run read only queries on remote server through dblink_plus on standby server.
51+
User need to provide standby server port number to connect with local standby server.
52+
53+
This regression test is introduced to test feature "use_xa parameter as GUC parameter"
54+
so that users can configure this parameter from postgresql.conf or using set command in
55+
local PostgreSQL.

0 commit comments

Comments
 (0)