← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to contrib/oracle/README.ora2pg

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

Lines of Context:
contrib/oracle/README.ora2pg
 
1
NAME
 
2
    Ora2Pg - Oracle to PostgreSQL database schema converter
 
3
 
 
4
SYNOPSIS
 
5
            BEGIN {
 
6
                    $ENV{ORACLE_HOME} = '/usr/local/oracle/oracle816';
 
7
            }
 
8
 
 
9
            use strict;
 
10
 
 
11
            use Ora2Pg;
 
12
 
 
13
            # Init the database connection
 
14
            my $dbsrc = 'dbi:Oracle:host=testdb.samse.fr;sid=TEST;port=1521';
 
15
            my $dbuser = 'system';
 
16
            my $dbpwd = 'manager';
 
17
 
 
18
            # Create an instance of the Ora2Pg perl module
 
19
            my $schema = new Ora2Pg (
 
20
                    datasource => $dbsrc,           # Database DBD datasource
 
21
                    user => $dbuser,                # Database user
 
22
                    password => $dbpwd,             # Database password
 
23
                    {
 
24
                            PrintError => 0,
 
25
                            RaiseError => 1,
 
26
                            AutoCommit => 0
 
27
                    }
 
28
            );
 
29
 
 
30
            # Create the POSTGRESQL representation of all objects in the database
 
31
            $schema->export_schema("output.sql");
 
32
 
 
33
            exit(0);
 
34
 
 
35
    or if you only want to extract some tables:
 
36
 
 
37
            # Create an instance of the Ora2Pg perl module
 
38
            my @tables = ('tab1', 'tab2', 'tab3');
 
39
            my $schema = new Ora2Pg (
 
40
                    datasource => $dbsrc,           # Database DBD datasource
 
41
                    user => $dbuser,                # Database user
 
42
                    password => $dbpwd,             # Database password
 
43
                    tables => \@tables,
 
44
            or                                      # Tables to extract
 
45
                    tables => [('tab1','tab2')],
 
46
                    debug => 1                      # To show somethings when running
 
47
            );
 
48
 
 
49
    or if you only want to extract the 10 first tables:
 
50
 
 
51
            # Create an instance of the Ora2Pg perl module
 
52
            my $schema = new Ora2Pg (
 
53
                    datasource => $dbsrc,           # Database DBD datasource
 
54
                    user => $dbuser,                # Database user
 
55
                    password => $dbpwd,             # Database password
 
56
                    max => 10                       # 10 first tables to extract
 
57
            );
 
58
 
 
59
    or if you only want to extract tables 10 to 20:
 
60
 
 
61
            # Create an instance of the Ora2Pg perl module
 
62
            my $schema = new Ora2Pg (
 
63
                    datasource => $dbsrc,           # Database DBD datasource
 
64
                    user => $dbuser,                # Database user
 
65
                    password => $dbpwd,             # Database password
 
66
                    min => 10,                      # Begin extraction at indice 10
 
67
                    max => 20                       # End extraction at indice 20
 
68
            );
 
69
 
 
70
    To choose a particular Oracle schema to export just set the following
 
71
    option to your schema name:
 
72
 
 
73
            schema => 'APPS'
 
74
 
 
75
    This schema definition can also be needed when you want to export data.
 
76
    If export failed and complain that the table doesn't exists use this to
 
77
    prefix the table name by the schema name.
 
78
 
 
79
    If you want to use PostgreSQL 7.3 schema support activate the init
 
80
    option 'export_schema' set to 1. Default is no schema export
 
81
 
 
82
    To know at which indices tables can be found during extraction use the
 
83
    option:
 
84
 
 
85
            showtableid => 1
 
86
 
 
87
    To extract all views set the type option as follow:
 
88
 
 
89
            type => 'VIEW'
 
90
 
 
91
    To extract all grants set the type option as follow:
 
92
 
 
93
            type => 'GRANT'
 
