Module org.tentackle.sql
Package org.tentackle.sql

Interface Backend

    • Method Detail

      • isMatchingUrl

        boolean isMatchingUrl​(String url)
        Checks whether the backend belongs to the given jdbc url.
        If multiple backend implementations are provided for the same database type, only one backend should match the URL. The others must be selected via name.
        Parameters:
        url - the jdbc url
        Returns:
        true if matches

      • isMatchingName

        boolean isMatchingName​(String name)
        Checks whether the backend belongs to the given name.
        Parameters:
        name - the backend's name
        Returns:
        true if matches

      • getName

        String getName()
        Gets the name of the backend.
        Returns:
        the name

      • getDriverClassName

        String getDriverClassName()
        Gets the JDBC driver class name.
        Returns:
        the class name

      • createConnection

        Connection createConnection​(String url,
                            String username,
                            char[] password)
                     throws SQLException
        Creates a jdbc connection.
        Parameters:
        url - the jdbc url
        username - the username
        password - the password
        Returns:
        the created connection
        Throws:
        SQLException - if connection could not be established

      • getMetaData

        DatabaseMetaData[] getMetaData​(BackendInfo backendInfo)
                        throws SQLException
        Gets the metadata from the backend.

        Important: the connection of the metadata is open!

        Parameters:
        backendInfo - the backend info
        Returns:
        the metadata, may be more than one if schemas set in backendInfo
        Throws:
        SQLException - if failed

      • isTemporaryName

        boolean isTemporaryName​(String name)
        Checks whether this is a temporary name.
        Returns whether an entity-, attribute- or index-name is temporary and should not be taken into account for migration or even used in the model.
        Depending on the backend, temporary names start with an underscore or some other lead string.
        Parameters:
        name - the name
        Returns:
        true temporary (invalid) name

      • isReservedTableName

        boolean isReservedTableName​(String name)
        Checks whether this a reserved table name for this backend.
        Applies only to tables. Not to be mixed up with getReservedWords().
        Useful to avoid conflicts with naming conventions for backend specific things, such as snapshots.
        Parameters:
        name - the table name
        Returns:
        true if reserved by backend

      • isReservedSchemaName

        boolean isReservedSchemaName​(String name)
        Checks whether this is a reserved schema name for this backend.
        Parameters:
        name - the schema name
        Returns:
        true if reserved by backend

      • buildSelectSql

        void buildSelectSql​(StringBuilder sqlBuilder,
                    boolean writeLock,
                    int limit,
                    int offset)
        Creates a select statement string from an inner sql string.

        sqlBuilder is anything as FROM... WHERE... ORDER BY....
        It is decorated with a leading SELECT plus optional clauses like for the given parameters.

        Parameters:
        sqlBuilder - the sql builder, initially containing the inner sql without leading SELECT.
        writeLock - true select should write lock
        limit - the limit value, ≤ 0 if no limit clause
        offset - the offset value, ≤ 0 if no offset clause

      • buildSelectSql

        String buildSelectSql​(String sql,
                      boolean writeLock,
                      int limit,
                      int offset)
        Creates a select statement string from an inner sql string.

        sqlBuilder is anything as FROM... WHERE... ORDER BY....
        It is decorated with a leading SELECT plus optional clauses like for the given parameters.

        Parameters:
        sql - the sql without leading SELECT.
        writeLock - true select should write lock
        limit - the limit value, ≤ 0 if no limit clause
        offset - the offset value, ≤ 0 if no offset clause
        Returns:
        the select statement

      • setLeadingSelectParameters

        int setLeadingSelectParameters​(BackendPreparedStatement stmt,
                               int limit,
                               int offset)
        Sets optional parameters before applying the original parameters.
        Parameters:
        stmt - the prepared statement
        limit - the limit value, ≤ 0 if no limit clause
        offset - the offset value, ≤ 0 if no offset clause
        Returns:
        the next parameter index

      • setTrailingSelectParameters

        int setTrailingSelectParameters​(BackendPreparedStatement stmt,
                                int index,
                                int limit,
                                int offset)
        Sets optional parameters after applying the original parameters.
        Parameters:
        stmt - the prepared statement
        index - the first parameter index
        limit - the limit value, ≤ 0 if no limit clause
        offset - the offset value, ≤ 0 if no offset clause
        Returns:
        the next parameter index

      • getEmptyString

        String getEmptyString()
        Gets the empty string.

        Some dbms (most famous: Oracle) handle empty strings as null. In such cases the empty string (e.g. Oracle) may consist of a single blank or whatever.

        Returns:
        the empty string (never null)

      • sqlResultSetIsClosedSupported

        boolean sqlResultSetIsClosedSupported()
        Determines whether the jdbc driver supports ResultSet.isClosed().
        Returns:
        true if the driver supports it

      • getCoalesceKeyword

        String getCoalesceKeyword()
        Gets the keyword for the COALESCE function.
        Returns:
        the keyword

      • allowsExpressionsReferringToTablesBeingUpdated

        boolean allowsExpressionsReferringToTablesBeingUpdated()
        Determines whether backend allows expressions referring to tables being updated.
        Returns:
        true if allowed

      • supportsSequences

        boolean supportsSequences()
        True if backend provides transactionless sequences.
        Returns:
        true if database supports sequences

      • sqlAsBeforeTableAlias

        String sqlAsBeforeTableAlias()
        Gets the string before the table alias.
        In most databases the " AS " is optional and some don't accept it all.
        Returns:
        the as-string

      • needAliasForSubselect

        boolean needAliasForSubselect()
        Returns whether backend needs an alias for a subselect.
        Returns:
        true if subselect needs an alias.

      • sqlNextFromSequene

        String sqlNextFromSequene​(String name)
        Creates the SQL string to retrieve the next id from a sequence.
        Parameters:
        name - the name of the sequence
        Returns:
        the SQL code

      • sqlComment

        String sqlComment​(String text)
        Create comment sql code that is interpreted as a comment by the backend.
        Parameters:
        text - any text, single or multiline
        Returns:
        the comment, null if text was null

      • sqlJoin

        String sqlJoin​(JoinType type,
               String joinedTableName,
               String joinedTableAlias,
               String join)
        Creates a join clause.
        Parameters:
        type - the join type
        joinedTableName - the joined tablename
        joinedTableAlias - the joined table alias, null if none
        join - the join expression
        Returns:
        the sql code

      • sqlFunction

        String sqlFunction​(String functionName,
                   String expression)
        Creates an sql function expression.

        Example: 

          sqlFunction("max", CN_ID) --> "MAX(id)"
        Parameters:
        functionName - the function name, will be translated to uppercase
        expression - the expression, may be null
        Returns:
        the sql code

      • needSetLongWorkaround

        boolean needSetLongWorkaround()
        Checks whether we need a workaround for the (Ingres) setLong-Bug.
        Returns:
        true if workaround needed

      • needTxForFetchsize

        boolean needTxForFetchsize()
        Checks for the (postgres) bug that fetchsize is ignored if not within a new transaction.
        Returns:
        true if start tx

      • isConstraintException

        boolean isConstraintException​(SQLException ex)
        Determines whether exception is a constraint violation.
        Parameters:
        ex - the exception
        Returns:
        true if constraint violation

      • isCommunicationLinkException

        boolean isCommunicationLinkException​(SQLException ex)
        Determines whether exception is a communication error.
        Parameters:
        ex - the exception
        Returns:
        true if comlink down or alike

      • isTransientTransactionException

        boolean isTransientTransactionException​(SQLException ex)
        Determines whether exception is transient and retrying the transaction may succeed.
        Typical transient exceptions are thrown when a deadlock is detected or when serialized transaction isolation is used.

        Other transient errors are not covered by this method (e.g. connection timeouts, etc...).

        Parameters:
        ex - the exception
        Returns:
        true if retrying the transaction may succeed

      • getMaxSize

        int getMaxSize​(SqlType sqlType)
        Returns the maximum size for a given SQL-type.
        Parameters:
        sqlType - the SQL-type
        Returns:
        the maximum size, 0 if unlimited, -1 if type without size

      • getMaxScale

        int getMaxScale​(SqlType sqlType,
                int size)
        Returns the maximum scale for a given SQL-type and size.
        Parameters:
        sqlType - the SQL-type
        size - the size, 0 if unlimited
        Returns:
        the maximum scale, 0 if unlimited

      • getDefaultSize

        int getDefaultSize​(SqlType sqlType)
        Gets the default size if no size given in model.
        Parameters:
        sqlType - the SQL-type
        Returns:
        the default size, 0 if no default size

      • getDefaultSchema

        String getDefaultSchema()
        Gets the default schema name.
        Some backends store the objects in a default schema, if no explicit schema is given.
        Returns:
        the defailt schema, null if none

      • getReservedWords

        Set<String> getReservedWords()
        Gets the list of reserved words for this backend.
        Returns:
        the list of reserved words

      • assertValidName

        void assertValidName​(SqlNameType nameType,
                     String name)
        Asserts that given string is a valid name and usage.
        Parameters:
        nameType - the type/usage of the name
        name - the name
        Throws:
        BackendException - if invalid name

      • getBackendId

        String getBackendId​(Connection connection)
        Determines the unique id or name used by the backend for a given connection.

        Useful to figure out the corresponding ManagedConnection from the backend's logfiles.

        Parameters:
        connection - the jdbc connection
        Returns:
        the backend id, null if none

      • getModelMetaData

        ModelMetaData getModelMetaData​(DatabaseMetaData[] metaData,
                               String[] schemas,
                               String... tableNames)
        Retrieves the metadata.
        Parameters:
        metaData - the meta data for the whole database
        schemas - the optional schemas to filter tables, null if no filter
        tableNames - the tables of the model
        Returns:
        the meta data, null if no such table

      • createColumnMetaData

        ColumnMetaData createColumnMetaData​(TableMetaData tableMetaData)
        Creates a column meta data instance.
        Parameters:
        tableMetaData - the table meta data this column belongs to
        Returns:
        the meta data

      • createTableMetaData

        TableMetaData createTableMetaData​(ModelMetaData metaData,
                                  String tableName)
        Creates a meta data instance.
        Parameters:
        metaData - the whole meta data
        tableName - the model's table name
        Returns:
        the meta data

      • createIndexMetaData

        IndexMetaData createIndexMetaData​(TableMetaData tableMetaData)
        Creates an index meta data instance.
        Parameters:
        tableMetaData - the table meta data this index belongs to
        Returns:
        the meta data

      • createIndexColumnMetaData

        IndexColumnMetaData createIndexColumnMetaData​(IndexMetaData indexMetaData)
        Creates an index column meta data instance.
        Parameters:
        indexMetaData - the meta meta data this column belongs to
        Returns:
        the meta data

      • sqlTypeToString

        String sqlTypeToString​(SqlType sqlType,
                       int size)
        Converts the java SQL-type to the database type name.
        Parameters:
        sqlType - the java sql type
        size - the column's size
        Returns:
        the corresponding type string

      • columnTypeToString

        String columnTypeToString​(SqlType sqlType,
                          int size,
                          int scale)
        Converts an sqltype, size and scale to a database type declaration.
        Parameters:
        sqlType - the SQL type
        size - the size
        scale - the scale
        Returns:
        the type definition

      • columnTypeNullDefaultToString

        String columnTypeNullDefaultToString​(String columnName,
                                     SqlType sqlType,
                                     int size,
                                     int scale,
                                     boolean nullable,
                                     Object defaultValue)
        Converts an sqltype, size, scale, nullable and default value to a database type declaration.
        Parameters:
        columnName - the database column name
        sqlType - the JDBC sql type
        size - the optional size
        scale - the optional scale
        nullable - true if NULL, else NOT NULL
        defaultValue - the optional default value
        Returns:
        the SQL code

      • valueToLiteral

        String valueToLiteral​(SqlType sqlType,
                      Object value)
        Conberts a type and value to a literal string.
        Parameters:
        sqlType - the sql type
        value - the value
        Returns:
        the constant

      • sqlCreateTableIntro

        String sqlCreateTableIntro​(String tableName,
                           String comment)
        Generates the first line of a CREATE TABLE statement.
        Parameters:
        tableName - the tablename with optional schema separated by a dot
        comment - optional comment, null if none
        Returns:
        the SQL code including the opening bracket

      • sqlCreateTableClosing

        String sqlCreateTableClosing​(String tableName,
                             String comment)
        Generates the last line of a CREATE TABLE statement.
        Parameters:
        tableName - the tablename with optional schema separated by a dot
        comment - optional comment, null if none
        Returns:
        the SQL code including the closing bracket

      • sqlAlterTableComment

        String sqlAlterTableComment​(String tableName,
                            String comment)
        Generates SQL code to alter the comment for a table.
        Parameters:
        tableName - the table name
        comment - optional comment, null to clear
        Returns:
        the SQL code

      • sqlCreateColumn

        String sqlCreateColumn​(String columnName,
                       String comment,
                       SqlType sqlType,
                       int size,
                       int scale,
                       boolean nullable,
                       Object defaultValue,
                       boolean primaryKey,
                       boolean withTrailingComma)
        Generates the attribute definition of a CREATE TABLE statement.
        Parameters:
        columnName - the database column name
        comment - optional comment, null if none
        sqlType - the JDBC sql type
        size - the optional size
        scale - the optional scale
        nullable - true if NULL, else NOT NULL
        defaultValue - the optional default value
        primaryKey - true if this is a primary key
        withTrailingComma - true if append a comma
        Returns:
        the SQL code

      • isDefaultEqual

        boolean isDefaultEqual​(ColumnMetaData column,
                       SqlType sqlType,
                       Object defaultValue)
        Checks whether the column's default corresponds to the model's default value.
        Parameters:
        column - the column to inspect
        sqlType - the sql type
        defaultValue - the model's default value
        Returns:
        true if same

      • getMigrationStrategy

        MigrationStrategy[] getMigrationStrategy​(ColumnMetaData column,
                                         String columnName,
                                         String comment,
                                         SqlType sqlType,
                                         int size,
                                         int scale,
                                         boolean nullable,
                                         Object defaultValue)
        Determines the best migration strategy.
        Parameters:
        column - old column meta data
        columnName - new column name
        comment - new comment
        sqlType - new sql type
        size - new size
        scale - new scale
        nullable - new nullable
        defaultValue - new default
        Returns:
        the strategies in order to achieve the migration

      • sqlRenameTable

        String sqlRenameTable​(String tableName,
                      String newTableName)
        Generate sql code to rename a table.
        Parameters:
        tableName - the old tablename (with leading schema, if any)
        newTableName - the new tablename (without schema)
        Returns:
        the SQL code

      • sqlRenameColumn

        String sqlRenameColumn​(String tableName,
                       String oldColumnName,
                       String newColumnName)
        Generates sql code to rename a column.
        Parameters:
        tableName - the tablename
        oldColumnName - the old column name
        newColumnName - the new column name
        Returns:
        the SQL code, null if need full spec sqlRenameAndAlterColumnType below

      • sqlRenameIndex

        String sqlRenameIndex​(String tableName,
                      String oldIndexName,
                      String newIndexName)
        Generates sql code to rename an index.
        Parameters:
        tableName - the tablename
        oldIndexName - the old column name
        newIndexName - the new column name
        Returns:
        the SQL code, null if not supported by the backend and we need to drop and create

      • sqlRenameAndAlterColumnType

        String sqlRenameAndAlterColumnType​(String tableName,
                                   String oldColumnName,
                                   String newColumnName,
                                   String comment,
                                   SqlType sqlType,
                                   int size,
                                   int scale,
                                   boolean nullable,
                                   Object defaultValue)
        Generates sql code to rename a column.
        Parameters:
        tableName - the tablename
        oldColumnName - the old column name
        newColumnName - the new column name
        comment - optional comment, null if none
        sqlType - the JDBC sql type
        size - the optional size
        scale - the optional scale
        nullable - true if NULL, else NOT NULL
        defaultValue - the optional default value
        Returns:
        the SQL code

      • sqlAddColumn

        String sqlAddColumn​(String tableName,
                    String columnName,
                    String comment,
                    SqlType sqlType,
                    int size,
                    int scale,
                    boolean nullable,
                    Object defaultValue)
        Generates sql code to add a column.
        Parameters:
        tableName - the tablename
        columnName - the new column name
        comment - optional comment, null if none
        sqlType - the JDBC sql type
        size - the optional size
        scale - the optional scale
        nullable - true if NULL, else NOT NULL
        defaultValue - the optional default value
        Returns:
        the SQL code

      • sqlDropColumn

        String sqlDropColumn​(String tableName,
                     String columnName)
        Generates sql code to drop a column.
        Parameters:
        tableName - the tablename
        columnName - the new column name
        Returns:
        the SQL code

      • sqlAlterColumnType

        String sqlAlterColumnType​(String tableName,
                          String columnName,
                          String comment,
                          SqlType sqlType,
                          int size,
                          int scale,
                          boolean nullable,
                          Object defaultValue)
        Generates sql code to change the datatype of a column.
        Parameters:
        tableName - the tablename
        columnName - the new column name
        comment - optional comment, null if none
        sqlType - the JDBC sql type
        size - the optional size
        scale - the optional scale
        nullable - true if NULL, else NOT NULL
        defaultValue - the optional default value
        Returns:
        the SQL code

      • sqlUpdateToNotNull

        String sqlUpdateToNotNull​(String tableName,
                          String columnName,
                          SqlType sqlType,
                          Object defaultValue)
        Generates code to update a column to a non-null value.
        Parameters:
        tableName - the tablename
        columnName - the column name
        sqlType - the sql type
        defaultValue - the optional default value if defined in the model
        Returns:
        the SQL code

      • sqlCreateIndex

        String sqlCreateIndex​(String tableName,
                      String indexName,
                      boolean unique,
                      String filterCondition,
                      String... columnNames)
        Generates the CREATE INDEX statement.
        Parameters:
        tableName - the table name
        indexName - the name of the index
        unique - true if index is unique
        filterCondition - the filter condition (null if none)
        columnNames - the column names (with a leading '-' if descending). Simple function-based indexes are also supported.
        Returns:
        the SQL code

      • sqlDropIndex

        String sqlDropIndex​(String schemaName,
                    String tableNameWithoutSchema,
                    String indexName)
        Generates the DROP INDEX statement.
        Parameters:
        schemaName - the optional schema, null if none
        tableNameWithoutSchema - the table name without the schema
        indexName - the name of the index
        Returns:
        the SQL code

      • sqlDropTable

        String sqlDropTable​(String schemaName,
                    String tableNameWithoutSchema)
        Generates the DROP TABLE statement.
        Parameters:
        schemaName - the optional schema, null if none
        tableNameWithoutSchema - the table name without the schema
        Returns:
        the SQL code

      • sqlCreateForeignKey

        String sqlCreateForeignKey​(String referencingTableName,
                           String referencingColumnName,
                           String referencedTableName,
                           String referencedColumnName,
                           String foreignKeyName,
                           boolean composite)
        Generates the ALTER TABLE statement to add a foreign key constraint.
        Parameters:
        referencingTableName - the referencing foreign table name
        referencingColumnName - the referencing foreign column name
        referencedTableName - the referenced primary table name
        referencedColumnName - the referenced primary column name
        foreignKeyName - the name of the foreign key
        composite - true if referencing table is a component of the referenced table
        Returns:
        the SQL code

      • sqlDropForeignKey

        String sqlDropForeignKey​(String referencingTableName,
                         String foreignKeyName)
        Generates the sql statement to drop a foreign key constraint.
        Parameters:
        referencingTableName - the referencing foreign table name
        foreignKeyName - the name of the foreign key
        Returns:
        the SQL code

      • sqlJoinSelects

        void sqlJoinSelects​(JoinType type,
                    boolean addColumns,
                    StringBuilder select,
                    String joinSelect,
                    String joinSelectIdAlias,
                    String joinAlias,
                    String join)
        Generate SQL code for joining a table to an existing select.
        Parameters:
        type - the join type
        addColumns - true if columns of joined table should be added to the result set
        select - the original select statement
        joinSelect - the select to join with the original sql or just a tablename
        joinSelectIdAlias - extra id alias to add to the joined select, null if none
        joinAlias - the alias of the joined select
        join - the join clause

      • sqlJoinSelects

        String sqlJoinSelects​(JoinType type,
                      boolean addColumns,
                      String select,
                      String joinSelect,
                      String joinSelectIdAlias,
                      String joinAlias,
                      String join)
        Generate SQL code for joining a table to an existing select.
        Parameters:
        type - the join type
        addColumns - true if columns of joined table should be added to the result set
        select - the original select statement
        joinSelect - the select to join with the original sql or just a tablename
        joinSelectIdAlias - extra id alias to add to the joined select, null if none
        joinAlias - the alias of the joined select
        join - the join clause
        Returns:
        the select statement

      • jdbcTypeToSqlType

        SqlType[] jdbcTypeToSqlType​(int jdbcType,
                            int size,
                            int scale)
        Converts the JDBC data type integer to a tentackle backend SqlTypes.

        There may be more than one sqltype returned!

        Parameters:
        jdbcType - the jdbc data type
        size - the column size
        scale - the column's scale
        Returns:
        the SqlTypes, empty array if no mapping available or no exact match (not generated by TT)
        See Also:
        Types

      • getTableMetaData

        TableMetaData getTableMetaData​(ModelMetaData modelMetaData,
                               String tableName)
        Gets the table meta data for a given table name.
        Parameters:
        modelMetaData - the model the table belongs to
        tableName - the model's table name
        Returns:
        the table data

      • toQuotedString

        String toQuotedString​(String str)
        Converts a string to a string enclosed in single quotes.
        Parameters:
        str - the string
        Returns:
        the quoted string

      • optimizeSql

        String optimizeSql​(String sql)
        Optimize SQL code.
        Replace WHERE 1=1 AND/OR to WHERE. Any remaining WHERE 1=1 will be removed too. If you don't want your statements getting optimized, use lowercase for those keywords.
        Parameters:
        sql - the original sql code
        Returns:
        the optimized sql code

      • isReleaseSavepointSupported

        boolean isReleaseSavepointSupported()
        Returns whether the backend supports releasing savepoints explicitly. If not, the savepoints are released when the transaction finishs.
        Returns:
        true if release is supported, else false

      • isClobSupported

        boolean isClobSupported()
        Returns whether the backend support CLOB types.
        If not, it will be emulated as VARCHAR with the maximum possible size.
        Returns:
        true if supported, false if treat as varchar

      • isFunctionBasedIndexSupported

        boolean isFunctionBasedIndexSupported()
        Returns whether function based indexes are supported.
        Returns:
        true if supported

      • isFilteredIndexSupported

        boolean isFilteredIndexSupported()
        Returns whether backend supports filtered indexes.
        Returns:
        true if supported, false if model will raise an error if filtered index is used

      • setDropIfExistsEnabled

        void setDropIfExistsEnabled​(boolean dropIfExists)
        Some database support drop index/constraint/column IF EXISTS.
        This may be useful if migration scripts are generated against non-production databases that contain test indexes etc...
        Notice, that those temporary DDL changes should better use the temporary prefix (see isTemporaryName(String) in order to be ignored by the migrator.
        Parameters:
        dropIfExists - true if use IF EXISTS if the backend supports it

      • isDropIfExistsEnabled

        boolean isDropIfExistsEnabled()
        Returns whether backend should add IF EXISTS for generated DROPs.
        Returns:
        true if IF EXISTS is turned on and supported, false if not supported or turned off

      • toInternalType

        String toInternalType​(String sqlTypeName)
        Converts a backend specific type name to an internal name used by driver specific methods.
        Parameters:
        sqlTypeName - the original type used in SQL scripts
        Returns:
        the JDBC internal name

      • isArrayOperatorSupported

        boolean isArrayOperatorSupported​(String operator)
        Returns whether the backend supports given array operator.
        Parameters:
        operator - the array operator
        Returns:
        true if supported

      • setArray

        void setArray​(PreparedStatement statement,
              int pos,
              SqlType type,
              Collection<?> elements,
              String operator)
       throws SQLException
        Sets an array parameter in a prepared statement.
        Parameters:
        statement - the prepared statement
        pos - the parameter position (starting at 1)
        type - the element's SQL type
        elements - the elements to be converted to an array parameter
        operator - the array operator
        Throws:
        SQLException