some how-to and why documentation
This commit is contained in:
Jim Lambert
parent
3f9a0298ab
commit
665549e1bc
164
dialects/oci8/README.md
Normal file
164
dialects/oci8/README.md
Normal file
@ -0,0 +1,164 @@
|
||||
# oci8 dialect
|
||||
|
||||
- [oci8 dialect](#oci8-dialect)
|
||||
- [Overview](#overview)
|
||||
- [Install oracle client (required by go module)](#install-oracle-client-required-by-go-module)
|
||||
- [Install the Module](#install-the-module)
|
||||
- [Basic Test](#basic-test)
|
||||
- [Running Oracle in Docker](#running-oracle-in-docker)
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
This document covers everything you need to install/configure/run to get the oci8 dialect up and running.
|
||||
|
||||
You'll find some additional documentation on various challenges and design decisions for the dialect in [doc.go](./doc.go)
|
||||
|
||||
## Install oracle client (required by go module)
|
||||
|
||||
Download instaclients from: https://www.oracle.com/database/technologies/instant-client/macos-intel-x86-downloads.html
|
||||
|
||||
You need the basic, sqlplus and sdk packages.
|
||||
|
||||
Move the zip instaclient files to `~/Library/Caches/Homebrew`
|
||||
|
||||
Install the clients with brew
|
||||
|
||||
```
|
||||
$ brew tap InstantClientTap/instantclient
|
||||
$ brew install instantclient-basic
|
||||
$ brew install instantclient-sqlplus
|
||||
$ brew install instantclient-sdk
|
||||
```
|
||||
|
||||
## Install the Module
|
||||
|
||||
```
|
||||
go get github.com/mattn/go-oci8
|
||||
```
|
||||
|
||||
Install pkg-config via brew
|
||||
|
||||
```
|
||||
$ brew install pkg-config
|
||||
```
|
||||
|
||||
Create `/usr/local/lib/pkgconfig/oci8.pc`
|
||||
Contents:
|
||||
```
|
||||
prefixdir=/usr/local/lib
|
||||
libdir=${prefixdir}
|
||||
includedir=${prefixdir}/sdk/include
|
||||
|
||||
Name: OCI
|
||||
Description: Oracle database driver
|
||||
Version: 12.2
|
||||
Libs: -L${libdir} -lclntsh
|
||||
Cflags: -I${includedir}%
|
||||
```
|
||||
|
||||
Test pkg-config for oci8
|
||||
```
|
||||
$ pkg-config --cflags --libs oci8
|
||||
-I/usr/local/lib/sdk/include -L/usr/local/lib -lclntsh
|
||||
```
|
||||
|
||||
### Basic Test
|
||||
|
||||
Once you've got Oracle up and running and you've created the gorm user with appropriate privs, try to run:
|
||||
```
|
||||
# chdir to the oci8 dialect's directory:
|
||||
$ cd dialect/oci8
|
||||
|
||||
# run a basic connection test
|
||||
$ go test -v -run Test_Connection
|
||||
=== RUN Test_Connection
|
||||
--- PASS: Test_Connection (0.06s)
|
||||
connection_test.go:29: The date is: 2020-02-14T20:09:37Z
|
||||
PASS
|
||||
ok github.com/jinzhu/gorm/dialects/oci8 1.609s
|
||||
```
|
||||
|
||||
## Running Oracle in Docker
|
||||
|
||||
Download the Oracle Express Edition version 18c (xe) Linux rpm from oracle.com
|
||||
|
||||
```
|
||||
git clone https://github.com/oracle/docker-images.git
|
||||
```
|
||||
|
||||
copy binary you downloaded
|
||||
```
|
||||
cp ~/Dowloads/<image-name> ./18.4.0
|
||||
```
|
||||
build image
|
||||
```
|
||||
./buildDockerImage.sh -x -v 18.4.0
|
||||
```
|
||||
start container
|
||||
```
|
||||
docker run -dit --name oracledb \
|
||||
-p 1521:1521 -p 5500:5500 -p 8080:8080 \
|
||||
-e ORACLE_PWD=oracle \
|
||||
-v $HOME/oracle/oradata:/opt/oracle/oradata \
|
||||
oracle/database:18.4.0-xe
|
||||
```
|
||||
|
||||
Check logs and wait for oracle to be ready…
|
||||
```
|
||||
❯ docker logs -f oracledb
|
||||
The Oracle base remains unchanged with value /opt/oracle
|
||||
#########################
|
||||
DATABASE IS READY TO USE!
|
||||
#########################
|
||||
```
|
||||
|
||||
Connect via sqlplus as sysdba via container
|
||||
```
|
||||
❯ docker exec -it oracledb sqlplus sys/oracle@localhost:1521/XE as sysdba
|
||||
|
||||
SQL*Plus: Release 18.0.0.0.0 - Production on Mon Feb 10 16:33:44 2020
|
||||
Version 18.4.0.0.0
|
||||
|
||||
Copyright (c) 1982, 2018, Oracle. All rights reserved.
|
||||
|
||||
|
||||
Connected to:
|
||||
Oracle Database 18c Express Edition Release 18.0.0.0.0 - Production
|
||||
Version 18.4.0.0.0
|
||||
|
||||
SQL>
|
||||
```
|
||||
|
||||
Connect via sqlplus as system user via container:
|
||||
```
|
||||
docker exec -it oracledb sqlplus system/oracle@localhost:1521/XE
|
||||
|
||||
SQL*Plus: Release 18.0.0.0.0 - Production on Mon Feb 10 17:08:04 2020
|
||||
Version 18.4.0.0.0
|
||||
|
||||
Copyright (c) 1982, 2018, Oracle. All rights reserved.
|
||||
|
||||
Last Successful login time: Mon Feb 10 2020 17:07:07 +00:00
|
||||
|
||||
Connected to:
|
||||
Oracle Database 18c Express Edition Release 18.0.0.0.0 - Production
|
||||
Version 18.4.0.0.0
|
||||
|
||||
SQL>
|
||||
```
|
||||
|
||||
create a gorm user
|
||||
```
|
||||
docker exec -it oracledb sqlplus system/oracle@localhost:1521/XE
|
||||
|
||||
SQL>
|
||||
-- creating user in the default PDB
|
||||
ALTER SESSION SET CONTAINER = XEPDB1;
|
||||
create user gorm identified by gorm;
|
||||
-- we need some privs
|
||||
GRANT CONNECT, RESOURCE, DBA TO gorm;
|
||||
GRANT CREATE SESSION TO gorm;
|
||||
GRANT UNLIMITED TABLESPACE TO gorm;
|
||||
```
|
||||
|
||||
48
dialects/oci8/doc.go
Normal file
48
dialects/oci8/doc.go
Normal file
@ -0,0 +1,48 @@
|
||||
package oci8
|
||||
|
||||
/*
|
||||
|
||||
Understanding Oracle
|
||||
|
||||
It's a bit different than the other RDBMS databases and I'll just try to
|
||||
hightlight a few of the important ones the dialect has to deal with:
|
||||
|
||||
1. Oracle upper cases all non-quoted identifiers. That means the dialect
|
||||
has to decide what to do:
|
||||
1. quote all identifiers which would require developers to quote every
|
||||
identifer they passed in a string to gorm.
|
||||
2. only quote identifers that conflict with reserved words and leave all
|
||||
other identifiers unquoted, which means Oracle will automatically
|
||||
upper case them. This would allow developers to pass unquoted
|
||||
identifiers in strings they passed to gorm and make the experience
|
||||
align better with the other dialects.
|
||||
We chose option #2.
|
||||
|
||||
This design decision has the following side affects:
|
||||
a. you must be case insensitive when matching column names, like in
|
||||
the Scope.scan function
|
||||
b. Devs will have to escape reserved words when they reference them
|
||||
in things like: First(&CreditCard{}, `"number" = ?`)
|
||||
|
||||
|
||||
2. Oracle handles last inserted id a bit differently, and requires a sql.Out
|
||||
parameter to return the value. Since Oracle parameters are positional, you
|
||||
need to know how many other bind variables there are before adding the returning
|
||||
clause. (see createCallback() )
|
||||
|
||||
3. Oracle doesn't let you specify "AS <tablename> " when selecting a count
|
||||
from a dynamic table, so you just omit it. (see Scope.count() )
|
||||
|
||||
4. Oracle handles foreign keys a bit differently:
|
||||
A. REFERENCES is implicit
|
||||
B. ON UPDATE is not supported
|
||||
(see scope.addForeignKey() )
|
||||
|
||||
5. Searching a blob requires using a function from the dbms_lob package like
|
||||
instr() and specifying the offset and number of matches.
|
||||
(see oci8.SearchBlob() )
|
||||
|
||||
6 Trailing semicolons are not allowed at the end of Oracle sql statements
|
||||
(so they were removed in the unit tests)
|
||||
|
||||
*/
|
||||
Loading…
x
Reference in New Issue
Block a user