def environment_needs_upgrade(self):
     """
     Called when Trac checks whether the environment needs to be upgraded.
     Returns `True` if upgrade is needed, `False` otherwise.
     """
     dbm = DatabaseManager(self.env)
     return dbm.get_database_version(db_version_key) != db_version

def do_upgrade(env, ver, cursor):
    """Add an auto-increment primary key to `node_change` table and indices
    (repos, rev, path) and (repos, path, rev) (#3676).
    """
    db_connector, _ = DatabaseManager(env)._get_connector()
    table = Table('node_change', key='id')[
        Column('id', auto_increment=True),
        Column('repos', type='int'),
        Column('rev', key_size=40),
        Column('path', key_size=255),
        Column('node_type', size=1),
        Column('change_type', size=1),
        Column('base_path'),
        Column('base_rev'),
        Index(['repos', 'rev', 'path']),
        Index(['repos', 'path', 'rev'])]

    with env.db_transaction:
        cursor.execute("""CREATE TEMPORARY TABLE node_change_old AS
                          SELECT * FROM node_change""")
        cursor.execute("DROP TABLE node_change")

        for stmt in db_connector.to_sql(table):
            cursor.execute(stmt)

        cursor.execute("""\
            INSERT INTO node_change
            (repos,rev,path,node_type,change_type,base_path,base_rev)
            SELECT repos,rev,path,node_type,change_type,base_path,base_rev
            FROM node_change_old""")
        cursor.execute("DROP TABLE node_change_old")

def trac_db_transaction(env):
    """
    Context manager to handle database connection and cursor from trac environment's
    read / write connection. This handles automatic commits, rollbacks and connection
    closing.

    Internally, this uses Trac's connection pool via the Trac DatabaseManager class.
    This is because it would appear that to multiproject uses, Trac's with_transaction()
    is not sufficient.

    For examples of use, see db_transaction()

    :param Environment env: The Trac Environment in use.
    """
    conn = None
    cursor = None

    try:
        dm = DatabaseManager(env)
        conn = dm.get_connection()
    except Exception:
        env.log.exception("Failed to get database connection from trac database manager")
        raise

    try:
        cursor = conn.cursor()
        yield cursor
        conn.commit()
    except Exception:
        env.log.error("Failed to perform transaction to database")
        conn.rollback()
        raise
    finally:
        cursor.close()
        conn.close()

def do_upgrade(env, ver, cursor):
    """Add two more subscription db tables for a better normalized schema."""

    connector = DatabaseManager(env).get_connector()[0]
    for table in schema:
        for stmt in connector.to_sql(table):
            cursor.execute(stmt)

def do_upgrade(env, ver, cursor):
    """Change `subscription_attribute` db table:

    + 'subscription_attribute.authenticated'
    """
    cursor.execute("""
        CREATE TEMPORARY TABLE subscription_attribute_old
            AS SELECT * FROM subscription_attribute
    """)
    cursor.execute("DROP TABLE subscription_attribute")

    connector = DatabaseManager(env).get_connector()[0]
    for table in schema:
        for stmt in connector.to_sql(table):
            cursor.execute(stmt)
    cursor.execute("""
        INSERT INTO subscription_attribute
               (sid,authenticated,class,realm,target)
        SELECT o.sid,s.authenticated,o.class,o.realm,o.target
          FROM subscription_attribute_old AS o
          LEFT JOIN session AS s
               ON o.sid=s.sid
    """)
    cursor.execute("DROP TABLE subscription_attribute_old")

    # DEVEL: Think that an old 'subscriptions' db table may still exist here.
    cursor.execute("DROP TABLE IF EXISTS subscriptions")

