Nextcloud PHP API (master)

IDBConnection
in

Interface IDBConnection

Tags
since
6.0.0

Table of Contents

Constants

PLATFORM_MARIADB  : mixed = 'mariadb'
PLATFORM_MYSQL  : mixed = 'mysql'
PLATFORM_ORACLE  : mixed = 'oracle'
PLATFORM_POSTGRES  : mixed = 'postgres'
PLATFORM_SQLITE  : mixed = 'sqlite'

Methods

beginTransaction()  : void
Start a transaction
close()  : void
Close the database connection
commit()  : void
Commit the database changes done during a transaction that is in progress
connect()  : bool
Establishes the connection with the database.
createSchema()  : Schema
Create the schema of the connected database
dropTable()  : void
Drop a table from the database if it exists
errorCode()  : int
Fetch the SQLSTATE associated with the last database operation.
errorInfo()  : array<string|int, mixed>
Fetch extended error information associated with the last database operation.
escapeLikeParameter()  : string
Escape a parameter to be used in a LIKE query
executeQuery()  : IResult
Executes an, optionally parameterized, SQL query.
executeStatement()  : int
Executes an SQL INSERT/UPDATE/DELETE query with the given parameters and returns the number of affected rows.
executeUpdate()  : int
Executes an SQL INSERT/UPDATE/DELETE query with the given parameters and returns the number of affected rows.
getCrossShardMoveHelper()  : CrossShardMoveHelper
Get a helper class for implementing cross-shard moves
getDatabasePlatform()  : AbstractPlatform
Gets the DatabasePlatform instance that provides all the metadata about the platform this driver connects to.
getDatabaseProvider()  : self::PLATFORM_MYSQL|self::PLATFORM_ORACLE|self::PLATFORM_POSTGRES|self::PLATFORM_SQLITE|self::PLATFORM_MARIADB
Returns the database provider name
getError()  : string
Gets the error code and message as a string for logging
getQueryBuilder()  : IQueryBuilder
Gets the QueryBuilder for the connection.
getShardDefinition()  : ShardDefinition|null
Get the shard definition by name, if configured
getTypedQueryBuilder()  : ITypedQueryBuilder
Gets the ITypedQueryBuilder for the connection.
insertIfNotExist()  : int
Insert a row if the matching row does not exists. To accomplish proper race condition avoidance it is needed that there is also a unique constraint on the values. Then this method will catch the exception and return 0.
insertIgnoreConflict()  : int
Insert a row if the row does not exist. Eventual conflicts during insert will be ignored.
inTransaction()  : bool
Check if a transaction is active
lastInsertId()  : int
Used to get the id of the just inserted element
lockTable()  : void
Create an exclusive read+write lock on a table
migrateToSchema()  : void
Migrate the database to the given schema
prepare()  : IPreparedStatement
Used to abstract the Nextcloud database access away
quote()  : mixed
Quotes a given input parameter.
rollBack()  : void
Rollback the database changes done during a transaction that is in progress
setValues()  : int
Insert or update a row value
supports4ByteText()  : bool
Check whether or not the current database support 4byte wide unicode
tableExists()  : bool
Check if a table exists
truncateTable()  : void
Truncate a table data if it exists
unlockTable()  : void
Release a previous acquired lock again

Constants

PLATFORM_MARIADB

public mixed PLATFORM_MARIADB = 'mariadb'
Tags
since
32.0.0

PLATFORM_MYSQL

public mixed PLATFORM_MYSQL = 'mysql'
Tags
since
28.0.0

PLATFORM_ORACLE

public mixed PLATFORM_ORACLE = 'oracle'
Tags
since
28.0.0

PLATFORM_POSTGRES

public mixed PLATFORM_POSTGRES = 'postgres'
Tags
since
28.0.0

PLATFORM_SQLITE

public mixed PLATFORM_SQLITE = 'sqlite'
Tags
since
28.0.0

Methods

beginTransaction()

Start a transaction

public beginTransaction() : void
Tags
since
6.0.0
throws
Exception

since 21.0.0

close()

Close the database connection

public close() : void
Tags
since
8.0.0

commit()

Commit the database changes done during a transaction that is in progress

public commit() : void
Tags
since
6.0.0
throws
Exception

since 21.0.0

connect()

Establishes the connection with the database.

public connect() : bool
Tags
throws
Exception

since 21.0.0

since
8.0.0
Return values
bool

createSchema()

Create the schema of the connected database

public createSchema() : Schema
Tags
throws
Exception

since 21.0.0

since
13.0.0
Return values
Schema

dropTable()

Drop a table from the database if it exists

public dropTable(string $table) : void
Parameters
$table : string

table name without the prefix