94
 
 
95
    To extract all sequences set the type option as follow:
 
96
 
 
97
            type => 'SEQUENCE'
 
98
 
 
99
    To extract all triggers set the type option as follow:
 
100
 
 
101
            type => 'TRIGGER'
 
102
 
 
103
    To extract all functions set the type option as follow:
 
104
 
 
105
            type => 'FUNCTION'
 
106
 
 
107
    To extract all procedures set the type option as follow:
 
108
 
 
109
            type => 'PROCEDURE'
 
110
 
 
111
    To extract all packages and body set the type option as follow:
 
112
 
 
113
            type => 'PACKAGE'
 
114
 
 
115
    Default is table extraction
 
116
 
 
117
            type => 'TABLE'
 
118
 
 
119
    To extract all data from table extraction as INSERT statement use:
 
120
 
 
121
            type => 'DATA'
 
122
 
 
123
    To extract all data from table extraction as COPY statement use:
 
124
 
 
125
            type => 'COPY'
 
126
 
 
127
    and data_limit => n to specify the max tuples to return. If you set this
 
128
    options to 0 or nothing, no limitation are used. Additional option
 
129
    'table', 'min' and 'max' can also be used.
 
130
 
 
131
    When use of COPY or DATA you can export data by calling method:
 
132
 
 
133
    $schema->export_data("output.sql");
 
134
 
 
135
    Data are dumped to the given filename or to STDOUT with no argument. You
 
136
    can also send these data directly to a PostgreSQL backend using the
 
137
    following method:
 
138
 
 
139
    $schema->send_to_pgdb($destdatasrc,$destuser,$destpasswd);
 
140
 
 
141
    In this case you must call export_data() without argument after the call
 
142
    to method send_to_pgdb().
 
143
 
 
144
    If you set type to COPY and you want to dump data directly to a PG
 
145
    database, you must call method send_to_pgdb but data will not be sent
 
146
    via DBD::Pg but they will be load to the database using the psql
 
147
    command. Calling this method is istill required to be able to extract
 
148
    database name, hostname and port information. Edit the $PSQL variable to
 
149
    match the path of your psql command (nothing to edit if psql is in your
 
150
    path).
 
151
 
 
152
DESCRIPTION
 
153
    Ora2Pg is a perl OO module used to export an Oracle database schema to a
 
154
    PostgreSQL compatible schema.
 
155
 
 
156
    It simply connect to your Oracle database, extract its structure and
 
157
    generate a SQL script that you can load into your PostgreSQL database.
 
158
 
 
159
    I'm not a Oracle DBA so I don't really know something about its internal
 
160
    structure so you may find some incorrect things. Please tell me what is
 
161
    wrong and what can be better.
 
162
 
 
163
    It currently dump the database schema (tables, views, sequences,
 
164
    indexes, grants), with primary, unique and foreign keys into PostgreSQL
 
165
    syntax without editing the SQL code generated.
 
166
 
 
167
    It now can dump Oracle data into PostgreSQL DB as online process. You
 
168
    can choose what columns can be exported for each table.
 
169
 
 
170
    Functions, procedures and triggers PL/SQL code generated must be
 
171
    reviewed to match the PostgreSQL syntax. Some usefull recommandation on
 
172
    porting Oracle to PostgreSQL can be found at
 
173
    http://techdocs.postgresql.org/ under the "Converting from other
 
174
    Databases to PostgreSQL" Oracle part. I just notice one thing more is
 
175
    that the trunc() function in Oracle is the same for number or date so be
 
176
    carefull when porting to PostgreSQL to use trunc() for number and
 
177
    date_trunc() for date.
 
178
 
 
179
ABSTRACT
 
180
    The goal of the Ora2Pg perl module is to cover all part needed to export
 
181
    an Oracle database to a PostgreSQL database without other thing that
 
182
    provide the connection parameters to the Oracle database.
 
183
 
 
184
    Features must include:
 
