FreetdsSqlUtil.qm

# -*- mode: qore; indent-tabs-mode: nil -*-
#! @file FreetdsSqlUtil.qm Qore user module for working with FreeTDS SQL data

/*  FreetdsSqlUtil.qm Copyright (C) 2015 - 2022 Qore Technologies, s.r.o.

    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.
*/

# minimum required Qore version
%requires qore >= 1.0

# requires the SqlUtil module
%requires SqlUtil >= 1.5

# requires the Util module
%requires Util >= 1.0

# don't use "$" signs for variables and class members, assume local variable scope
%new-style

# require type definitions everywhere
%require-types

# enable all warnings
%enable-all-warnings

module FreetdsSqlUtil {
    version = "1.4.2";
    desc = "user module for working with FreeTDS SQL data";
    author = "David Nichols <david@qore.org>";
    url = "http://qore.org";
    license = "MIT";
}

# version history is included below in the docs

/** @mainpage FreetdsSqlUtil Module

    @tableofcontents

    @section freetdssqlutilintro FreetdsSqlUtil Module Introduction

    The %FreetdsSqlUtil module provides a high level API for working with database objects through the freetds driver.

    Usually this module is loaded on demand from the SqlUtil module, however to use this module
    directly, use \c "%requires FreetdsSqlUtil" in your code.

    All the public symbols in the module are defined in the FreetdsSqlUtil namespace

    @note This module requires the <a href="https://github.com/qorelanguage/module-sybase">freetds</a> binary module for communication with MS SQL Server and Sybase databases

    @section freetds_sql_operations SQL Operations with the FreeTDS Driver

    Queries are limited in the number of arguments in the \c "in" operator depending on the database server; use a join with a temporary table
    to select a large number of values known at runtime instead of using the \c "in" operator (see @ref SqlUtil::op_in()).

    %FreetdsSqlUtil supports the following additional @ref select_option_hash "select option" when working with MS SQL Server databases:
    - \c "tablehint": A single string or a list of strings with the following possible values:
      - \c "index(...)": Specifies the name or ID of the indexes to be used by SQL Server when processing the statement. Only one index hint per table can be specified.  If a clustered index exists, \c "index(0)" forces a clustered index scan and \c "index(1)" forces a clustered index scan or seek. If no clustered index exists, \c "index(0)" forces a table scan and \c "index(1)" is interpreted as an error.  See SQL Server docs for more information.
      - \c "fastfirstrow": Equivalent to SQL Server option \c "(FAST 1)"
      - \c "holdlock": Makes shared locks more restrictive by holding them until the completion of a transaction (instead of releasing the shared lock as soon as the required table or data page is no longer needed, whether or not the transaction has been completed). The scan is performed with the same semantics as a transaction running at the \c "SERIALIZABLE" isolation level.  equivalent to \c "serializable"
      - \c "nolock": Equivalent to \c "readuncommitted"
      - \c "paglock": Takes shared page locks where a single shared table lock is normally taken
      - \c "readcommitted": Specifies that a scan is performed with the same locking semantics as a transaction running at \c "READ COMMITTED" isolation level
      - \c "readpast": Specifies that locked rows are skipped (read past)
      - \c "readuncommitted": Specifies that dirty reads are allowed
      - \c "repeatableread": Specifies that a scan is performed with the same locking semantics as a transaction running at \c "REPEATABLE READ" isolation level
      - \c "rowlock": Specifies that a shared row lock is taken when a single shared page or table lock is normally taken
      - \c "serializable": Makes shared locks more restrictive by holding them until the completion of a transaction (instead of releasing the shared lock as soon as the required table or data page is no longer needed, whether or not the transaction has been completed). The scan is performed with the same semantics as a transaction running at the \c "SERIALIZABLE" isolation level.  Equivalent to \c "holdlock".
      - \c "tablock": Specifies that a shared lock is taken on the table held until the end-of-statement. If \c "holdlock" is also specified, the shared table lock is held until the end of the transaction.
      - \c "tablockx": Specifies that an exclusive lock is taken on the table held until the end-of-statement or end-of-transaction.
      - \c "updlock": Specifies that update locks instead of shared locks are taken while reading the table, and that they are held until the end-of-statement or end-of-transaction.
      - \c "xlock": Specifies that exclusive locks should be taken and held until the end of transaction on all data processed by the statement. If specified with \c "paglock" or \c "tablock", the exclusive locks apply to the appropriate level of granularity.

    @note
    - From the SQL Server docs: The SQL Server query optimizer automatically makes the correct determination. It is recommended that table-level locking hints be used to change the default locking behavior only when necessary. Disallowing a locking level can affect concurrency adversely.
    - For more details on the above hints as well as information on which hints are supported for your particular version of SQL Server, see the SQL Server docs

    @section freetds_schema_management Schema Management with the FreeTDS Driver

    @subsection freetds_type_mapping Type Mapping

    Column types are mapped from %Qore types as follows:

    <b>FreeTDS Column Type Mappings</b>
    |!Generic Type Name|!FreeTDS Type Used
    |\c float|\c float
    |\c integer|\c bigint
    |\c number|\c numeric
    |\c string|\c varchar
    |\c date|\c datetime
    |\c binary|\c varbinary
    |\c bool|\c tinyint
    |@ref SqlUtil::BLOB|\c varbinary
    |@ref SqlUtil::CHAR|\c char
    |@ref SqlUtil::CLOB|\c text
    |@ref SqlUtil::NUMERIC|\c numeric
    |@ref SqlUtil::VARCHAR|\c varchar

    To use other types, use the \c "native_type"
    @ref SqlUtil::AbstractTable::ColumnDescOptions "column description option" with the native FreeTDS type name
    instead (under the \c "driver" and \c "freetds" keys for schemas supporting multiple databases).

    @subsection freetdssqlutilv141 FreetdsSqlUtil v1.4.2
    - fixed a bug where \c offset and \c limit were not properly supported with MS SQL Server DBs
      (<a href="https://github.com/qorelanguage/qore/issues/4408">issue 4408</a>)
    - fixed a bug where date/time values in other time zones were not bound correctly
      (<a href="https://github.com/qorelanguage/qore/issues/4403">issue 4403</a>)
    - fixed a bug handling transaction savepoints
      (<a href="https://github.com/qorelanguage/qore/issues/4402">issue 4402</a>)
    - allow a \c VARCHAR column to be created without a size, assume a default size
      (<a href="https://github.com/qorelanguage/qore/issues/4399">issue 4399</a>)

    @subsection freetdssqlutilv141 FreetdsSqlUtil v1.4.1
    - added APIs to enable duplicate record creation errors to be detected
      (<a href="https://github.com/qorelanguage/qore/issues/4308">issue 4308</a>)

    @subsection freetdssqlutilv14 FreetdsSqlUtil v1.4
    - added support for the DataProvider module
      (<a href="https://github.com/qorelanguage/qore/issues/3545">issue 3545</a>)

    @subsection freetdssqlutilv131 FreetdsSqlUtil v1.3.1
    - fixed quoting of reserved words in column names in table alignment
      (<a href="https://github.com/qorelanguage/qore/issues/3400">issue 3400</a>)

    @subsection freetdssqlutilv13 FreetdsSqlUtil v1.3
    - added support for serializing and deserializing @ref SqlUtil::AbstractTable "AbstractTable" objects
      (<a href="https://github.com/qorelanguage/qore/issues/2663">issue 2663</a>)

    @subsection freetdssqlutilv121 FreetdsSqlUtil v1.2.1
    - implemented support for custom column operators
      (<a href="https://github.com/qorelanguage/qore/issues/2314">issue 2314</a>)

    @subsection freetdssqlutilv12 FreetdsSqlUtil v1.2
    - fixed a bug where @ref SqlUtil::BLOB columns were created as \c VARBINARY columns instead of \c VARBINARY(MAX)
      (<a href="https://github.com/qorelanguage/qore/issues/1852">issue 1852</a>)
    - implemented @ref cop_trunc_date() operator
      (<a href="https://github.com/qorelanguage/qore/issues/2032">issue 2032</a>)

    @subsection freetdssqlutilv11 FreetdsSqlUtil v1.1
    - implemented the \a force option (i.e. cascade) for dropping code objects
      (<a href="https://github.com/qorelanguage/qore/issues/1314">issue 1314</a>)

    @subsection freetdssqlutilv10 FreetdsSqlUtil v1.0
    - initial release
*/

#! the FreetdsSqlUtil namespace contains all the objects in the FreetdsSqlUtil module
public namespace FreetdsSqlUtil {
    #! returns a FreetdsTable object corresponding to the arguments
    public FreetdsTable sub get_table(AbstractDatasource nds, string nname, *hash<auto> opts) {
        return new FreetdsTable(nds, nname, opts);
    }

    #! returns a FreetdsDatabase object corresponding to the arguments
    public FreetdsDatabase sub get_database(AbstractDatasource nds, *hash<auto> opts) {
        return new FreetdsDatabase(nds, opts);
    }

    sub parse_schema_name(string nname, reference<string> schema, reference<string> name, string default_schema = "dbo") {
        *string sstr = (nname =~ x/^(\w+)\.\w+/)[0];
        if (sstr) {
            schema = sstr;
            splice nname, 0, schema.size() + 1;
            name = nname;
        } else {
            schema = default_schema;
            name = nname;
        }
    }

    #! FreeTDS savepoint helper
    public class FreetdsSavepointHelper inherits AbstractSavepointHelper {
        #! Creates the object
        /** @note MS SQL Server savepoint identifiers cannot be longer than 32 character by default; the default
            savepoint value uses the unique hash for the object, which is 40 characters long, so we have to use
            another algorithm to create the savepoint string on Oracle
        */
        constructor(AbstractDatasource ds, *string savepoint = "x" + get_random_string(31))
            : AbstractSavepointHelper(ds, savepoint) {
        }

        #! Creates the savepoint
        private createSavepointImpl() {
            ds.exec("begin transaction");
            ds.exec("save tran " + savepoint);
        }

        #! Rolls back to the savepoint
        private rollbackImpl() {
            ds.exec("rollback tran " + savepoint);
        }

