Skip to content

Latest commit

 

History

History
125 lines (97 loc) · 6.52 KB

ddl2cpp.md

File metadata and controls

125 lines (97 loc) · 6.52 KB

< Index

Code generation

sqlpp23 requires C++ representations for the database tables you want interact with. You can generate these table representations using the sqlpp23-ddl2cpp script.

Generate ddl files

You need DDL files representing the tables you are interested in. Often, you would have them for you project anyway, because you need them to set up databases.

Otherwise, you can obtain them from your database backend. Here is an example of how this could look like:

mysqldump --no-data MyDatabase > MyDatabase.sql

For detailed instructions refer to the documentation of your database.

Custom data types

sqlpp23-ddl2cpp allows you to define aliases of existing data types, which can be useful if your DDL files use SQL data types that are not supported natively by sqlpp23. In this case you can create a file mapping each of the unsupported SQL data types to one of the natively supported base types and tell sqlpp23-ddl2cpp to use that file through the --path-to-custom-types command-line option (see Command-line options).

The custom types file is a CSV file in which fields can be optionally single or double-quoted. Each line starts with a base type, followed by one or more custom types that are mapped to that base type. For example:

integral, MYINT, another_int, type2
floating_point, double, "my float", fpvalue, fp_too

The base type names follow closely the data types supported by sqlpp23:

  • blob: Blob (binary large object).
  • boolean: Boolean.
  • date: Date (year + month + day of month).
  • floating_point: Floating-point.
  • integral: Integral (integer) data type. Booleans are not considered an integral type.
  • serial: Integral (integer) value with auto-increment. Always has a default value, so it cannot be NULL.
  • text: Text.
  • time: Time of day.
  • timestamp: Tmestamp (date + time).

The custom type names are case-insensitive just like the native SQL types.

Command-line options

Help

Option Required Default Description Before v0.67
-h or --help No1 Display help and exit. Same

Required parameters for code generation

Option Required Default Description Before v0.67
--path-to-ddl PATH_TO_DDL ... Yes One or more pathnames of input DDL files. First command-line argument
--namespace NAMESPACE Yes C++ namespace of the generated database model. Third command-line argument

Paths

Option Required Default Description Before v0.67
--path-to-header PATH_TO_HEADER No2 Output pathname of the generated C++ header. Second command-line argument
--path-to-header-directory PATH_TO_HEADER_DIRECTORY No2 Output Directory for the generated C++ headers Second command-line argument + -split-tables.
--path-to-module PATH_TO_MODULE No32 Output pathname of the generated C++ module. N/A
--path-to-custom-types PATH_TO_CUSTOM_TYPES No Input pathname of a CSV file defining aliases of existing data types. Same

Additional options

Option Required Default Description Before v0.67
--module-name MODULE_NAME No3 Name of the generated C++ module N/A
--suppress-timestamp-warning No False Don't display a warning when date/time data types are used. -no-timestamp-warning
--assume-auto-id No False Treat columns called id as if they have a default auto-increment value. -auto-id
--naming-style {camel-case,identity} No camel-case Naming style for generated tables and columns. camel-case interprets _ as word separator and translates table names to UpperCamelCase and column names to lowerCamelCase. identity uses table and column names as-is in generated code. -identity-naming
--generate-table-creation-helper No False For each table in the database model create a helper function that drops and creates the table. N/A
--use-import-sqlpp23 No False Import sqlpp23 as module instead of including the header file. N/A
--use-import-std No False Import std as module instead of including the respective standard header files. N/A
--self-test No1 Run parser self-test. -test

Program exit code

The program follows the POSIX standard and exits with a zero code on success and a non-zero code on failure. Below is a full list of the currently supported exit codes:

Exit code Meaning
0 Success. The requested operation(s) were completed successfully.
1 Bad command-line arguments. The specified command-line arguments or their combination was invalid.
10 DDL execution error. The input DDL file(s) were valid syntactically but had a semantic error, e.g. duplicate table name, duplicate column name, column using an unknown data type (custom data types might help you in this case), etc.
20 DDL parse error. At least one of the specified DDL input file(s) has invalid syntax.
30 Bad custom types. The specified custom data types file is not valid.
Other OS-specific runtime error. While the program does not use these exit codes directly, some OSes may report other termination codes, that are not listed here, when the program fails to run or is terminated forcefully.

Please note that the error codes are not set in stone and may change in the future. The only thing the program guarantees, is that a zero exit code means success and a non-zero code means some kind of error.

Examples of program usage

Once you have the DDL files, you can create C++ headers or modules for them with provided sqlpp23-ddl2cpp script, e.g.

# generate header from ddl file(s)
scripts/sqlpp23-ddl2cpp \
    --path-to-ddl my_project/tables.ddl
    --namespace my_project
    --path-to-header my_project/tables.h

# generate module from ddl file(s)
scripts/sqlpp23-ddl2cpp \
    --path-to-ddl my_project/tables.ddl
    --namespace my_project
    --path-to-module my_project/tables.cppm

More details can be learned from scripts/sqlpp23-ddl2cpp --help.

< Index

Footnotes

  1. Overrides every other option. ↩ ↩2

  2. Exactly one of --path-to-module, --path-to-header or --path-to-header-directory should be specified. ↩ ↩2 ↩3

  3. To generate a C++ module, both --path-to-module and --module-name should be specified. ↩ ↩2