github.com/brandonmartin/migrate/v4@v4.14.2/database/oracle/README.md (about)

     1  # oracle
     2  The golang oracle driver [godror](https://github.com/godror/godror) does not natively support executing multiple statements in a single query. 
     3  Here are the strategies for splitting the migration text into separately-executed statements if multi statements detecting isn't been disable explicitly via `x-disable-multi-statements`:
     4  1. If there is no PL/SQL statement in a migration file, the `semicolons` will be the separator
     5  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`, 
     6     And in this case the multiple statements cannot be used when a statement in the migration contains a string with the given `line separator`.
     7  
     8  `oracle://user:password@host:port/sid?query`
     9  
    10  | URL Query  | WithInstance Config | Description |
    11  |------------|---------------------|-------------|
    12  | `x-migrations-table` | `MigrationsTable` | Name of the migrations table in UPPER case |
    13  | `x-disable-multi-statements` | `DisableMultiStatements` | Indicate if disable multi statements detection automatically |
    14  | `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 `---` |
    15  
    16  ## Runtime dependency
    17  
    18  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
    19  
    20  ## Supported & tested version
    21  - 12c-ee
    22  - 18c-xe
    23  
    24  ## How to use
    25  
    26  In order to compile & run the migration against Oracle database, basically it will require:
    27  
    28  ## Build cli
    29  
    30  ```bash
    31  $ cd /path/to/repo/dir
    32  $ go build  -tags 'oracle' -o bin/migrate github.com/golang-migrate/migrate/v4/cli
    33  ```
    34  
    35  ## Configure Oracle database
    36  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 and download xe [here](https://www.oracle.com/database/technologies/xe-downloads.html)
    37  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`
    38  1. Wait a moment, first time will take a while to run for as the oracle-xe configure script needs to complete
    39  
    40  ## Download runtime dependency
    41  
    42  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.
    43  
    44  ## Play
    45  
    46  ### Run test code 
    47  
    48  ```bash
    49  $ cd /path/to/repo/database/oracle/dir
    50  $ 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
    51  ```
    52  
    53  ### Write migration files
    54  
    55  Check [example migration files](examples)
    56  
    57  ## FAQs
    58  
    59  Maybe not "frequently asked", but hopefully these answers will be useful.
    60  
    61  ### Why the test code for oracle in CI are disabled
    62  
    63  Setup test case via oracle container in CI is very expensive for these reasons:
    64  1. There is no public official docker images available
    65  1. The oracle image size in community is 8GB, which is huge
    66  1. The volume size of one single oracle container is about 5GB, which is huge too
    67  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.
    68  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. 
    69  
    70  ### Why there is a dockerfile for oracle only?
    71  
    72  The dependent dynamic libs are missing in alpine system, the dockerfile for oracle is based on debian system.
    73  
    74  ### Why there is an assets dir for the oracle libs
    75  
    76  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.
    77  1. In order to make `Dockerfile.oracle` works, I download them manually and put them in the `assets` dir.
    78  
    79  ### Why we need the dynamic library?
    80  
    81  There is no static lib for the application to compile & link. check [here](https://community.oracle.com/thread/4177571) for more details.
    82  
    83  ### Are there public docker images available
    84  
    85  1. There is no official pubic docker images available
    86  1. Based on [this official open-source repo](https://github.com/oracle/docker-images), I published [maxnilz/oracle-ee:12.2.0.1](https://hub.docker.com/repository/docker/maxnilz/oracle-ee) and [maxnilz/oracle-xe:18c](https://hub.docker.com/repository/docker/maxnilz/oracle-xe) in docker hub 
    87  1. JUST FOR LEARN PURPOSE!!!