        #! Deletes the savepoint
        private deleteSavepointImpl() {
            # this method intentionally left blank
        }
    }

    #! the data type for FreeTDS DECIMAL columns
    public class FreetdsNumberDataType inherits SqlUtil::AbstractNumericDataType {
        #! creates the object
        constructor(string native_type, bool nullable, *hash<auto> options)
                : AbstractNumericDataType(native_type, nullable, options) {
        }
    }

    #! represents a FreeTDS-specific index
    public class FreetdsIndex inherits SqlUtil::AbstractIndex {
        public {
            #! the tablespace (filegroup) name of the index
            *string filegroup;
        }

        #! creates the object from the arguments
        constructor(string n_name, bool n_unique, hash n_cols, *string n_filegroup)
                : AbstractIndex(n_name, n_unique, n_cols) {
            filegroup = n_filegroup;
        }

        #! returns a string that can be used to create the index in the database
        string getCreateSql(string table_name, *hash opt) {
            string sql = sprintf("create %sindex %s on %s (%s)", unique ? "unique " : "", name, table_name,
                (foldl $1 + ", " + $2, columns.getSqlColumnNameIterator()));

            *string ts = opt.index_filegroup ? opt.index_filegroup : filegroup;
            if (ts)
                sql += sprintf(" on %s", ts);
            return sql;
        }

        #! returns @ref True "True" if the argument is equal to the current index, @ref False "False" if not
        private bool equalImpl(AbstractIndex ix) {
            return True;
        }

        #! returns a string that can be used to rename the index in the database
        string getRenameSql(string table_name, string new_name) {
            return sprintf("exec sp_rename '%s.%s', '%s', 'INDEX'", table_name, name, new_name);
        }
    }

    #! represents a FreeTDS-specific foreign constraint
    public class FreetdsForeignConstraint inherits SqlUtil::AbstractForeignConstraint {
        #! creates the constraint from the supplied arguments
        constructor(string n, Columns c, ForeignConstraintTarget t) : AbstractForeignConstraint(n, c, t) {
        }

        #! returns a string that can be used to create the constraint in the database
        string getCreateSql(string table_name, *hash opt) {
            return getCreateSql(name, table_name, opt);
        }

        softlist getRenameSql(string table_name, string new_name) {
            # the following is only valid with FreeTDS 9.2+
            #return sprintf("alter table %s rename constraint %s to %s", table_name, name, new_name);
            list l += getDropSql(table_name);
            l += getCreateSql(new_name, table_name);
            return l;
        }

        #! returns a string that can be used to create the constraint in the database
        string getCreateSql(string name, string table_name, *hash opt) {
            return sprintf("alter table %s add constraint %s foreign key (%s) references %s (%s)", table_name, name,
                (foldl $1 + ", " + $2, h.keys()), target.table, (foldl $1 + ", " + $2, target.columns.keys()));
        }
    }

    #! represents a FreeTDS-specific check constraint
    public class FreetdsCheckConstraint inherits SqlUtil::AbstractCheckConstraint {
        #! creates the constraint from the supplied arguments
        constructor(string n, string n_src) : AbstractCheckConstraint(n, n_src) {
        }

        #! returns a string that can be used to create the constraint in the database
        string getCreateSql(string table_name, *hash opt) {
            return getCreateSql(name, table_name, opt);
        }

        list getRenameSql(string table_name, string new_name) {
            # the following is only valid with FreeTDS 9.2+
            #return sprintf("alter table %s rename constraint %s to %s", table_name, name, new_name);
            list l += getDropSql(table_name);
            l += getCreateSql(new_name, table_name);
            return l;
        }

        #! returns a string that can be used to create the constraint in the database
        string getCreateSql(string name, string table_name, *hash opt) {
            return sprintf("alter table %s add constraint %s check (%s)", table_name, name, src);
        }
    }

    #! represents a FreeTDS-specific column
    public class FreetdsColumn inherits SqlUtil::AbstractColumn {
        public {
            #! byte size of the column
            int byte_size;
        }

        #! empty constructor for subclasses
        private constructor() {
        }

        #! creates the column from the supplied arguments
        constructor(string n, string nt, *string qt, int sz, bool nul, *string dv, *string cm, softint bs, *int scale)
                : AbstractColumn(n, nt, qt, sz, nul, dv, cm, scale) {
            byte_size = bs;
        }

        #! returns a list of sql strings that can be used to add the column to an existing table
        /** @par Example:
            @code{.py}
list l = col.getAddColumnSql(t);
            @endcode

            @param t the SqlUtil::AbstractTable object to modify
         */
        softlist getAddColumnSql(AbstractTable t) {
            return sprintf("alter table %s add %s", t.getSqlName(), AbstractColumn::getCreateSql(t));
        }

        #! returns a list of sql strings that can be used to modify the column to the new definition; if the column definitions are identical then an empty list is returned
        /** @par Example:
            @code{.py}
list l = col.getModifySql(t, newcol);
            @endcode

            The column names are assumed to be equal.

            @param t the SqlUtil::AbstractTable object to modify
            @param col the new column definition
            @param opt column modification options (none are supported in this class)

            @return a list of sql strings that can be used to modify the column to the new definition; if the column definitions are identical then an empty list is returned
         */
        list getModifySqlImpl(AbstractTable t, AbstractColumn col, *hash opt) {
            list l = ();
            FreetdsColumn c = col;

            # get new native type declaration string
            string nts = c.getNativeTypeString();
            string dv_name = getDdlName("dv_" + name);
            if (getNativeTypeString() != nts) {
                #printf("ME: %s\nDB: %s\n", nts, getNativeTypeString());
                if (exists def_val && def_val !== c.def_val)
                    l += sprintf("alter table %s drop constraint %s", t.getSqlName(), dv_name);

                l += sprintf("alter table %s alter column %s %s %snull", t.getSqlName(), ddl_name, nts, c.nullable ? "" : "not ");

                if (def_val !== c.def_val && exists c.def_val && c.def_val !== NULL)
                    l += sprintf("alter table %s add constraint %s default %s for %s", t.getSqlName(), dv_name, c.def_val, ddl_name);
            } else {
                if (def_val !== c.def_val) {
                    #printf("L: %N\nXXXXXXXXXXXXXXX\nR: %N\n\n", self, c);
                    if (exists c.def_val && c.def_val !== NULL)
                        l += sprintf("alter table %s add constraint %s default %s for %s", t.getSqlName(), dv_name, c.def_val, ddl_name);
                    else
                        l += sprintf("alter table %s drop constraint %s", t.getSqlName(), dv_name);
                }
                if (nullable != c.nullable) {
                    l += sprintf("alter table %s alter column %s %s %snull", t.getSqlName(), ddl_name, nts, c.nullable ? "" : "not ");
                }
            }

            return l;
        }

        #! returns a string that can be used to rename the column
        /** @par Example:
            @code{.py}
string str = col.getRenameSql(t, "new_name");
            @endcode

            @param t the SqlUtil::AbstractTable object to modify
            @param new_name the new name for the column

            @return a string that can be used to rename the column
        */
        string getRenameSql(AbstractTable t, string new_name) {
            return sprintf("sp_rename '%s.%s', '%s', 'COLUMNS'", t.getSqlName(), ddl_name, getDdlName(new_name));
        }

        #! returns the column name with quoting in case the column name is a reserved word
        /** the name returned here will be used when executing DDL
        */
        string getDdlName(string name) {
            return FreetdsDatabase::FreetdsReservedWords{name.lwr()} ? ("[" + name + "]") : name;
        }

        #! returns @ref True "True" if the argument is equal to the current object, @ref False "False" if not
        private bool equalImpl(AbstractColumn c) {
            return True;
        }
    }

    #! represents a FreeTDS-specific numeric column
    public class FreetdsNumericColumn inherits FreetdsColumn {
        #! creates the column from the supplied arguments
        constructor(string n, string nt, *string qt, int sz, bool nul, *string dv, *string cm, softint bs,
                softint scale) : FreetdsColumn(n, nt, qt, sz, nul, dv, cm, bs, scale) {
        }
    }

    #! common base class for unique constraints
    public class FreetdsUniqueConstraintCommon inherits SqlUtil::AbstractUniqueConstraint {
        private {
            #! any filegroup for the unique key index
            *string filegroup;
        }

        #! empty constructor for subclasses
        private constructor() {
        }

        #! creates the constraint with an optional filegroup name
        constructor(*string ts) {
            filegroup = ts;
        }

        #! returns the filegroup name used for this constraint, if known
        *string getTablespace() {
            return filegroup;
        }

        #! sets or clears the filegroup name
        setTablespace(*string ts) {
            filegroup = ts;
        }

        #! sets the supporting index name
        bool setIndexBase(string ix) {
            if (index && index != ix)
                return False;
            index = ix;
            delete filegroup;
            return True;
        }

        #! clears any index base for the constraint
        clearIndex() {
            delete index;
        }

        #! adds index options onto the sql creation string
        getIndexSql(reference<string> sql, string name, *hash opts) {
            sql += sprintf(" (%s)", (foldl $1 + ", " + $2, getSqlColumnNameIterator()));
        }
    }

    #! class modeling a unique constraint
    public class FreetdsUniqueConstraint inherits SqlUtil::AbstractUniqueConstraint, FreetdsUniqueConstraintCommon {
        private {
            #! @ref True "True" if the constraint is enabled, @ref False "False" if not
            bool enabled;
        }

        #! creates the object with the given attributes
        /** @param n name of the constraint
            @param n_cols column hash
            @param e the enabled status of the constraint
            @param ts optional filegroup name
        */
        constructor(string n, hash n_cols, bool e = True, *string ts) : AbstractUniqueConstraint(n, n_cols), FreetdsUniqueConstraintCommon(ts) {
            enabled = e;
        }

        #! returns the FreetdsColumn value of the given key if it exists, otherwise throws a \c KEY-ERROR exception
        /** @par Example:
            @code{.py}
auto v = c.name;
            @endcode

            @param k the name of the key to access

            @return the value of the given key in the contained hash if it exists

            @throw KEY-ERROR the given key does not exist in the contained hash

            @note this method is called automatically when an unknown or inaccessible member name is accessed from outside the class

            @see @ref memberGate_methods
        */
        FreetdsColumn memberGate(string k) {
            if (!h.hasKey(k))
                throw "KEY-ERROR", sprintf("cannot access unknown %s %y; expecting one of: %y", getElementName(), k, h.keys());
            return h{k};
        }

