#include <connection.h>

Inheritance diagram for KexiDB::Connection:

Classes
class	SelectStatementOptions

Public Member Functions
virtual	~Connection ()

ConnectionData *	data () const

Driver *	driver () const

bool	connect ()

bool	isConnected () const

bool	isDatabaseUsed () const

virtual bool	isReadOnly () const

virtual void	clearError ()

bool	disconnect ()

TQStringList	databaseNames (bool also_system_db=false)

bool	databaseExists (const TQString &dbName, bool ignoreErrors=true)

bool	createDatabase (const TQString &dbName)

bool	useDatabase (const TQString &dbName, bool kexiCompatible=true, bool cancelled=0, MessageHandler msgHandler=0)

bool	closeDatabase ()

TQString	currentDatabase () const

bool	dropDatabase (const TQString &dbName=TQString())

TQStringList	objectNames (int objType=KexiDB::AnyObjectType, bool *ok=0)

TQStringList	tableNames (bool also_system_tables=false)

KexiDB::ServerVersionInfo *	serverVersion () const

KexiDB::DatabaseVersionInfo *	databaseVersion () const

DatabaseProperties &	databaseProperties ()

TQValueList< int >	tableIds ()

TQValueList< int >	queryIds ()

TQValueList< int >	objectIds (int objType)

Transaction	beginTransaction ()

bool	commitTransaction (Transaction trans=Transaction::null, bool ignore_inactive=false)

bool	rollbackTransaction (Transaction trans=Transaction::null, bool ignore_inactive=false)

Transaction &	defaultTransaction () const

void	setDefaultTransaction (const Transaction &trans)

const TQValueList< Transaction > &	transactions ()

bool	autoCommit () const

bool	setAutoCommit (bool on)

virtual Cursor *	prepareQuery (const TQString &statement, uint cursor_options=0)=0

Cursor *	prepareQuery (QuerySchema &query, const TQValueList< TQVariant > &params, uint cursor_options=0)

virtual Cursor *	prepareQuery (QuerySchema &query, uint cursor_options=0)=0

Cursor *	prepareQuery (TableSchema &table, uint cursor_options=0)

Cursor *	executeQuery (const TQString &statement, uint cursor_options=0)

Cursor *	executeQuery (QuerySchema &query, const TQValueList< TQVariant > &params, uint cursor_options=0)

Cursor *	executeQuery (QuerySchema &query, uint cursor_options=0)

Cursor *	executeQuery (TableSchema &table, uint cursor_options=0)

bool	deleteCursor (Cursor *cursor)

TableSchema *	tableSchema (int tableId)

TableSchema *	tableSchema (const TQString &tableName)

QuerySchema *	querySchema (int queryId)

QuerySchema *	querySchema (const TQString &queryName)

bool	setQuerySchemaObsolete (const TQString &queryName)

tristate	querySingleRecord (const TQString &sql, RowData &data, bool addLimitTo1=true)

tristate	querySingleRecord (QuerySchema &query, RowData &data, bool addLimitTo1=true)

tristate	querySingleString (const TQString &sql, TQString &value, uint column=0, bool addLimitTo1=true)

tristate	querySingleNumber (const TQString &sql, int &number, uint column=0, bool addLimitTo1=true)

bool	queryStringList (const TQString &sql, TQStringList &list, uint column=0)

bool	resultExists (const TQString &sql, bool &success, bool addLimitTo1=true)

bool	isEmpty (TableSchema &table, bool &success)

int	resultCount (const TQString &sql)

bool	insertRecord (TableSchema &tableSchema, TQValueList< TQVariant > &values)

bool	insertRecord (FieldList &fields, TQValueList< TQVariant > &values)

bool	createTable (TableSchema *tableSchema, bool replaceExisting=false)

tristate	dropTable (TableSchema *tableSchema)

tristate	dropTable (const TQString &table)

tristate	alterTable (TableSchema &tableSchema, TableSchema &newTableSchema)

bool	alterTableName (TableSchema &tableSchema, const TQString &newName, bool replace=false)

bool	dropQuery (QuerySchema *querySchema)

bool	dropQuery (const TQString &query)

bool	removeObject (uint objId)

Field *	findSystemFieldName (FieldList *fieldlist)

virtual TQString	anyAvailableDatabaseName ()

void	setAvailableDatabaseName (const TQString &dbName)

bool	useTemporaryDatabaseIfNeeded (TQString &tmpdbName)

TQ_ULLONG	lastInsertedAutoIncValue (const TQString &aiFieldName, const TQString &tableName, TQ_ULLONG *ROWID=0)

TQ_ULLONG	lastInsertedAutoIncValue (const TQString &aiFieldName, const TableSchema &table, TQ_ULLONG *ROWID=0)

bool	executeSQL (const TQString &statement)

TQString	selectStatement (QuerySchema &querySchema, const TQValueList< TQVariant > &params, const SelectStatementOptions &options=SelectStatementOptions()) const

TQString	selectStatement (QuerySchema &querySchema, const SelectStatementOptions &options=SelectStatementOptions()) const

bool	storeObjectSchemaData (SchemaData &sdata, bool newObject)

tristate	loadObjectSchemaData (int objectID, SchemaData &sdata)

tristate	loadObjectSchemaData (int objectType, const TQString &objectName, SchemaData &sdata)

tristate	loadDataBlock (int objectID, TQString &dataString, const TQString &dataID)

bool	storeDataBlock (int objectID, const TQString &dataString, const TQString &dataID=TQString())

bool	removeDataBlock (int objectID, const TQString &dataID=TQString())

void	registerForTableSchemaChanges (TableSchemaChangeListenerInterface &listener, TableSchema &schema)

void	unregisterForTableSchemaChanges (TableSchemaChangeListenerInterface &listener, TableSchema &schema)

void	unregisterForTablesSchemaChanges (TableSchemaChangeListenerInterface &listener)

TQPtrList< Connection::TableSchemaChangeListenerInterface > *	tableSchemaChangeListeners (TableSchema &tableSchema) const

tristate	closeAllTableSchemaChangeListeners (TableSchema &tableSchema)

void	removeTableSchemaInternal (KexiDB::TableSchema *tableSchema)

void	insertInternalTableSchema (TableSchema *tableSchema)

virtual bool	drv_containsTable (const TQString &tableName)=0

virtual bool	drv_createTable (const TableSchema &tableSchema)

virtual bool	drv_alterTableName (TableSchema &tableSchema, const TQString &newName)

virtual bool	drv_dropTable (const TQString &name)

virtual PreparedStatement::Ptr	prepareStatement (PreparedStatement::StatementType type, FieldList &fields)=0

bool	isInternalTableSchema (const TQString &tableName)

bool	setupObjectSchemaData (const RowData &data, SchemaData &sdata)

KexiDB::Field *	setupField (const RowData &data)

Public Member Functions inherited from KexiDB::Object
bool	error () const

const TQString &	errorMsg () const

int	errorNum () const

int	previousServerResult () const

TQString	previousServerResultName () const

void	debugError ()

virtual TQString	serverErrorMsg ()

virtual int	serverResult ()

virtual TQString	serverResultName ()

TQString	msgTitle () const

const TQString	recentSQLString () const

Static Public Member Functions
static const TQStringList &	kexiDBSystemTableNames ()

Public Attributes
	H_INS_REC_ALL

Protected Member Functions
	Connection (Driver *driver, ConnectionData &conn_data)

void	destroy ()

tristate	dropTable (KexiDB::TableSchema *tableSchema, bool alsoRemoveSchema)

virtual bool	drv_connect (KexiDB::ServerVersionInfo &version)=0

virtual bool	drv_disconnect ()=0

virtual bool	drv_executeSQL (const TQString &statement)=0

virtual bool	drv_getDatabasesList (TQStringList &list)

virtual bool	drv_getTablesList (TQStringList &list)=0

virtual bool	drv_databaseExists (const TQString &dbName, bool ignoreErrors=true)

virtual bool	drv_createDatabase (const TQString &dbName=TQString())=0

virtual bool	drv_useDatabase (const TQString &dbName=TQString(), bool cancelled=0, MessageHandler msgHandler=0)=0

virtual bool	drv_closeDatabase ()=0

virtual bool	drv_isDatabaseUsed () const

virtual bool	drv_dropDatabase (const TQString &dbName=TQString())=0

TQString	createTableStatement (const TableSchema &tableSchema) const

TQString	selectStatement (TableSchema &tableSchema, const SelectStatementOptions &options=SelectStatementOptions()) const

virtual bool	drv_createTable (const TQString &tableSchemaName)

virtual TQ_ULLONG	drv_lastInsertRowID ()=0

virtual TransactionData *	drv_beginTransaction ()

virtual bool	drv_commitTransaction (TransactionData *trans)

