Symbian^3 Application Developer Library >

RSqlDatabase Class Reference

class RSqlDatabase

A handle to a SQL database.

A RSqlDatabase object is, in effect, a handle to the SQL database. A client can:

The RSqlDatabase handles are not thread-safe.

A client can create either a non-secure database or a secure database, depending on the variant of RSqlDatabase::Create() that is used.

  • a non-secure database is created if the RSqlDatabase::Create(const TDesC&) variant is used.

  • a secure database is created if the RSqlDatabase::Create(const TDesC&, const RSqlSecurityPolicy&) variant is used. In this case, a container containing a collection of security policies needs to be set up first and passed to this Create() function. See references to RSqlSecurityPolicy for more information on security policies.

A client can also specify how it wants a transaction to interact with other transactions that may be running concurrently. The various ways in which transactions can interact (i.e. how one transaction can affect another) are referred to as "transaction isolation levels", and are defined by the values of the TIsolationLevel enum. A client specifies this by calling RSqlDatabase::SetIsolationLevel() .

Each of the various flavours of Open and Create allows the optional provision of a configuration string. It is acceptable for this string to be missing. In the case where the string is missing, the config in the SqlServer.sql file will be used. If that does not exist then the MMH macro definitions will be used.

The config string is in the format PARAM=VALUE; PARAM=VALUE;...

Allowed parameters are: cache_size=nnnn page_size=nnnn encoding=UTF8|UTF16

Badly formed config strings are reported as KErrArgument

The string may not exceed 255 characters.

Please note that a database can only be accessed within the thread where it has been created. It is then not possible to create a database from thread1 and access it from thread2.

A client calls RSqlDatabase::Exec() to execute SQL statements. RSqlDatabase::Create() RSqlDatabase::Open() RSqlDatabase::Close() RSqlDatabase::Copy() RSqlDatabase::Delete() RSqlDatabase::Attach() RSqlDatabase::Detach() RSqlDatabase::SetIsolationLevel() RSqlDatabase::Exec() TIsolationLevel RSqlSecurityPolicy

Nested Classes and Structures

Public Member Functions
RSqlDatabase ()
IMPORT_C TInt Attach (const TDesC &, const TDesC &)
IMPORT_C void Close ()
IMPORT_C TInt Compact ( TInt64 , const TDesC &)
IMPORT_C void Compact ( TInt64 , TRequestStatus &, const TDesC &)
IMPORT_C TInt Copy (const TDesC &, const TDesC &)
IMPORT_C TInt Create (const TDesC &, const TDesC8 *)
IMPORT_C TInt Create (const TDesC &, const RSqlSecurityPolicy &, const TDesC8 *)
IMPORT_C void CreateL (const TDesC &, const TDesC8 *)
IMPORT_C void CreateL (const TDesC &, const RSqlSecurityPolicy &, const TDesC8 *)
IMPORT_C TInt Delete (const TDesC &)
IMPORT_C TInt Detach (const TDesC &)
IMPORT_C TInt Exec (const TDesC &)
IMPORT_C TInt Exec (const TDesC8 &)
IMPORT_C void Exec (const TDesC &, TRequestStatus &)
IMPORT_C void Exec (const TDesC8 &, TRequestStatus &)
IMPORT_C TInt GetReserveAccess ()
IMPORT_C TInt GetSecurityPolicy ( RSqlSecurityPolicy &)
IMPORT_C void GetSecurityPolicyL ( RSqlSecurityPolicy &)
IMPORT_C TBool InTransaction ()
IMPORT_C TPtrC LastErrorMessage ()
IMPORT_C TInt64 LastInsertedRowId ()
IMPORT_C TInt Open (const TDesC &, const TDesC8 *)
IMPORT_C void OpenL (const TDesC &, const TDesC8 *)
IMPORT_C void ReleaseReserveAccess ()
IMPORT_C TInt ReserveDriveSpace ( TInt )
IMPORT_C TInt SetIsolationLevel ( TIsolationLevel )
IMPORT_C TInt Size ()
IMPORT_C TInt Size ( TSize &, const TDesC &)
Private Member Functions
CSqlDatabaseImpl & Impl ()
Public Member Enumerations
enum anonymous { EMaxCompaction  = -1 }
enum TIsolationLevel { EReadUncommitted , EReadCommitted , ERepeatableRead , ESerializable }
Private Attributes
CSqlDatabaseImpl * iImpl