Tags
throws
Exception

since 21.0.0

since
8.0.0
psalm-taint-sink

sql $table

errorCode()

Fetch the SQLSTATE associated with the last database operation.

public errorCode() : int

doesn't return anything anymore

Tags
since
8.0.0
Return values
int —

The last error code.

errorInfo()

Fetch extended error information associated with the last database operation.

public errorInfo() : array<string|int, mixed>

doesn't return anything anymore

Tags
since
8.0.0
Return values
array<string|int, mixed> —

The last error information.

escapeLikeParameter()

Escape a parameter to be used in a LIKE query

public escapeLikeParameter(string $param) : string
Parameters
$param : string
Tags
since
9.0.0
Return values
string

executeQuery()

Executes an, optionally parameterized, SQL query.

public executeQuery(string $sql[, array<string|int, string> $params = [] ][, array<string|int, mixed> $types = [] ]) : IResult

If the query is parameterized, a prepared statement is used. If an SQLLogger is configured, the execution is logged.

Parameters
$sql : string

The SQL query to execute.

$params : array<string|int, string> = []

The parameters to bind to the query, if any.

$types : array<string|int, mixed> = []

The types the previous parameters are in.

Tags
since
8.0.0
throws
Exception

since 21.0.0

psalm-taint-sink

sql $sql

Return values
IResult —

The executed statement.

executeStatement()

Executes an SQL INSERT/UPDATE/DELETE query with the given parameters and returns the number of affected rows.

public executeStatement(string $sql[, array<string|int, mixed> $params = [] ][, array<string|int, mixed> $types = [] ]) : int

This method supports PDO binding types as well as DBAL mapping types.

Parameters
$sql : string

The SQL query.

$params : array<string|int, mixed> = []

The query parameters.

$types : array<string|int, mixed> = []

The parameter types.

Tags
since
21.0.0
throws
Exception

since 21.0.0

psalm-taint-sink

sql $sql

Return values
int —

The number of affected rows.

executeUpdate()

Executes an SQL INSERT/UPDATE/DELETE query with the given parameters and returns the number of affected rows.

public executeUpdate(string $sql[, array<string|int, mixed> $params = [] ][, array<string|int, mixed> $types = [] ]) : int

use executeStatement

This method supports PDO binding types as well as DBAL mapping types.

Parameters
$sql : string

The SQL query.

$params : array<string|int, mixed> = []

The query parameters.

$types : array<string|int, mixed> = []

The parameter types.

Tags
since
8.0.0
throws
Exception

since 21.0.0

psalm-taint-sink

sql $sql

Return values
int —

The number of affected rows.

getCrossShardMoveHelper()

Get a helper class for implementing cross-shard moves

public getCrossShardMoveHelper() : CrossShardMoveHelper
Tags
since
30.0.0
Return values
CrossShardMoveHelper

getDatabasePlatform()

Gets the DatabasePlatform instance that provides all the metadata about the platform this driver connects to.

public getDatabasePlatform() : AbstractPlatform

Please use self::getDatabaseProvider() and compare to self::PLATFORM_* constants

Tags
since
8.0.0
Return values
AbstractPlatform —

The database platform.

getDatabaseProvider()

Returns the database provider name

public getDatabaseProvider([bool $strict = false ]) : self::PLATFORM_MYSQL|self::PLATFORM_ORACLE|self::PLATFORM_POSTGRES|self::PLATFORM_SQLITE|self::PLATFORM_MARIADB
Parameters
$strict : bool = false

differentiate between database flavors, e.g. MySQL vs MariaDB

Tags
link
https://github.com/nextcloud/server/issues/30877
since
32.0.0

Optional parameter $strict was added

28.0.0
Return values
self::PLATFORM_MYSQL|self::PLATFORM_ORACLE|self::PLATFORM_POSTGRES|self::PLATFORM_SQLITE|self::PLATFORM_MARIADB

getError()

Gets the error code and message as a string for logging

public getError() : string

doesn't return anything meaningful

Tags
since
6.0.0
Return values
string

getQueryBuilder()

Gets the QueryBuilder for the connection.

public getQueryBuilder() : IQueryBuilder
Tags
since
8.2.0
note

Since 34.0.0 prefer using self::getTypedQueryBuilder() instead.

Return values
IQueryBuilder

getShardDefinition()

Get the shard definition by name, if configured

public getShardDefinition(string $name) : ShardDefinition|null
Parameters
$name : string
Tags
since
30.0.0
Return values
ShardDefinition|null

insertIfNotExist()

Insert a row if the matching row does not exists. To accomplish proper race condition avoidance it is needed that there is also a unique constraint on the values. Then this method will catch the exception and return 0.

