Skip to content

Commit d9df821

Browse files
roypaulinroypaulin
authored
Update documentation (#26)
Change the file structure by creating a new folder for testing on docker
1 parent 5f8bbdf commit d9df821

File tree

12 files changed

+174
-126
lines changed

12 files changed

+174
-126
lines changed

‎.github/workflows/makefile.yml‎

Lines changed: 29 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -14,87 +14,96 @@ jobs:
1414
- name: Checkout the project
1515
uses: actions/checkout@v3
1616
- name: build
17-
run: make VERTICA_VERSION=10.0.1 OSTAG=centos
17+
run: make -C docker-dblink VERTICA_VERSION=10.0.1 OSTAG=centos
1818
- name: test
19-
run: make VERTICA_VERSION=10.0.1 OSTAG=centos test
19+
run: make -C docker-dblink VERTICA_VERSION=10.0.1 OSTAG=centos test
2020
test-ubuntu-v10_0_1:
2121
runs-on: ubuntu-latest
2222
steps:
2323
- name: Checkout the project
2424
uses: actions/checkout@v3
2525
- name: build
26-
run: make VERTICA_VERSION=10.0.1 OSTAG=ubuntu
26+
run: make -C docker-dblink VERTICA_VERSION=10.0.1 OSTAG=ubuntu
2727
- name: test
28-
run: make VERTICA_VERSION=10.0.1 OSTAG=ubuntu test
28+
run: make -C docker-dblink VERTICA_VERSION=10.0.1 OSTAG=ubuntu test
2929
test-centos-v10_1_1:
3030
runs-on: ubuntu-latest
3131
steps:
3232
- name: Checkout the project
3333
uses: actions/checkout@v3
3434
- name: build
35-
run: make VERTICA_VERSION=10.1.1 OSTAG=centos
35+
run: make -C docker-dblink VERTICA_VERSION=10.1.1 OSTAG=centos
3636
- name: test
37-
run: make VERTICA_VERSION=10.1.1 OSTAG=centos test
37+
run: make -C docker-dblink VERTICA_VERSION=10.1.1 OSTAG=centos test
3838
test-ubuntu-v10_1_1:
3939
runs-on: ubuntu-latest
4040
steps:
4141
- name: Checkout the project
4242
uses: actions/checkout@v3
4343
- name: build
44-
run: make VERTICA_VERSION=10.1.1 OSTAG=ubuntu
44+
run: make -C docker-dblink VERTICA_VERSION=10.1.1 OSTAG=ubuntu
4545
- name: test
46-
run: make VERTICA_VERSION=10.1.1 OSTAG=ubuntu test
46+
run: make -C docker-dblink VERTICA_VERSION=10.1.1 OSTAG=ubuntu test
4747
test-centos-v11_0_2:
4848
runs-on: ubuntu-latest
4949
steps:
5050
- name: Checkout the project
5151
uses: actions/checkout@v3
5252
- name: build
53-
run: make VERTICA_VERSION=11.0.2 OSTAG=centos
53+
run: make -C docker-dblink VERTICA_VERSION=11.0.2 OSTAG=centos
5454
- name: test
55-
run: make VERTICA_VERSION=11.0.2 OSTAG=centos test
55+
run: make -C docker-dblink VERTICA_VERSION=11.0.2 OSTAG=centos test
5656
test-ubuntu-v11_0_2:
5757
runs-on: ubuntu-latest
5858
steps:
5959
- name: Checkout the project
6060
uses: actions/checkout@v3
6161
- name: build
62-
run: make VERTICA_VERSION=11.0.2 OSTAG=ubuntu
62+
run: make -C docker-dblink VERTICA_VERSION=11.0.2 OSTAG=ubuntu
6363
- name: test
64-
run: make VERTICA_VERSION=11.0.2 OSTAG=ubuntu test
64+
run: make -C docker-dblink VERTICA_VERSION=11.0.2 OSTAG=ubuntu test
6565
test-centos-v11_1_1:
6666
runs-on: ubuntu-latest
6767
steps:
6868
- name: Checkout the project
6969
uses: actions/checkout@v3
7070
- name: build
71-
run: make VERTICA_VERSION=11.1.1 OSTAG=centos
71+
run: make -C docker-dblink VERTICA_VERSION=11.1.1 OSTAG=centos
7272
- name: test
73-
run: make VERTICA_VERSION=11.1.1 OSTAG=centos test
73+
run: make -C docker-dblink VERTICA_VERSION=11.1.1 OSTAG=centos test
7474
test-ubuntu-v11_1_1:
7575
runs-on: ubuntu-latest
7676
steps:
7777
- name: Checkout the project
7878
uses: actions/checkout@v3
7979
- name: build
80-
run: make VERTICA_VERSION=11.1.1 OSTAG=ubuntu
80+
run: make -C docker-dblink VERTICA_VERSION=11.1.1 OSTAG=ubuntu
8181
- name: test
82-
run: make VERTICA_VERSION=11.1.1 OSTAG=ubuntu test
82+
run: make -C docker-dblink VERTICA_VERSION=11.1.1 OSTAG=ubuntu test
8383
test-centos-v12_0_3:
8484
runs-on: ubuntu-latest
8585
steps:
8686
- name: Checkout the project
8787
uses: actions/checkout@v3
8888
- name: build
89-
run: make VERTICA_VERSION=12.0.3 OSTAG=centos
89+
run: make -C docker-dblink VERTICA_VERSION=12.0.3 OSTAG=centos
9090
- name: test
91-
run: make VERTICA_VERSION=12.0.3 OSTAG=centos test
91+
run: make -C docker-dblink VERTICA_VERSION=12.0.3 OSTAG=centos test
9292
test-ubuntu-v12_0_3:
9393
runs-on: ubuntu-latest
9494
steps:
9595
- name: Checkout the project
9696
uses: actions/checkout@v3
9797
- name: build
98-
run: make VERTICA_VERSION=12.0.3 OSTAG=ubuntu
98+
run: make -C docker-dblink VERTICA_VERSION=12.0.3 OSTAG=ubuntu
9999
- name: test
100-
run: make VERTICA_VERSION=12.0.3 OSTAG=ubuntu test
100+
run: make -C docker-dblink VERTICA_VERSION=12.0.3 OSTAG=ubuntu test
101+
test-centos-v12_0_4:
102+
runs-on: ubuntu-latest
103+
steps:
104+
- name: Checkout the project
105+
uses: actions/checkout@v3
106+
- name: build
107+
run: make -C docker-dblink VERTICA_VERSION=12.0.4 OSTAG=centos
108+
- name: test
109+
run: make -C docker-dblink VERTICA_VERSION=12.0.4 OSTAG=centos test

‎Makefile‎

Lines changed: 16 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,18 @@
1-
#
2-
# dblink Makefile
3-
# usage: make VERTICA_VERSION=<major.minor.patch> OSTAG=<ubuntu|centos>
4-
#
5-
6-
SHELL=/bin/bash # because WSL defaults to /bin/sh
7-
8-
# build local unless VERSION_TAG and OSTAG are speified
9-
VERSION_TAG=local
10-
ifdef OSTAG
11-
ifdef VERTICA_VERSION
12-
export OSTAG
13-
export VERTICA_VERSION
14-
VERSION_TAG=$(OSTAG)-v$(VERTICA_VERSION)
15-
VERTICA_SDK_IMAGE=vertica/verticasdk:$(VERSION_TAG)
16-
LOCAL_IMAGE=dblink_builder:$(VERSION_TAG)
17-
endif
18-
endif
19-
201
CXX = g++
21-
DOCKER = docker
22-
CXXDOCKER = $(DOCKER) run --rm -u "$(shell id -u):$(shell id -g)" -w "$(PWD)" -v "$(PWD):$(PWD):rw" $(LOCAL_IMAGE) g++
23-
CXXFLAGS = -O3 -D HAVE_LONG_INT_64 -Wall -std=c++11 -shared -Wno-unused-value -D_GLIBCXX_USE_CXX11_ABI=0 -fPIC
2+
CXXFLAGS = -O3 -D HAVE_LONG_INT_64 -Wall -std=c++11 -shared -Wno-unused-value -DODBC64 -D_GLIBCXX_USE_CXX11_ABI=0 -fPIC
243
INCPATH = -I/opt/vertica/sdk/include -I/opt/vertica/sdk/examples/HelperLibraries
254
VERPATH = /opt/vertica/sdk/include/Vertica.cpp
265
UDXLIBNAME = ldblink
27-
UDXLIB = $(UDXLIBNAME).so
6+
UDXLIB = /tmp/$(UDXLIBNAME).so
287
UDXSRC = $(UDXLIBNAME).cpp
29-
COMPILE_VERSION_LE_12_0_4 = $(CXXDOCKER) $(CXXFLAGS) $(INCPATH) -o $@ $< $(VERPATH) -lodbc
30-
31-
CXXDOCKER_FOR_NEW_SDK = $(DOCKER) run --rm -u "$(shell id -u):$(shell id -g)" -w "$(PWD)" -v "$(PWD):$(PWD):rw" $(LOCAL_IMAGE) "$(PWD)"
32-
CXXCMD = g++ $(CXXFLAGS)
33-
COMPILE_VERSION_GREATER_THAN_12_0_4 = $(CXXDOCKER_FOR_NEW_SDK) "$(CXXCMD) $(INCPATH) -o $@ $< $(VERPATH) -lodbc"
34-
OLD_SDK_MAX_VERSION = 12.0.4
35-
GETMINVERSION = echo "$(VERTICA_VERSION) $(OLD_SDK_MAX_VERSION)" | tr " " "\n" | sort -V | head -n 1
36-
MINVERSION=$(shell $(GETMINVERSION))
37-
38-
$(UDXLIB): $(UDXLIB).$(VERSION_TAG)
39-
@ln -snf $< $@
408

41-
$(UDXLIB).local: $(UDXSRC)
42-
@echo $(CXX) $(CXXFLAGS) $(INCPATH) -o $@ $< $(VERPATH) -lodbc
43-
@$(CXX) $(CXXFLAGS) $(INCPATH) -o $@ $< $(VERPATH) -lodbc || \
44-
if [[ ! -r /opt/vertica/sdk/include/Vertica.cpp ]] || ! type -p $(CXX) >/dev/null 2>&1 ; then \
45-
echo "usage: make VERTICA_VERSION=<major.minor.patch> OSTAG=<ubuntu|centos>" >&2; \
46-
exit 1; \
47-
else \
48-
echo "to build with docker: make VERTICA_VERSION=<major.minor.patch> OSTAG=<ubuntu|centos>" >&2; \
49-
exit 1; \
50-
fi
9+
all: compile
5110

52-
$(UDXLIB).$(OSTAG)-v$(VERTICA_VERSION): $(UDXSRC)
53-
@$(MAKE) .container.$(OSTAG)-v$(VERTICA_VERSION)
54-
ifeq ($(MINVERSION), $(VERTICA_VERSION))
55-
$(COMPILE_VERSION_LE_12_0_4)
56-
else
57-
$(COMPILE_VERSION_GREATER_THAN_12_0_4)
58-
endif
11+
debug: CXXFLAGS += -DDBLINK_DEBUG=1
12+
debug: compile
5913

60-
.PHONY: check
61-
check:
62-
@if ! type -p $(DOCKER) >/dev/null 2>&1 ; then \
63-
echo "Cannot find docker. To build with the local sdk in" >&2; \
64-
echo "/opt/vertica, unset VERSION_VERTICA and OSTAG" >&2; \
65-
fi
66-
@if ! [[ "$(VERTICA_VERSION)" =~ ^[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*$$ ]]; then \
67-
echo "VERTICA_VERSION must be set to the version of Vertica, i.e. 12.0.2" >&2; \
68-
exit 1; \
69-
fi
70-
@if ! [[ "$(OSTAG)" =~ ^(centos|ubuntu)$$ ]]; then \
71-
echo "OSTAG must be set to either centos or ubuntu" >&2; \
72-
exit 1; \
73-
fi
74-
@echo compiling for $(OSTAG) and Vertica version $(VERTICA_VERSION)
75-
76-
77-
.PHONY: container
78-
container: check .container.$(OSTAG)-v$(VERTICA_VERSION)
79-
@if ! $(DOCKER) image inspect $(LOCAL_IMAGE) >/dev/null 2>&1; then \
80-
rm .container.$(OSTAG)-v$(VERTICA_VERSION) ; \
81-
make .container.$(OSTAG)-v$(VERTICA_VERSION) ; \
82-
fi
83-
84-
.container.$(OSTAG)-v$(VERTICA_VERSION): tests/odbc.ini tests/odbcinst.ini tests/dblink.cids
85-
@$(DOCKER) build -f Dockerfile_$(OSTAG) -t $(LOCAL_IMAGE) --build-arg=IMAGE=$(VERTICA_SDK_IMAGE) .
86-
@touch .container.$(OSTAG)-v$(VERTICA_VERSION)
14+
compile: $(UDXSRC)
15+
$(CXX) $(CXXFLAGS) $(INCPATH) -o $(UDXLIB) $(UDXSRC) $(VERPATH) -lodbc
8716

8817
install: $(UDXLIB)
8918
@echo " \
@@ -93,24 +22,14 @@ install: $(UDXLIB)
9322
GRANT USAGE ON LIBRARY $(UDXLIBNAME) TO PUBLIC ; \
9423
" | vsql -U dbadmin -X -f - -e
9524

96-
uninstall:
25+
install_unfenced: $(UDXLIB)
9726
@echo " \
98-
DROP LIBRARY $(UDXLIBNAME) CASCADE ; \
27+
CREATE OR REPLACE LIBRARY $(UDXLIBNAME) AS '$(UDXLIB)' LANGUAGE 'C++'; \
28+
CREATE OR REPLACE TRANSFORM FUNCTION dblink AS LANGUAGE 'C++' NAME 'DBLinkFactory' LIBRARY $(UDXLIBNAME) NOT FENCED ; \
29+
GRANT EXECUTE ON TRANSFORM FUNCTION dblink() TO PUBLIC ; \
30+
GRANT USAGE ON LIBRARY $(UDXLIBNAME) TO PUBLIC ; \
9931
" | vsql -U dbadmin -X -f - -e
100-
101-
clean: check
102-
@$(DOCKER) image rm $(LOCAL_IMAGE) || true
103-
@ rm -f .container.$(OSTAG)-v$(VERTICA_VERSION)
104-
#$(DOCKER) image rm $(VERTICA_SDK_IMAGE) || true
105-
106-
# build all versions for release purposes
107-
release:
108-
@for i in $$(curl https://hub.docker.com/v2/namespaces/vertica/repositories/verticasdk/tags | perl -nE 'print join "\n",m/(?:ubuntu|centos)-v\d+\.\d+\.\d+/g') ; do \
109-
$(MAKE) VERTICA_VERSION="$${i##*-v}" OSTAG="$${i%%-v*}" || ((errors++));\
110-
done; \
111-
((errors==0)) # return an error if there are errors
112-
113-
.PHONY: test
114-
test: $(UDXLIB).$(VERSION_TAG) .container.$(OSTAG)-v$(VERTICA_VERSION)
115-
@cd tests; OSTAG=$(OSTAG) VERTICA_VERSION=$(VERTICA_VERSION) ./test_script.sh
116-
32+
clean:
33+
@echo " \
34+
DROP LIBRARY $(UDXLIBNAME) CASCADE ; \
35+
" | vsql -U dbadmin -X -f - -e

‎README.md‎

Lines changed: 32 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -87,31 +87,54 @@ You can install `DBLINK()` from the latest released binaries without needing to
8787
8888
### Installing pre-built binaries
8989
90-
1. Download the appropriate build of ldblink.so from the [latest release](https://github.com/vertica/dblink/releases) to `ldblink.so`.
91-
2. Copy `ldblink.so` to the initiator node.
92-
3. Execute this SQL substituting the full path of ldblink.so on the initiator node:
90+
1. Download the appropriate build of ldblink.so from the [latest release](https://github.com/vertica/dblink/releases).
91+
Example:
92+
ldblink.so.centos-v23.3.0 -> binary for vertica v23.3.0 on CentOS
93+
2. Rename the binary to `ldblink.so`
94+
3. Copy `ldblink.so` to the initiator node.
95+
4. Execute this SQL substituting the full path of ldblink.so on the initiator node:
9396
```sql
9497
CREATE OR REPLACE LIBRARY DBLink AS '/full/path/to/ldblink.so' LANGUAGE 'C++';
9598
CREATE OR REPLACE TRANSFORM FUNCTION dblink AS LANGUAGE 'C++' NAME 'DBLinkFactory' LIBRARY DBLink ;
9699
GRANT EXECUTE ON TRANSFORM FUNCTION dblink() TO PUBLIC ;
97100
```
98-
4. (optional) Delete ldblink.so from initiator node.
101+
5. Create a [Connection Identifier Database](#connection-identifier-database) (a simple text file) under `/usr/local/etc/dblink.cids`. You can use a different location by changing the `DBLINK_CIDS` define in the source code.
102+
For details, see [Configure DBLINK()](#configure-dblink).
103+
104+
6. (optional) Delete ldblink.so from initiator node.
99105
100106
### Build DBLINK() From Source
101107
102108
Before you run `make` commands, review the [Makefile](Makefile) and make any necessary changes.
103109
110+
#### On your own build environment
111+
112+
- First you need to [Setup a C++ Development Environment](https://docs.vertica.com/23.3.x/en/extending/developing-udxs/developing-with-sdk/cpp-sdk/setting-up-cpp-sdk/)
113+
- Then to build using the installed Vertica SDK and devtoolset (centos): just run
114+
> ```make```
115+
- Install the library in Vertica (as dbadmin):
116+
>```make install```
117+
- Create a [Connection Identifier Database](#connection-identifier-database) (a simple text file) under `/usr/local/etc/dblink.cids`. You can use a different location by changing the `DBLINK_CIDS` define in the source code.
118+
For details, see [Configure DBLINK()](#configure-dblink).
119+
120+
#### Without setting up a build environment
121+
122+
This is mainly for <b>testing</b> and <b>release</b>, or when you want to build dblink for a specific vertica version on centos/ubuntu but you do not have the tools to do it. It uses the [verticasdk](https://hub.docker.com/r/vertica/verticasdk) docker image owned by Vertica to build dblink for any specified vertica version.
104123
1. Compile the DBLINK source code with for the appropriate Vertica version and Linux distribution.
105-
- To build using the installed Vertica SDK and devtoolset (centos), just run `make`
106124
- To build without needing to set up a build environment, specify the version and target OS. For example:
107-
> ```$ make VERTICA_VERSION=12.0.2 OSTAG=ubuntu```
108-
2. Follow the install proceedures above or use the `install` makefile target to deploy the library in Vertica as dbadmin:
109-
> ```$ make install```.
125+
```
126+
$ make -C docker-dblink VERTICA_VERSION=12.0.2 OSTAG=ubuntu
127+
```
128+
it will create `ldblink.s0.ubuntu-v12.0.2` in the docker-dblink directory
129+
130+
2. Install the library in Vertica (as dbadmin):
131+
Follow [Installing pre-built libraries](#installing-pre-built-binaries) from step 2.
132+
110133
3. Create a [Connection Identifier Database](#connection-identifier-database) (a simple text file) under `/usr/local/etc/dblink.cids`. You can use a different location by changing the `DBLINK_CIDS` define in the source code.
111134
For details, see [Configure DBLINK()](#configure-dblink).
112135
113136
### Uninstall DBLINK()
114-
You can uninstall the library with `DROP LIBRARAY DBLink` in vsql or by running `make clean`.
137+
You can uninstall the library with `DROP LIBRARY DBLink` in vsql or by running `make clean`.
115138
116139
## Configure DBLINK()
117140

Dockerfile_centos renamed to docker-dblink/Dockerfile_centos

File renamed without changes.

Dockerfile_ubuntu renamed to docker-dblink/Dockerfile_ubuntu

File renamed without changes.

0 commit comments

Comments
 (0)