Constructor & Destructor Documentation

RSqlDatabase()

IMPORT_C RSqlDatabase ( )

Initialises the pointer to the implementation object to NULL.

capability
None

Member Functions Documentation

Attach(const TDesC &, const TDesC &)

IMPORT_C TInt Attach ( const TDesC & aDbFileName,
const TDesC & aDbName
)

Attaches an existing database to the current database connection.

The attached database can be read, written or modified. One database can be attched multiple times to the same connection, using different logical database names. Tables in an attached database can be referred to using "database-name.table-name" syntax. If an attached table doesn't have a duplicate table name in the main database, it doesn't require a database name prefix.

Transactions involving multiple attached databases are atomic.

capability
None, if aDbFileName refers to a non-secure database; RSqlSecurityPolicy::ESchemaPolicy or RSqlSecurityPolicy::EReadPolicy or RSqlSecurityPolicy::EWritePolicy database policy type, if aDbFileName refers to a secure database;
RSqlSecurityPolicy RSqlSecurityPolicy::TPolicyType

Parameters

const TDesC & aDbFileName The name of the file that hosts the database. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a private or shared non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which created the attached database.
const TDesC & aDbName Logical database name. It must be unique (per database connection). This is the name which can be used for accessing tables in the attached database. The syntax is "database-name.table-name".

Close()

IMPORT_C void Close ( )

Closes this handle to the database.

The function frees memory and any allocated resources.

You can reuse this object, but you must reinitialise it by calling RSqlDatabase::Create() or RSqlDatabase::Open() .

RSqlDatabase::Create() RSqlDatabase::Open()
capability
None

Compact(TInt64, const TDesC &)

IMPORT_C TInt Compact ( TInt64 aSize,
const TDesC & aDbName =  KNullDesC
)

Compacts the database. This function should be used for databases that have been configured for a manual compaction during the database creation. The function has no effect if the database has been configured for an auto compaction. The function has no effect if the aSize argument value is zero. The function has no effect also if there aren't any free pages in the database file. If the database has been configured for a background compaction, then the function works as if the database has been configured for a manual compaction.

capability
None

Parameters

TInt64 aSize Can be one of: RSqlDatabase::EMaxCompaction - requests a full database compaction. All free pages (if any exists) will be removed; Positive 32-bit signed integer value - the server will attempt to compact the database removing at most aSize bytes from the database file, rounded up to the nearest page count, e.g. request for removing 1 byte will remove one free page from the database;
const TDesC & aDbName =  KNullDesC The attached database name or KNullDesC for the main database

Compact(TInt64, TRequestStatus &, const TDesC &)

IMPORT_C void Compact ( TInt64 aSize,
TRequestStatus & aStatus,
const TDesC & aDbName =  KNullDesC
)

Parameters

TInt64 aSize
TRequestStatus & aStatus
const TDesC & aDbName =  KNullDesC

Copy(const TDesC &, const TDesC &)

IMPORT_C TInt Copy ( const TDesC & aSrcDbFileName,
const TDesC & aDestDbFileName
) [static]

Copies a database file to the specified location.

Note that this is a static function, and its use is not restricted to any specific RSqlDatabase instance.

The allowed copying operations are:

  • secure to secure database. Only the application created the database is allowed to copy it.

  • non-secure to non-secure database. No restrictions apply to this operation.

capability
None
Note that if the source database is a secure database, only the application, which created the database, can copy it.

Parameters

const TDesC & aSrcDbFileName Source database file name. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which created the database.
const TDesC & aDestDbFileName Destination database file name. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which performs the copying operation.

Create(const TDesC &, const TDesC8 *)

IMPORT_C TInt Create ( const TDesC & aDbFileName,
const TDesC8 * aConfig = NULL
)

Creates a new shared non-secure or private secure database.

capability
None

Parameters

const TDesC & aDbFileName The full path name of the file that is to host the database.
const TDesC8 * aConfig = NULL the configuration string "PARAM=VALUE;....". The following parameters can be set using the configuration string: cache_size=value - where "value" is the cache size in pages. "value" must be a positive integer number; page_size=value - where "value" is the page size in bytes. The "page_size" parameter can accept the following values: 512, 1024, 2048, 4096, 8192, 16384, 32768; encoding=value - where "value" is the desired database encoding. "value" could be either "UTF-8" or "UTF-16"; compaction=value - where "value" is the desired compaction mode. "value" could be either "background", "synchronous" or "manual".