virtual bool	drv_rollbackTransaction (TransactionData *trans)

virtual bool	drv_setAutoCommit (bool on)

bool	beginAutoCommitTransaction (TransactionGuard &tg)

bool	commitAutoCommitTransaction (const Transaction &trans)

bool	rollbackAutoCommitTransaction (const Transaction &trans)

bool	checkConnected ()

bool	checkIsDatabaseUsed ()

TableSchema *	setupTableSchema (const RowData &data)

QuerySchema *	setupQuerySchema (const RowData &data)

bool	updateRow (QuerySchema &query, RowData &data, RowEditBuffer &buf, bool useROWID=false)

bool	insertRow (QuerySchema &query, RowData &data, RowEditBuffer &buf, bool getROWID=false)

bool	deleteRow (QuerySchema &query, RowData &data, bool useROWID=false)

bool	deleteAllRows (QuerySchema &query)

bool	setupKexiDBSystemSchema ()

TableSchema *	newKexiDBSystemTableSchema (const TQString &tsname)

TQString	escapeIdentifier (const TQString &id, int escaping=Driver::EscapeDriver\|Driver::EscapeAsNecessary) const

void	removeMe (TableSchema *ts)

bool	checkIfColumnExists (Cursor *cursor, uint column)

tristate	querySingleRecordInternal (RowData &data, const TQString sql, QuerySchema query, bool addLimitTo1=true)

void	setReadOnly (bool set)

bool	loadExtendedTableSchemaData (TableSchema &tableSchema)

bool	storeExtendedTableSchemaData (TableSchema &tableSchema)

bool	storeMainFieldSchema (Field *field)

virtual tristate	drv_changeFieldProperty (TableSchema &table, Field &field, const TQString &propertyName, const TQVariant &value)

Protected Member Functions inherited from KexiDB::Object
	Object (MessageHandler *handler=0)

virtual void	setError (int code=ERR_OTHER, const TQString &msg=TQString())

virtual void	setError (const TQString &msg)

virtual void	setError (const TQString &title, const TQString &msg)

void	setError (KexiDB::Object *obj, const TQString &prependMessage=TQString())

virtual void	setError (KexiDB::Object *obj, int code, const TQString &prependMessage=TQString())

virtual int	askQuestion (const TQString &message, KMessageBox::DialogType dlgType, KMessageBox::ButtonCode defaultResult, const KGuiItem &buttonYes=KStdGuiItem::yes(), const KGuiItem &buttonNo=KStdGuiItem::no(), const TQString &dontShowAskAgainName=TQString(), int options=KMessageBox::Notify, MessageHandler *msgHandler=0)

virtual void	drv_clearServerResult ()

Protected Attributes
TQPtrDict< KexiDB::Cursor >	m_cursors

Protected Attributes inherited from KexiDB::Object
TQString	m_sql

TQString	m_errorSql

int	m_serverResult

TQString	m_serverResultName

TQString	m_serverErrorMsg

TQString	m_errMsg

Friends
class	KexiDB::Driver

class	KexiDB::Cursor

class	KexiDB::TableSchema

class	KexiDB::DatabaseProperties

class	ConnectionPrivate

class	KexiDB::AlterTableHandler

Detailed Description

Provides database connection, allowing queries and data modification.

This class represents a database connection established within a data source. It supports data queries and modification by creating client-side database cursors. Database transactions are supported.

Definition at line 61 of file connection.h.

Constructor & Destructor Documentation

◆ ~Connection()

Connection::~Connection ( )

virtual

Opened connection is automatically disconnected and removed from driver's connections list. Note for driver developers: you should call destroy() from you Connection's subclass destructor.

Definition at line 222 of file connection.cpp.

◆ Connection()

Connection::Connection	(	Driver *	driver,
		ConnectionData &	conn_data
	)

protected

Used by Driver

Definition at line 199 of file connection.cpp.

Member Function Documentation

◆ alterTable()

tristate Connection::alterTable	(	TableSchema &	tableSchema,
		TableSchema &	newTableSchema
	)

Alters tableSchema using newTableSchema in memory and on the db backend.

Returns: true on success, cancelled if altering was cancelled.

Todo:

(js): implement real altering

(js): update any structure (e.g. query) that depend on this table!

Definition at line 1766 of file connection.cpp.

◆ alterTableName()

bool Connection::alterTableName	(	TableSchema &	tableSchema,
		const TQString &	newName,
		bool	replace = `false`
	)

Alters name of table described by tableSchema to newName. If replace is true, destination table is completely dropped and replaced by tableSchema, if present. In this case, identifier of tableSchema becomes equal to the dropped table's id, what can be useful if tableSchema was created with a temporary name and ID (used in AlterTableHandler).

If replace is false (the default) and destination table is present – false is returned and ERR_OBJECT_EXISTS error is set. The schema of tableSchema is updated on success.

Returns: true on success.

Definition at line 1792 of file connection.cpp.

◆ anyAvailableDatabaseName()

TQString Connection::anyAvailableDatabaseName ( )

virtual

Returns: name of any (e.g. first found) database for this connection. This method does not close or open this connection. The method can be used (it is also internally used, e.g. for database dropping) when we need a database name before we can connect and execute any SQL statement (e.g. DROP DATABASE).

The method can return nul lstring, but in this situation no automatic (implicit) connections could be made, what is useful by e.g. dropDatabase().

Note for driver developers: return here a name of database which you are sure is existing. Default implementation returns:

value that previously had been set using setAvailableDatabaseName() for this connection, if it is not empty
else (2nd priority): value of DriverBehaviour::ALWAYS_AVAILABLE_DATABASE_NAME if it is not empty.

See decription of DriverBehaviour::ALWAYS_AVAILABLE_DATABASE_NAME member. You may want to reimplement this method only when you need to depend on this connection specifics (e.g. you need to check something remotely).

Definition at line 3122 of file connection.cpp.

◆ autoCommit()

bool Connection::autoCommit ( ) const

Returns: true if "auto commit" option is on.