185
 
 
186
            - Database schema export (tables, views, sequences, indexes),
 
187
              with unique, primary and foreign key.
 
188
            - Grants/privileges export by user and group.
 
189
            - Table selection (by name and max table) export.
 
190
            - Export Oracle schema to PostgreSQL 7.3 schema.
 
191
            - Predefined functions/triggers/procedures/packages export.
 
192
            - Data export.
 
193
            - Sql query converter (todo)
 
194
 
 
195
    My knowledge regarding database is really poor especially for Oracle so
 
196
    contribution is welcome.
 
197
 
 
198
REQUIREMENT
 
199
    You just need the DBI, DBD::Pg and DBD::Oracle perl module to be
 
200
    installed
 
201
 
 
202
PUBLIC METHODS
 
203
  new HASH_OPTIONS
 
204
 
 
205
    Creates a new Ora2Pg object.
 
206
 
 
207
    Supported options are:
 
208
 
 
209
            - datasource    : DBD datasource (required)
 
210
            - user          : DBD user (optional with public access)
 
211
            - password      : DBD password (optional with public access)
 
212
            - schema        : Oracle internal schema to extract
 
213
            - type          : Type of data to extract, can be TABLE,VIEW,GRANT,SEQUENCE,
 
214
                              TRIGGER,FUNCTION,PROCEDURE,DATA,COPY,PACKAGE
 
215
            - debug         : Print the current state of the parsing
 
216
            - export_schema : Export Oracle schema to PostgreSQL 7.3 schema
 
217
            - tables        : Extract only the given tables (arrayref)
 
218
            - showtableid   : Display only the table indice during extraction
 
219
            - min           : Indice to begin extraction. Default to 0
 
220
            - max           : Indice to end extraction. Default to 0 mean no limits
 
221
            - data_limit    : Number max of tuples to return during data extraction (default 0 no limit)
 
222
 
 
223
    Attempt that this list should grow a little more because all
 
224
    initialization is done by this way.
 
225
 
 
226
  export_data FILENAME
 
227
 
 
228
    Print SQL data output to a filename or to STDOUT if no file is given.
 
229
 
 
230
    Must be used only if type option is set to DATA or COPY =cut
 
231
 
 
232
    sub export_data { my ($self, $outfile) = @_;
 
233
 
 
234
            $self->_get_sql_data($outfile);
 
235
    }
 
236
 
 
237
  export_sql FILENAME
 
238
 
 
239
    Print SQL conversion output to a filename or simply return these data if
 
240
    no file is given.
 
241
 
 
242
  send_to_pgdb DEST_DATASRC DEST_USER DEST_PASSWD
 
243
 
 
244
    Open a DB handle to a PostgreSQL database
 
245
 
 
246
  modify_struct TABLE_NAME ARRAYOF_FIELDNAME
 
247
 
 
248
    Modify a table structure during export. Only given fieldname will be
 
249
    exported.
 
250
 
 
251
PRIVATE METHODS
 
252
  _init HASH_OPTIONS
 
253
 
 
254
    Initialize a Ora2Pg object instance with a connexion to the Oracle
 
255
    database.
 
256
 
 
257
  _grants
 
258
 
 
259
    This function is used to retrieve all privilege information.
 
260
 
 
261
    It extract all Oracle's ROLES to convert them as Postgres groups and
 
262
    search all users associated to these roles.
 
263
 
 
264
    Set the main hash $self->{groups}. Set the main hash $self->{grantss}.
 
265
 
 
266
  _sequences
 
267
 
 
268
    This function is used to retrieve all sequences information.
 
269
 
 
270
    Set the main hash $self->{sequences}.
 
271
 
 
272
  _triggers
 
273
 
 
274
    This function is used to retrieve all triggers information.
 
275
 
 
276
    Set the main hash $self->{triggers}.
 
277
 
 
278
  _functions
 
279
 
 
280
    This function is used to retrieve all functions information.
 