Create(const TDesC &, const RSqlSecurityPolicy &, const TDesC8 *)

IMPORT_C TInt Create ( const TDesC & aDbFileName,
const RSqlSecurityPolicy & aSecurityPolicy,
const TDesC8 * aConfig = NULL
)

Creates a new shared secure database.

capability
The calling application must satisfy the database policy of RSqlSecurityPolicy::ESchemaPolicy type;
RSqlSecurityPolicy RSqlSecurityPolicy::TPolicyType

Parameters

const TDesC & aDbFileName The name of the file that is to host the database. The format of the name is <drive>:<[SID]database file name excluding the path>. "[SID]" refers to the application SID.
const RSqlSecurityPolicy & aSecurityPolicy The container for the security policies.
const TDesC8 * aConfig = NULL the configuration string "PARAM=VALUE;...." The following parameters can be set using the configuration string: cache_size=value - where "value" is the cache size in pages. "value" must be a positive integer number; page_size=value - where "value" is the page size in bytes. The "page_size" parameter can accept the following values: 512, 1024, 2048, 4096, 8192, 16384, 32768; encoding=value - where "value" is the desired database encoding. "value" could be either "UTF-8" or "UTF-16"; compaction=value - where "value" is the desired compaction mode. "value" could be either "background", "synchronous" or "manual".

CreateL(const TDesC &, const TDesC8 *)

IMPORT_C void CreateL ( const TDesC & aDbFileName,
const TDesC8 * aConfig = NULL
)

Parameters

const TDesC & aDbFileName
const TDesC8 * aConfig = NULL

CreateL(const TDesC &, const RSqlSecurityPolicy &, const TDesC8 *)

IMPORT_C void CreateL ( const TDesC & aDbFileName,
const RSqlSecurityPolicy & aSecurityPolicy,
const TDesC8 * aConfig = NULL
)

Creates a new shared secure database. compaction=value - where "value" is the desired compaction mode. "value" could be either "background", "synchronous" or "manual".

leave
KErrNoMemory, an out of memory condition has occurred; KErrArgument, the file name does not refer to a secure database; KErrArgument, system table name found in the security policies (aSecurityPolicy), invalid configuration string, invalid parameter values in the configuration string; KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory; KErrAlreadyExists, the file already exists; KErrNotReady, the drive does not exist or is not ready; KErrInUse, the file is already open; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that the function may leave with database specific errors categorised as ESqlDbError and other system-wide error codes.
capability
The calling application must satisfy the database policy of RSqlSecurityPolicy::ESchemaPolicy type;
RSqlSecurityPolicy RSqlSecurityPolicy::TPolicyType

Parameters

const TDesC & aDbFileName The name of the file that is to host the database. The format of the name is <drive>:<[SID]database file name excluding the path>. "[SID]" refers to the application SID.
const RSqlSecurityPolicy & aSecurityPolicy The container for the security policies.
const TDesC8 * aConfig = NULL the configuration string "PARAM=VALUE;...." The following parameters can be set using the configuration string: cache_size=value - where "value" is the cache size in pages. "value" must be a positive integer number; page_size=value - where "value" is the page size in bytes. The "page_size" parameter can accept the following values: 512, 1024, 2048, 4096, 8192, 16384, 32768; encoding=value - where "value" is the desired database encoding. "value" could be either "UTF-8" or "UTF-16";

Delete(const TDesC &)

IMPORT_C TInt Delete ( const TDesC & aDbFileName ) [static]

Deletes the specified database file.

Note that this is a static function, and its use is not restricted to any specific RSqlDatabase instance.

capability
None
Note that if the database to be deleted is a secure database, only the application, which created the database, can delete it.

Parameters

const TDesC & aDbFileName The name of the database file. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a private or shared non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which created the database.

Detach(const TDesC &)

IMPORT_C TInt Detach ( const TDesC & aDbName )

Detaches previously attached database.

capability
None

Parameters

const TDesC & aDbName Logical database name. The logical name of the database to be detached.

Exec(const TDesC &)

IMPORT_C TInt Exec ( const TDesC & aSqlStmt )

Executes one or more 16-bit SQL statements.

This method should be used for executing DDL/DML statements, but note the following point:

  • if an SQL statement contains one or more parameters, then the function will execute it, giving the parameters default NULL values.

This class ( RSqlDatabase ) does not offer functions for setting the parameter values. Use the RSqlStatement class instead.