        #! returns a string that can be used to create the constraint
        string getCreateSql(string table_name, *hash opts) {
            return getCreateSql(name, table_name, opts);
        }

        list getRenameSql(string table_name, string new_name) {
            # the following is only valid with FreeTDS 9.2+
            #return sprintf("alter table %s rename constraint %s to %s", table_name, name, new_name);
            list l += getDropSql(table_name);
            l += getCreateSql(new_name, table_name);
            return l;
        }

        #! returns a string that can be used to rename the constraint
        string getCreateSql(string name, string table_name, *hash opts) {
            string sql = sprintf("alter table %s add constraint %s unique ", table_name, name);
            return sql;
        }

        #! returns @ref True "True" if the constraint is enabled, @ref False "False" if not
        bool isEnabled() {
            return enabled;
        }
    }

    #! represents a FreeTDS-specific primary key constraint
    public class FreetdsPrimaryKey inherits SqlUtil::AbstractPrimaryKey, FreetdsUniqueConstraintCommon {
        #! creates an empty primary key object
        constructor() {
        }

        #! creates the object with the given attributes
        /** @param n name of the constraint
            @param c column hash
            @param ts optional filegroup name
        */
        constructor(string n, *hash c, *string ts) : AbstractPrimaryKey(n, c), FreetdsUniqueConstraintCommon(ts) {
        }

        #! returns the FreetdsColumn value of the given key if it exists, otherwise throws a \c KEY-ERROR exception
        /** @par Example:
            @code{.py}
any v = c.name;
            @endcode

            @param k the name of the key to access

            @return the value of the given key in the contained hash if it exists

            @throw KEY-ERROR the given key does not exist in the contained hash

            @note this method is called automatically when an unknown or inaccessible member name is accessed from outside the class

            @see @ref memberGate_methods
        */
        FreetdsColumn memberGate(string k) {
            if (!h.hasKey(k))
                throw "KEY-ERROR", sprintf("cannot access unknown %s %y; expecting one of: %y", getElementName(), k, h.keys());
            return h{k};
        }

        #! returns a string that can be used to create the constraint
        string getCreateSql(string table_name, *hash opts) {
            string sql = sprintf("alter table %s add constraint %s primary key", table_name, name);
            getIndexSql(\sql, name, opts);
            return sql;
        }

        #! returns a string that can be used to rename the constraint
        softlist getRenameSql(string table_name, string new_name) {
            return sprintf("sp_rename '%s.%s', '%s', 'OBJECT'", table_name, name, new_name);
        }
    }

    #! class for FreeTDS sequences
    public class FreetdsSequence inherits SqlUtil::AbstractSequence {
        #! creates the object from the arguments
        constructor(string n_name, number n_start = 1, number n_increment = 1, *softnumber n_end) : AbstractSequence(n_name, n_start, n_increment, n_end) {
        }

        #! returns a string that can be used to create the sequence in the database
        string getCreateSql(*hash opt) {
            string sql = sprintf("create sequence %s start with %d increment by %d ", name, start, increment);
            sql += max ? sprintf("maxvalue %d", max) : "no maxvalue";
            return sql;
        }

        #! returns a string that can be used to rename the sequence in the database
        /** The object is renamed in place with this call
            @param new_name the new name of the object
            @param opt this option is ignored
         */
        softlist getRenameSql(string new_name, *hash opt) {
            # no idea if this will work
            return sprintf("sp_rename '%s', '%s', 'OBJECT'", name, new_name);
        }
    }

    #! represents a FreeTDS view
    public class FreetdsView inherits SqlUtil::AbstractView {
        #! creates the object from the arguments
        constructor(string n_name, string n_src, *string n_schemaname) : AbstractView(n_name, n_src) {
            schema = n_schemaname;
            updatable = False;
        }

        #! returns a string that can be used to create the view in the database
        string getCreateSql(*hash opt) {
            # TODO/FIXME: more freetds options - what's allowed in "opt"?
            return sprintf("create %s%sview %s as %s",
                           opt.replace ? "or replace " : "",
                           opt.temp ? "temp " : "",
                           name,
                           src
                          );
        }

        #! returns a string that can be used to rename the view in the database
        /** The object is renamed in place with this call
            @param new_name the new name of the object
            @param opt this option is ignored
         */
        softlist getRenameSql(string new_name, *hash opt) {
            # no idea if this will work
            return sprintf("sp_rename '%s', '%s', 'OBJECT'", name, new_name);
        }
    }

    #! represents a FreeTDS-specific trigger
    public class FreetdsTrigger inherits SqlUtil::AbstractTrigger {
        #! creates the object and sets its name and the trigger source
        constructor(string n, string n_src) : AbstractTrigger(n, n_src) {
        }

        #! returns a string that can be used to create the trigger in the database
        softlist getCreateSql(string table_name, *hash opt) {
            return sprintf("create trigger %s %s", name, src);
        }

        #! returns a string that can be used to drop the trigger from the database
        softlist getDropSql(string table_name) {
            return sprintf("drop trigger %s", name);
        }

        #! returns @ref True "True" if the argument is equal to the current object, @ref False "False" if not
        private bool equalImpl(AbstractFunctionBase t) {
            return True;
        }

        #! returns a string that can be used to rename the trigger in the database
        softlist getRenameSql(string table_name, string new_name) {
            # no idea if this will work
            return sprintf("sp_rename '%s', '%s', 'OBJECT'", name, new_name);
        }
    }

    #! represents a FreeTDS-specific function
    public class FreetdsFunction inherits SqlUtil::AbstractFunction {
        public {
            *string args;
        }

        constructor(string n, string n_src, *string a) : AbstractFunction(n, "function", n_src) {
            args = a;
        }

        #! returns a string that can be used to create the function in the database
        softlist getCreateSql(*hash opt) {
            return sprintf("create function %s %s", name, src);
        }

        #! returns a string that can be used to drop the function from the database
        /** @param opt this argument is ignored
         */
        string getDropSql(*hash opt) {
            return sprintf("drop function %s", name);
        }

        #! returns @ref True "True" if the argument is equal to the current object, @ref False "False" if not
        private bool equalImpl(AbstractFunctionBase t) {
            return True;
        }

        #! returns a string that can be used to rename the function in the database
        /** @param new_name the new name of the object
            @param opt this argument is ignored
         */
        softlist getRenameSql(string new_name, *hash opt) {
            # no idea if this will work
            return sprintf("sp_rename '%s', '%s', 'OBJECT'", name, new_name);
        }

        #! sets the new name of the function
        setName(string new_name) {
            name = new_name;
        }
    }

    #! provides the FreeTDS-specific implementation of the AbstractDatabase interface
    public class FreetdsDatabase inherits SqlUtil::AbstractDatabase {
        public {
            #! sybase flag
            bool is_sybase;

            #! default schema for user
            string default_schema = "dbo";

            #! FreeTDS-specific schema description keys
            const FreetdsSchemaDescriptionOptions = AbstractDatabase::SchemaDescriptionOptions;

            const FreeTDS_TempSavepoint = "qore_freetds_tmp_savepoint";

            #! Options for reclaimSpace()
            const FreetdsReclaimSpaceOptions = ReclaimSpaceOptions;

            #! hash of reserved words
            const FreetdsReservedWords = (
                "add": True,
                "all": True,
                "alter": True,
                "and": True,
                "any": True,
                "as": True,
                "asc": True,
                "authorization": True,
                "backup": True,
                "begin": True,
                "between": True,
                "break": True,
                "browse": True,
                "bulk": True,
                "by": True,
                "cascade": True,
                "case": True,
                "check": True,
                "checkpoint": True,
                "close": True,
                "clustered": True,
                "coalesce": True,
                "collate": True,
                "column": True,
                "commit": True,
                "compute": True,
                "constraint": True,
                "contains": True,
                "containstable": True,
                "continue": True,
                "convert": True,
                "create": True,
                "cross": True,
                "current": True,
                "current_date": True,
                "current_time": True,
                "current_timestamp": True,
                "current_user": True,
                "cursor": True,
                "database": True,
                "dbcc": True,
                "deallocate": True,
                "declare": True,
                "default": True,
                "delete": True,
                "deny": True,
                "desc": True,
                "disk": True,
                "distinct": True,
                "distributed": True,
                "double": True,
                "drop": True,
                "dump": True,
                "else": True,
                "end": True,
                "errlvl": True,
                "escape": True,
                "except": True,
                "exec": True,
                "execute": True,
                "exists": True,
                "exit": True,
                "external": True,
                "fetch": True,
                "file": True,
                "fillfactor": True,
                "for": True,
                "foreign": True,
                "freetext": True,
                "freetexttable": True,
                "from": True,
                "full": True,
                "function": True,
                "goto": True,
                "grant": True,
                "group": True,
                "having": True,
                "holdlock": True,
                "identity": True,
                "identity_insert": True,
                "identitycol": True,
                "if": True,
                "in": True,
                "index": True,
                "inner": True,
                "insert": True,
                "intersect": True,
                "into": True,
                "is": True,
                "join": True,
                "key": True,
                "kill": True,
                "left": True,
                "like": True,
                "lineno": True,
                "load": True,
                "merge": True,
                "national": True,
                "nocheck": True,
                "nonclustered": True,
                "not": True,
                "null": True,
                "nullif": True,
                "of": True,
                "off": True,
                "offsets": True,
                "on": True,
                "open": True,
                "opendatasource": True,
                "openquery": True,
                "openrowset": True,
                "openxml": True,
                "option": True,
                "or": True,
                "order": True,
                "outer": True,
                "over": True,
                "percent": True,
                "pivot": True,
                "plan": True,
                "precision": True,
                "primary": True,
                "print": True,
                "proc": True,
                "procedure": True,
                "public": True,
                "raiserror": True,
                "read": True,
                "readtext": True,
                "reconfigure": True,
                "references": True,
                "replication": True,
                "restore": True,
                "restrict": True,
                "return": True,
                "revert": True,
                "revoke": True,
                "right": True,
                "rollback": True,
                "rowcount": True,
                "rowguidcol": True,
                "rule": True,
                "save": True,
                "schema": True,
                "securityaudit": True,
                "select": True,
                "semantickeyphrasetable": True,
                "semanticsimilaritydetailstable": True,
                "semanticsimilaritytable": True,
                "session_user": True,
                "set": True,
                "setuser": True,
                "shutdown": True,
                "some": True,
                "statistics": True,
                "system_user": True,
                "table": True,
                "tablesample": True,
                "textsize": True,
                "then": True,
                "to": True,
                "top": True,
                "tran": True,
                "transaction": True,
                "trigger": True,
                "truncate": True,
                "try_convert": True,
                "tsequal": True,
                "union": True,
                "unique": True,
                "unpivot": True,
                "update": True,
                "updatetext": True,
                "use": True,
                "user": True,
                "values": True,
                "varying": True,
                "view": True,
                "waitfor": True,
                "when": True,
                "where": True,
                "while": True,
                "with": True,
                "within group": True,
                "writetext": True,
            );

            #! Maximum precision
            const MaxPrecision = 38;
        }