def trac_db_query(env):
    """
    Context manager to handle database connection and cursor from trac environment's
    read only connection. This does not attempt to roll back or commit, the connection
    is meant only for accessing the data. For examples on use, see db_query().

    Internally, this uses Trac's connection pool via the Trac DatabaseManager class

    :param Environment env: The Trac environment
    """
    conn = None
    cursor = None

    try:
        dm = DatabaseManager(env)
        conn = dm.get_connection()
    except Exception:
        env.log.exception("Failed to get database connection from trac database manager")
        raise

    try:
        # NOTE: Trac's connection does not support alternative cursor types!
        cursor = conn.cursor()
        yield cursor
    except Exception:
        env.log.error("Failed to query database")
        raise
    finally:
        cursor.close()
        conn.close()

 def upgrade_environment(self, db):
     db_connector, _ = DatabaseManager(self.env).get_connector() 
     cursor = db.cursor()
     dbver = self.get_db_version()
     if dbver == 0:
         self.env.log.info("Initialize %s database schema to version %s",
                      PLUGIN_NAME, PLUGIN_VERSION)
         for table in SCHEMA:
             for stmt in db_connector.to_sql(table):
                 cursor.execute(stmt)
         cursor.execute("""
             INSERT INTO system (name, value)
             VALUES (%s, %s)
             """, (PLUGIN_NAME, PLUGIN_VERSION))
     else:
         while dbver != PLUGIN_VERSION:
             dbver = dbver + 1
             self.env.log.info("Upgrade %s database schema to version %s",
                      PLUGIN_NAME, dbver)
             modulename = 'db%i' % dbver
             upgrades = __import__('cards.upgrades', globals(), locals(), [modulename])
             script = getattr(upgrades, modulename)
             script.do_upgrade(self.env, dbver, cursor)
         cursor.execute("""
             UPDATE system
             SET value=%s
             WHERE name=%s
             """, (PLUGIN_VERSION, PLUGIN_NAME))

 def upgrade_environment(self, db):
     self.log.debug("Upgrading schema for svnhooks plugin")
     db_backend, _ = DatabaseManager(self.env).get_connector()
     cursor = db.cursor()
     for table in SVNHooksModel.svnhooks_schema:
         for stmt in db_backend.to_sql(table):
             self.log.debug(stmt)
             cursor.execute(stmt)

 def _utf8_size(self, cnx):
     if cnx is None:
         connector, args = DatabaseManager(self.env).get_connector()
         cnx = connector.get_connection(**args)
         charset = cnx.charset
         cnx.close()
     else:
         charset = cnx.charset
     return 4 if charset == 'utf8mb4' else 3

    def reset_db(self, default_data=None):
        """Remove all data from Trac tables, keeping the tables themselves.
        :param default_data: after clean-up, initialize with default data
        :return: True upon success
        """
        from trac import db_default
        if EnvironmentStub.dbenv:
            db = self.get_db_cnx()
            scheme, db_prop = _parse_db_str(self.dburi)

            tables = []
            db.rollback() # make sure there's no transaction in progress
            try:
                # check the database version
                cursor = db.cursor()
                cursor.execute("SELECT value FROM system "
                               "WHERE name='database_version'")
                database_version = cursor.fetchone()
                if database_version:
                    database_version = int(database_version[0])
                if database_version == db_default.db_version:
                    # same version, simply clear the tables (faster)
                    m = sys.modules[__name__]
                    reset_fn = 'reset_%s_db' % scheme
                    if hasattr(m, reset_fn):
                        tables = getattr(m, reset_fn)(db, db_prop)
                else:
                    # different version or version unknown, drop the tables
                    self.destroy_db(scheme, db_prop)
            except:
                db.rollback()
                # tables are likely missing

            if not tables:
                del db
                dm = DatabaseManager(EnvironmentStub.dbenv)
                dm.init_db()
                # we need to make sure the next get_db_cnx() will re-create 
                # a new connection aware of the new data model - see #8518.
                dm.shutdown() 

        db = self.get_db_cnx()
        cursor = db.cursor()
        if default_data:
            for table, cols, vals in db_default.get_data(db):
                cursor.executemany("INSERT INTO %s (%s) VALUES (%s)"
                                   % (table, ','.join(cols),
                                      ','.join(['%s' for c in cols])),
                                   vals)
        elif EnvironmentStub.dbenv:
            cursor.execute("INSERT INTO system (name, value) "
                           "VALUES (%s, %s)",
                           ('database_version', str(db_default.db_version)))
        db.commit()

 def environment_created(self):
     db_connector, _ = DatabaseManager(self.env).get_connector()
     with self.env.db_transaction as db:
         cursor = db.cursor()
         for table in SCHEMA:
             for stmt in db_connector.to_sql(table): 
                 cursor.execute(stmt) 
         cursor.execute(""" 
             INSERT INTO system (name, value) 
             VALUES (%s, %s) 
             """, (PLUGIN_NAME, PLUGIN_VERSION)) 

 def upgrade_environment(self, db):
     self.log.debug("Upgrading schema for disclaimer plugin")
     db_backend, _ = DatabaseManager(self.env).get_connector()
     cursor = db.cursor()
     for table in DisclaimerModel.disclaimer_schema:
         for stmt in db_backend.to_sql(table):
             self.log.debug(stmt)
             cursor.execute(stmt)
     cursor.execute("select count(*) from disclaimer")
     entries = cursor.fetchone()[0]
     if entries == 0:
         DisclaimerModel(self.env).insert(self.c_name,
                                          self.c_text,
                                          'system',
                                          db=db)