If the call to this function fails because of a database-specific type error (i.e. the error is categorised as of type ESqlDbError), then a textual description of the error can be obtained calling RSqlDatabase::LastErrorMessage() .

capability
None, if current RSqlDatabase object represents a handle to a non-secure database; RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; RSqlSecurityPolicy::EReadPolicy or RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; RSqlSecurityPolicy::EWritePolicy or RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;
RSqlStatement TSqlRetCodeClass::ESqlDbError RSqlDatabase::LastErrorMessage() RSqlSecurityPolicy RSqlSecurityPolicy::TPolicyType

Parameters

const TDesC & aSqlStmt A string of 16-bit wide characters containing one or more DDL/DML SQL statements; each statement is separated by a ';' character.

Exec(const TDesC8 &)

IMPORT_C TInt Exec ( const TDesC8 & aSqlStmt )

Parameters

const TDesC8 & aSqlStmt

Exec(const TDesC &, TRequestStatus &)

IMPORT_C void Exec ( const TDesC & aSqlStmt,
TRequestStatus & aStatus
)

Executes one or more 16-bit SQL statements asynchronously to allow client to avoid being blocked by server activity.

No other operations can be performed on current RSqlDatabase object and RSqlStatement objects using it until the asynchronous operation completes.

This method should be used for executing DDL/DML statements, but note the following point:

  • if an SQL statement contains one or more parameters, then the function will execute it, giving the parameters default NULL values.

This class ( RSqlDatabase ) does not offer functions for setting the parameter values. Use the RSqlStatement class instead.

If the call to this function fails because of a database-specific type error (i.e. the error is categorised as ESqlDbError), then a textual description of the error can be obtained calling RSqlDatabase::LastErrorMessage() .

capability
None, if current RSqlDatabase object represents a handle to a non-secure database; RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; RSqlSecurityPolicy::EReadPolicy or RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; RSqlSecurityPolicy::EWritePolicy or RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;
RSqlStatement TSqlRetCodeClass::ESqlDbError RSqlDatabase::LastErrorMessage() RSqlSecurityPolicy RSqlSecurityPolicy::TPolicyType

Parameters

const TDesC & aSqlStmt A string of 16-bit wide characters containing one or more DDL/DML SQL statements; each statement is separated by a ';' character.
TRequestStatus & aStatus Completion status of asynchronous request, one of the following: >=0, The operation has completed successfully. The number of database rows that were changed/inserted/deleted by the most recently completed DDL/DML sql statement. Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 if the operation has completed successfully (disregarding the number of the deleted rows); KErrNoMemory, an out of memory condition has occured; KSqlErrGeneral, a syntax error has occurred - text describing the problem can be obtained by calling RSqlDatabase::LastErrorMessage(); KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation. In all other cases the database connection should be closed and some disk space freed before reopening the database; KErrPermissionDenied, the caller does not satisfy the relevant database security policies; Note that aStatus may be set with database specific errors categorised as ESqlDbError, and other system-wide error codes.

Exec(const TDesC8 &, TRequestStatus &)

IMPORT_C void Exec ( const TDesC8 & aSqlStmt,
TRequestStatus & aStatus
)

Parameters

const TDesC8 & aSqlStmt
TRequestStatus & aStatus

GetReserveAccess()

IMPORT_C TInt GetReserveAccess ( )

Gives the client an access to the already reserved disk space.

RSqlDatabase::ReserveDriveSpace() RSqlDatabase::FreeReservedSpace() RSqlDatabase::ReleaseReserveAccess()

GetSecurityPolicy(RSqlSecurityPolicy &)

IMPORT_C TInt GetSecurityPolicy ( RSqlSecurityPolicy & aSecurityPolicy ) const

Initializes aSecurityPolicy output parameter with a copy of the database security policies. The caller is responsible for destroying the initialized aSecurityPolicy paramemter.

Note that there may be no security policies in force for this database.

capability
None

Parameters

RSqlSecurityPolicy & aSecurityPolicy Input/Output parameter, which will be initialized with the database security policies.

GetSecurityPolicyL(RSqlSecurityPolicy &)

IMPORT_C void GetSecurityPolicyL ( RSqlSecurityPolicy & aSecurityPolicy ) const

Initializes aSecurityPolicy output parameter with a copy of the database security policies. The caller is responsible for destroying the initialized aSecurityPolicy paramemter.

Note that there may be no security policies in force for this database.