        constructor(AbstractDatasource nds, *hash opts) : AbstractDatabase(nds, opts) {
            is_sybase = FreetdsDatabase::isSybase(ds);
            if (!is_sybase) {
                default_schema = nds.selectRow("select schema_name() as \"schema\"").schema;
            }
        }

        #! Returns @ref True if the driver requires a scale to support decimal values in numeric or decimal columns
        /** @return @ref True if the driver requires a scale to support decimal values in numeric or decimal columns

            @since %FreeSqlUtil 1.4.2
        */
        bool requiresScale() {
            return True;
        }

        #! Returns the maximum precision for numeric or decimal columns
        /** @return -1 means, no maximum

            @since %FreeSqlUtil 1.4.2
        */
        int getMaximumPrecision() {
            return MaxPrecision;
        }

        private list<string> featuresImpl() {
            return (DB_TABLES, DB_VIEWS, DB_SEQUENCES,
                    DB_FUNCTIONS, DB_PROCEDURES);
        }

        private FreetdsSequence makeSequenceImpl(string name, number start = 1, number increment = 1, *softnumber end, *hash opts) {
            return new FreetdsSequence(name, start, increment, end);
        }

        private *AbstractSequence getSequenceImpl(string name) {
            return new FreetdsSequence(name);
        }

        private *AbstractView getViewImpl(string name) {
            string schema;
            parse_schema_name(name, \schema, \name, default_schema);

            # information_schema will return NULL if the view definition > 4000 chars, so we use system tables
            *hash<auto> row = ds.selectRow("select smv.definition from sys.all_views v join sys.sql_modules smv on smv.object_id = v.object_id join sys.schemas s on s.schema_id = v.schema_id where s.name = %v and v.name = %v", schema, name);

            if (!row)
                return;

            if (!row.definition)
                throw "VIEW-ERROR", sprintf("view %y exists but the current user does not have permission to read the view", name);

            row.definition =~ s/create view .* as //ig;

            return new FreetdsView(name, row.definition, schema);
        }

        private FreetdsFunction makeFunctionImpl(string name, string src, *hash opts) {
            throw "UNIMPLEMENTED", "unimplemented";
        }

        private FreetdsFunction makeProcedureImpl(string name, string src, *hash opts) {
            return makeFunctionImpl(name, src, opts);
        }

        private *AbstractFunction getFunctionImpl(string name) {
            throw "UNIMPLEMENTED", "unimplemented";
        }

        private AbstractFunction getProcedureImpl(string name) {
            return getFunctionImpl(name);
        }

        private list getDropSchemaSqlImpl(hash schema_hash, *hash opt) {
            return ();
        }

        private list getAlignSqlImpl(hash schema_hash, *hash opt) {
            return ();
        }

        #! returns a list of string table names in the database
        private softlist<string> listTablesImpl() {
            return ds.select("select name from sysobjects where type = %v", "U").name;
            #return ds.select("select table_name from information_schema.tables").table_name;
        }

        #! returns a list of string function names in the database
        /** The function names will include arguments in parentheses after the names

            @return a list of string function names in the database
        */
        private list<string> listFunctionsImpl() {
            return ds.select("select routine_name from information_schema.routines").routine_name;
        }

        #! since FreeTDS only supports functions, this method is identical to listFunctionsImpl()
        /** @see listFunctionsImpl()
        */
        private list<string> listProceduresImpl() {
            return listFunctionsImpl();
        }

        private list<string> listSequencesImpl() {
            throw "UNIMPLEMENTED", "unimplemented";
        }

        private list<string> listViewsImpl() {
            return ds.select("select name from sysobjects where type = %v", "V").name;
            #return ds.select("select table_name from information_schema.views").table_name;
        }

        #! returns a string that can be used to create the schema in the database
        private string getCreateSqlImpl(list l) {
            return FreetdsDatabase::getCreateSql(l);
        }

        #! returns @ref True if the DB is a Sybase database
        static bool isSybase(AbstractDatasource ds) {
            return ds.getServerVersion() =~ /Adaptive Server/;
        }

        #! returns a string that can be used to create the schema in the database
        static string getCreateSql(list l) {
            return !l ? "" : foldl $1 + "\n" + $2, l;
        }

        #! returns driver-specific options to the base abstract class
        private hash getSchemaDescriptionOptions() {
            return FreetdsSchemaDescriptionOptions;
        }

        #! returns driver-specific options to the base abstract class
        private hash getReclaimSpaceOptions() {
            return FreetdsReclaimSpaceOptions;
        }

        #! returns the next value in the given sequence
        private softint getNextSequenceValueImpl(string name) {
            return ds.selectRow("select next value for %v as nextval", name).nextval;
        }

        #! returns the last value issued for the given sequence in the current session
        private softint getCurrentSequenceValueImpl(string name) {
            return ds.selectRow("select current_value from sys.sequences where name = %v", name).current_value;
        }

        #! returns @ref True "True" if the database supports sequences
        private bool supportsSequencesImpl() {
            # MS SQL Server 2012+ supports sequences
            if (isSybase(ds)) {
                return False;
            }
            # set vars for MS SQL Server
            *softint ver = (ds.getServerVersion() =~ x/Microsoft SQL Server ([0-9]+)/)[0];
            return ver >= 2012;
        }

        #! returns @ref True "True" if the database supports named types
        private bool supportsTypesImpl() {
            return True;
        }

        #! returns @ref True "True" if the database supports packages
        private bool supportsPackagesImpl() {
            return False;
        }

        #! rebuild index implementation. See @ref SqlUtil::AbstractDatabase::rebuildIndex()
        private bool rebuildIndexImpl(string name, *hash options) {
            ds.select("alter index %v on %v reorganize", name, options.table_name);
            return True;
        }

        #! compute statistics implementation. See @ref SqlUtil::AbstractDatabase::computeStatistics()
        private computeStatisticsImpl(*hash options) {
            if (options.tables)
                map ds.select("update statistics %v", $1), options.tables;
            else # otherwise update all statistics in the DB
                ds.select("exec sp_updatestats");
        }

        #! reclaim space implementation. See @ref SqlUtil::AbstractDatabase::reclaimSpace()
        private reclaimSpaceImpl(*hash options) {
            ds.select("dbcc shrinkdatabase");
        }

        #! @ref SqlUtil::AbstractDatabase.getPhysicalSize()
        private int getPhysicalSizeImpl() {
            *string dbname = ds.getDBName();
            if (!exists dbname) {
                return GET_PHYSICAL_DB_SIZE_NOVAL;
            }
            return ds.selectRow("select f.size * 8 as val -- to bytes
                                    from sys.master_files f
                                    inner join sys.databases d on d.database_id = f.database_id
                                    where d.name = %v", dbname).val ?? GET_PHYSICAL_DB_SIZE_NOVAL;
        }

        #! tries to execute a command so that if an error occurs the current transaction status is not lost
        private auto tryExecArgsImpl(string sql, *softlist<auto> args) {
            return FreetdsDatabase::tryExecArgs(ds, sql, args);
        }

        #! tries to execute a command so that if an error occurs the current transaction status is not lost
        private auto tryExecRawImpl(string sql, *softlist<auto> args) {
            return FreetdsDatabase::tryExecRaw(ds, sql);
        }

        #! tries to execute a command so that if an error occurs the current transaction status is not lost
        static auto tryExecArgs(AbstractDatasource ds, string sql, *softlist<auto> args) {
            ds.exec("save tran " + FreeTDS_TempSavepoint);

            auto rv;
            try {
                rv = ds.vexec(sql, args);
            }
            catch (hash<ExceptionInfo> ex) {
                ds.exec("rollback transaction " + FreeTDS_TempSavepoint);
                rethrow;
            }
            return rv;
        }

        #! tries to execute a command so that if an error occurs the current transaction status is not lost
        static auto tryExecRaw(AbstractDatasource ds, string sql) {
            ds.exec("save tran " + FreeTDS_TempSavepoint);

            auto rv;
            try {
                rv = ds.execRaw(sql);
            }
            catch (hash<ExceptionInfo> ex) {
                ds.exec("rollback transaction " + FreeTDS_TempSavepoint);
                rethrow;
            }
            return rv;
        }
    }

