Update documentation (#26)

Change the file structure by creating a new folder for testing on docker
vertica · Sep 11, 2023 · d9df821 · d9df821
1 parent 5f8bbdf
commit d9df821
Show file tree

Hide file tree

Showing 12 changed files with 174 additions and 126 deletions.
diff --git a/.github/workflows/makefile.yml b/.github/workflows/makefile.yml
@@ -14,87 +14,96 @@ jobs:
     - name: Checkout the project
       uses: actions/checkout@v3
     - name: build
-      run: make VERTICA_VERSION=10.0.1 OSTAG=centos
+      run: make -C docker-dblink VERTICA_VERSION=10.0.1 OSTAG=centos
     - name: test
-      run: make VERTICA_VERSION=10.0.1 OSTAG=centos test
+      run: make -C docker-dblink VERTICA_VERSION=10.0.1 OSTAG=centos test
   test-ubuntu-v10_0_1:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout the project
       uses: actions/checkout@v3
     - name: build
-      run: make VERTICA_VERSION=10.0.1 OSTAG=ubuntu
+      run: make -C docker-dblink VERTICA_VERSION=10.0.1 OSTAG=ubuntu
     - name: test
-      run: make VERTICA_VERSION=10.0.1 OSTAG=ubuntu test
+      run: make -C docker-dblink VERTICA_VERSION=10.0.1 OSTAG=ubuntu test
   test-centos-v10_1_1:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout the project
       uses: actions/checkout@v3
     - name: build
-      run: make VERTICA_VERSION=10.1.1 OSTAG=centos
+      run: make -C docker-dblink VERTICA_VERSION=10.1.1 OSTAG=centos
     - name: test
-      run: make VERTICA_VERSION=10.1.1 OSTAG=centos test
+      run: make -C docker-dblink VERTICA_VERSION=10.1.1 OSTAG=centos test
   test-ubuntu-v10_1_1:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout the project
       uses: actions/checkout@v3
     - name: build
-      run: make VERTICA_VERSION=10.1.1 OSTAG=ubuntu
+      run: make -C docker-dblink VERTICA_VERSION=10.1.1 OSTAG=ubuntu
     - name: test
-      run: make VERTICA_VERSION=10.1.1 OSTAG=ubuntu test
+      run: make -C docker-dblink VERTICA_VERSION=10.1.1 OSTAG=ubuntu test
   test-centos-v11_0_2:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout the project
       uses: actions/checkout@v3
     - name: build
-      run: make VERTICA_VERSION=11.0.2 OSTAG=centos
+      run: make -C docker-dblink VERTICA_VERSION=11.0.2 OSTAG=centos
     - name: test
-      run: make VERTICA_VERSION=11.0.2 OSTAG=centos test
+      run: make -C docker-dblink VERTICA_VERSION=11.0.2 OSTAG=centos test
   test-ubuntu-v11_0_2:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout the project
       uses: actions/checkout@v3
     - name: build
-      run: make VERTICA_VERSION=11.0.2 OSTAG=ubuntu
+      run: make -C docker-dblink VERTICA_VERSION=11.0.2 OSTAG=ubuntu
     - name: test
-      run: make VERTICA_VERSION=11.0.2 OSTAG=ubuntu test
+      run: make -C docker-dblink VERTICA_VERSION=11.0.2 OSTAG=ubuntu test
   test-centos-v11_1_1:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout the project
       uses: actions/checkout@v3
     - name: build
-      run: make VERTICA_VERSION=11.1.1 OSTAG=centos
+      run: make -C docker-dblink VERTICA_VERSION=11.1.1 OSTAG=centos
     - name: test
-      run: make VERTICA_VERSION=11.1.1 OSTAG=centos test
+      run: make -C docker-dblink VERTICA_VERSION=11.1.1 OSTAG=centos test
   test-ubuntu-v11_1_1:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout the project
       uses: actions/checkout@v3
     - name: build
-      run: make VERTICA_VERSION=11.1.1 OSTAG=ubuntu
+      run: make -C docker-dblink VERTICA_VERSION=11.1.1 OSTAG=ubuntu
     - name: test
-      run: make VERTICA_VERSION=11.1.1 OSTAG=ubuntu test
+      run: make -C docker-dblink VERTICA_VERSION=11.1.1 OSTAG=ubuntu test
   test-centos-v12_0_3:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout the project
       uses: actions/checkout@v3
     - name: build
-      run: make VERTICA_VERSION=12.0.3 OSTAG=centos
+      run: make -C docker-dblink VERTICA_VERSION=12.0.3 OSTAG=centos
     - name: test
-      run: make VERTICA_VERSION=12.0.3 OSTAG=centos test
+      run: make -C docker-dblink VERTICA_VERSION=12.0.3 OSTAG=centos test
   test-ubuntu-v12_0_3:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout the project
       uses: actions/checkout@v3
     - name: build
-      run: make VERTICA_VERSION=12.0.3 OSTAG=ubuntu
+      run: make -C docker-dblink VERTICA_VERSION=12.0.3 OSTAG=ubuntu
     - name: test
-      run: make VERTICA_VERSION=12.0.3 OSTAG=ubuntu test
+      run: make -C docker-dblink VERTICA_VERSION=12.0.3 OSTAG=ubuntu test
+  test-centos-v12_0_4:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout the project
+      uses: actions/checkout@v3
+    - name: build
+      run: make -C docker-dblink VERTICA_VERSION=12.0.4 OSTAG=centos
+    - name: test
+      run: make -C docker-dblink VERTICA_VERSION=12.0.4 OSTAG=centos test
diff --git a/Makefile b/Makefile
@@ -1,89 +1,18 @@
-#
-# dblink Makefile
-# usage: make VERTICA_VERSION=<major.minor.patch> OSTAG=<ubuntu|centos>
-#
-
-SHELL=/bin/bash # because WSL defaults to /bin/sh
-
-# build local unless VERSION_TAG and OSTAG are speified
-VERSION_TAG=local
-ifdef OSTAG
-ifdef VERTICA_VERSION
-export OSTAG
-export VERTICA_VERSION
-VERSION_TAG=$(OSTAG)-v$(VERTICA_VERSION)
-VERTICA_SDK_IMAGE=vertica/verticasdk:$(VERSION_TAG)
-LOCAL_IMAGE=dblink_builder:$(VERSION_TAG)
-endif
-endif
-
 CXX = g++
-DOCKER = docker
-CXXDOCKER = $(DOCKER) run --rm -u "$(shell id -u):$(shell id -g)" -w "$(PWD)" -v "$(PWD):$(PWD):rw" $(LOCAL_IMAGE) g++
-CXXFLAGS = -O3 -D HAVE_LONG_INT_64 -Wall -std=c++11 -shared -Wno-unused-value -D_GLIBCXX_USE_CXX11_ABI=0 -fPIC
+CXXFLAGS = -O3 -D HAVE_LONG_INT_64 -Wall -std=c++11 -shared -Wno-unused-value -DODBC64 -D_GLIBCXX_USE_CXX11_ABI=0 -fPIC 
 INCPATH = -I/opt/vertica/sdk/include -I/opt/vertica/sdk/examples/HelperLibraries
 VERPATH = /opt/vertica/sdk/include/Vertica.cpp
 UDXLIBNAME = ldblink
-UDXLIB = $(UDXLIBNAME).so
+UDXLIB = /tmp/$(UDXLIBNAME).so
 UDXSRC = $(UDXLIBNAME).cpp
-COMPILE_VERSION_LE_12_0_4 = $(CXXDOCKER) $(CXXFLAGS) $(INCPATH) -o $@ $< $(VERPATH) -lodbc
-
-CXXDOCKER_FOR_NEW_SDK = $(DOCKER) run --rm -u "$(shell id -u):$(shell id -g)" -w "$(PWD)" -v "$(PWD):$(PWD):rw" $(LOCAL_IMAGE) "$(PWD)"
-CXXCMD = g++ $(CXXFLAGS)
-COMPILE_VERSION_GREATER_THAN_12_0_4 = $(CXXDOCKER_FOR_NEW_SDK) "$(CXXCMD) $(INCPATH) -o $@ $< $(VERPATH) -lodbc"
-OLD_SDK_MAX_VERSION = 12.0.4
-GETMINVERSION = echo "$(VERTICA_VERSION) $(OLD_SDK_MAX_VERSION)" | tr " " "\n" | sort -V | head -n 1
-MINVERSION=$(shell $(GETMINVERSION))
-
-$(UDXLIB): $(UDXLIB).$(VERSION_TAG)
-	@ln -snf $< $@
 
-$(UDXLIB).local: $(UDXSRC)
-	@echo $(CXX) $(CXXFLAGS) $(INCPATH) -o $@ $< $(VERPATH) -lodbc
-	@$(CXX) $(CXXFLAGS) $(INCPATH) -o $@ $< $(VERPATH) -lodbc || \
-	  if [[ ! -r /opt/vertica/sdk/include/Vertica.cpp ]] || ! type -p $(CXX) >/dev/null 2>&1 ; then \
-	    echo "usage: make VERTICA_VERSION=<major.minor.patch> OSTAG=<ubuntu|centos>" >&2; \
-	    exit 1; \
-	  else \
-	    echo "to build with docker: make VERTICA_VERSION=<major.minor.patch> OSTAG=<ubuntu|centos>" >&2; \
-	    exit 1; \
-	  fi
+all: compile
 
-$(UDXLIB).$(OSTAG)-v$(VERTICA_VERSION): $(UDXSRC)
-	@$(MAKE) .container.$(OSTAG)-v$(VERTICA_VERSION)
-ifeq ($(MINVERSION), $(VERTICA_VERSION))
-	$(COMPILE_VERSION_LE_12_0_4)
-else
-	$(COMPILE_VERSION_GREATER_THAN_12_0_4)
-endif
+debug: CXXFLAGS += -DDBLINK_DEBUG=1
+debug: compile
 
-.PHONY: check
-check:
-	@if ! type -p $(DOCKER) >/dev/null 2>&1 ; then \
-	  echo "Cannot find docker.  To build with the local sdk in" >&2; \
-	  echo "/opt/vertica, unset VERSION_VERTICA and OSTAG" >&2; \
-	fi
-	@if ! [[ "$(VERTICA_VERSION)" =~ ^[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*$$ ]]; then \
-	  echo "VERTICA_VERSION must be set to the version of Vertica, i.e.  12.0.2" >&2; \
-	  exit 1; \
-	fi
-	@if ! [[ "$(OSTAG)" =~ ^(centos|ubuntu)$$ ]]; then \
-	  echo "OSTAG must be set to either centos or ubuntu" >&2; \
-	  exit 1; \
-	fi
-	@echo compiling for $(OSTAG) and Vertica version $(VERTICA_VERSION)
-
-
-.PHONY: container
-container: check .container.$(OSTAG)-v$(VERTICA_VERSION)
-	@if ! $(DOCKER) image inspect $(LOCAL_IMAGE) >/dev/null 2>&1; then \
-	  rm .container.$(OSTAG)-v$(VERTICA_VERSION) ; \
-	  make .container.$(OSTAG)-v$(VERTICA_VERSION) ; \
-	fi
-
-.container.$(OSTAG)-v$(VERTICA_VERSION): tests/odbc.ini tests/odbcinst.ini tests/dblink.cids
-	@$(DOCKER) build -f Dockerfile_$(OSTAG) -t $(LOCAL_IMAGE) --build-arg=IMAGE=$(VERTICA_SDK_IMAGE) .
-	@touch .container.$(OSTAG)-v$(VERTICA_VERSION)
+compile: $(UDXSRC)
+	$(CXX) $(CXXFLAGS) $(INCPATH) -o $(UDXLIB) $(UDXSRC) $(VERPATH) -lodbc
 
 install: $(UDXLIB)
 	@echo " \
@@ -93,24 +22,14 @@ install: $(UDXLIB)
 		GRANT USAGE ON LIBRARY $(UDXLIBNAME) TO PUBLIC ; \
 	" | vsql -U dbadmin  -X -f - -e
 
-uninstall:
+install_unfenced: $(UDXLIB)
 	@echo " \
-	    DROP LIBRARY $(UDXLIBNAME) CASCADE ; \
+	    CREATE OR REPLACE LIBRARY $(UDXLIBNAME) AS '$(UDXLIB)' LANGUAGE 'C++'; \
+	    CREATE OR REPLACE TRANSFORM FUNCTION dblink AS LANGUAGE 'C++' NAME 'DBLinkFactory' LIBRARY $(UDXLIBNAME) NOT FENCED ; \
+		GRANT EXECUTE ON TRANSFORM FUNCTION dblink() TO PUBLIC ; \
+		GRANT USAGE ON LIBRARY $(UDXLIBNAME) TO PUBLIC ; \
 	" | vsql -U dbadmin  -X -f - -e
-
-clean: check
-	@$(DOCKER) image rm $(LOCAL_IMAGE) || true
-	@ rm -f .container.$(OSTAG)-v$(VERTICA_VERSION)
-	#$(DOCKER) image rm $(VERTICA_SDK_IMAGE) || true
-
-# build all versions for release purposes
-release:
-	@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 \
-	  $(MAKE) VERTICA_VERSION="$${i##*-v}" OSTAG="$${i%%-v*}"  || ((errors++));\
-	done; \
-	((errors==0)) # return an error if there are errors
-
-.PHONY: test
-test: $(UDXLIB).$(VERSION_TAG) .container.$(OSTAG)-v$(VERTICA_VERSION)
-	@cd tests; OSTAG=$(OSTAG) VERTICA_VERSION=$(VERTICA_VERSION) ./test_script.sh
-
+clean:
+	@echo " \
+	    DROP LIBRARY $(UDXLIBNAME) CASCADE ; \
+	" | vsql -U dbadmin  -X -f - -e
diff --git a/README.md b/README.md
@@ -87,31 +87,54 @@ You can install `DBLINK()` from the latest released binaries without needing to
 
 ### Installing pre-built binaries
 
-1. Download the appropriate build of ldblink.so from the [latest release](https://github.com/vertica/dblink/releases) to `ldblink.so`.
-2. Copy `ldblink.so` to the initiator node.
-3. Execute this SQL substituting the full path of ldblink.so on the initiator node:
+1. Download the appropriate build of ldblink.so from the [latest release](https://github.com/vertica/dblink/releases).
+Example:
+ldblink.so.centos-v23.3.0 -> binary for vertica v23.3.0 on CentOS
+2. Rename the binary to `ldblink.so`
+3. Copy `ldblink.so` to the initiator node.
+4. Execute this SQL substituting the full path of ldblink.so on the initiator node:
 ```sql
 	    CREATE OR REPLACE LIBRARY DBLink AS '/full/path/to/ldblink.so' LANGUAGE 'C++';
 	    CREATE OR REPLACE TRANSFORM FUNCTION dblink AS LANGUAGE 'C++' NAME 'DBLinkFactory' LIBRARY DBLink ;
             GRANT EXECUTE ON TRANSFORM FUNCTION dblink() TO PUBLIC ;
 ```
-4. (optional) Delete ldblink.so from initiator node.
+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.
+   For details, see [Configure DBLINK()](#configure-dblink).
+
+6. (optional) Delete ldblink.so from initiator node.
 
 ### Build DBLINK() From Source
 
 Before you run `make` commands, review the [Makefile](Makefile) and make any necessary changes.
 
+#### On your own build environment
+
+- 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/)
+- Then to build using the installed Vertica SDK and devtoolset (centos): just run
+    > ```make```
+- Install the library in Vertica (as dbadmin):
+    >```make install```
+- 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.
+   For details, see [Configure DBLINK()](#configure-dblink).
+
+#### Without setting up a build environment
+
+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.
 1. Compile the DBLINK source code with for the appropriate Vertica version and Linux distribution.
-   - To build using the installed Vertica SDK and devtoolset (centos), just run `make`
    - To build without needing to set up a build environment, specify the version and target OS.  For example:
-> ```$ make VERTICA_VERSION=12.0.2 OSTAG=ubuntu```
-2. Follow the install proceedures above or use the `install` makefile target to deploy the library in Vertica as dbadmin:
-> ```$ make install```.
+        ```
+        $ make -C docker-dblink VERTICA_VERSION=12.0.2 OSTAG=ubuntu
+        ```
+        it will create `ldblink.s0.ubuntu-v12.0.2` in the docker-dblink directory
+
+2. Install the library in Vertica (as dbadmin):
+    Follow [Installing pre-built libraries](#installing-pre-built-binaries) from step 2.
+
 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.
    For details, see [Configure DBLINK()](#configure-dblink).
 
 ### Uninstall DBLINK()
-You can uninstall the library with `DROP LIBRARAY DBLink` in vsql or by running `make clean`.
+You can uninstall the library with `DROP LIBRARY DBLink` in vsql or by running `make clean`.
 
 ## Configure DBLINK()
 

diff --git a/Dockerfile_centos → docker-dblink/Dockerfile_centos b/Dockerfile_centos → docker-dblink/Dockerfile_centos
diff --git a/Dockerfile_ubuntu → docker-dblink/Dockerfile_ubuntu b/Dockerfile_ubuntu → docker-dblink/Dockerfile_ubuntu