public insertIfNotExist(string $table, array<string|int, mixed> $input[, array<string|int, mixed>|null $compare = null ]) : int
  • use unique index and "try { $db->insert() } catch (\OCP\DB\Exception $e) { if ($e->getReason() === \OCP\DB\Exception::REASON_CONSTRAINT_VIOLATION) } }" instead, because it is more reliable and does not have the risk for deadlocks - see https://github.com/nextcloud/server/pull/12371
Parameters
$table : string

The table name (will replace PREFIX with the actual prefix)

$input : array<string|int, mixed>

data that should be inserted into the table (column name => value)

$compare : array<string|int, mixed>|null = null

List of values that should be checked for "if not exists" If this is null or an empty array, all keys of $input will be compared Please note: text fields (clob) must not be used in the compare array

Tags
throws
Exception

used to be the removed dbal exception, since 21.0.0 it's \OCP\DB\Exception

since
6.0.0
  • parameter $compare was added in 8.1.0, return type changed from boolean in 8.1.0
Return values
int —

number of inserted rows

insertIgnoreConflict()

Insert a row if the row does not exist. Eventual conflicts during insert will be ignored.

public insertIgnoreConflict(string $table, array<string|int, mixed> $values) : int

Implementation is not fully finished and should not be used!

Parameters
$table : string

The table name (will replace PREFIX with the actual prefix)

$values : array<string|int, mixed>

data that should be inserted into the table (column name => value)

Tags
since
16.0.0
Return values
int —

number of inserted rows

inTransaction()

Check if a transaction is active

public inTransaction() : bool
Tags
since
8.2.0
Return values
bool

lastInsertId()

Used to get the id of the just inserted element

public lastInsertId(string $table) : int

use \OCP\DB\QueryBuilder\IQueryBuilder::getLastInsertId

Parameters
$table : string

the name of the table where we inserted the item

Tags
since
6.0.0
throws
Exception

since 21.0.0

Return values
int —

the id of the inserted element

lockTable()

Create an exclusive read+write lock on a table

public lockTable(string $tableName) : void

Important Note: Due to the nature how locks work on different DBs, it is only possible to lock one table at a time. You should also NOT start a transaction while holding a lock.

Parameters
$tableName : string
Tags
throws
Exception

since 21.0.0

since
9.1.0

migrateToSchema()

Migrate the database to the given schema

public migrateToSchema(Schema $toSchema) : void
Parameters
$toSchema : Schema
Tags
throws
Exception

since 21.0.0

since
13.0.0

prepare()

Used to abstract the Nextcloud database access away

public prepare(string $sql[, int|null $limit = null ][, int|null $offset = null ]) : IPreparedStatement
Parameters
$sql : string

the sql query with ? placeholder for params

$limit : int|null = null

the maximum number of rows

$offset : int|null = null

from which row we want to start

Tags
since
6.0.0
throws
Exception

since 21.0.0

psalm-taint-sink

sql $sql

Return values
IPreparedStatement —

The prepared statement.

rollBack()

Rollback the database changes done during a transaction that is in progress

public rollBack() : void
Tags
since
6.0.0
throws
Exception

since 21.0.0

setValues()

Insert or update a row value

public setValues(string $table, array<string|int, mixed> $keys, array<string|int, mixed> $values[, array<string|int, mixed> $updatePreconditionValues = [] ]) : int
Parameters
$table : string
$keys : array<string|int, mixed>

(column name => value)

$values : array<string|int, mixed>

(column name => value)

$updatePreconditionValues : array<string|int, mixed> = []

ensure values match preconditions (column name => value)

Tags
throws
Exception

used to be the removed dbal exception, since 21.0.0 it's \OCP\DB\Exception

PreConditionNotMetException
since
9.0.0
Return values
int —

number of new rows

supports4ByteText()

Check whether or not the current database support 4byte wide unicode

public supports4ByteText() : bool
Tags
since
11.0.0
Return values
bool

tableExists()

Check if a table exists

public tableExists(string $table) : bool
Parameters
$table : string

table name without the prefix

Tags
throws
Exception

since 21.0.0

since
8.0.0
Return values
bool

truncateTable()

Truncate a table data if it exists

public truncateTable(string $table, bool $cascade) : void

Cascade is not supported on many platforms but would optionally cascade the truncate by following the foreign keys.

Parameters
$table : string

table name without the prefix

$cascade : bool

whether to truncate cascading

Tags
throws
Exception
since
32.0.0
psalm-taint-sink

sql $table

unlockTable()

Release a previous acquired lock again

public unlockTable() : void
Tags
throws
Exception

since 21.0.0

since
9.1.0
On this page

Search results