Impelement oracle database migration

Dockerfile-oracle

@@ -0,0 +1,33 @@
+FROM golang:1.13-buster as builder
+
+RUN apt-get update && apt-get install -y --no-install-recommends zip unzip build-essential libaio1 \
+	&& rm -rf /var/lib/apt/lists/*
+
+ARG VERSION
+
+COPY database/oracle/assets/instantclient-basiclite-linux.x64-18.5.0.0.0dbru.zip /opt/oracle/
+RUN unzip -d /opt/oracle /opt/oracle/instantclient-basiclite-linux.x64-18.5.0.0.0dbru.zip
+ENV LD_LIBRARY_PATH="/opt/oracle/instantclient_18_5"
+
+WORKDIR /go/src/github.com/golang-migrate/migrate
+
+COPY go.mod go.sum ./
+
+RUN go mod download
+
+COPY . ./
+
+RUN go build -a -o build/migrate.linux-386 -ldflags="-s -w -X main.Version=${VERSION}" -tags "oracle" ./cmd/migrate
+
+FROM debian:buster-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends libaio1 ca-certificates \
+	&& rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /opt/oracle/instantclient_18_5 /opt/oracle/instantclient_18_5
+COPY --from=builder /go/src/github.com/golang-migrate/migrate/build/migrate.linux-386 /migrate
+
+ENV LD_LIBRARY_PATH="/opt/oracle/instantclient_18_5:${LD_LIBRARY_PATH}"
+
+ENTRYPOINT ["/migrate"]
+CMD ["--help"]

database/oracle/README.md

@@ -0,0 +1,80 @@
+# oracle
+The golang oracle driver [godror](https://github.com/godror/godror) does not natively support executing multiple statements in a single query. 
+Here are the strategies for splitting the migration text into separately-executed statements:
+1. If there is no PL/SQL statement in a migration file, the `semicolons` will be the separator
+1. If there is any PL/SQL statement in a migration file, the separator will be `---` in a single line or specified by `x-plsql-line-separator`, 
+   And in this case the multiple statements cannot be used when a statement in the migration contains a string with the given `line separator`.
+
+`oracle://user:password@host:port/sid?query`
+
+| URL Query  | WithInstance Config | Description |
+|------------|---------------------|-------------|
+| `x-migrations-table` | `MigrationsTable` | Name of the migrations table in UPPER case |
+| `x-plsql-line-separator` | `PLSQLStatementSeparator` | a single line which use as the token to spilt multiple statements in single migration file (See note above), default `---` |
+
+## Runtime dependency
+
+Although an Oracle client is NOT required for compiling, it is at run time. One can download it from https://www.oracle.com/database/technologies/instant-client/downloads.html
+
+## Supported & tested version
+- 12c-ee
+- 18c-xe
+
+## How to use
+
+In order to compile & run the migration against Oracle database, basically it will require:
+
+## Build cli
+
+```bash
+$ cd /path/to/repo/dir
+$ go build  -tags 'oracle' -o bin/migrate github.com/golang-migrate/migrate/v4/cli
+```
+
+## Configure Oracle database
+1. Example Oracle version: `Oracle Database Express Edition`, check [here](https://docs.oracle.com/cd/B28359_01/license.111/b28287/editions.htm#DBLIC119) from version details.
+1. Start a oracle docker container based on customized community oracle-xe image(include a PDB database & default user `oracle` in it): `docker run --name oracle -d -p 1521:1521 -p 5500:5500 --volume ~/data/oracle-xe:/opt/oracle/oradata maxnilz/oracle-xe:18c`
+1. Wait a moment, first time will take a while to run for as the oracle-xe configure script needs to complete
+
+## Download runtime dependency
+
+Download [oracle client dynamic library](https://www.oracle.com/technetwork/database/database-technologies/instant-client/downloads/index.html) from their official site manually, because it requires to logon and honor a check box on download page manually.
+
+## Play
+
+### Run test code 
+
+```bash
+$ cd /path/to/repo/database/oracle/dir
+$ ORACLE_DSN=oracle://oracle:oracle@localhost:1521/XEPDB1 LD_LIBRARY_PATH=/path/to/oracle/lib/dir go test -tags "oracle" -race -v -covermode atomic ./... -coverprofile .coverage
+```
+
+### Write migration files
+
+Check [example migration files](examples)
+
+## FAQs
+
+Maybe not "frequently asked", but hopefully these answers will be useful.
+
+### Why the test code for oracle in CI are disabled
+
+Setup test case via oracle container in CI is very expensive for these reasons:
+1. There is no public official docker images available
+1. The oracle image size in community is 8GB, which is huge
+1. The volume size of one single oracle container is about 5GB, which is huge too
+1. And more importantly, It will take a long time to start just a single oracle container & configure it(almost 30min on my 16GB memory, 8 cores machine). The test case will run in parallel and each case will require it's own container, which will increase the resource & time costs many times.
+1. Although an Oracle client is NOT required for compiling, it is at run time. and it's tricky to download the dynamic lib directly/automatically because of the oracle download policies. 
+
+### Why there is a dockerfile for oracle only?
+
+The dependent dynamic libs are missing in alpine system, the dockerfile for oracle is based on debian system.
+
+### Why there is an assets dir for the oracle libs
+
+1. It requires to login to the oracle official site & config the license manually for downloading these oracle lib, we can't use wget & curl to download directly.
+1. In order to make `Dockerfile.oracle` works, I download them manually and put them in the `assets` dir.
+
+### Why we need the dynamic library?
+
+There is no static lib for the application to compile & link. check [here](https://community.oracle.com/thread/4177571) for more details.

database/oracle/examples/migrations/1085649617_create_users_table.down.sql

@@ -0,0 +1,8 @@
+BEGIN
+EXECUTE IMMEDIATE 'DROP TABLE USERS';
+EXCEPTION
+    WHEN OTHERS THEN
+        IF SQLCODE != -942 THEN
+            RAISE;
+        END IF;
+END;

database/oracle/examples/migrations/1085649617_create_users_table.up.sql

@@ -0,0 +1,24 @@
+CREATE TABLE USERS (
+  USER_ID integer unique,
+  NAME    varchar(40),
+  EMAIL   varchar(40)
+);
+
+---
+
+BEGIN
+EXECUTE IMMEDIATE 'DROP TABLE USERS';
+EXCEPTION
+    WHEN OTHERS THEN
+        IF SQLCODE != -942 THEN
+            RAISE;
+        END IF;
+END;
+
+---
+
+CREATE TABLE USERS (
+   USER_ID integer unique,
+   NAME    varchar(40),
+   EMAIL   varchar(40)
+);

database/oracle/examples/migrations/1185749658_add_city_to_users.down.sql

@@ -0,0 +1,14 @@
+DECLARE
+    v_column_exists number := 0;
+BEGIN
+    SELECT COUNT(*)
+    INTO v_column_exists
+    FROM user_tab_cols
+    WHERE  table_name = 'USERS'
+      AND column_name = 'CITY';
+
+    IF( v_column_exists = 1 )
+    THEN
+        EXECUTE IMMEDIATE 'ALTER TABLE users DROP COLUMN CITY';
+    END IF;
+END;

database/oracle/examples/migrations/1185749658_add_city_to_users.up.sql

@@ -0,0 +1,4 @@
+ALTER TABLE USERS ADD CITY varchar(100);
+ALTER TABLE USERS ADD ALIAS varchar(100);
+
+

database/oracle/examples/migrations/1285849751_add_index_on_user_emails.down.sql

@@ -0,0 +1,12 @@
+DECLARE
+   COUNT_INDEXES   INTEGER;
+BEGIN
+   SELECT COUNT ( * )
+     INTO COUNT_INDEXES
+     FROM USER_INDEXES
+    WHERE INDEX_NAME = 'users_email_index';
+   IF COUNT_INDEXES > 0
+   THEN
+      EXECUTE IMMEDIATE 'DROP INDEX users_email_index';
+   END IF;
+END;

database/oracle/examples/migrations/1285849751_add_index_on_user_emails.up.sql

@@ -0,0 +1 @@
+CREATE UNIQUE INDEX users_email_index ON users (email);

database/oracle/examples/migrations/1385949617_create_books_table.down.sql

@@ -0,0 +1,8 @@
+BEGIN
+EXECUTE IMMEDIATE 'DROP TABLE BOOKS';
+EXCEPTION
+    WHEN OTHERS THEN
+        IF SQLCODE != -942 THEN
+            RAISE;
+        END IF;
+END;

database/oracle/examples/migrations/1385949617_create_books_table.up.sql

@@ -0,0 +1,5 @@
+CREATE TABLE BOOKS (
+  USER_ID integer,
+  NAME    varchar(40),
+  AUTHOR  varchar(40)
+);

database/oracle/examples/migrations/1485949617_create_movies_table.down.sql

@@ -0,0 +1,8 @@
+BEGIN
+EXECUTE IMMEDIATE 'DROP TABLE MOVIES';
+EXCEPTION
+    WHEN OTHERS THEN
+        IF SQLCODE != -942 THEN
+            RAISE;
+        END IF;
+END;

database/oracle/examples/migrations/1485949617_create_movies_table.up.sql

@@ -0,0 +1,5 @@
+CREATE TABLE MOVIES (
+  USER_ID   integer,
+  NAME      varchar(40),
+  DIRECTOR  varchar(40)
+);

database/oracle/examples/migrations/1585849751_just_a_comment.up.sql

@@ -0,0 +1 @@
+-- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean sed interdum velit, tristique iaculis justo. Pellentesque ut porttitor dolor. Donec sit amet pharetra elit. Cras vel ligula ex. Phasellus posuere.

database/oracle/examples/migrations/1685849751_another_comment.up.sql

@@ -0,0 +1 @@
+-- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean sed interdum velit, tristique iaculis justo. Pellentesque ut porttitor dolor. Donec sit amet pharetra elit. Cras vel ligula ex. Phasellus posuere.

database/oracle/examples/migrations/1785849751_another_comment.up.sql

@@ -0,0 +1 @@
+-- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean sed interdum velit, tristique iaculis justo. Pellentesque ut porttitor dolor. Donec sit amet pharetra elit. Cras vel ligula ex. Phasellus posuere.

database/oracle/examples/migrations/1885849751_another_comment.up.sql

@@ -0,0 +1 @@
+-- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean sed interdum velit, tristique iaculis justo. Pellentesque ut porttitor dolor. Donec sit amet pharetra elit. Cras vel ligula ex. Phasellus posuere.