The instructions on this page are outdated. Use the to convert an Oracle schema into a compatible CockroachDB schema, and a tool such as or to migrate data from Oracle to CockroachDB.
- Swingbench OrderEntry data set, which is based on the
oeschema that ships with Oracle Database 11g and Oracle Database 12c. - Oracle Data Pump, which enables the movement of data and metadata from one database to another, and comes with all Oracle installations.
- SQL*Plus, the interactive and batch query tool that comes with every Oracle Database installation.
Step 1. Export the Oracle schema
Using Oracle’s Data Pump Export utility, export the schema:oracle_example.dmp).
Step 2. Convert the Oracle schema to SQL
Using Oracle’s Data Pump Import utility, load the exported DMP file to convert it to a SQL file:Step 3. Export table data
You need to extract each table’s data into a data list file (.lst). We wrote a simple SQL script (spool.sql) to do this:
In the example SQL script,
| is used as a delimiter. Choose a delimiter that will not also occur in the rows themselves. For more information, see ..lst) with leading and trailing spaces is created for each table.
Exit SQL*Plus:
Step 4. Configure and convert the table data to CSV
Each table’s data list file needs to be converted to CSV and formatted for CockroachDB. We wrote a simple Python script (fix-example.py) to do this:
CSV requirements
You will need to export one CSV file per table, with the following requirements:- Files must be in valid CSV format.
- Files must be UTF-8 encoded.
- If one of the following characters appears in a field, the field must be enclosed by double quotes:
- delimiter (
,by default) - double quote (
") - newline (
\n) - carriage return (
\r)
- delimiter (
- If double quotes are used to enclose fields, then a double quote appearing inside a field must be escaped by preceding it with another double quote. For example:
"aaa","b""bb","ccc" - If a column is of type , it can either be a valid UTF-8 string or a beginning with
\x. For example, a field whose value should be the bytes1,2would be written as\x0102.
CSV configuration options
The following options are available to :Step 5. Compress the CSV files
Compress the CSV files for a faster import:Step 6. Host the files where the cluster can access them
Each node in the CockroachDB cluster needs to have access to the files being imported. There are several ways for the cluster to access the data; for more information on the types of storage can pull from, see the following:Step 7. Map Oracle to CockroachDB data types
Using the SQL file created in Step 2, write statements that match the schemas of the table data you’re importing. Remove all Oracle-specific attributes and remap all Oracle data types. For example, to create aCUSTOMERS table, issue the following statement in the CockroachDB SQL shell:
Data type mapping
Use the table below for data type mappings:- 1
BLOBSandCLOBSshould be converted to , or where the size is variable, but it’s recommended to keep values under 1 MB to ensure performance. Anything above 1 MB would require refactoring into an object store with a pointer embedded in the table in place of the object. - 2
JSONandXMLtypes can be converted to using any XML to JSON conversion.XMLmust be converted toJSONBbefore importing into CockroachDB. - 3 When converting
NUMBER(p,0), considerNUMBERtypes with Base-10 limits map to the Base-10 Limits for CockroachDB types. Optionally,NUMBERScan be converted to .
- If columns are used only for payload, consider switching to .
- Max size of a single (by default, the ).
NULLs
For information on how CockroachDB handlesNULLs, see and .
Primary key, constraints, and secondary indexes
Cockroach distributes a table by the or by a defaultROWID when a primary key is not provided. This also requires the primary key creation to be part of the table creation. Using the above data type mapping, refactor each table DDL to include the , , and .
For more information and examples, refer to the following:
Privileges for users and roles
The Oracle privileges for and must be rewritten for CockroachDB. Once the CockroachDB cluster is , CockroachDB follows the same methodology as Oracle.Step 8. Import the CSV
Use to import data into each table created in Step 7. For example, to import the data fromCUSTOMERS.csv.gz into an existing CUSTOMERS table, issue the following statement in the CockroachDB SQL shell:
Step 9. Refactor application SQL
The last phase of the migration process is to change the transactional behavior and SQL dialect of your application.Transactions, locking, and concurrency control
Both Oracle and CockroachDB support , which are atomic and guarantee ACID semantics. However, CockroachDB operates under isolation by default, while Oracle defaults to , which can create both when a transaction reads data twice. It is typical that Oracle developers will useSELECT FOR UPDATE to work around READ COMMITTED concurrency anomalies. Both the isolation level and the statement are supported in CockroachDB.
Regarding locks, Cockroach utilizes a to serialize access to common keys across concurrent transactions. Oracle and CockroachDB transaction control flows only have a few minor differences; for more details, refer to .
Because CockroachDB does not allow serializable anomalies under SERIALIZABLE isolation, may experience deadlocks or . This is expected during concurrency on the same keys. These can be addressed with either or .
SQL dialect
Cockroach is ANSI SQL compliant with a PostgreSQL dialect, which allows you to use to connect applications and ORMs to CockroachDB. CockroachDB’s supports full relational schema and SQL (similar to Oracle). You will have to refactor Oracle SQL and functions that do not comply with ANSI SQL-92 in order to work with CockroachDB. For more information about the and a , see below:-
DUALtable Oracle requires use of theDUALtable, as Oracle requires aSELECT ... FROM. In CockroachDB, all reference to theDUALtable should be eliminated. - See also:
-
CockroachDB supports , , and joins. Oracle uses the
+operator forLEFTandRIGHTjoins, but CockroachDB uses the ANSI join syntax. -
Sequences in CockroachDB do not require a trigger to self-increment; place the sequence in the table DDL:
-
SYSDATECockroachDB does not supportSYSDATE; however, it does support date and time with the following:

