ODB Compiler Manual

source: http://www.codesynthesis.com/products/odb/doc/odb.xhtml

  


  NAME


  odb - object-relational mapping (ORM) compiler for C++


  SYNOPSIS


  
    odb [options] file [file...]
  


  DESCRIPTION


  Given a set of C++ classes in a header file, odb
  generates C++ code that allows you to persist, query, and update objects
  of these classes in a relational database (RDBMS). The relational
  database that the generated code should target is specified with the
  required --database option (see below).


  For an input file in the form name.hxx (other
  file extensions can be used instead of .hxx),
  in the single-database mode (the default), the generated C++ files
  by default have the following names:
  name-odb.hxx (header file),
  name-odb.ixx (inline file), and
  name-odb.cxx (source file).


  Additionally, if the --generate-schema option is
  specified and the sql schema format is requested (see
  --schema-format), the name.sql
  database schema file is generated. If the separate
  schema format is requested, the database creation code is generated
  into the separate name-schema.cxx file.


  In the multi-database mode (see the --multi-database
     option below), the generated files corresponding to the
     common database have the same names as in the
     single-database mode. For other databases, the file names include
     the database name:
     name-odb-db.hxx,
     name-odb-db.ixx,
     name-odb-db.cxx,
     name-db.sql, and
     name-schema-db.cxx
     (where db is the database name).


  OPTIONS








  --help
  Print usage information and exit.


  --version
  Print version and exit.


  -I dir
  Add dir to the beginning of the list of directories to be searched
  for included header files.


  -D name[=def]
  Define macro name with definition def. If definition is
  omitted, define name to be 1.


  -U name
  Cancel any previous definitions of macro name, either built-in or
  provided with the -D option.


  --database|-d db
  Generate code for the db database. Valid values are
  mssql, mysql,
  oracle, pgsql,
  sqlite, and common (multi-database
  mode only).


  --multi-database|-m type
  Enable multi-database support and specify its type. Valid values for this
  option are static and dynamic.


  In the multi-database mode, options that determine the kind (for example,
  --schema-format), names (for example,
  --odb-file-suffix), or content (for example, prologue
  and epilogue options) of the output files can be prefixed with the database
  name followed by a colon, for example, mysql:value. This
  restricts the value of such an option to only apply to generated files
  corresponding to this database.


  --default-database db
  When static multi-database support is used, specify the database that should
  be made the default. When dynamic multi-database support is used,
  common is always made the default database.


  --generate-query|-q
  Generate query support code. Without this support you cannot use views and
  can only load objects via their ids.


  --generate-prepared
  Generate prepared query execution support code.


  --omit-unprepared
  Omit un-prepared (once-off) query execution support code.


  --generate-session|-e
  Generate session support code. With this option session support will be
  enabled by default for all the persistent classes except those for which it
  was explicitly disabled using the db session pragma.


  --generate-schema|-s
  Generate the database schema. The database schema contains SQL statements
  that create database tables necessary to store persistent classes defined in
  the file being compiled. Note that by applying this schema, all the existing
  information stored in such tables will be lost.


  Depending on the database being used (--database
  option), the schema is generated either as a standalone SQL file or embedded
  into the generated C++ code. By default the SQL file is generated for the
  MySQL, PostgreSQL, Oracle, and Microsoft SQL Server databases and the schema
  is embedded into the C++ code for the SQLite database. Use the
  --schema-format option to alter the default schema
  format.


  --generate-schema-only
  Generate only the database schema. Note that this option is only valid when
  generating schema as a standalone SQL file (see
  --schema-format for details).


  --schema-format format
  Generate the database schema in the specified format. Pass
  sql as format to generate the database schema as
  a standalone SQL file or pass embedded to embed the
  schema into the generated C++ code. The separate value
  is similar to embedded except the schema creation code
  is generated into a separate C++ file (name-schema.cxx
  by default). This value is primarily useful if you want to place the schema
  creation functionality into a separate program or library. Repeat this
  option to generate the same database schema in multiple formats.


  --omit-drop
  Omit DROP statements from the generated database schema.


  --omit-create
  Omit CREATE statements from the generated database
  schema.


  --schema-name name
  Use name as the database schema name. Schema names are primarily used
  to distinguish between multiple embedded schemas in the schema catalog. They
  are not to be confused with database schemas (database namespaces) which are
  specified with the --schema option. If this option is
  not specified, the empty name, which is the default schema name, is used.


  --default-pointer ptr
  Use ptr as the default pointer for persistent objects and views.
  Objects and views that do not have a pointer assigned with the db
  pointer pragma will use this pointer by default. The value of
  this option can be * which denotes the raw pointer and
  is the default, or qualified name of a smart pointer class template, for
  example, std::auto_ptr. In the latter case, the ODB
  compiler constructs the object or view pointer by adding a single template
  argument of the object or view type to the qualified name, for example
  std::auto_ptr<object>. The ODB runtime uses object
  and view pointers to return, and, in case of objects, pass and cache
  dynamically allocated instances of object and view types.


  Except for the raw pointer and the standard smart pointers defined in the
  <memory> header file, you are expected to include the
  definition of the default pointer at the beginning of the generated header
  file. There are two common ways to achieve this: you can either include the
  necessary header in the file being compiled or you can use the
  --hxx-prologue option to add the necessary
  #include directive to the generated code.


  --session-type type
  Use type as the alternative session type instead of the default
  odb::session. This option can be used to specify a
  custom session implementation to be use by the persistent classes. Note that
  you will also need to include the definition of the custom session type into
  the generated header file. This is normally achieved with the
  --hxx-prologue* options.


  --profile|-p name
  Specify a profile that should be used during compilation. A profile is an
  options file. The ODB compiler first looks for a database-specific version
  with the name constructed by appending the
  -database.options
  suffix to name, where database is the database
  name as specified with the --database option. If this
  file is not found, then the ODB compiler looks for a database-independant
  version with the name constructed by appending just the
  .options suffix.


  The profile options files are searched for in the same set of directories
  as C++ headers included with the #include <...>
  directive (built-in paths plus those specified with the
  -I options). The options file is first searched for in
  the directory itself and then in its odb/
  subdirectory.


  For the format of the options file refer to the
  --options-file option below. You can repeat this option
  to specify more than one profile.


  --at-once
  Generate code for all the input files as well as for all the files that they
  include at once. The result is a single set of source/schema files that
  contain all the generated code. If more than one input file is specified
  together with this option, then the --output-name option
  must also be specified in order to provide the base name for the output
  files. In this case, the directory part of such a base name is used as the
  location of the combined file. This can be important for the
  #include directive resolution.


  --schema schema
  Specify a database schema (database namespace) that should be assigned to
  the persistent classes in the file being compiled. Database schemas are not
  to be confused with database schema names (schema catalog names) which are
  specified with the --schema-name option.


  --export-symbol symbol
  Insert symbol in places where DLL export/import control statements
  (__declspec(dllexport/dllimport)) are necessary. See
  also the --extern-symbol option below.


  --extern-symbol symbol
  If symbol is defined, insert it in places where a template
  instantiation must be declared extern. This option is
  normally used together with --export-symbol when both
  multi-database support and queries are enabled.


  --std version
  Specify the C++ standard that should be used during compilation. Valid
  values are c++98 (default) and
  c++11.


  --output-dir|-o dir
  Write the generated files to dir instead of the current directory.


  --output-name name
  Use name instead of the input file to construct the names of the
  generated files.


  --odb-file-suffix suffix
  Use suffix to construct the names of the generated C++ files. In the
  single-database mode the default value for this option is
  -odb. In the multi-database mode it is
  -odb for the files corresponding to the
  common database and -odb-db
  (where db is the database name) for other databases.


  --sql-file-suffix suffix
  Use suffix to construct the name of the generated schema SQL file. In
  the single-database mode by default no suffix is used. In the multi-database
  mode the default value for this option is -db
  (where db is the database name).


  --schema-file-suffix suffix
  Use suffix to construct the name of the generated schema C++ source
  file. In the single-database mode the default value for this option is
  -schema. In the multi-database mode it is
  -schema-db (where db is the
  database name). See the --schema-format option for
  details.


  --hxx-suffix suffix
  Use suffix instead of the default .hxx to
  construct the name of the generated C++ header file.


  --ixx-suffix suffix
  Use suffix instead of the default .ixx to
  construct the name of the generated C++ inline file.


  --cxx-suffix suffix
  Use suffix instead of the default .cxx to
  construct the name of the generated C++ source file.


  --sql-suffix suffix
  Use suffix instead of the default .sql to
  construct the name of the generated database schema file.


  --hxx-prologue text
  Insert text at the beginning of the generated C++ header file.


  --ixx-prologue text
  Insert text at the beginning of the generated C++ inline file.


  --cxx-prologue text
  Insert text at the beginning of the generated C++ source file.


  --schema-prologue text
  Insert text at the beginning of the generated schema C++ source file.


  --sql-prologue text
  Insert text at the beginning of the generated database schema file.


  --sql-interlude text
  Insert text after all the DROP and before any
  CREATE statements in the generated database schema file.


  --hxx-epilogue text
  Insert text at the end of the generated C++ header file.


  --ixx-epilogue text
  Insert text at the end of the generated C++ inline file.


  --cxx-epilogue text
  Insert text at the end of the generated C++ source file.


  --schema-epilogue text
  Insert text at the end of the generated schema C++ source file.


  --sql-epilogue text
  Insert text at the end of the generated database schema file.


  --hxx-prologue-file file
  Insert the content of file at the beginning of the generated C++
  header file.


  --ixx-prologue-file file
  Insert the content of file at the beginning of the generated C++
  inline file.


  --cxx-prologue-file file
  Insert the content of file at the beginning of the generated C++
  source file.


  --schema-prologue-file file
  Insert the content of file at the beginning of the generated schema
  C++ source file.


  --sql-prologue-file file
  Insert the content of file at the beginning of the generated database
  schema file.


  --sql-interlude-file file
  Insert the content of file after all the DROP and
  before any CREATE statements in the generated database
  schema file.


  --hxx-epilogue-file file
  Insert the content of file at the end of the generated C++ header
  file.


  --ixx-epilogue-file file
  Insert the content of file at the end of the generated C++ inline
  file.


  --cxx-epilogue-file file
  Insert the content of file at the end of the generated C++ source
  file.


  --schema-epilogue-file file
  Insert the content of file at the end of the generated schema C++
  source file.


  --sql-epilogue-file file
  Insert the content of file at the end of the generated database
  schema file.


  --odb-prologue text
  Compile text before the input header file. This option allows you to
  add additional declarations, such as custom traits specializations, to the
  ODB compilation process.


  --odb-prologue-file file
  Compile file contents before the input header file. Prologue files
  are compiled after all the prologue text fragments
  (--odb-prologue option).


  --odb-epilogue text
  Compile text after the input header file. This option allows you to
  add additional declarations, such as custom traits specializations, to the
  ODB compilation process.


  --odb-epilogue-file file
  Compile file contents after the input header file. Epilogue files are
  compiled after all the epilogue text fragments
  (--odb-epilogue option).


  --table-prefix prefix
  Add prefix to table names and, for databases that have global index
  and/or foreign key names, to those names as well. The prefix is added to
  both names that were specified with the db table and
  db index pragmas and those that were automatically
  derived from class and data member names. If you require a separator, such
  as an underscore, between the prefix and the name, then you should include
  it into the prefix value.


  --index-suffix suffix
  Use suffix instead of the default _i to construct
  index names. The suffix is only added to names that were automatically
  derived from data member names. If you require a separator, such as an
  underscore, between the name and the suffix, then you should include it into
  the suffix value.


  --fkey-suffix suffix
  Use suffix instead of the default _fk to
  construct foreign key names. If you require a separator, such as an
  underscore, between the name and the suffix, then you should include it into
  the suffix value.


  --sequence-suffix suffix
  Use suffix instead of the default _seq to
  construct sequence names. If you require a separator, such as an underscore,
  between the name and the suffix, then you should include it into the suffix
  value.


  --sql-name-case case
  Convert all automatically-derived SQL names to upper or lower case. Valid
  values for this option are  upper and
  lower.


  --table-regex regex
  Add regex to the list of regular expressions that is used to
  transform automatically-derived table names. See the SQL NAME
  TRANSFORMATIONS section below for details.


  --column-regex regex
  Add regex to the list of regular expressions that is used to
  transform automatically-derived column names. See the SQL NAME
  TRANSFORMATIONS section below for details.


  --index-regex regex
  Add regex to the list of regular expressions that is used to
  transform automatically-derived index names. See the SQL NAME
  TRANSFORMATIONS section below for details.


  --fkey-regex regex
  Add regex to the list of regular expressions that is used to
  transform automatically-derived foreign key names. See the SQL NAME
  TRANSFORMATIONS section below for details.


  --sequence-regex regex
  Add regex to the list of regular expressions that is used to
  transform automatically-derived sequence names. See the SQL NAME
  TRANSFORMATIONS section below for details.


  --sql-name-regex regex
  Add regex to the list of regular expressions that is used to
  transform all automatically-derived SQL names. See the SQL NAME
  TRANSFORMATIONS section below for details.


  --sql-name-regex-trace
  Trace the process of applying regular expressions specified with the SQL
  name --*-regex options. Use this option to find out why
  your regular expressions don't do what you expected them to do.


  --accessor-regex regex
  Add regex to the list of regular expressions used to transform data
  member names to function names when searching for a suitable accessor
  function. The argument to this option is a Perl-like regular expression in
  the form
  /pattern/replacement/. Any
  character can be used as a delimiter instead of / and
  the delimiter can be escaped inside pattern and
  replacement with a backslash (\).
  You can specify multiple regular expressions by repeating this option.


  All the regular expressions are tried in the order specified and the
  first expression that produces a suitable accessor function is used. Each
  expression is tried twice: first with the actual member name and then with
  the member's public name which is obtained by removing the common
  member name decorations, such as leading and trailing underscores, the
  m_ prefix, etc. The ODB compiler also includes a number
  of built-in expressions for commonly used accessor names, such as
  get_foo, getFoo,
  getfoo, and just foo. The built-in
  expressions are tried last.


  As an example, the following expression transforms data members with
  public names in the form foo to accessor names in the
  form GetFoo:


  /(.+)/Get\u$1/


  See also the REGEX AND SHELL QUOTING section below.


  --accessor-regex-trace
  Trace the process of applying regular expressions specified with the
  --accessor-regex option. Use this option to find out why
  your regular expressions don't do what you expected them to do.


  --modifier-regex regex
  Add regex to the list of regular expressions used to transform data
  member names to function names when searching for a suitable modifier
  function. The argument to this option is a Perl-like regular expression in
  the form
  /pattern/replacement/. Any
  character can be used as a delimiter instead of / and
  the delimiter can be escaped inside pattern and
  replacement with a backslash (\).
  You can specify multiple regular expressions by repeating this option.


  All the regular expressions are tried in the order specified and the
  first expression that produces a suitable modifier function is used. Each
  expression is tried twice: first with the actual member name and then with
  the member's public name which is obtained by removing the common
  member name decorations, such as leading and trailing underscores, the
  m_ prefix, etc. The ODB compiler also includes a number
  of built-in expressions for commonly used modifier names, such as
  set_foo, setFoo,
  setfoo, and just foo. The built-in
  expressions are tried last.


  As an example, the following expression transforms data members with
  public names in the form foo to modifier names in the
  form SetFoo:


  /(.+)/Set\u$1/


  See also the REGEX AND SHELL QUOTING section below.


  --modifier-regex-trace
  Trace the process of applying regular expressions specified with the
  --modifier-regex option. Use this option to find out why
  your regular expressions don't do what you expected them to do.


  --include-with-brackets
  Use angle brackets (<>) instead of quotes ("") in the generated
  #include directives.


  --include-prefix prefix
  Add prefix to the generated #include directive
  paths.


  --include-regex regex
  Add regex to the list of regular expressions used to transform
  generated #include directive paths. The argument to this
  option is a Perl-like regular expression in the form
  /pattern/replacement/. Any
  character can be used as a delimiter instead of / and
  the delimiter can be escaped inside pattern and
  replacement with a backslash (\).
  You can specify multiple regular expressions by repeating this option. All
  the regular expressions are tried in the order specified and the first
  expression that matches is used.


  As an example, the following expression transforms include paths in the
  form foo/bar-odb.h to paths in the form
  foo/generated/bar-odb.h:


  %foo/(.+)-odb.h%foo/generated/$1-odb.h%


  See also the REGEX AND SHELL QUOTING section below.


  --include-regex-trace
  Trace the process of applying regular expressions specified with the
  --include-regex option. Use this option to find out why
  your regular expressions don't do what you expected them to do.


  --guard-prefix prefix
  Add prefix to the generated header inclusion guards. The prefix is
  transformed to upper case and characters that are illegal in a preprocessor
  macro name are replaced with underscores.


  --show-sloc
  Print the number of generated physical source lines of code (SLOC).


  --sloc-limit num
  Check that the number of generated physical source lines of code (SLOC) does
  not exceed num.


  --options-file file
  Read additional options from file with each option appearing on a
  separate line optionally followed by space and an option value. Empty lines
  and lines starting with # are ignored. Option values can
  be enclosed in double (") or single
  (') quotes  to preserve leading and trailing whitespaces
  as well as to specify empty values. If the value itself contains trailing or
  leading quotes, enclose it with an extra pair of quotes, for example
  '"x"'. Non-leading and non-trailing quotes are
  interpreted as being part of the option value.


  The semantics of providing options in a file is equivalent to providing
  the same set of options in the same order on the command line at the point
  where the --options-file option is specified except that
  the shell escaping and quoting is not required. You can repeat this option
  to specify more than one options file.


  -x option
  Pass option to the underlying C++ compiler (g++).
  The option value that doesn't start with - is
  considered the g++ executable name.


  -v
  Print the commands executed to run the stages of compilation.


  --trace
  Trace the compilation process.


  --mssql-server-version ver
  Specify the minimum SQL Server server version with which the generated C++
  code will be used. This information is used to enable version-specific
  optimizations and workarounds in the generated C++ code. The version must be
  in the major.minor form, for example,
  9.0 (SQL Server 2005), 10.5
  (2008R2), or 11.0 (2012). If this option is not
  specified, then 10.0 (SQL Server 2008) or later is
  assumed.


  --mssql-short-limit size
  Specify the short data size limit. If a character, national character, or
  binary data type has a maximum length (in bytes) less than or equal to this
  limit, then it is treated as short data, otherwise it is long
  data. For short data ODB pre-allocates an intermediate buffer of the
  maximum size and binds it directly to a parameter or result column. This way
  the underlying API (ODBC) can read/write directly from/to this buffer. In
  the case of long data, the data is read/written in chunks using the
  SQLGetData()/SQLPutData() ODBC
  functions. While the long data approach reduces the amount of memory used by
  the application, it may require greater CPU resources. The default short
  data limit is 1024 bytes. When setting a custom short data limit, make sure
  that it is sufficiently large so that no object id in the application is
  treated as long data.


  --mysql-engine engine
  Use engine instead of the default InnoDB in the
  generated database schema file. For more information on the storage engine
  options see the MySQL documentation. If you would like to use the
  database-default engine, pass default as the value for
  this option.


  --oracle-client-version ver
  Specify the minimum Oracle client library (OCI) version with which the
  generated C++ code will be linked. This information is used to enable
  version-specific optimizations and workarounds in the generated C++ code.
  The version must be in the major.minor
  form, for example, 11.2. If this option is not
  specified, then 10.1 or later is assumed.


  --sqlite-lax-auto-id
  Do not force monotonically increasing automatically-assigned object ids. In
  this mode the generated database schema omits the
  AUTOINCREMENT keyword which results in faster object
  persistence but may lead to automatically-assigned ids not being in a
  strictly ascending order. Refer to the SQLite documentation for details.




  SQL NAME TRANSFORMATIONS


  The ODB compiler provides a number of mechanisms for transforming
     automatically-derived SQL names, such as tables, columns, etc.,
     to match a specific naming convention. At the higher level, we can
     add a prefix to global names (tables and, for some databases,
     indexes and/or foreign keys) with the --table-prefix
     option. Similarly, we can specify custom suffixes for
     automatically-derived
     index (--index-suffix; default is _i),
     foreign key (--fkey-suffix; default is _fk), and
     sequence (--sequence-suffix; default is _seq)
     names. Finally, we can also convert all the names to upper or lower
     case with the --sql-name-case option (valid values
     are upper and lower).


  At the lower level we can specify a set of regular expressions to
     implement arbitrary transformations of the automatically-derived SQL
     names. If we want a particular regular expression only to apply to
     a specific name, for example, table or column, then we use one of the
     --kind-regex options, where
     kind can be table,
     column, index,
     fkey, or sequence. On the
     other hand, if we want our regular expressions to apply to all SQL
     names, then we use the --sql-name-regex option.


  The interaction between the higher and lower level transformations
     is as follows. Prefixes and suffixes are added first. Then the
     regular expression transformations are applied. Finally, if requested,
     the name is converted to upper or lower case. Note also that all of
     these transformations except for --table-prefix
     only apply to automatically-derived names. In other words, if a table,
     column, etc., name was explicitly specified with a pragma, then it
     is used as is, without applying any (except for the table prefix)
     transformations.


  The value for the --*-regex options is a Perl-like
     regular expression in the form
     /pattern/replacement/.
     Any character can be used as a delimiter instead of /
     and the delimiter can be escaped inside pattern and
     replacement with a backslash (\).
     You can also specify multiple regular expressions by repeating these
     options.


  All the regular expressions are tried in the order specified with the
     name-specific expressions (for example, --table-regex)
     tried first followed by the generic expressions
     (--sql-name-regex). The first expression that
     matches is used.


  As an example, consider a regular expression that transforms a class
     name in the form CFoo to a table name in the
     form FOO:


  --table-regex '/C(.+)/\U$1/'


  As a more interesting example, consider the transformation of class
     names that follow the upper camel case convention (for example,
     FooBar) to table names that follow the
     underscore-separated, all upper case convention (for example,
     FOO_BAR). For this case we have to use
     separate expressions to handle one-word, two-word, etc.,
     names:


   --table-regex '/([A-z][a-z]+)/\U$1/'
   --table-regex '/([A-z][a-z]+)([A-z][a-z]+)/\U$1_$2/'


  See also the REGEX AND SHELL QUOTING section below.


  REGEX AND SHELL QUOTING


  When entering a regular expression argument in the shell
     command line it is often necessary to use quoting (enclosing
     the argument in " " or
     ' ') in order to prevent the shell
     from interpreting certain characters, for example, spaces as
     argument separators and $ as variable
     expansions.


  Unfortunately it is hard to achieve this in a manner that is
     portable across POSIX shells, such as those found on
     GNU/Linux and UNIX, and Windows shell. For example, if you
     use " " for quoting you will get a
     wrong result with POSIX shells if your expression contains
     $. The standard way of dealing with this
     on POSIX systems is to use ' ' instead.
     Unfortunately, Windows shell does not remove ' '
     from arguments when they are passed to applications. As a result you
     may have to use ' ' for POSIX and
     " " for Windows ($ is
     not treated as a special character on Windows).


  Alternatively, you can save regular expression options into
     a file, one option per line, and use this file with the
     --options-file option. With this approach
     you don't need to worry about shell quoting.


  DIAGNOSTICS


  If the input file is not valid C++, odb
     will issue diagnostic messages to STDERR and exit with non-zero exit
     code.


  BUGS


  Send bug reports to the
     odb-users@codesynthesis.com mailing list.


  
  
    © 2009-2013 Code Synthesis Tools CC


    
      Permission is granted to copy, distribute and/or modify this
      document under the terms of the
      GNU Free
      Documentation License, version 1.3; with no Invariant Sections,
      no Front-Cover Texts and no Back-Cover Texts.