    #! provides the FreeTDS-specific implementation of the SqlUtil::AbstractTable interface
    public class FreetdsTable inherits SqlUtil::AbstractTable {
        public {
            #! sybase flag
            bool is_sybase;

            #! "has merge" flag for SQL server
            bool ss_has_merge = False;

            #! "has sequences" flag for SQL server
            bool ss_has_sequences = False;

            #! maps postgresql type names to type configurations
            const FreetdsTypeMap = (
                "numeric": ("qore": Type::Number, "size": SZ_NUM,),
                "decimal": ("qore": Type::Number, "size": SZ_NUM,),
                "tinyint": ("qore": Type::Int,),
                "smallint": ("qore": Type::Int,),
                "int": ("qore": Type::Int,),
                "bigint": ("qore": Type::Int,),
                "double": ("qore": Type::Float,),
                "float": ("qore": Type::Float,), # NOTE: optional precision
                "real": ("qore": Type::Float,),
                "money": ("qore": Type::Number,),
                "smallmoney": ("qore": Type::Number,),

                "datetime2": ("qore": Type::Date,),
                "datetime": ("qore": Type::Date,),
                "smalldatetime": ("qore": Type::Date,),
                "date": ("qore": Type::Date,),
                "time": ("qore": Type::Date,),

                # NOTE: "size_range" is different between MS SQL Server and Sybase SQL Anywhere Server
                # MS SQL: range is (1, 8000) or special keyword "max" for varchar types
                # Sybase: range is (1, 32767) and size is mandatory for character-length semantics
                "char": ("qore": Type::String, "size": SZ_OPT),
                "char varying": ("qore": Type::String, "size": SZ_OPT),
                "character varying": ("qore": Type::String, "size": SZ_OPT),
                "varchar": ("qore": Type::String, "size": SZ_OPT, "default_size": 80),

                # The following uni* types are used in Sybase Adaptive Server
                "unichar": ("qore": Type::String, "size": SZ_MAND,),
                "univarchar": ("qore": Type::String, "size": SZ_MAND,),
                "unitext": ("qore": Type::String,),

                # NOTE: "size_range" is different between MS SQL Server and Sybase SQL Anywhere Server
                # MS SQL: range is (1, 8000) or special keyword "max" for varbinary types
                # Sybase: range is (1, 32767)
                "binary": {
                    "qore": Type::Binary,
                    "size": SZ_OPT,
                },
                "binary varying": ("qore": Type::Binary, "size": SZ_OPT),
                "varbinary": {
                    "qore": Type::Binary,
                    "size": SZ_OPT,
                    "default_size": 80,
                },
                "varbinary(max)": ("qore": Type::Binary,),

                # The following are used in Sybase, supported & deprecated in MS SQL
                "text": ("qore": Type::String,), # domain, implemented as "long varchar"
                "image": ("qore": Type::Binary,), # domain, implemented as "long binary"
                # The following are Sybase specific
                "long binary": ("qore": Type::Binary,),
                "long varchar": ("qore": Type::String,),
            );

            #! maps qore type names to DB type names
            const QoreTypeMap = (
                "integer": "bigint",
                "float": "float",
                "number": "numeric",
                "string": "varchar",
                "binary": "varbinary",
                "bool": "tinyint",
                SqlUtil::CHAR: "char",
                SqlUtil::CLOB: "text",
            );

            #! maps qore type names to MS SQL Server type names
            const MsQoreTypeMap = QoreTypeMap + {
                SqlUtil::BLOB: "varbinary(max)",
                "date": "datetime2",
            };

            #! maps qore type names to Sybase/SAP type names
            const SybaseQoreTypeMap = QoreTypeMap + {
                "date": "datetime",
            };

            #! equal to @ref SqlUtil::AbstractTable::TableDescriptionHashOptions
            const FreetdsTableDescriptionHashOptions = AbstractTable::TableDescriptionHashOptions;

            const FreetdsColumnDescOptions = AbstractTable::ColumnDescOptions;

            const FreetdsIndexOptions = AbstractTable::IndexOptions;

            const FreetdsConstraintOptions = AbstractTable::ConstraintOptions + FreetdsIndexOptions;

            const FreetdsTableCreationOptions = AbstractTable::TableCreationOptions + FreetdsConstraintOptions;

            const FreetdsAlignTableOptions = AbstractTable::AlignTableOptions + FreetdsTableCreationOptions;

            #! select options supported by FreetdsSqlUtil
            const FreetdsSelectOptions = AbstractTable::SelectOptions + (
                "tablehint": "softstringlist",
            );

            #! query hints
            const MsSqlServerTableHints = (
                "fastfirstrow": True,
                "holdlock": True,
                "nolock": True,
                "paglock": True,
                "readcommitted": True,
                "readpast": True,
                "readuncommitted": True,
                "repeatableread": True,
                "rowlock": True,
                "serializable": True,
                "tablock": True,
                "tablockx": True,
                "updlock": True,
                "xlock": True,
            );

            #! where operator specializations for FreeTDS
            const FreetdsOpMap = DefaultOpMap + (
                OP_SUBSTR: (
                    "code": string sub (object t, string cn, softlist arg, reference<list> args, *hash jch, bool join = False, *hash ch, *hash psch) {
                        args += arg[0]; # start
                        if (!exists arg[1]) {
                            args += arg[2]; # text
                            return sprintf("substring(%s,%v,32767) = %v", cn); # NOTE: length arg is required
                        }
                        args += arg[1]; # count
                        args += arg[2]; # text
                        return sprintf("substring(%s,%v,%v) = %v", cn);
                    },
                ),
            );

            #! column operator specializations for FreeTDS
            const FreetdsCopMap = (
                COP_CAST: (
                    "code": string sub (string cve, list<auto> args) {
                        string name = QoreTypeMap{args[0]} ?? args[0];
                        hash desc = FreetdsTypeMap{name};
                        string sql = sprintf ("cast (%s as %s", cve, name);
                        switch (name) {
                            default:
                                if (desc.size == SZ_MAND) {
                                    if (!exists args[1] && !exists desc.size_range)
                                        throw "OPERATOR-ERROR", sprintf ("op_cast operator missing size for type %s", name);
                                    sql += sprintf("(%d)", args[1] ?? desc.size_range[1]);
                                }
                                else if (desc.size == SZ_NUM && exists args[1]) {
                                    sql += sprintf("(%d", args[1]);
                                    sql += exists args[2] ? sprintf(",%d)", args[2]) : ")";
                                }
                                else if (desc.size == SZ_OPT && exists args[1]) {
                                    sql += sprintf("(%d)", args[1]);
                                }
                        }
                        sql += ")";
                        return sql;
                    },
                ),
                COP_PREPEND: (
                    "arg": Type::String,
                    "sqlvalue": True,
                    "code": string sub (string cve, string arg) {
                        return sprintf("%s + %s", arg, cve);
                    },
                ),
                COP_APPEND: (
                    "arg": Type::String,
                    "sqlvalue": True,
                    "code": string sub (string cve, string arg) {
                        return sprintf("%s + %s", cve, arg);
                    },
                ),
                COP_SUBSTR: (
                    "code": string sub (string cve, list<auto> args) {
                        if (!exists args[1])
                            return sprintf("substring(%s,%d,32767)", cve, args[0]); # NOTE: length arg is required
                        return sprintf("substring(%s,%d,%d)", cve, args[0], args[1]);
                    },
                ),
                COP_YEAR: (
                    "code": string sub (string arg1, auto arg) {
                        return sprintf("substring(convert(varchar, dt, 120), 1, 4)", arg1);
                    }
                ),
                COP_YEAR_MONTH: (
                    "code": string sub (string arg1, auto arg) {
                        return sprintf("substring(convert(varchar, dt, 120), 1, 7)", arg1);
                    }
                ),
                COP_YEAR_DAY: (
                    "code": string sub (string arg1, auto arg) {
                        return sprintf("substring(convert(varchar, dt, 120), 1, 10)", arg1);
                    }
                ),
                COP_YEAR_HOUR: (
                    "code": string sub (string arg1, auto arg) {
                        return sprintf("substring(convert(varchar, dt, 120), 1, 13)", arg1);
                    }
                ),
                COP_SEQ: (
                    "nocolumn": True,
                    "withalias": True,
                    "code": string sub (*string cve, hash arg, reference<hash> psch) {
                        string sql = sprintf("next value for %s", arg.seq);
                        if (arg.as) {
                            psch{arg.as} = sql;
                            sql += " as " + arg.as;
                        }
                        return sql;
                    }
                ),
                COP_SEQ_CURRVAL: (
                    "nocolumn": True,
                    "code": string sub (*string cve, hash arg) {
                        throw "SEQUENCE-ERROR", sprintf("cannot select the current value of sequence %y because this database does not support this operation", arg.seq);
                    }
                ),
                COP_LENGTH: (
                    "code": string sub (string cve, auto arg) {
                        return sprintf("len(%s)", cve);
                    },
                ),
                COP_TRUNC_DATE: (
                    "code": string sub(string arg1, auto arg) {
                        if (!FreetdsTruncDate.hasKey(arg)) {
                            throw "COP-TRUNC-DATE-ERROR", sprintf("Not allowed format argument: %n: allowed: %n", arg, FreetdsTruncDate.keys());
                        }
                        string cmd = FreetdsTruncDate{arg};
                        return replace(cmd, "%s", arg1);
                    }
                )
            );

            #! Map @ref SqlUtil::cop_trunc_date() constants to FreeTDS internal masks
            /*  Impl. note here. There is shorter workaround for this, but it does not work with seconds
                and with dates older than 1.1.1970. (minutes will overflow later too etc.).
                So no usage for: dateadd(ss, datediff(ss, 0, %s), 0) for example
             */
            const FreetdsTruncDate = (
                DT_YEAR     : "datetimefromparts(datepart(year, %s), 1, 1, 0, 0, 0, 0)",
                DT_MONTH    : "datetimefromparts(datepart(year, %s), datepart(month, %s), 1, 0, 0, 0, 0)",
                DT_DAY      : "datetimefromparts(datepart(year, %s), datepart(month, %s), datepart(day, %s), 0, 0, 0, 0)",
                DT_HOUR     : "datetimefromparts(datepart(year, %s), datepart(month, %s), datepart(day, %s), datepart(hour, %s), 0, 0, 0)",
                DT_MINUTE   : "datetimefromparts(datepart(year, %s), datepart(month, %s), datepart(day, %s), datepart(hour, %s), datepart(minute, %s), 0, 0)",
                DT_SECOND   : "datetimefromparts(datepart(year, %s), datepart(month, %s), datepart(day, %s), datepart(hour, %s), datepart(minute, %s), datepart(second, %s), 0)",
            );

            #! a hash of default value operator descriptions for FreeTDS
            const FreetdsIopMap = DefaultIopMap + (
                IOP_SEQ: (
                    "arg": Type::String,
                    "placeholder": "next value for %v",
                ),
            );

            #! a hash of default update operator definitions for FreeTDS
            const FreetdsUopMap = DefaultUopMap + (
                COP_SEQ: (
                    "nocolumn": True,
                    "withalias": True,
                    "code": string sub (*string cve, string arg) {
                        return sprintf("next value for %s", arg);
                    }
                ),
                COP_SEQ_CURRVAL: (
                    "nocolumn": True,
                    "code": string sub (*string cve, string arg) {
                        throw "SEQUENCE-ERROR", sprintf("cannot select the current value of sequence %y because this database does not support this operation", arg);
                    }
                ),
            );
        }