When auto commit is on (the default on for any new Connection object), every sql functional statement (statement that changes data in the database implicitly starts a new transaction. This transaction is automatically committed after successful statement execution or rolled back on error.

For drivers that do not support transactions (see Driver::features()) this method shouldn't be called because it does nothing ans always returns false.

No internal KexiDB object should changes this option, although auto commit's behaviour depends on database engine's specifics. Engines that support only single transaction per connection (see Driver::SingleTransactions), use this single connection for autocommiting, so if there is already transaction started by the KexiDB user program (with beginTransaction()), this transaction is committed before any sql functional statement execution. In this situation default transaction is also affected (see defaultTransaction()).

Only for drivers that support nested transactions (Driver::NestedTransactions), autocommiting works independently from previously started transaction,

For other drivers set this option off if you need use transaction for grouping more statements together.

NOTE: nested transactions are not yet implemented in KexiDB API.

Definition at line 2165 of file connection.cpp.

◆ beginAutoCommitTransaction()

bool Connection::beginAutoCommitTransaction ( TransactionGuard & tg )

protected

Internal, for handling autocommited transactions: begins transaction if one is supported.

Returns: true if new transaction started successfully or no transactions are supported at all by the driver or if autocommit option is turned off. A handle to a newly created transaction (or null on error) is passed to tg parameter.

Special case when used database driver has only single transaction support (Driver::SingleTransactions): and there is already transaction started, it is committed before starting a new one, but only if this transaction has been started inside Connection object. (i.e. by beginAutoCommitTransaction()). Otherwise, a new transaction will not be started, but true will be returned immediately.

Definition at line 1962 of file connection.cpp.

◆ beginTransaction()

Transaction Connection::beginTransaction ( )

Creates new transaction handle and starts a new transaction.

Returns: KexiDB::Transaction object if transaction has been started successfully, otherwise null transaction. For drivers that allow single transaction per connection (Driver::features() && SingleTransactions) this method can be called one time, and then this single transaction will be default ( setDefaultTransaction() will be called). For drivers that allow multiple transactions per connection, no default transaction is set automatically in beginTransaction() method, you could do this by hand.

See also: setDefaultTransaction(), defaultTransaction().

Definition at line 2023 of file connection.cpp.

◆ checkConnected()

bool Connection::checkConnected ( )

protected

Creates cursor data and initializes cursor using statement for later data retrieval.

Closes and deletes cursor data.

Helper: checks if connection is established; if not: error message is set up and false returned

Definition at line 294 of file connection.cpp.

◆ checkIfColumnExists()

bool Connection::checkIfColumnExists	(	Cursor *	cursor,
		uint	column
	)

protected

Definition at line 2407 of file connection.cpp.

◆ checkIsDatabaseUsed()

bool Connection::checkIsDatabaseUsed ( )

protected

Helper: checks both if connection is established and database any is used; if not: error message is set up and false returned

Definition at line 304 of file connection.cpp.

◆ clearError()

void Connection::clearError ( )

virtual

Reimplemented from Object: also clears sql string.

See also: recentSQLString()

Reimplemented from KexiDB::Object.

Definition at line 268 of file connection.cpp.

◆ closeAllTableSchemaChangeListeners()

tristate Connection::closeAllTableSchemaChangeListeners ( TableSchema & tableSchema )

Definition at line 3521 of file connection.cpp.

◆ closeDatabase()

bool Connection::closeDatabase ( )

Closes currently used database for this connection.

Any active transactions (if supported) are rolled back, so commit these before closing, if you'd like to save your changes.

Todo:: (js) add CLEVER algorithm here for nested transactions

Definition at line 624 of file connection.cpp.

◆ commitAutoCommitTransaction()

bool Connection::commitAutoCommitTransaction ( const Transaction & trans )

protected

Internal, for handling autocommited transactions: Commits transaction prevoiusly started with beginAutoCommitTransaction().

Returns: true on success or when no transactions are supported at all by the driver.

Special case when used database driver has only single transaction support (Driver::SingleTransactions): if trans has been started outside Connection object (i.e. not by beginAutoCommitTransaction()), the transaction will not be committed.

Definition at line 1995 of file connection.cpp.

◆ commitTransaction()

bool Connection::commitTransaction	(	Transaction	trans = `Transaction::null`,
		bool	ignore_inactive = `false`
	)

Todo:: for nested transactions: Tansaction* beginTransaction(transaction *parent_transaction);

Commits transaction trans. If there is not trans argument passed, and there is default transaction (obtained from defaultTransaction()) defined, this one will be committed. If default is not present, false is returned (when ignore_inactive is false, the default), or true is returned (when ignore_inactive is true).

On successful commit, trans object will be destroyed. If this was default transaction, there is no default transaction for now.

Definition at line 2061 of file connection.cpp.

◆ connect()

bool Connection::connect ( )

Connects to driver with given parameters.

Returns: true if successful.

Definition at line 246 of file connection.cpp.

◆ createDatabase()

bool Connection::createDatabase ( const TQString & dbName )

Creates new database with name dbName, using this connection.

If database with dbName already exists, or other error occurred, false is returned. For file-based drivers, dbName should be equal to the database filename (the same as specified for ConnectionData).

See doc/dev/kexidb_issues.txt document, chapter "Table schema, query schema, etc. storage" for database schema documentation (detailed description of kexi__* 'system' tables).

See also: useDatabase()

Definition at line 435 of file connection.cpp.

◆ createTable()

bool Connection::createTable	(	KexiDB::TableSchema *	tableSchema,
		bool	replaceExisting = `false`
	)

Creates a table according to the given schema.

Creates table defined by tableSchema. Schema information is also added into kexi system tables, for later reuse.

Returns: true on success - tableSchema object is then inserted to Connection structures - it is owned by Connection object now, so you shouldn't destroy the tableSchema object by hand (or declare it as local-scope variable).

If replaceExisting is false (the default) and table with the same name (as tableSchema->name()) exists, false is returned. If replaceExisting is true, a table schema with the same name (if exists) is overwritten, then a new table schema gets the same identifier as existing table schema's identifier.

Note that on error:

tableSchema is not inserted into Connection's structures, so you are still owner of this object
existing table schema object is not destroyed (i.e. it is still available e.g. using Connection::tableSchema(const TQString& ), even if the table was physically dropped.

Creates a table according to the given TableSchema, adding the table and column definitions to kexi__* tables. Checks that a database is in use, that the table name is not that of a system table, and that the schema defines at least one column. If the table exists, and replaceExisting is true, the table is replaced. Otherwise, the table is not replaced.

Definition at line 1525 of file connection.cpp.

◆ createTableStatement()

TQString Connection::createTableStatement ( const TableSchema & tableSchema ) const

protected

Returns: "CREATE TABLE ..." statement string needed for tableSchema creation in the database.

Note: The statement string can be specific for this connection's driver database, and thus not reusable in general.

Todo:: IS this ok for all engines?: if (!autoinc && !field->isPrimaryKey() && field->isNotNull())

Definition at line 871 of file connection.cpp.

◆ currentDatabase()

TQString Connection::currentDatabase ( ) const

Get the name of the current database.

Returns: name of currently used database for this connection or empty string if there is no used database

Definition at line 667 of file connection.cpp.

◆ data()

ConnectionData * Connection::data ( ) const

Returns: parameters that were used to create this connection.

Definition at line 241 of file connection.cpp.

◆ databaseExists()

bool Connection::databaseExists	(	const TQString &	dbName,
		bool	ignoreErrors = `true`
	)

Returns: true if database dbName exists. If ignoreErrors is true, error flag of connection won't be modified for any errors (it will quietly return), else (ignoreErrors == false) we can check why the database does not exist using error(), errorNum() and/or errorMsg().

Definition at line 373 of file connection.cpp.

◆ databaseNames()

TQStringList Connection::databaseNames ( bool also_system_db = false )

Returns: list of database names for opened connection. If also_system_db is true, the system database names are also returned.

Definition at line 314 of file connection.cpp.

◆ databaseProperties()

DatabaseProperties & Connection::databaseProperties ( )

Returns: DatabaseProperties object allowing to read and write global database properties for this connection.

Definition at line 832 of file connection.cpp.

◆ databaseVersion()

KexiDB::DatabaseVersionInfo * Connection::databaseVersion ( ) const

Returns: version information for this connection. If database is not used (i.e. isDatabaseUsed() is false) 0 is returned. It can be compared to drivers' and KexiDB library version to maintain backward/upward compatiblility.

Definition at line 827 of file connection.cpp.

◆ defaultTransaction()

Transaction & Connection::defaultTransaction ( ) const

Returns: handle for default transaction for this connection or null transaction if there is no such a transaction defined. If transactions are supported: Any operation on database (e.g. inserts) that is started without specifying transaction context, will be performed in the context of this transaction.

Returned null transaction doesn't mean that there is no transactions started at all. Default transaction can be defined automatically for some drivers – see beginTransaction().

See also: KexiDB::Driver::transactionsSupported()

Definition at line 2141 of file connection.cpp.

◆ deleteAllRows()

bool Connection::deleteAllRows ( QuerySchema & query )

protected

Delete all existing rows.

Definition at line 3458 of file connection.cpp.

◆ deleteCursor()

bool Connection::deleteCursor ( Cursor * cursor )

Deletes cursor cursor previously created by functions like executeQuery() for this connection. There is an attempt to close the cursor with Cursor::close() if it was opened. Anyway, at last cursor is deleted.

Returns: true if cursor is properly closed before deletion.

Definition at line 2256 of file connection.cpp.

◆ deleteRow()

bool Connection::deleteRow	(	QuerySchema &	query,
		RowData &	data,
		bool	useROWID = `false`
	)

protected

Delete an existing row.

Todo:: allow to delete from a table without pkey

Definition at line 3392 of file connection.cpp.

◆ destroy()

void Connection::destroy ( )

protected

Method to be called form Connection's subclass destructor.

See also: ~Connection()

Definition at line 215 of file connection.cpp.

◆ disconnect()

bool Connection::disconnect ( )

Disconnects from driver with given parameters.

The database (if used) is closed, and any active transactions (if supported) are rolled back, so commit these before disconnecting, if you'd like to save your changes.

Definition at line 274 of file connection.cpp.

◆ driver()

Driver * KexiDB::Connection::driver ( ) const

inline

Returns: the driver used for this connection.

Definition at line 78 of file connection.h.

◆ dropDatabase()

bool Connection::dropDatabase ( const TQString & dbName = TQString() )

Drops database with name dbName.

if dbName is not specified, currently used database name is used (it is closed before dropping).

Definition at line 696 of file connection.cpp.

◆ dropQuery() [1/2]

bool Connection::dropQuery ( const TQString & query )

It is a convenience function, does exactly the same as bool dropQuery( KexiDB::QuerySchema* querySchema )

Definition at line 1935 of file connection.cpp.

◆ dropQuery() [2/2]

bool Connection::dropQuery ( KexiDB::QuerySchema * querySchema )

Drops a query defined by querySchema. If true is returned, schema information querySchema is destoyed (because it's owned), so don't keep this anymore!

Definition at line 1901 of file connection.cpp.

◆ dropTable() [1/3]

tristate Connection::dropTable ( const TQString & table )

It is a convenience function, does exactly the same as bool dropTable( KexiDB::TableSchema* tableSchema )

Definition at line 1754 of file connection.cpp.

◆ dropTable() [2/3]

tristate Connection::dropTable	(	KexiDB::TableSchema *	tableSchema,
		bool	alsoRemoveSchema
	)

protected

Todo:: js: update any structure (e.g. queries) that depend on this table!

Definition at line 1697 of file connection.cpp.

◆ dropTable() [3/3]

tristate Connection::dropTable ( KexiDB::TableSchema * tableSchema )

Drops a table corresponding to the name in the given schema.

Drops a table defined by tableSchema (both table object as well as physically). If true is returned, schema information tableSchema is destoyed (because it's owned), so don't keep this anymore! No error is raised if the table does not exist physically

its schema is removed even in this case.
Todo:
(js): update any structure (e.g. query) that depend on this table!

Drops a table according to the name given by the TableSchema, removing the table and column definitions to kexi__* tables. Checks first that the table is not a system table.

TODO: Should check that a database is currently in use? (c.f. createTable)

Definition at line 1692 of file connection.cpp.

◆ drv_alterTableName()

bool Connection::drv_alterTableName	(	TableSchema &	tableSchema,
		const TQString &	newName
	)

virtual

Alters table's described tableSchema name to newName. This is the default implementation, using "ALTER TABLE <oldname> RENAME TO <newname>", what's supported by SQLite >= 3.2, PostgreSQL, MySQL. Backends lacking ALTER TABLE, for example SQLite2, reimplement this with by an inefficient data copying to a new table. In any case, renaming is performed at the backend. It's good idea to keep the operation within a transaction.

Returns: true on success.

Moved to public for KexiProject.

Todo:: fix this after refactoring

Definition at line 1887 of file connection.cpp.

◆ drv_beginTransaction()

TransactionData * Connection::drv_beginTransaction ( )

protectedvirtual

Note for driver developers: begins new transaction and returns handle to it. Default implementation just executes "BEGIN" sql statement and returns just empty data (TransactionData object).

Drivers that do not support transactions (see Driver::features()) do never call this method. Reimplement this method if you need to do something more (e.g. if you driver will support multiple transactions per connection). Make subclass of TransactionData (declared in transaction.h) and return object of this subclass. You should return NULL if any error occurred. Do not check anything in connection (isConnected(), etc.) - all is already done.

Reimplemented in KexiDB::pqxxSqlConnection.

Definition at line 2180 of file connection.cpp.

◆ drv_changeFieldProperty()

virtual tristate KexiDB::Connection::drv_changeFieldProperty	(	TableSchema &	table,
		Field &	field,
		const TQString &	propertyName,
		const TQVariant &	value
	)

inlineprotectedvirtual

This is a part of alter table interface implementing lower-level operations used to perform table schema altering. Used by AlterTableHandler.

Changes value of field property.

Returns: true on success, false on failure, cancelled if the action has been cancelled.

Note for driver developers: implement this if the driver has to support the altering.

Reimplemented in KexiDB::SQLiteConnection.

Definition at line 1175 of file connection.h.

◆ drv_closeDatabase()

virtual bool KexiDB::Connection::drv_closeDatabase ( )

protectedpure virtual

For reimplemenation: closes previously opened database using connection.

Implemented in KexiDB::MySqlConnection, KexiDB::pqxxSqlConnection, and KexiDB::SQLiteConnection.

◆ drv_commitTransaction()

bool Connection::drv_commitTransaction ( TransactionData * trans )

protectedvirtual

Note for driver developers: begins new transaction and returns handle to it. Default implementation just executes "COMMIT" sql statement and returns true on success.

See also: drv_beginTransaction()

Reimplemented in KexiDB::pqxxSqlConnection.

Definition at line 2188 of file connection.cpp.

◆ drv_connect()

virtual bool KexiDB::Connection::drv_connect ( KexiDB::ServerVersionInfo & version )

protectedpure virtual

For reimplemenation: connects to database. version should be set to real server's version.

Returns: true on success.

Implemented in KexiDB::MySqlConnection, KexiDB::pqxxSqlConnection, and KexiDB::SQLiteConnection.

◆ drv_containsTable()

virtual bool KexiDB::Connection::drv_containsTable ( const TQString & tableName )

pure virtual

Todo:: move this somewhere to low level class (MIGRATION?)

LOW LEVEL METHOD. For reimplemenation: returns true if table with name tableName exists in the database.

Returns: false if it does not exist or error occurred. The lookup is case insensitive.

Implemented in KexiDB::MySqlConnection, KexiDB::pqxxSqlConnection, and KexiDB::SQLiteConnection.

◆ drv_createDatabase()

virtual bool KexiDB::Connection::drv_createDatabase ( const TQString & dbName = TQString() )

protectedpure virtual

For reimplemenation: creates new database using connection

Implemented in KexiDB::MySqlConnection, KexiDB::pqxxSqlConnection, and KexiDB::SQLiteConnection.

◆ drv_createTable() [1/2]

bool Connection::drv_createTable ( const TableSchema & tableSchema )

virtual

Creates table using tableSchema information.

Returns: true on success. Default implementation builds a statement using createTableStatement() and calls drv_executeSQL() Note for driver developers: reimplement this only if you want do to this in other way.

Moved to public for KexiMigrate.

Todo:: fix this after refactoring

Definition at line 1947 of file connection.cpp.

◆ drv_createTable() [2/2]

bool Connection::drv_createTable ( const TQString & tableSchemaName )

protectedvirtual

Creates table named by tableSchemaName. Schema object must be on schema tables' list before calling this method (otherwise false if returned). Just uses drv_createTable( const KexiDB::TableSchema& tableSchema ). Used internally, e.g. in createDatabase().

Returns: true on success

Definition at line 1954 of file connection.cpp.

◆ drv_databaseExists()

bool Connection::drv_databaseExists	(	const TQString &	dbName,
		bool	ignoreErrors = `true`
	)

protectedvirtual

For optional reimplemenation: asks server if database dbName exists. This method is used internally in databaseExists(). The default implementation calls databaseNames and checks if that list contains dbName. If you need to ask the server specifically if a database exists, eg. if you can't retrieve a list of all available database names, please reimplement this method and do all needed checks.

See databaseExists() description for details about ignoreErrors argument. You should use this appropriately in your implementation.

Note: This method should also work if there is already database used (with useDatabase()); in this situation no changes should be made in current database selection.

Definition at line 357 of file connection.cpp.

◆ drv_disconnect()

virtual bool KexiDB::Connection::drv_disconnect ( )

protectedpure virtual

For reimplemenation: disconnects database

Returns: true on success.

Implemented in KexiDB::MySqlConnection, KexiDB::pqxxSqlConnection, and KexiDB::SQLiteConnection.

◆ drv_dropDatabase()

virtual bool KexiDB::Connection::drv_dropDatabase ( const TQString & dbName = TQString() )

protectedpure virtual

For reimplemenation: drops database from the server using connection. After drop, database shouldn't be accessible anymore.

Implemented in KexiDB::MySqlConnection, KexiDB::pqxxSqlConnection, and KexiDB::SQLiteConnection.

◆ drv_dropTable()

bool Connection::drv_dropTable ( const TQString & name )

virtual

Physically drops table named with name. Default impelmentation executes "DROP TABLE.." command, so you rarely want to change this.

Moved to public for KexiMigrate

Todo:: fix this after refatoring

Definition at line 1679 of file connection.cpp.

◆ drv_executeSQL()

virtual bool KexiDB::Connection::drv_executeSQL ( const TQString & statement )

protectedpure virtual

Executes query statement, but without returning resulting rows (used mostly for functional queries). Only use this method if you really need.

Implemented in KexiDB::MySqlConnection, KexiDB::pqxxSqlConnection, and KexiDB::SQLiteConnection.

◆ drv_getDatabasesList()

bool Connection::drv_getDatabasesList ( TQStringList & list )

protectedvirtual

For reimplemenation: loads list of databases' names available for this connection and adds these names to list. If your server is not able to offer such a list, consider reimplementing drv_databaseExists() instead. The method should return true only if there was no error on getting database names list from the server. Default implementation puts empty list into list and returns true.

Reimplemented in KexiDB::MySqlConnection, KexiDB::pqxxSqlConnection, and KexiDB::SQLiteConnection.

Definition at line 351 of file connection.cpp.

◆ drv_getTablesList()

virtual bool KexiDB::Connection::drv_getTablesList ( TQStringList & list )

protectedpure virtual

Todo:: move this somewhere to low level class (MIGRATION?)

LOW LEVEL METHOD. For reimplemenation: loads low-level list of table names available for this connection. The names are in lower case. The method should return true only if there was no error on getting database names list from the server.

Implemented in KexiDB::MySqlConnection, KexiDB::pqxxSqlConnection, and KexiDB::SQLiteConnection.

◆ drv_isDatabaseUsed()

virtual bool KexiDB::Connection::drv_isDatabaseUsed ( ) const

inlineprotectedvirtual

Returns: true if internal driver's structure is still in opened/connected state and database is used. Note for driver developers: Put here every test that you can do using your internal engine's database API, eg (a bit schematic): my_connection_struct->isConnected()==true. Do not check things like Connection::isDatabaseUsed() here or other things that "KexiDB already knows" at its level. If you cannot test anything, just leave default implementation (that returns true).

Result of this method is used as an addtional chance to check for isDatabaseUsed(). Do not call this method from your driver's code, it should be used at KexiDB level only.

Reimplemented in KexiDB::pqxxSqlConnection.

Definition at line 934 of file connection.h.

◆ drv_lastInsertRowID()

virtual TQ_ULLONG KexiDB::Connection::drv_lastInsertRowID ( )

protectedpure virtual

Executes query statement and returns resulting rows (used mostly for SELECT query). *‍/ virtual bool drv_executeQuery( const TQString& statement ) = 0;

    /*! \return unique identifier of last inserted row. 
     Typically this is just primary key value. 
     This identifier could be reused when we want to reference
     just inserted row.
     Note for driver developers: contact js (at) iidea.pl 
     if your engine do not offers this information.

Implemented in KexiDB::MySqlConnection, KexiDB::pqxxSqlConnection, and KexiDB::SQLiteConnection.

◆ drv_rollbackTransaction()

bool Connection::drv_rollbackTransaction ( TransactionData * trans )

protectedvirtual

Note for driver developers: begins new transaction and returns handle to it. Default implementation just executes "ROLLBACK" sql statement and returns true on success.

See also: drv_beginTransaction()

Reimplemented in KexiDB::pqxxSqlConnection.

Definition at line 2193 of file connection.cpp.

◆ drv_setAutoCommit()

bool Connection::drv_setAutoCommit ( bool on )

protectedvirtual

Changes autocommiting option for established connection.

Returns: true on success.

Note for driver developers: reimplement this only if your engine allows to set special auto commit option (like "SET AUTOCOMMIT=.." in MySQL). If not, auto commit behaviour will be simulated if at least single transactions per connection are supported by the engine. Do not set any internal flags for autocommiting – it is already done inside setAutoCommit().

Default implementation does nothing with connection, just returns true.

See also: drv_beginTransaction(), autoCommit(), setAutoCommit()

Definition at line 2198 of file connection.cpp.

◆ drv_useDatabase()

virtual bool KexiDB::Connection::drv_useDatabase	(	const TQString &	dbName = `TQString()`,
		bool *	cancelled = `0`,
		MessageHandler *	msgHandler = `0`
	)

protectedpure virtual

For reimplemenation: opens existing database using connection

Returns: true on success, false on failure and cancelled if user has cancelled this action.

Implemented in KexiDB::MySqlConnection, KexiDB::pqxxSqlConnection, and KexiDB::SQLiteConnection.

◆ escapeIdentifier()

TQString KexiDB::Connection::escapeIdentifier	(	const TQString &	id,
		int	escaping = `Driver::EscapeDriver\|Driver::EscapeAsNecessary`
	)		const

inlineprotected

Identifier escaping function in the associated Driver.

Calls the identifier escaping function in the associated Driver to escape table and column names. This should be used when explicitly constructing SQL strings (e.g. "FROM " + escapeIdentifier(tablename)). It should not be used for other functions (e.g. don't do useDatabase(escapeIdentifier(database))), because the identifier will be escaped when the called function generates, for example, "USE " + escapeIdentifier(database).

For efficiency, kexi__* system tables and columns therein are not escaped

we assume these are valid identifiers for all drivers.

Definition at line 1124 of file connection.h.

◆ executeQuery() [1/4]

KexiDB::Connection::executeQuery	(	const TQString &	statement,
		uint	cursor_options = `0`
	)

Executes SELECT query described by statement.

Returns: opened cursor created for results of this query or NULL if there was any error on the cursor creation or opening. Cursor can have optionally applied cursor_options (one of more selected from KexiDB::Cursor::Options). Identifiers in statement that are the same as keywords in Kexi SQL or the backend's SQL need to have been escaped.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

params are values of parameters that will be inserted into places marked with [] before execution of the query.

Statement is build from data provided by query schema. Kexi SQL and driver-specific escaping is performed on table names.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Executes query described by query schema without parameters. Statement is build from data provided by table schema, it is like "select * from table_name".

Definition at line 2203 of file connection.cpp.

◆ executeQuery() [2/4]

Cursor * Connection::executeQuery	(	QuerySchema &	query,
		const TQValueList< TQVariant > &	params,
		uint	cursor_options = `0`
	)

Definition at line 2218 of file connection.cpp.

◆ executeQuery() [3/4]

Cursor * Connection::executeQuery	(	QuerySchema &	query,
		uint	cursor_options = `0`
	)

Definition at line 2232 of file connection.cpp.

◆ executeQuery() [4/4]

Cursor * Connection::executeQuery	(	TableSchema &	table,
		uint	cursor_options = `0`
	)

Definition at line 2237 of file connection.cpp.

◆ executeSQL()

bool Connection::executeSQL ( const TQString & statement )

Executes query statement, but without returning resulting rows (used mostly for functional queries). Only use this method if you really need.

Definition at line 1056 of file connection.cpp.

◆ findSystemFieldName()

Field * Connection::findSystemFieldName ( KexiDB::FieldList * fieldlist )

Returns: first field from fieldlist that has system name, null if there are no such field. For checking Driver::isSystemFieldName() is used, so this check can be driver-dependent.

Definition at line 1405 of file connection.cpp.

◆ insertInternalTableSchema()

void Connection::insertInternalTableSchema ( TableSchema * tableSchema )

Definition at line 3026 of file connection.cpp.

◆ insertRecord() [1/2]

bool Connection::insertRecord	(	FieldList &	fields,
		TQValueList< TQVariant > &	values
	)

Definition at line 1027 of file connection.cpp.

◆ insertRecord() [2/2]

C_INS_REC_ALL bool Connection::insertRecord	(	TableSchema &	tableSchema,
		TQValueList< TQVariant > &	values
	)

Definition at line 999 of file connection.cpp.

◆ insertRow()

bool Connection::insertRow	(	QuerySchema &	query,
		RowData &	data,
		RowEditBuffer &	buf,
		bool	getROWID = `false`
	)

protected

Insert a new row.

Todo:: now only if PKEY is present, this should also work when there's no PKEY

Todo:: safe to cast it?

Todo:: show error

Todo:: remove just inserted row. How? Using ROLLBACK?

Todo:: show error

Definition at line 3240 of file connection.cpp.

◆ isConnected()

bool Connection::isConnected ( ) const

Returns: true, if connection is properly established.

Definition at line 289 of file connection.cpp.

◆ isDatabaseUsed()

bool Connection::isDatabaseUsed ( ) const

Returns: true, both if connection is properly established and any database within this connection is properly used with useDatabase().

Definition at line 263 of file connection.cpp.

◆ isEmpty()

bool Connection::isEmpty	(	TableSchema &	table,
		bool &	success
	)

Returns: true if there is at least one record in table.

Definition at line 2513 of file connection.cpp.

◆ isInternalTableSchema()

bool Connection::isInternalTableSchema ( const TQString & tableName )

Definition at line 3018 of file connection.cpp.

◆ isReadOnly()

bool Connection::isReadOnly ( ) const

virtual

Returns: true for read only connection. Used especially for file-based drivers. Can be reimplemented in a driver to provide real read-only flag of the connection (SQlite3 dirver does this).

Reimplemented in KexiDB::SQLiteConnection.

Definition at line 3551 of file connection.cpp.

◆ kexiDBSystemTableNames()

const TQStringList & Connection::kexiDBSystemTableNames ( )

static

Returns: list of internal KexiDB system table names (kexi__*). This does not mean that these tables can be found in currently opened database. Just static list of table names is returned.

The list contents may depend on KexiDB library version; opened database can contain fewer 'system' tables than in current KexiDB implementation, if the current one is newer than the one used to build the database.

Todo:: (js): this will depend on KexiDB lib version

Definition at line 806 of file connection.cpp.

◆ lastInsertedAutoIncValue() [1/2]

TQ_ULLONG Connection::lastInsertedAutoIncValue	(	const TQString &	aiFieldName,
		const TableSchema &	table,
		TQ_ULLONG *	ROWID = `0`
	)

Definition at line 1436 of file connection.cpp.

◆ lastInsertedAutoIncValue() [2/2]

int KexiDB::Connection::lastInsertedAutoIncValue	(	const TQString &	aiFieldName,
		const TQString &	tableName,
		TQ_ULLONG *	ROWID = `0`
	)

Returns: autoincrement field's aiFieldName value of last inserted record. This refers tableName table.

Simply, method internally fetches last inserted record and returns selected field's value. Requirements: field must be of integer type, there must be a record inserted in current database session (whatever this means). On error (TQ_ULLONG)-1 is returned. Last inserted record is identified by magical row identifier, usually called ROWID (PostgreSQL has it as well as SQLite; see DriverBehaviour::ROW_ID_FIELD_RETURNS_LAST_AUTOINCREMENTED_VALUE). ROWID's value will be assigned back to ROWID if this pointer is not null.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 1416 of file connection.cpp.

◆ loadDataBlock()

tristate Connection::loadDataBlock	(	int	objectID,
		TQString &	dataString,
		const TQString &	dataID
	)

Loads (potentially large) data block (e.g. xml form's representation), referenced by objectID and puts it to dataString. The can be block indexed with optional dataID.

Returns: true on success, false on failure and cancelled when there is no such data block

See also: storeDataBlock().

Definition at line 2893 of file connection.cpp.

◆ loadExtendedTableSchemaData()

bool Connection::loadExtendedTableSchemaData ( TableSchema & tableSchema )

protected

Loads extended schema information for table tableSchema, if present (see ExtendedTableSchemaInformation in Kexi Wiki).

Returns: true on success

Todo:: look at the current format version (KEXIDB_EXTENDED_TABLE_SCHEMA_VERSION)

Todo:: more properties

Todo:: more properties...

Definition at line 2657 of file connection.cpp.

◆ loadObjectSchemaData() [1/2]

tristate Connection::loadObjectSchemaData	(	int	objectID,
		SchemaData &	sdata
	)

Added for convenience.

See also: setupObjectSchemaData( const KexiDB::RowData &data, SchemaData &sdata ).

Returns: true on success, false on failure and cancelled when such object couldn't

Definition at line 2300 of file connection.cpp.

◆ loadObjectSchemaData() [2/2]

tristate Connection::loadObjectSchemaData	(	int	objectType,
		const TQString &	objectName,
		SchemaData &	sdata
	)

Finds object schema data for object of type objectType and name objectName. If the object is found, resulted schema is stored in sdata and true is returned, otherwise false is returned.

Definition at line 2310 of file connection.cpp.

◆ newKexiDBSystemTableSchema()

TableSchema * Connection::newKexiDBSystemTableSchema ( const TQString & tsname )

protected

used internally by setupKexiDBSystemSchema(): Allocates single table KexiDB system object named tsname and adds this to list of such objects (for later removal on closeDatabase()).

Definition at line 3011 of file connection.cpp.

◆ objectIds()

TQValueList< int > Connection::objectIds ( int objType )

Returns: names of all schemas of object with objType type that are stored in currently used database.

Definition at line 847 of file connection.cpp.

◆ objectNames()

TQStringList Connection::objectNames	(	int	objType = `KexiDB::AnyObjectType`,
		bool *	ok = `0`
	)

Returns: names of all the objecttype (see ObjectTypes in global.h) schemas stored in currently used database. KexiDB::AnyObjectType can be passed as objType to get names of objects of any type. If ok is not null then variable pointed by it will be set to the result. On error, the functions can return incomplete list.

Definition at line 754 of file connection.cpp.

◆ prepareQuery() [1/3]

KexiDB::Connection::prepareQuery	(	const TQString &	statement = `TQString()`,
		uint	cursor_options = `0`
	)

pure virtual

driver-specific string escaping

Prepares SELECT query described by raw statement.

Returns: opened cursor created for results of this query or NULL if there was any error. Cursor can have optionally applied cursor_options (one of more selected from KexiDB::Cursor::Options). Preparation means that returned cursor is created but not opened. Open this when you would like to do it with Cursor::open().

Note for driver developers: you should initialize cursor engine-specific resources and return Cursor subclass' object (passing statement and cursor_options to it's constructor).

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Prepares query described by query schema. params are values of parameters that will be inserted into places marked with [] before execution of the query.

Note for driver developers: you should initialize cursor engine-specific resources and return Cursor subclass' object (passing query and cursor_options to it's constructor). Kexi SQL and driver-specific escaping is performed on table names.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Statement is build from data provided by table schema, it is like "select * from table_name".

Implemented in KexiDB::SQLiteConnection, KexiDB::MySqlConnection, and KexiDB::pqxxSqlConnection.

◆ prepareQuery() [2/3]

Cursor * Connection::prepareQuery	(	QuerySchema &	query,
		const TQValueList< TQVariant > &	params,
		uint	cursor_options = `0`
	)

Definition at line 2247 of file connection.cpp.

◆ prepareQuery() [3/3]

Cursor * Connection::prepareQuery	(	TableSchema &	table,
		uint	cursor_options = `0`
	)

Definition at line 2242 of file connection.cpp.

◆ prepareStatement()

virtual PreparedStatement::Ptr KexiDB::Connection::prepareStatement	(	PreparedStatement::StatementType	type,
		FieldList &	fields
	)

pure virtual

Prepare a SQL statement and return a PreparedStatement instance.

Implemented in KexiDB::MySqlConnection, KexiDB::pqxxSqlConnection, and KexiDB::SQLiteConnection.

◆ queryIds()

TQValueList< int > Connection::queryIds ( )

Returns: ids of all database query schemas stored in currently used database. These ids can be later used as argument for querySchema(). This is a shortcut for objectIds(TableObjectType).

Definition at line 842 of file connection.cpp.

◆ querySchema() [1/2]

QuerySchema * Connection::querySchema ( const TQString & queryName )

Returns: schema of a query pointed by queryName, retrieved from currently used database.

See also: querySchema( int queryId )

Definition at line 2969 of file connection.cpp.

◆ querySchema() [2/2]

QuerySchema * Connection::querySchema ( int queryId )

Returns: schema of a query pointed by queryId, retrieved from currently used database. The schema is cached inside connection, so retrieval is performed only once, on demand.

Definition at line 2985 of file connection.cpp.

◆ querySingleNumber()

tristate Connection::querySingleNumber	(	const TQString &	sql,
		int &	number,
		uint	column = `0`,
		bool	addLimitTo1 = `true`
	)

Convenience function: executes sql query and stores first record's field's (number column) value inside number.

See also: querySingleString(). Note: "LIMIT 1" is appended to sql statement if addLimitTo1 is true (the default).

Returns: true if query was successfully executed and first record has been found, false on data retrieving failure, and cancelled if there's no single record available.

Definition at line 2438 of file connection.cpp.

◆ querySingleRecord() [1/2]

tristate Connection::querySingleRecord	(	const TQString &	sql,
		RowData &	data,
		bool	addLimitTo1 = `true`
	)

Executes sql query and stores first record's data inside data. This is convenient method when we need only first record from query result, or when we know that query result has only one record. If addLimitTo1 is true (the default), adds a LIMIT clause to the query, so sql should not include one already.

Returns: true if query was successfully executed and first record has been found, false on data retrieving failure, and cancelled if there's no single record available.

Definition at line 2397 of file connection.cpp.

◆ querySingleRecord() [2/2]

tristate Connection::querySingleRecord	(	QuerySchema &	query,
		RowData &	data,
		bool	addLimitTo1 = `true`
	)

Like tristate querySingleRecord(const TQString& sql, RowData &data) but uses QuerySchema object. If addLimitTo1 is true (the default), adds a LIMIT clause to the query.

Definition at line 2402 of file connection.cpp.

◆ querySingleRecordInternal()

tristate Connection::querySingleRecordInternal	(	RowData &	data,
		const TQString *	sql,
		QuerySchema *	query,
		bool	addLimitTo1 = `true`
	)

protected

Todo:: does not work with non-SQL data sources

Definition at line 2374 of file connection.cpp.

◆ querySingleString()

tristate Connection::querySingleString	(	const TQString &	sql,
		TQString &	value,
		uint	column = `0`,
		bool	addLimitTo1 = `true`
	)

Executes sql query and stores first record's field's (number column) string value inside value. For efficiency it's recommended that a query defined by sql should have just one field (SELECT one_field FROM ....). If addLimitTo1 is true (the default), adds a LIMIT clause to the query, so sql should not include one already.

Returns: true if query was successfully executed and first record has been found, false on data retrieving failure, and cancelled if there's no single record available.

See also: queryStringList()

Definition at line 2416 of file connection.cpp.

◆ queryStringList()

bool Connection::queryStringList	(	const TQString &	sql,
		TQStringList &	list,
		uint	column = `0`
	)

Executes sql query and stores Nth field's string value of every record inside list, where N is equal to column. The list is initially cleared. For efficiency it's recommended that a query defined by sql should have just one field (SELECT one_field FROM ....).

Returns: true if all values were fetched successfuly, false on data retrieving failure. Returning empty list can be still a valid result. On errors, the list is not cleared, it may contain a few retrieved values.

Definition at line 2449 of file connection.cpp.

◆ registerForTableSchemaChanges()

void Connection::registerForTableSchemaChanges	(	TableSchemaChangeListenerInterface &	listener,
		TableSchema &	schema
	)

Register listener for receiving (listening) information about changes in TableSchema object.

Changes could be: altering and removing.

Definition at line 3481 of file connection.cpp.

◆ removeDataBlock()

bool Connection::removeDataBlock	(	int	objectID,
		const TQString &	dataID = `TQString()`
	)

Removes (potentially large) string data (e.g. xml form's representation), referenced by objectID, and pointed by optional dataID.

Returns: true on success. Does not fail if the block does not exist. Note that if dataID is not specified, all data blocks for this dialog will be removed.

See also: loadDataBlock() storeDataBlock().

Definition at line 2925 of file connection.cpp.

◆ removeMe()

void Connection::removeMe ( TableSchema * ts )

protected

Called by TableSchema – signals destruction to Connection object To avoid having deleted table object on its list.

Definition at line 3114 of file connection.cpp.

◆ removeObject()

bool Connection::removeObject ( uint objId )

Removes information about object with objId from internal "kexi__object" and "kexi__objectdata" tables.

Returns: true on success.

Definition at line 1667 of file connection.cpp.

◆ removeTableSchemaInternal()

void Connection::removeTableSchemaInternal ( KexiDB::TableSchema * tableSchema )

Definition at line 1661 of file connection.cpp.

◆ resultCount()

int KexiDB::Connection::resultCount ( const TQString & sql )

Todo:: perhaps use TQ_ULLONG here?

Returns: number of records in sql query. Does not fetch any records. -1 is returned on query execution errors (>0 otherwise). Note: real executed query is: "SELECT COUNT() FROM (\a sql) LIMIT 1" (using querySingleNumber())

◆ resultExists()

bool Connection::resultExists	(	const TQString &	sql,
		bool &	success,
		bool	addLimitTo1 = `true`
	)

Returns: true if there is at least one record returned in sql query. Does not fetch any records. success will be set to false on query execution errors (true otherwise), so you can see a difference between "no results" and "query execution error" states. Note: real executed query is: "SELECT 1 FROM (\a sql) LIMIT 1" if addLimitTo1 is true (the default).

Definition at line 2480 of file connection.cpp.

◆ rollbackAutoCommitTransaction()

bool Connection::rollbackAutoCommitTransaction ( const Transaction & trans )

protected

Internal, for handling autocommited transactions: Rollbacks transaction prevoiusly started with beginAutoCommitTransaction().

Returns: true on success or when no transactions are supported at all by the driver.

Special case when used database driver has only single transaction support (Driver::SingleTransactions): trans will not be rolled back if it has been started outside this Connection object.

Definition at line 2008 of file connection.cpp.

◆ rollbackTransaction()

bool Connection::rollbackTransaction	(	Transaction	trans = `Transaction::null`,
		bool	ignore_inactive = `false`
	)

Rollbacks transaction trans. If there is not trans argument passed, and there is default transaction (obtained from defaultTransaction()) defined, this one will be rolled back. If default is not present, false is returned (when ignore_inactive is false, the default), or true is returned (when ignore_inactive is true).

or any error occurred, false is returned.

On successful rollback, trans object will be destroyed. If this was default transaction, there is no default transaction for now.

Definition at line 2097 of file connection.cpp.

◆ selectStatement() [1/3]

TQString KexiDB::Connection::selectStatement	(	QuerySchema &	querySchema,
		const SelectStatementOptions &	options = `SelectStatementOptions()`
	)		const

inline

Definition at line 700 of file connection.h.

◆ selectStatement() [2/3]

TQString Connection::selectStatement	(	KexiDB::QuerySchema &	querySchema,
		const TQValueList< TQVariant > &	params,
		const SelectStatementOptions &	options = `SelectStatementOptions()`
	)		const

Returns: "SELECT ..." statement's string needed for executing query defined by querySchema and params.

Todo:: looking at singleTable is visually nice but a field name can conflict with function or variable name...

Todo:: add option that allows to omit "AS" keyword

Todo:: Add lookup schema option for separator other than ' ' or even option for placeholders like "Name ? ?"

Todo:

Todo:: Add possibility for joining the values at client side.

Todo:: Add lookup schema option for separator other than ' ' or even option for placeholders like "Name ? ?"

Todo:

Todo:: Add possibility for joining the values at client side.

Todo:: (js) add other sql parts

Definition at line 1068 of file connection.cpp.

◆ selectStatement() [3/3]

TQString Connection::selectStatement	(	KexiDB::TableSchema &	tableSchema,
		const SelectStatementOptions &	options = `SelectStatementOptions()`
	)		const

protected

Returns: "SELECT ..." statement's string needed for executing query defined by "select * from table_name" where table_name is tableSchema's name. This method's variant can be useful when there is no appropriate QuerySchema defined.

Note: The statement string can be specific for this connection's driver database, and thus not reusable in general.

Definition at line 1399 of file connection.cpp.

◆ serverVersion()

KexiDB::ServerVersionInfo * Connection::serverVersion ( ) const

Returns: server version information for this connection. If database is not connected (i.e. isConnected() is false) 0 is returned.

Definition at line 822 of file connection.cpp.

◆ setAutoCommit()

bool Connection::setAutoCommit ( bool on )

Changes auto commit option. This does not affect currently started transactions. This option can be changed even when connection is not established.

See also: autoCommit()

Definition at line 2170 of file connection.cpp.

◆ setAvailableDatabaseName()

void Connection::setAvailableDatabaseName ( const TQString & dbName )

Sets dbName as name of a database that can be accessible. This is option that e.g. application that make use of KexiDB library can set to tune connection's behaviour when it needs to temporary connect to any database in the server to do some work. You can pass empty dbName - then anyAvailableDatabaseName() will try return DriverBehaviour::ALWAYS_AVAILABLE_DATABASE_NAME (the default) value instead of the one previously set with setAvailableDatabaseName().

See also: anyAvailableDatabaseName()

Definition at line 3130 of file connection.cpp.

◆ setDefaultTransaction()

void Connection::setDefaultTransaction ( const Transaction & trans )

Sets default transaction that will be used as context for operations on data in opened database for this connection.

Definition at line 2146 of file connection.cpp.

◆ setQuerySchemaObsolete()

bool Connection::setQuerySchemaObsolete ( const TQString & queryName )

Sets queryName query obsolete by moving it out of the query sets, so it will not be accessible by querySchema( const TQString& queryName ). The existing query object is not destroyed, to avoid problems when it's referenced. In this case, a new query schema will be retrieved directly from the backend.

For now it's used in KexiQueryDesignerGuiEditor::storeLayout(). This solves the problem when user has changed a query schema but already form still uses previously instantiated query schema.

Returns: true if there is such query. Otherwise the method does nothing.

Definition at line 3000 of file connection.cpp.

◆ setReadOnly()

void Connection::setReadOnly ( bool set )

protected

Definition at line 3544 of file connection.cpp.

◆ setupField()

KexiDB::Field * Connection::setupField ( const RowData & data )

Returns: a new field table schema for a table retrieved from data. Used internally by tableSchema().

Moved to public for KexiMigrate

Todo:: fix this after refatoring

Definition at line 2756 of file connection.cpp.

◆ setupKexiDBSystemSchema()

bool Connection::setupKexiDBSystemSchema ( )

protected

Creates kexi__* tables.

Allocates all needed table KexiDB system objects for kexi__* KexiDB liblary's system tables schema. These objects are used internally in this connection and are added to list of tables (by name, not by id because these have no ids).

Definition at line 3034 of file connection.cpp.

◆ setupObjectSchemaData()

bool Connection::setupObjectSchemaData	(	const RowData &	data,
		SchemaData &	sdata
	)

Setups schema data for object that owns sdata (e.g. table, query) using cursor opened on 'kexi__objects' table, pointing to a record corresponding to given object.

Moved to public for KexiMigrate

Todo:: fix this after refatoring

Definition at line 2269 of file connection.cpp.

◆ setupQuerySchema()

KexiDB::QuerySchema * Connection::setupQuerySchema ( const RowData & data )

protected

Returns: a full query schema for a query using 'kexi__*' system tables. Used internally by querySchema() methods.

Definition at line 2936 of file connection.cpp.

◆ setupTableSchema()

KexiDB::TableSchema * Connection::setupTableSchema ( const RowData & data )

protected

Returns: a full table schema for a table retrieved using 'kexi__*' system tables. Used internally by tableSchema() methods.

Definition at line 2800 of file connection.cpp.

◆ storeDataBlock()

bool Connection::storeDataBlock	(	int	objectID,
		const TQString &	dataString,
		const TQString &	dataID = `TQString()`
	)

Stores (potentially large) data block dataString (e.g. xml form's representation), referenced by objectID. Block will be stored in "kexi__objectdata" table and an optional dataID identifier. If there is already such record in the table, it's simply overwritten.

Returns: true on success

See also: loadDataBlock().

Definition at line 2903 of file connection.cpp.

◆ storeExtendedTableSchemaData()

bool Connection::storeExtendedTableSchemaData ( TableSchema & tableSchema )

protected

Stores extended schema information for table tableSchema, (see ExtendedTableSchemaInformation in Kexi Wiki). The action is performed within the current transaction, so it's up to you to commit. Used, e.g. by createTable(), within its transaction.

Returns: true on success

Todo:: future: save in older versions if neeed

Definition at line 2596 of file connection.cpp.

◆ storeMainFieldSchema()

bool Connection::storeMainFieldSchema ( Field * field )

protected

Definition at line 1483 of file connection.cpp.

◆ storeObjectSchemaData()

bool Connection::storeObjectSchemaData	(	SchemaData &	sdata,
		bool	newObject
	)

Stores object's schema data (id, name, caption, help text) described by sdata on the backend. If newObject is true, new entry is created, and (when sdata.id() was <=0), new, unique object identifier is obtained and assigned to sdata (see SchemaData::id()).

If newObject is false, it's expected that entry on the backend already exists, so it's updated (changes to identifier are not allowed).

Returns: true on success.

Todo:: safe to cast it?

Definition at line 2320 of file connection.cpp.

◆ tableIds()

TQValueList< int > Connection::tableIds ( )

Returns: ids of all table schema names stored in currently used database. These ids can be later used as argument for tableSchema(). This is a shortcut for objectIds(TableObjectType). If also_system_tables is true, Internal KexiDB system tables (kexi__*) are not available here because these have no identifiers assigned (more formally: id=-1).

Definition at line 837 of file connection.cpp.

◆ tableNames()

TQStringList Connection::tableNames ( bool also_system_tables = false )

Returns: names of all table schemas stored in currently used database. If also_system_tables is true, internal KexiDB system table names (kexi__*) are also returned.

See also: kexiDBSystemTableNames()

Definition at line 795 of file connection.cpp.

◆ tableSchema() [1/2]

TableSchema * Connection::tableSchema ( const TQString & tableName )

Returns: schema of a table pointed by tableName, retrieved from currently used database. KexiDB system table schema can be also retrieved.

See also: tableSchema( int tableId )

Definition at line 2862 of file connection.cpp.

◆ tableSchema() [2/2]

TableSchema * Connection::tableSchema ( int tableId )

Returns: schema of a table pointed by tableId, retrieved from currently used database. The schema is cached inside connection, so retrieval is performed only once, on demand.

Definition at line 2878 of file connection.cpp.

◆ tableSchemaChangeListeners()

TQPtrList< Connection::TableSchemaChangeListenerInterface > * Connection::tableSchemaChangeListeners ( TableSchema & tableSchema ) const

Definition at line 3515 of file connection.cpp.

◆ transactions()

const TQValueList< Transaction > & Connection::transactions ( )

Returns: set of handles of currently active transactions. Note that in multithreading environment some of these transactions can be already inactive after calling this method. Use Transaction::active() to check that. Inactive transaction handle is useless and can be safely dropped.

Definition at line 2160 of file connection.cpp.

◆ unregisterForTableSchemaChanges()

void Connection::unregisterForTableSchemaChanges	(	TableSchemaChangeListenerInterface &	listener,
		TableSchema &	schema
	)

Definition at line 3494 of file connection.cpp.

◆ unregisterForTablesSchemaChanges()

void Connection::unregisterForTablesSchemaChanges ( TableSchemaChangeListenerInterface & listener )

Definition at line 3504 of file connection.cpp.

◆ updateRow()

bool Connection::updateRow	(	QuerySchema &	query,
		RowData &	data,
		RowEditBuffer &	buf,
		bool	useROWID = `false`
	)

protected

Update a row.

Todo:: perhaps we can try to update without using PKEY?

Definition at line 3152 of file connection.cpp.

◆ useDatabase()

bool Connection::useDatabase	(	const TQString &	dbName,
		bool	kexiCompatible = `true`,
		bool *	cancelled = `0`,
		MessageHandler *	msgHandler = `0`
	)

Opens an existing database specified by dbName.

If kexiCompatible is true (the default) initial checks will be performed to recognize database Kexi-specific format. Set kexiCompatible to false if you're using native database (one that have no Kexi System tables). For file-based drivers, dbName should be equal to filename (the same as specified for ConnectionData).

Returns: true on success, false on failure. If user has cancelled this action and cancelled is not 0, *cancelled is set to true.

Definition at line 537 of file connection.cpp.

◆ useTemporaryDatabaseIfNeeded()

bool Connection::useTemporaryDatabaseIfNeeded ( TQString & tmpdbName )

Because some engines need to have opened any database before executing administrative sql statements like "create database" or "drop database", this method is used to use appropriate, existing database for this connection. For file-based db drivers this always return true and does not set tmpdbName to any value. For other db drivers: this sets tmpdbName to db name computed using anyAvailableDatabaseName(), and if the name computed is empty, false is returned; if it is not empty, useDatabase() is called. False is returned also when useDatabase() fails. You can call this method from your application's level if you really want to perform tasks that require any used database. In such a case don't forget to closeDatabase() if returned tmpdbName is not empty.

Note: This method has nothing to do with creating or using temporary databases in such meaning that these database are not persistent

Definition at line 672 of file connection.cpp.

Friends And Related Symbol Documentation

◆ ConnectionPrivate

friend class ConnectionPrivate

friend

Definition at line 1192 of file connection.h.

◆ KexiDB::AlterTableHandler

friend class KexiDB::AlterTableHandler

friend

Definition at line 1193 of file connection.h.

◆ KexiDB::Cursor

friend class KexiDB::Cursor

friend

Definition at line 1189 of file connection.h.

◆ KexiDB::DatabaseProperties

friend class KexiDB::DatabaseProperties

friend

for setError()

Definition at line 1191 of file connection.h.

◆ KexiDB::Driver

friend class KexiDB::Driver

friend

Definition at line 1188 of file connection.h.

◆ KexiDB::TableSchema

friend class KexiDB::TableSchema

friend

for removeMe()

Definition at line 1190 of file connection.h.

Member Data Documentation

◆ H_INS_REC_ALL

KexiDB::Connection::H_INS_REC_ALL

Definition at line 504 of file connection.h.

◆ m_cursors

TQPtrDict<KexiDB::Cursor> KexiDB::Connection::m_cursors

protected

cursors created for this connection

Definition at line 1181 of file connection.h.

The documentation for this class was generated from the following files:

kexi

Classes

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ~Connection()

◆ Connection()

Member Function Documentation

◆ alterTable()

◆ alterTableName()

◆ anyAvailableDatabaseName()

◆ autoCommit()

◆ beginAutoCommitTransaction()

◆ beginTransaction()

◆ checkConnected()

◆ checkIfColumnExists()

◆ checkIsDatabaseUsed()

◆ clearError()

◆ closeAllTableSchemaChangeListeners()

◆ closeDatabase()

◆ commitAutoCommitTransaction()

◆ commitTransaction()

◆ connect()

◆ createDatabase()

◆ createTable()

◆ createTableStatement()

◆ currentDatabase()

◆ data()

◆ databaseExists()

◆ databaseNames()

◆ databaseProperties()

◆ databaseVersion()

◆ defaultTransaction()

◆ deleteAllRows()

◆ deleteCursor()

◆ deleteRow()

◆ destroy()

◆ disconnect()

◆ driver()

◆ dropDatabase()

◆ dropQuery() [1/2]

◆ dropQuery() [2/2]

◆ dropTable() [1/3]

◆ dropTable() [2/3]

◆ dropTable() [3/3]

◆ drv_alterTableName()

◆ drv_beginTransaction()

◆ drv_changeFieldProperty()

◆ drv_closeDatabase()

◆ drv_commitTransaction()

◆ drv_connect()

◆ drv_containsTable()

◆ drv_createDatabase()

◆ drv_createTable() [1/2]

◆ drv_createTable() [2/2]

◆ drv_databaseExists()

◆ drv_disconnect()

◆ drv_dropDatabase()

◆ drv_dropTable()

◆ drv_executeSQL()

◆ drv_getDatabasesList()

◆ drv_getTablesList()

◆ drv_isDatabaseUsed()

◆ drv_lastInsertRowID()

◆ drv_rollbackTransaction()

◆ drv_setAutoCommit()

◆ drv_useDatabase()

◆ escapeIdentifier()

◆ executeQuery() [1/4]

◆ executeQuery() [2/4]

◆ executeQuery() [3/4]

◆ executeQuery() [4/4]

◆ executeSQL()

◆ findSystemFieldName()

◆ insertInternalTableSchema()