281
 
 
282
    Set the main hash $self->{functions}.
 
283
 
 
284
  _packages
 
285
 
 
286
    This function is used to retrieve all packages information.
 
287
 
 
288
    Set the main hash $self->{packages}.
 
289
 
 
290
  _tables
 
291
 
 
292
    This function is used to retrieve all table information.
 
293
 
 
294
    Set the main hash of the database structure $self->{tables}. Keys are
 
295
    the names of all tables retrieved from the current database. Each table
 
296
    information compose an array associated to the table_info key as array
 
297
    reference. In other way:
 
298
 
 
299
        $self->{tables}{$class_name}{table_info} = [(OWNER,TYPE)];
 
300
 
 
301
    DBI TYPE can be TABLE, VIEW, SYSTEM TABLE, GLOBAL TEMPORARY, LOCAL
 
302
    TEMPORARY, ALIAS, SYNONYM or a data source specific type identifier.
 
303
    This only extract TABLE type.
 
304
 
 
305
    It also get the following informations in the DBI object to affect the
 
306
    main hash of the database structure :
 
307
 
 
308
        $self->{tables}{$class_name}{field_name} = $sth->{NAME};
 
309
        $self->{tables}{$class_name}{field_type} = $sth->{TYPE};
 
310
 
 
311
    It also call these other private subroutine to affect the main hash of
 
312
    the database structure :
 
313
 
 
314
        @{$self->{tables}{$class_name}{column_info}} = $self->_column_info($class_name, $owner);
 
315
        @{$self->{tables}{$class_name}{primary_key}} = $self->_primary_key($class_name, $owner);
 
316
        @{$self->{tables}{$class_name}{unique_key}}  = $self->_unique_key($class_name, $owner);
 
317
        @{$self->{tables}{$class_name}{foreign_key}} = $self->_foreign_key($class_name, $owner);
 
318
 
 
319
  _views
 
320
 
 
321
    This function is used to retrieve all views information.
 
322
 
 
323
    Set the main hash of the views definition $self->{views}. Keys are the
 
324
    names of all views retrieved from the current database values are the
 
325
    text definition of the views.
 
326
 
 
327
    It then set the main hash as follow:
 
328
 
 
329
        # Definition of the view
 
330
        $self->{views}{$table}{text} = $view_infos{$table};
 
331
 
 
332
  _get_sql_data
 
333
 
 
334
    Returns a string containing the entire SQL Schema definition compatible
 
335
    with PostgreSQL
 
336
 
 
337
  _get_data TABLE
 
338
 
 
339
    This function implements a Oracle-native data extraction.
 
340
 
 
341
    Return a list of array reference containing the data
 
342
 
 
343
  _sql_type INTERNAL_TYPE LENGTH PRECISION SCALE
 
344
 
 
345
    This function return the PostgreSQL datatype corresponding to the Oracle
 
346
    internal type.
 
347
 
 
348
  _column_info TABLE OWNER
 
349
 
 
350
    This function implements a Oracle-native column information.
 
351
 
 
352
    Return a list of array reference containing the following informations
 
353
    for each column the given a table
 
354
 
 
355
    [( column name, column type, column length, nullable column, default
 
356
    value )]
 
357
 
 
358
  _primary_key TABLE OWNER
 
359
 
 
360
    This function implements a Oracle-native primary key column information.
 
361
 
 
362
    Return a list of all column name defined as primary key for the given
 
363
    table.
 
364
 
 
365
  _unique_key TABLE OWNER
 
366
 
 
367
    This function implements a Oracle-native unique key column information.
 
368
 
 
369
    Return a list of all column name defined as unique key for the given
 
370
    table.
 
371
 
 
372
  _foreign_key TABLE OWNER
 
373
 
 
374
    This function implements a Oracle-native foreign key reference
 
375
    information.
 
376
 
 
377
    Return a list of hash of hash of array reference. Ouuf! Nothing very
 