        private {
            #! filegroup name for the table, if known
            *string filegroup;

            #! schema name for the table
            string schema;

            #! contains any trigger functions supporting triggers on the table
            Functions triggerFunctions;

            #! the default schema for the user
            string default_schema = "dbo";
        }

        constructor(AbstractDatasource nds, string nname, *hash opts) : AbstractTable(nds, nname, opts) {
            is_sybase = FreetdsDatabase::isSybase(ds);
            # set vars for MS SQL Server
            if (!is_sybase) {
                *softint ver = (ds.getServerVersion() =~ x/Microsoft SQL Server ([0-9]+)/)[0];
                if (ver >= 2008) {
                    ss_has_merge = True;
                    if (ver >= 2012) {
                        ss_has_sequences = True;
                    }
                }
                default_schema = nds.selectRow("select schema_name() as \"schema\"").schema;
            }
            # see if there is a schema in the name
            parse_schema_name(nname, \schema, \name, default_schema);
        }

        #! returns the schema name
        string getSchemaName() {
            return schema;
        }

        #! returns the data filegroup name for the table or @ref nothing if none is known
        *string getTablespaceName() {
            return filegroup;
        }

        #! returns a closure for performing upserts; if the underlying dataserver supports an optimized \c MERGE statement (Microsoft SQL Server 2008+), the \a upsert_strategy argument is ignored and a closure using a merge statement is returned, otherwise the standard upsert closure is returned according to @ref SqlUtil::AbstractTable::getUpsertClosure()
        code getUpsertClosure(hash<auto> row, int upsert_strategy = UpsertAuto, *hash opt) {
            if (!ss_has_merge)
                return AbstractTable::getUpsertClosure(row, upsert_strategy, opt);

            Columns cols = checkUpsertRow(row, \upsert_strategy);

            # if the strategy is "select first", then respect this strategy; this is a slow upsert method anyway
            if (upsert_strategy == UpsertSelectFirst)
                return getUpsertSelectFirst(cols, row, opt);

            # get update columns
            list updc = ();
            # hash of columns to skip on update if applicable
            *hash suh = map {$1: True}, opt.omit_update;
            map updc += $1, keys row, !cols.hasKey($1) && !suh.$1;
            # cannot use merge where only the join columns are present
            if (!updc)
                return getUpsertInsertOnly(cols, row, opt);

            string sql = sprintf("merge %s t using (select ", getSqlName());
            sql += foldl $1 + "," + $2, (map "%v", keys row);
            sql += ") as source (";
            sql += foldl $1 + "," + $2, row.keyIterator();
            sql += ") on (";
            sql += foldl $1 + " and " + $2, (map sprintf("t.%s=source.%s", $1, $1), getColumnSqlNames(cols.keys()));
            sql += ")";
            if (upsert_strategy != UpsertInsertOnly) {
                sql += sprintf(" when matched then update set ");
                # get update columns
                sql += (foldl $1 + "," + $2, (map sprintf("t.%s=source.%s", $1, $1), getColumnSqlNames(updc)));
            }
            if (upsert_strategy != UpsertUpdateOnly) {
                sql += sprintf(" when not matched then insert (");
                sql += (foldl $1 + "," + $2, getColumnSqlNames(row.keys()));
                sql += ") values (";
                sql += (foldl $1 + "," + $2, (map "source." + $1, keys row));
                sql += ")";
            }
            sql += ";";

            #printf("sql: %s\n", sql);

            if (upsert_strategy == UpsertInsertOnly) {
                return int sub (hash crow) {
                    list<auto> args = crow.values();
                    #on_error printf("SQL: %s args: %y\n", sql, args);
                    return ds.vexec(sql, args) ? UR_Inserted : UR_Unchanged;
                };
            }

            if (upsert_strategy == UpsertUpdateOnly) {
                return int sub (hash crow) {
                    list<auto> args = crow.values();
                    #on_error printf("SQL: %s args: %y\n", sql, args);
                    return ds.vexec(sql, args) ? UR_Verified : UR_Unchanged;
                };
            }

            return int sub (hash crow) {
                list<auto> args = crow.values();
                #on_error printf("SQL: %s args: %y\n", sql, args);
                ds.vexec(sql, args);
                return UR_Verified;
            };
        }

        #! returns @ref False "False" because the freetds driver does not support array binds / bulk DML operations
        bool hasArrayBind() {
            return False;
        }

        #! returns the name of the table to be used in SQL (with a possible qualifiers for schema, etc)
        string getSqlName() {
            return schema + "." + name;
        }

        #! returns the "where" operator map for this object
        hash<auto> getWhereOperatorMap() {
            return FreetdsOpMap;
        }

        private string getFromIntern(string from, *hash qh) {
            # grep from clause with optional hints
            string hstr = from;
            *hash hh = !is_sybase ? MsSqlServerTableHints : NOTHING;
            list l;
            foreach string hint in (qh.tablehint) {
                # explicit support for index() hints
                if (hint =~ /^index/) {
                    # remove whitespace
                    string istr = replace(hint, " ", "");
                    # get index list
                    *string ilstr = (istr =~ x/^index\((.*)\)$/)[0];
                    if (!ilstr.val())
                        throw "TABLEHINT-ERROR", sprintf("\"index\" table hint is missing the index arguments in "
                            "parentheses: %y", hint);
                    # manually process hints as integers to ensure there are no SQL injections
                    l += ("index(" + (foldl $1 + "," + $2, (map $1.toInt(), ilstr.split(","))) + ")");
                    continue;
                }

                if (!hh{hint})
                    throw "TABLEHINT-ERROR", sprintf("unknown hint %y; known hints: %y", hint, hh.keys());
                l += hint;
            }
            if (l)
                hstr += " with (" + (foldl $1 + "," + $2, l) + ")";
            #printf("from: %y opt: %y hstr: %y\n", from, qh, hstr);
            return hstr;
        }

        private hash getTableCreationOptions() {
            return FreetdsTableCreationOptions;
        }

        private hash getTableDescriptionHashOptions() {
            return FreetdsTableDescriptionHashOptions;
        }

        private hash getColumnDescOptions() {
            return FreetdsColumnDescOptions;
        }

        private hash getIndexOptions() {
            return FreetdsIndexOptions;
        }

        private hash getConstraintOptions() {
            return FreetdsConstraintOptions;
        }

        private hash getAlignTableOptions() {
            return FreetdsAlignTableOptions;
        }

        #! returns the column operator map for this object
        private hash getColumnOperatorMapImpl() {
            return FreetdsCopMap;
        }

        #! returns the insert operator map for this object
        private hash getInsertOperatorMap() {
            return FreetdsIopMap;
        }

        #! returns the raw (default) update operator map for this object
        private hash getRawUpdateOperatorMap() {
            return FreetdsUopMap;
        }

        #! returns the select options for this driver
        private hash getSelectOptions() {
            return FreetdsSelectOptions;
        }

        private bool checkExistenceImpl() {
            *hash qh = ds.selectRow("select name from sysobjects where type = %v and name = %v", "U", name);
            #*hash qh = ds.selectRow("select * from information_schema.tables where table_schema = %v and
            #   table_name = %v", schema, name);
            if (qh)
                return inDb = True;
            return False;
        }

        private Columns describeImpl() {
            return is_sybase ? describeSybaseImpl() : describeMssqlImpl();
        }