leave
KErrNotSupported, the current database is not a secure database; KErrNoMemory, an out of memory condition has occurred;
capability
None

Parameters

RSqlSecurityPolicy & aSecurityPolicy Input/Output parameter, which will be initialized with the database security policies.

Impl()

CSqlDatabaseImpl & Impl ( ) const [private]

Returns a reference to the implementation object of RSqlDatabase - CSqlDatabaseImpl .

panic
SqlDb 2 Create() or Open() has not previously been called on this RSqlDatabase object.

InTransaction()

IMPORT_C TBool InTransaction ( ) const

Checks the database transaction state.

capability
None

LastErrorMessage()

IMPORT_C TPtrC LastErrorMessage ( ) const
Retrieves a reference to the textual description of the error returned by the most recent call to any of the functions:

Note that the function can only return a reference to text for database-specific type errors, i.e. those errors that are categorised as of type ESqlDbError.

TSqlRetCodeClass::ESqlDbError RSqlDatabase::Exec() RSqlStatement::Exec() RSqlStatement::Next() RSqlStatement::Reset()
capability
None

LastInsertedRowId()

IMPORT_C TInt64 LastInsertedRowId ( ) const

Returns the ROWID of the most recent successful INSERT into the database from this database connection.

capability
None

Open(const TDesC &, const TDesC8 *)

IMPORT_C TInt Open ( const TDesC & aDbFileName,
const TDesC8 * aConfig = NULL
)
Opens an existing database, which can be: 
         - shared non-secure;
 - shared secure;
 - private secure;
capability
None, if aDbFileName refers to a non-secure database; RSqlSecurityPolicy::ESchemaPolicy or RSqlSecurityPolicy::EReadPolicy or RSqlSecurityPolicy::EWritePolicy database policy type, if aDbFileName refers to a secure database;
RSqlSecurityPolicy RSqlSecurityPolicy::TPolicyType

Parameters

const TDesC & aDbFileName The name of the file that hosts the database. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which created the database.
const TDesC8 * aConfig = NULL the configuration string "PARAM=VALUE;...." The following parameters can be set using the configuration string: cache_size=value - where "value" is the cache size in pages. "value" must be a positive integer number;

OpenL(const TDesC &, const TDesC8 *)

IMPORT_C void OpenL ( const TDesC & aDbFileName,
const TDesC8 * aConfig = NULL
)
Opens an existing database, which can be: 
         - shared non-secure;
 - shared secure;
 - private secure;
leave
KErrNoMemory, an out of memory condition has occurred; KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory; KErrNotReady, the drive does not exist or is not ready; KErrInUse, the file is already open; KErrNotFound, database file not found; KErrArgument, invalid configuration string, invalid parameter values in the configuration string; KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database); KErrPermissionDenied, the caller does not satisfy the relevant database security policies; KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database). Note that the function may leave with database specific errors categorised as ESqlDbError and other system-wide error codes.
capability
None, if aDbFileName refers to a non-secure database; RSqlSecurityPolicy::ESchemaPolicy or RSqlSecurityPolicy::EReadPolicy or RSqlSecurityPolicy::EWritePolicy database policy type, if aDbFileName refers to a secure database;
RSqlSecurityPolicy RSqlSecurityPolicy::TPolicyType

Parameters

const TDesC & aDbFileName The name of the file that hosts the database. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which created the database.
const TDesC8 * aConfig = NULL the configuration string "PARAM=VALUE;...." The following parameters can be set using the configuration string: cache_size=value - where "value" is the cache size in pages. "value" must be a positive integer number;

ReleaseReserveAccess()

IMPORT_C void ReleaseReserveAccess ( )

Releases the access to the reserved disk space.

RSqlDatabase::ReserveDriveSpace() RSqlDatabase::FreeReservedSpace() RSqlDatabase::GetReserveAccess()

ReserveDriveSpace(TInt)

IMPORT_C TInt ReserveDriveSpace ( TInt aSize )

Reserves a predefined amount of disk space on the drive where the database file is.

At the moment the max possible amount, allowed by the file server, is reserved on the database file drive. Use this call to ensure that if your "delete records" transaction fails because of "out of disk space" circumstances, you can get an access to the already reserved disk space and complete your transaction successfully the second time.

There is no strong, 100% guarantee, that the reserved disk space will always help the client in "low memory" situations.