378
    difficult. The first hash is composed of all foreign key name. The
 
379
    second hash just have two key known as 'local' and remote' corresponding
 
380
    to the local table where the foreign key is defined and the remote table
 
381
    where the key refer.
 
382
 
 
383
    The foreign key name is composed as follow:
 
384
 
 
385
        'local_table_name->remote_table_name'
 
386
 
 
387
    Foreign key data consist in two array representing at the same indice
 
388
    the local field and the remote field where the first one refer to the
 
389
    second. Just like this:
 
390
 
 
391
        @{$link{$fkey_name}{local}} = @local_columns;
 
392
        @{$link{$fkey_name}{remote}} = @remote_columns;
 
393
 
 
394
  _get_users
 
395
 
 
396
    This function implements a Oracle-native users information.
 
397
 
 
398
    Return a hash of all users as an array.
 
399
 
 
400
  _get_roles
 
401
 
 
402
    This function implements a Oracle-native roles information.
 
403
 
 
404
    Return a hash of all groups (roles) as an array of associated users.
 
405
 
 
406
  _get_all_grants
 
407
 
 
408
    This function implements a Oracle-native user privilege information.
 
409
 
 
410
    Return a hash of all tables grants as an array of associated users.
 
411
 
 
412
  _get_indexes TABLE OWNER
 
413
 
 
414
    This function implements a Oracle-native indexes information.
 
415
 
 
416
    Return hash of array containing all unique index and a hash of array of
 
417
    all indexes name which are not primary keys for the given table.
 
418
 
 
419
  _get_sequences
 
420
 
 
421
    This function implements a Oracle-native sequences information.
 
422
 
 
423
    Return a hash of array of sequence name with MIN_VALUE, MAX_VALUE,
 
424
    INCREMENT and LAST_NUMBER for the given table.
 
425
 
 
426
  _get_views
 
427
 
 
428
    This function implements a Oracle-native views information.
 
429
 
 
430
    Return a hash of view name with the SQL query it is based on.
 
431
 
 
432
  _alias_info
 
433
 
 
434
    This function implements a Oracle-native column information.
 
435
 
 
436
    Return a list of array reference containing the following informations
 
437
    for each alias of the given view
 
438
 
 
439
    [( column name, column id )]
 
440
 
 
441
  _get_triggers
 
442
 
 
443
    This function implements a Oracle-native triggers information.
 
444
 
 
445
    Return an array of refarray of all triggers informations
 
446
 
 
447
  _get_functions
 
448
 
 
449
    This function implements a Oracle-native functions information.
 
450
 
 
451
    Return a hash of all function name with their PLSQL code
 
452
 
 
453
  _get_packages
 
454
 
 
455
    This function implements a Oracle-native packages information.
 
456
 
 
457
    Return a hash of all function name with their PLSQL code
 
458
 
 
459
  _table_info
 
460
 
 
461
    This function retrieve all Oracle-native tables information.
 
462
 
 
463
    Return a handle to a DB query statement
 
464
 
 
465
AUTHOR
 
466
    Gilles Darold <gilles@darold.net>
 
467
 
 
468
COPYRIGHT
 
469
    Copyright (c) 2001 Gilles Darold - All rights reserved.
 
470
 
 
471
    This program is free software; you can redistribute it and/or modify it
 
472
    under the same terms as Perl itself.
 
473
 
 
474
BUGS
 
475
    This perl module is in the same state as my knowledge regarding
 
476
    database, it can move and not be compatible with older version so I will
 
477
    do my best to give you official support for Ora2Pg. Your volontee to
 
478
    help construct it and your contribution are welcome.
 
479
 
 
480
SEE ALSO
 
481
    the DBI manpage, the DBD::Oracle manpage, the DBD::Pg manpage
 
482
 
 
483
ACKNOWLEDGEMENTS
 
484
    Thanks to Jason Servetar who decided me to implement data extraction.
 
485