        private Columns describeSybaseImpl() {
            # get column descriptions
            *hash qh = ds.select("select
	sc.name column_name, t.name data_type, sc.prec numeric_precision, sc.scale numeric_scale, sc.length,
    substring(cm.text, 10, 500) column_default,
    case sc.status & 0x8 when 0x8 then 'YES' else 'NO' end is_nullable
from
	syscolumns sc
	join sysobjects so on (sc.id = so.id)
	left join systypes t on (/*sc.type = t.type and */sc.usertype = t.usertype)
	left join syscomments cm on (cm.id = case when sc.cdefault = 0 then sc.computedcol else sc.cdefault end)
where
	so.name = %v", name);
            if (!qh.column_name)
                throw "TABLE-ERROR", sprintf("cannot retrieve table information for table %y in %y", getSqlName(),
                    dsdesc);

            hash rv;
            foreach hash<auto> row in (qh.contextIterator()) {
                row.column_name = row.column_name.lwr();
                *hash th = FreetdsTypeMap.(row.data_type);
                softint size = row.length;
                switch (th.qore) {
                    case Type::Int:
                    case Type::Float: {
                        row.numeric_precision = 0;
                        size = 0;
                        break;
                    }
                }

                FreetdsColumn c;
                *string defval = row.column_default;

                if (row.numeric_precision)
                    c = new FreetdsNumericColumn(row.column_name, row.data_type, th.qore, row.numeric_precision,
                        row.is_nullable == "YES", defval, NOTHING, 0, row.numeric_scale);
                else
                    c = new FreetdsColumn(row.column_name, row.data_type, th.qore, exists size ? size : 0,
                        row.is_nullable == "YES", defval, NOTHING, row.length);

                rv.(row.column_name) = c;
            }

            return new Columns(rv);
        }

        private Columns describeMssqlImpl() {
            # get column descriptions
            *hash qh = ds.select("select * from information_schema.columns where table_schema = %v and "
                "table_name = %v order by ordinal_position", schema, name);
            if (!qh.column_name)
                throw "TABLE-ERROR", sprintf("cannot retrieve table information for table %y in %y", getSqlName(),
                    dsdesc);

            hash rv;
            foreach hash<auto> row in (qh.contextIterator()) {
                row.column_name = row.column_name.lwr();
                *hash th = FreetdsTypeMap.(row.data_type);
                softint size = row.character_maximum_length ? row.character_maximum_length : row.numeric_precision;
                switch (th.qore) {
                    case Type::Int:
                    case Type::Float: {
                        row.numeric_precision = 0;
                        size = 0;
                        break;
                    }
                }

                FreetdsColumn c;
                *string defval = row.column_default;
                # normalize default value expressions
                if (defval =~ /^\(\(.*\)\)$/)
                    defval =~ s/^\(\((.*)\)\)$/$1/;

                if (row.numeric_precision)
                    c = new FreetdsNumericColumn(row.column_name, row.data_type, th.qore, row.numeric_precision,
                        row.is_nullable == "YES", defval, NOTHING, 0, row.numeric_scale);
                else
                    c = new FreetdsColumn(row.column_name, row.data_type, th.qore, exists size ? size : 0,
                        row.is_nullable == "YES", defval, NOTHING, row.character_octet_length);

                rv.(row.column_name) = c;
            }

            return new Columns(rv);
        }

        private FreetdsPrimaryKey getPrimaryKeyImpl() {
            return is_sybase ? getPrimaryKeySybaseImpl() : getPrimaryKeyMssqlImpl();
        }

        private FreetdsPrimaryKey getPrimaryKeySybaseImpl() {
            *hash pkh = ds.selectRow("select
	object_name(i.id) table_name, i.indid, i.keycnt,
	-- i.status & 2048,
	i.name constraint_name, i.id,
    -- identifies pkey constrained clustered indexes
	case (i.status2 & 512) when 512 then 'YES' else 'NO' END is_clustered,
	index_col(object_name(i.id),i.indid,1) col1,
	index_col(object_name(i.id),i.indid,2) col2,
	index_col(object_name(i.id),i.indid,3) col3,
	index_col(object_name(i.id),i.indid,4) col4,
	index_col(object_name(i.id),i.indid,5) col5,
	index_col(object_name(i.id),i.indid,6) col6,
	index_col(object_name(i.id),i.indid,7) col7,
	index_col(object_name(i.id),i.indid,8) col8,
	index_col(object_name(i.id),i.indid,9) col9,
	index_col(object_name(i.id),i.indid,10) col10,
	index_col(object_name(i.id),i.indid,11) col11,
	index_col(object_name(i.id),i.indid,12) col12,
	index_col(object_name(i.id),i.indid,13) col13,
	index_col(object_name(i.id),i.indid,14) col14,
	index_col(object_name(i.id),i.indid,15) col15,
	index_col(object_name(i.id),i.indid,16) col16,
	s.name segment_name
from sysindexes i
	inner join sysobjects o on (o.id = i.id)
	inner join syssegments s on (i.segment = s.segment)
where
	o.type = 'U'
	and i.indid between 1 and 254
	and o.uid = 1
	and (((i.status2 & 3) > 0)
		 or charindex(convert(varchar,i.id),i.name) > 0)
    and object_name(i.id) = %v", name);
            if (!pkh.constraint_name)
                return new FreetdsPrimaryKey();

            hash rv;
            for (int i = 1; i <= pkh.keycnt; ++i) {
                string key = pkh{"col" + i}.lwr();
                rv{key} = columns{key};
            }
            return new FreetdsPrimaryKey(pkh.constraint_name, rv);
        }

        private FreetdsPrimaryKey getPrimaryKeyMssqlImpl() {
            *hash pkh = ds.selectRow("select * from information_schema.table_constraints where table_schema = %v and "
                "table_name = %v and constraint_type = 'PRIMARY KEY'", schema, name);
            if (!pkh.constraint_name)
                return new FreetdsPrimaryKey();

            # get primary key description
            *hash qh = ds.select("select * from information_schema.key_column_usage where table_schema = %v and "
                "table_name = %v and constraint_name = %v order by ordinal_position", schema, name,
                pkh.constraint_name);
            if (!qh.constraint_name)
                return new FreetdsPrimaryKey();

            #printf("FreetdsTable::getPrimaryKeyImpl(): %s: %N\n", getName(), qh);
            hash rv = map {$1: columns.$1}, (map $1.lwr(), qh.column_name);

            return new FreetdsPrimaryKey(pkh.constraint_name.lwr(), rv);
        }

        private Indexes getIndexesImpl() {
            return is_sybase ? getIndexesSybaseImpl() : getIndexesMssqlImpl();
        }

        private Indexes getIndexesSybaseImpl() {
            return new Indexes();
        }

        private Indexes getIndexesMssqlImpl() {
            hash rv;

            # get index descriptions
            *hash qh = ds.select("select
	t.name table_name, i.name index_name, i.is_unique, i.is_primary_key, c.name column_name
from
	sys.indexes i, sys.tables t, sys.schemas s, sys.index_columns ic, sys.columns c
where
	t.type_desc = 'USER_TABLE' and i.object_id = t.object_id
        and i.index_id = ic.index_id and t.schema_id = s.schema_id
	and t.object_id = ic.object_id and c.object_id = t.object_id and ic.column_id = c.column_id
        and i.name is not null and i.is_primary_key != 1
	and s.name = %v and t.name = %v order by i.name, ic.key_ordinal", schema, name);

            if (qh.index_name) {
                hash<auto> ih;
                foreach hash<auto> row in (qh.contextIterator()) {
                    row.column_name = row.column_name.lwr();
                    row.index_name = row.index_name.lwr();

                    if (!ih.(row.index_name)) {
                        ih{row.index_name} = <auto>{
                            "unique": row.is_unique,
                            "primary": row.is_primary_key,
                        };
                    }
                    # send "blank" column for function index
                    if (row.column_name =~ /\(.*\)/ || !columns.hasKey(row.column_name)) {
                        ih.(row.index_name).columns{row.column_name} = {};
                    } else {
                        ih.(row.index_name).columns{row.column_name} = columns{row.column_name};
                    }
                }

                foreach hash<auto> i in (ih.pairIterator()) {
                    # check primary key index and add filegroup to primary key definition
                    if (i.primary && !primaryKey.empty()) {
                        FreetdsPrimaryKey pk = cast<FreetdsPrimaryKey>(primaryKey);
                        if (i.value.filegroup && !pk.filegroup)
                            pk.filegroup = i.value.filegroup;
                        continue;
                    }
                    # check unique indexes to make sure they are not matched with a unique constraint
                    if (i.value.unique && constraints.hasKey(i.key)
                        && (constraints{i.key} instanceof AbstractUniqueConstraint)) {
                        FreetdsUniqueConstraint uk = cast<FreetdsUniqueConstraint>(constraints{i.key});
                        if (uk.matchKeys(i.value.columns)) {
                            # set filegroup in constraint
                            if (i.value.filegroup && !uk.getTablespace())
                                uk.setTablespace(i.value.filegroup);
                            continue;
                        }
                    }
                    rv.(i.key) = new FreetdsIndex(i.key, i.value.unique, i.value.columns,
                        i.value.filegroup ? i.value.filegroup : NOTHING);
                }
            }

            return new Indexes(rv);
        }

        private ForeignConstraints getForeignConstraintsImpl(*hash opts) {
            return is_sybase ? getForeignConstraintsSybaseImpl() : getForeignConstraintsMssqlImpl();
        }

        private ForeignConstraints getForeignConstraintsSybaseImpl() {
            return new ForeignConstraints();
        }

        private ForeignConstraints getForeignConstraintsMssqlImpl() {
            hash rv;
            # get foreign referential constraints
            *hash qh = ds.select("select tc.constraint_name, c1.column_name source_column,
                c2.column_name target_column
from
    information_schema.table_constraints tc,
    information_schema.referential_constraints rc,
    information_schema.key_column_usage c1,
    information_schema.key_column_usage c2
where
	tc.table_schema = %v and tc.table_name = %v and tc.constraint_type = 'FOREIGN KEY'
	and tc.constraint_catalog = rc.constraint_catalog and tc.constraint_name = rc.constraint_name
	and rc.constraint_catalog = c1.constraint_catalog and rc.constraint_schema = c1.constraint_schema
        and rc.constraint_name = c1.constraint_name
	and rc.unique_constraint_catalog = c2.constraint_catalog and rc.unique_constraint_schema = c2.constraint_schema
        and rc.unique_constraint_name = c2.constraint_name
	and c2.ordinal_position = c1.ordinal_position
order by
	rc.constraint_name, c1.ordinal_position",
                                 name, schema);
            if (qh.constraint_name) {
                hash ch;
                foreach hash<auto> row in (qh.contextIterator()) {
                    reference<hash> c = \ch.(row.constraint_name.lwr());
                    row.source_column = row.source_column.lwr();
                    c.columns.(row.source_column) = columns{row.source_column};
                    c.target.table = row.target_table.lwr();
                    c.target.columns.(row.target_column.lwr()) = True;
                }

                foreach hash c in (ch.pairIterator()) {
                    # get a description of the target table's columns
                    Columns targ_columns = getReferencedTableColumnsUnlocked(c.value.target.table, opts.table_cache);
                    ForeignConstraintTarget fct(c.value.target.table,
                        targ_columns.subset(c.value.target.columns.keys()));
                    rv.(c.key) = new FreetdsForeignConstraint(c.key, new Columns(c.value.columns), fct);
                }
            }

            return new ForeignConstraints(rv);
        }

        private Constraints getConstraintsImpl() {
            return is_sybase ? getConstraintsSybaseImpl() : getConstraintsMssqlImpl();
        }

        private Constraints getConstraintsSybaseImpl() {
            return new Constraints();
        }

        private Constraints getConstraintsMssqlImpl() {
            # get check constraints
            *hash qh;
            hash rv;
            #foreach hash<auto> row in (qh.contextIterator())
            #    rv.(row.constraint_name) = new FreetdsCheckConstraint(row.constraint_name, row.consrc);

            Constraints c = new Constraints(rv);

            # get unique constraints
            qh = ds.select("select
	tc.constraint_name, c1.column_name
from
	information_schema.table_constraints tc,
	information_schema.key_column_usage c1
where
	tc.table_schema = %v and tc.table_name = %v and tc.constraint_type = 'UNIQUE'
	and tc.constraint_catalog = c1.constraint_catalog and tc.constraint_schema = c1.constraint_schema and
        tc.constraint_name = c1.constraint_name
order by
	tc.constraint_name, c1.ordinal_position", schema, name);
            delete rv;
            foreach hash<auto> row in (qh.contextIterator()) {
                reference<FreetdsUniqueConstraint> ch = \rv.(row.constraint_name.lwr());
                if (!ch)
                    ch = new FreetdsUniqueConstraint(row.constraint_name, {}, row.status == "ENABLED");
                row.column_name = row.column_name.lwr();
                ch.add(row.column_name, columns{row.column_name});
            }

            # add unique constraints to constraint hash
            map c.add($1.key, $1.value), rv.pairIterator();

            return c;
        }

        private Triggers getTriggersImpl() {
            return new Triggers();
        }

        #! returns a string that can be used to create the table in the database
        private string getCreateTableSqlImpl(*hash opt) {
            string sql = sprintf("create table %s (\n", name);

            sql += foldl $1 + ",\n" + $2, (map "  " + $1.getCreateSql(self), columns.iterator());
            sql += "\n)";

            *string ts = opt.data_tablespace ? opt.data_tablespace : filegroup;
            if (ts)
                sql += sprintf(" on %s", ts);

            return sql;
        }

        private *list getCreateMiscSqlImpl(*hash opt, bool cache) {
        }

        private *list getAlignSqlImpl(AbstractTable table, *hash opt) {
        }

        #! returns a string that can be used to create the table in the database
        private string getCreateSqlImpl(list l) {
            return FreetdsDatabase::getCreateSql(l);
        }

        private string getRenameSqlImpl(string new_name) {
            return sprintf("exec cp_name '%s', '%s'", getSqlName(), new_name);
        }

        private AbstractColumn addColumnImpl(string cname, hash opt, bool nullable = True) {
            if (opt.precision)
                return new FreetdsNumericColumn(cname, opt.native_type, opt.qore_type, opt.precision, nullable,
                    opt.default_value, opt.comment, 0, opt.scale);
            return new FreetdsColumn(cname, opt.native_type, opt.qore_type, opt.size, nullable, opt.default_value,
                opt.comment, 0);
        }

        private AbstractPrimaryKey addPrimaryKeyImpl(string cname, hash ch, *hash opt) {
            return new FreetdsPrimaryKey(cname, ch, opt.index_filegroup);
        }

        private AbstractIndex addIndexImpl(string iname, bool enabled, hash ch, *hash opt) {
            return new FreetdsIndex(iname, enabled, ch, opt.index_filegroup);
        }

        private AbstractForeignConstraint addForeignConstraintImpl(string cname, hash ch, string table, hash tch,
                *hash opt) {
            ForeignConstraintTarget fct(table, new Columns(tch));
            return new FreetdsForeignConstraint(cname, new Columns(ch), fct);
        }

        private AbstractCheckConstraint addCheckConstraintImpl(string cname, string src, *hash opt) {
            return new FreetdsCheckConstraint(cname, src);
        }

        private AbstractUniqueConstraint addUniqueConstraintImpl(string cname, hash ch, *hash opt) {
            return new FreetdsUniqueConstraint(cname, ch, True, opt.index_filegroup);
        }

        private AbstractTrigger addTriggerImpl(string tname, string src, *hash opt) {
            return new FreetdsTrigger(tname, src);
        }

        private bool tryInsertImpl(string sql, hash<auto> row) {
            try {
                ds.vexec(sql, row.values());
            } catch (hash<ExceptionInfo> ex) {
                if (isDuplicateRowError(ex)) {
                    return False;
                }
                rethrow;
            }
            return True;
        }

        #! Returns True if the exception was raised because of a duplicate row / key error
        /** @since FreetdsSqlUtil 1.4.1
        */
        private bool isDuplicateRowErrorImpl(hash<ExceptionInfo> ex) {
            return (ex.desc =~ /Cannot insert duplicate/);
        }

        private hash getQoreTypeMapImpl() {
            return is_sybase ? SybaseQoreTypeMap : MsQoreTypeMap;
        }

        private hash getTypeMapImpl() {
            return FreetdsTypeMap;
        }

        #! returns a string for use in SQL queries representing the DB-specific value of the argument
        /** returns NOTHING if the type cannot be converted to an SQL string
        */
        private *string getSqlValueImpl(auto v) {
            switch (v.typeCode()) {
                case NT_FLOAT:
                case NT_INT: return v.toString();

                case NT_NUMBER: return string(v);

                # double any single quotes in strings
                case NT_STRING: v =~ s/'/''/g; return "'" + v + "'";

                case NT_NULL:
                case NT_NOTHING: return "null";

                case NT_BOOLEAN: return v ? "true" : "false";

                case NT_DATE: return sprintf("cast('%s' as datetimeoffset(6))",
                    TimeZone::get().date(v).format("YYYY-MM-DD HH:mm:SS.us"));
            }
        }

        #! returns the column name for use in SQL strings; subclasses can return a special string in case the column name is a reserved word
        string getColumnSqlName(string col) {
            return FreetdsDatabase::FreetdsReservedWords{col.lwr()} ? ("\"" + col + "\"") : col;
        }

        #! returns a list of column names for use in SQL strings; subclasses can process the argument list in case a column name is a reserved word
        list getColumnSqlNames(softlist cols) {
            return map getColumnSqlName($1), cols;
        }

        private bool emptyImpl() {
            return True;
        }

        #! clears FreeTDS-specific table information
        private clearImpl() {
        }

        private setupTableImpl(hash desc, *hash opt) {
        }

        #! returns @ref True "True" if the database links constraints to indexes (ie dropping the constraint drops the index, etc)
        private bool constraintsLinkedToIndexesImpl() {
            return True;
        }

        #! returns @ref True "True" if the database automatically creates a unique constraint with a unique index
        private bool uniqueIndexCreatesConstraintImpl() {
            return True;
        }

        #! returns @ref True "True" if the database support tablespaces
        private bool supportsTablespacesImpl() {
            return False;
        }

        #! processes a string for use in SQL select statements with "limit" but no "orderby" or "offset"
        private doSelectLimitOnlyUnlockedImpl(reference<string> sql, reference<list<auto>> args, *hash<auto> qh) {
            if (!qh.limit) {
                return;
            }

            # this rule is broken here with reason:
            # In a SELECT statement, always use an ORDER BY clause with the TOP clause.
            # This is the only way to predictably indicate which rows are affected by TOP
            sql = regex_subst(sql, "^select ", sprintf("select top %d ", qh.limit));
            args += qh.limit;
        }

        #! processes a string for use in SQL select statements when there is an "order by" and "offset" argument
        private doSelectOrderByWithOffsetSqlUnlockedImpl(reference<string> sql, reference<list<auto>> args,
                *hash<auto> qh, *hash<auto> jch, *hash<auto> ch, *hash<auto> psch, list<auto> coll) {
            if (is_sybase) {
                # NOTE Sybase ASE does not support this, but Sybase SQL Anywhere does
                throw "UNIMPLEMENTED", "offset not yet implemented";
            }

            doSelectOrderBySqlUnlocked(\sql, \args, qh, jch, ch, psch, coll);

            sql += " offset %v rows";
            args += qh.offset ?? 0;

            if (qh.limit) {
                sql += " fetch next %v rows only";
                args += qh.limit;
            }
        }

        #! tries to execute a command so that if an error occurs the current transaction status is not lost
        private auto tryExecArgsImpl(string sql, *softlist<auto> args) {
            return FreetdsDatabase::tryExecArgs(ds, sql, args);
        }

        #! tries to execute a command so that if an error occurs the current transaction status is not lost
        private auto tryExecRawImpl(string sql, *softlist<auto> args) {
            return FreetdsDatabase::tryExecRaw(ds, sql);
        }

        #! db-specific copy actions
        private copyImpl(AbstractTable old) {
        }

        private *hash doReturningImpl(hash opt, reference<string> sql, list<auto> args) {
            list l = ();
            foreach auto v in (opt.returning) {
                hash rh;
                switch (v.typeCode()) {
                    case NT_STRING: rh.key = v; break;
                    case NT_HASH: rh = v; break;
                    default: throw "RETURNING-ERROR", sprintf("got type %y in \"returning\" option; "
                        "expected \"string\" or \"hash\"", v.type());
                }
                if (!rh.key.val() || rh.key.typeCode() != NT_STRING)
                    throw "RETURNING-ERROR", sprintf("got %y for \"returning\" option key value instead of name of "
                        "output column", rh.key.type());

                *FreetdsColumn c = columns{rh.key};
                if (!c)
                    throw "COLUMN-ERROR", sprintf("%s.%s is not a valid column for the \"returning\" option (valid "
                        "columns: %y)", name, rh.key, columns.keys());
                l += rh.key;
                args += rh.type ?* c.qore_type ?* Type::String;
            }
            if (l) {
                throw "UNIMPLEMENTED", "output not yet implemented";
            }

            *hash h = execData(opt, sql, args);
            return h ? map {$1.key: $1.value[0]}, h.pairIterator() : h;
        }

        private softbool tryUpdate(string sql, hash<auto> row, Columns cols, list updc) {
            list<auto> args = row{updc}.values() + row{cols.keys()}.values();
            auto x = ds.vexec(sql, args);
            return x.typeCode() == NT_HASH ? x.firstValue() : x;
        }

        #! returns the type for number / numeric columns for the database so that data conversions can be handled properly
        private AbstractDataProviderType getNumericTypeImpl(string native_type, bool nullable, *hash<auto> options) {
            return new FreetdsNumberDataType(native_type, nullable, options);
        }

        #! get DB-specific savepoint helper
        /** @param savepoint the savepoint string, if not given a unique savepoint string will be generated

            @since SqlUtil 1.6
        */
        private AbstractSavepointHelper getSavepointHelperImpl(*string savepoint) {
            return new FreetdsSavepointHelper(ds, savepoint);
        }
    }
}