RSqlDatabase::FreeReservedSpace() RSqlDatabase::GetReserveAccess() RSqlDatabase::ReleaseReserveAccess()

Parameters

TInt aSize

SetIsolationLevel(TIsolationLevel)

IMPORT_C TInt SetIsolationLevel ( TIsolationLevel aIsolationLevel )

Sets the transaction isolation level for the database.

A transaction isolation level defines the way in which a transaction interacts with other transactions that may be in progress concurrently.

Transaction isolation levels are defined by the values of the RSqlDatabase::TIsolationLevel enum.

The default isolation level is RSqlDatabase::ESerializable

Note that the isolation level is not a persistent property of the database. It is set to the default value, i.e. RSqlDatabase::ESerializable , whenever the database is created or opened.

RSqlDatabase::TIsolationLevel
capability
None

Parameters

TIsolationLevel aIsolationLevel The isolation level to be set.

Size()

IMPORT_C TInt Size ( ) const

Returns the database file size, in bytes.

capability
None

Size(TSize &, const TDesC &)

IMPORT_C TInt Size ( TSize & aSize,
const TDesC & aDbName =  KNullDesC
) const

Parameters

TSize & aSize
const TDesC & aDbName =  KNullDesC

Member Enumerations Documentation

Enum anonymous

If this value is used as an argument of RSqlDatabase::Compact() (aSize argument), then all free space will be removed

Enumerators

EMaxCompaction = -1

Enum TIsolationLevel

Defines a set of values that represents the transaction isolation level.

A transaction isolation level defines the way in which a transaction interacts with other transactions that may be in progress concurrently.

A client sets the transaction isolation level by calling SetIsolationLevel()

RSqlDatabase::SetIsolationLevel()

Enumerators

EReadUncommitted

A transaction can read uncommitted data, i.e. data that is being changed by another transaction, which is still in progress.

This means that

  • a 'database read' transaction will not block 'database write' transactions being performed by different database connections on the same shared database.

  • a 'database read' transaction will not be blocked by 'database write' transactions performed by the same database connection.

  • concurrent 'database write' transactions are prevented.

This transaction isolation level can be set at any time during the lifetime of the database.

TIsolationLevel RSqlDatabase::SetIsolationLevel()

EReadCommitted

Not currently supported.

A transaction cannot read uncommitted data. "Dirty reads" are prevented.

"Dirty read" is a data inconsistency type which can be described with the following example:

  • Transaction A updates TableA.Column1 value from 1 to 2;

  • Transaction B reads TableA.Column1 value;

  • Transaction A rolls back and restores the original value of TableA.Column1 (1);

  • Transaction B ends showing that TableA.Column1 value is 2, even though, logically and transactionally, this data never really even existed in the database because Transaction A never committed that change to the database;

TIsolationLevel RSqlDatabase::SetIsolationLevel()

ERepeatableRead

Not currently supported.

A transaction cannot change data that is being read by a different transaction. "Dirty reads" and "non-repeatable reads" are prevented.

"Non-repeatable reads" is a data inconsistency type which can be described with the following example:

  • Transaction A reads TableA.Column1 value which is 1;

  • Transaction B updates TableA.Column1 value from 1 to 2;

  • Transaction B commits the chages;

  • Transaction A reads TableA.Column1 value again. Transaction A has inconsistent data because TableA.Column1 value now is 2 instead of 1, all within the scope of the same Transaction A;

TIsolationLevel RSqlDatabase::SetIsolationLevel()

ESerializable

Any number of 'database read' transactions can be performed concurrently by different database connections on the same shared database.

Only one 'database write' transaction can be performed at any one time. If a 'database write' transaction is in progress, then any attempt to start another 'database read' or 'database write' transaction will be blocked until the first 'database write' transaction has completed.

This is the default isolation level, if no isolation level is explicitly set.

"Dirty reads", "non-repeatable" reads and "phantom reads" are prevented.

"Phantom reads" is a data inconsistency type which can be described with the following example:

  • Transaction A reads all rows that have Column1 = 1;

  • Transaction B inserts a new row which has Column1 = 1;

  • Transaction B commits;

  • Transaction A updates all rows that have Column1 = 1. This will also update the row that Transaction B inserted, because Transaction A must read the data again in order to update it.

  • Transaction A commits;

TIsolationLevel RSqlDatabase::SetIsolationLevel()

Member Data Documentation

CSqlDatabaseImpl * iImpl

CSqlDatabaseImpl * iImpl [private]

Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.