def create_table(env):
    '''
    Constructor, see trac/db/postgres_backend.py:95 (method init_db)
    '''
    conn, dummyArgs = DatabaseManager(env).get_connector()
    db = env.get_read_db()
    cursor = db.cursor()

    for stmt in conn.to_sql(XMAIL_TABLE):
        if db.schema:
            stmt = re.sub(r'CREATE TABLE ','CREATE TABLE "' 
                          + db.schema + '".', stmt) 
        env.log.info( "result of execution: %s" % cursor.execute(stmt) )
    db.commit()
    db.close()

    def get_version(self, initial=False):
        """Return the current version of the database.  If the
        optional argument `initial` is set to `True`, the version of
        the database used at the time of creation will be returned.

        In practice, for database created before 0.11, this will
        return `False` which is "older" than any db version number.

        :since: 0.11

        :since 1.0.2: The lazily-evaluated attributes `database_version` and
                      `database_initial_version` should be used instead. This
                      method will be removed in release 1.3.1.
        """
        dbm = DatabaseManager(self)
        return dbm.get_database_version("{0}database_version".format("initial_" if initial else ""))

def do_upgrade(env, ver, cursor):
    """Migrate old `subscriptions` db table.

    Changes to other tables:
    'subscription.priority' type=(default == char) --> 'int'
    'subscription_attribute.name --> 'subscription_attribute.realm'
    'subscription_attribute.value --> 'subscription_attribute.target'
    """
    with env.db_transaction as db:
        cursor = db.cursor()
        cursor.execute("""
            CREATE TEMPORARY TABLE subscription_old
                AS SELECT * FROM subscription
        """)
        cursor.execute("DROP TABLE subscription")
        cursor.execute("""
            CREATE TEMPORARY TABLE subscription_attribute_old
                AS SELECT * FROM subscription_attribute
        """)
        cursor.execute("DROP TABLE subscription_attribute")

        connector = DatabaseManager(env).get_connector()[0]
        for table in schema:
            for stmt in connector.to_sql(table):
                cursor.execute(stmt)
        # Convert priority values to integer.
        cursor.execute("""
            INSERT INTO subscription
                   (time,changetime,class,sid,authenticated,
                    distributor,format,priority,adverb)
            SELECT o.time,o.changetime,o.class,o.sid,o.authenticated,
                   o.distributor,o.format,%s,o.adverb
              FROM subscription_old AS o
            """ % db.cast('o.priority', 'int'))
        cursor.execute("DROP TABLE subscription_old")

        # Copy table on column name change.
        cursor.execute("""
            INSERT INTO subscription_attribute
                   (sid,class,realm,target)
            SELECT o.sid,o.class,o.name,o.value
              FROM subscription_attribute_old AS o
        """)
        cursor.execute("DROP TABLE subscription_attribute_old")

        # DEVEL: Migrate old subscription db table data.
        cursor.execute("DROP TABLE IF EXISTS subscriptions")

    def upgrade_environment(self, db):
        dbm = DatabaseManager(self.env)
        pluginName = 'wikimeta_version'
        schema_ver = self.get_schema_version(db=db, pluginName=pluginName)

        if schema_ver == 0:
            dbm.create_tables(PLUGIN_SCHEMA)

            cursor = db.cursor()

            cursor.execute("""
                INSERT into system (name, value)
                   values (%s,%s)
                """, (pluginName, PLUGIN_DB_VERSION))
            self.log.info("initialized wikimeta db schema: %d to %d"
                      % (schema_ver, PLUGIN_DB_VERSION))
            db.commit()

    def upgrade_environment(self, db):
        """Each schema version should have its own upgrade module, named
        upgrades/dbN.py, where 'N' is the version number (int).
        """
        db_mgr = DatabaseManager(self.env)
        schema_ver = self.get_schema_version(db)

        cursor = db.cursor()
        # Is this a new installation?
        if not schema_ver:
            # Perform a single-step install: Create plugin schema and
            # insert default data into the database.
            connector = db_mgr._get_connector()[0]
            for table in db_default.schema:
                for stmt in connector.to_sql(table):
                    cursor.execute(stmt)
            for table, cols, vals in db_default.get_data(db):
                cursor.executemany("INSERT INTO %s (%s) VALUES (%s)" % (table,
                                   ','.join(cols),
                                   ','.join(['%s' for c in cols])), vals)
        else:
            # Perform incremental upgrades.
            for i in range(schema_ver + 1, db_default.schema_version + 1):
                name  = 'db%i' % i
                try:
                    upgrades = __import__('tractags.upgrades', globals(),
                                          locals(), [name])
                    script = getattr(upgrades, name)
                except AttributeError:
                    raise TracError(_("No upgrade module for version %(num)i "
                                      "(%(version)s.py)", num=i, version=name))
                script.do_upgrade(self.env, i, cursor)
        cursor.execute("""
            UPDATE system
               SET value=%s
             WHERE name='tags_version'
            """, (db_default.schema_version,))
        self.log.info("Upgraded TracTags db schema from version %d to %d"
                      % (schema_ver, db_default.schema_version))

        TicketTagProvider(self.env)._fetch_tkt_tags(db)
        self.log.info("Synchronized ticket attributes to tags table")

        db.commit()

 def create_table(self):
     '''
     Constructor, see trac/postgres_backend.py:95 (method init_db)
     '''
     conn, dummyArgs = DatabaseManager(self.env).get_connector()
     try:
         with self.env.db_transaction as db:
             for stmt in conn.to_sql(BUDGETING_TABLE):
                 if db.schema:
                     stmt = re.sub(r'CREATE TABLE ', 'CREATE TABLE "'
                                   + db.schema + '".', stmt)
                 stmt = re.sub(r'(?i)bigint', 'NUMERIC(10,2)', stmt)
                 stmt += ";"
                 self.log.info("[INIT table] executing sql: %s" % stmt)
                 db(stmt)
                 self.log.info("[INIT table] successfully created table %s"
                                % BUDGETING_TABLE.name)
     except Exception, e:
         self.log.error("[INIT table] Error executing SQL Statement \n %s" % e)

 def upgrade_environment(self):
     """
     Actually perform an environment upgrade, but don't commit as
     that is done by the common upgrade procedure when all plugins are done.
     """
     dbm = DatabaseManager(self.env)
     current_ver = dbm.get_database_version(db_version_key)
     if current_ver == 0:
         dbm.create_tables(schema.values())
     else:
         while current_ver + 1 <= db_version:
             upgrade_map[current_ver + 1](self.env)
             current_ver += 1
     dbm.set_database_version(db_version, db_version_key)

def to_sql(env, table):
    """ Convenience function to get the to_sql for the active connector."""
    dc = DatabaseManager(env)._get_connector()[0]
    return dc.to_sql(table)