Andromeda\Core\Database\Database | Andromeda Server API

class Database implements Transactions

This class implements the PDO database abstraction.

Manages connecting to the database, installing config, abstracting some driver differences, and logging queries and performance statistics. Queries are always made as part of a transaction, and always used as prepared statements. Performance statistics and queries are tracked as a stack, but transactions cannot be nested. Queries made must always be compatible with all supported drivers.

Constants

private CONFIG_PATHS	the default path for storing the config file
DRIVER_MYSQL
DRIVER_SQLITE
DRIVER_POSTGRESQL
private DRIVERS
QUERY_READ
QUERY_WRITE

Properties

private	$connection	the PDO database connection
protected array<string,mixed>	$config
protected	$driver	The enum value of the driver being used
private	$read_only	if true, don't allow writes
private DBStats[]	$stats_stack
private	$queries	global history of SQL queries sent to the DB (not a stack)

Methods

int

getDriver()

No description

__construct(string|null $config = null)

Constructs the database and initializes the PDO connection

static string

GetInstallUsage()

Returns a string with the primary CLI usage for Install()

static array

GetInstallUsages()

Returns the CLI usages specific to each driver

static string|null

Install(Input $input)

Creates and tests a new database config from the given user input

array

GetClientObject()

returns the array of config that was loaded from the config file

array

getInfo()

returns an array with some PDO attributes for debugging

Database

setReadOnly(bool $ro = true)

Sets the database as writeable or readonly

bool

isReadOnly()

Returns true if the database is read-only

Database

importTemplate(string $path)

Imports the appropriate SQL template file for an app

Database

importFile(string $path)

Parses and imports an SQL file into the database

bool

SupportsRETURNING()

Whether or not the DB supports the RETURNING keyword

bool

RequiresSAVEPOINT()

Whether or not the DB aborts transactions after an error and requires use of SAVEPOINTs

bool

BinaryAsStreams()

Whether or not the DB fetches binary/blob fields as streams rather than scalars

bool

BinaryEscapeInput()

Whether or not the DB requires binary input to be escaped

bool

UsePublicSchema()

Whether or not the DB expects using public. as a prefix for table names

string

SQLConcat(string ...$args)

Returns the given arguments concatenated in SQL

string

SQLUpsert(string $query)

Returns the driver-specific SQL UPSERT DO NOTHING query

bool

inTransaction()

Returns true if the DB is currently in a transaction

array|int|null

query(string $sql, int $type, array|null $data = null)

Sends an SQL query down to the database, possibly beginning a transaction

string

logQuery(string $sql, array|null $data)

Logs a query to the internal query history, logging the actual data values if debug allows

void

fetchStreams(array $rows)

Loops through an array of row results and replaces streams with their values

void

beginTransaction()

Begins a new database transaction

rollback()

Rolls back the current database transaction

commit()

Commits the current database transaction

void

startTimingQuery()

Begins timing a query (performance metrics)

void

stopTimingQuery(string $sql, int $type, bool $count = true)

Ends timing a query (performance metrics)

Database

pushStatsContext()

Add a new performance metrics context on to the stack

DBStats|null

popStatsContext()

Pop the current performance metrics context off of the stack

array

getAllQueries()

Returns the array of query history

Details

at line 90
`int getDriver()`

No description

Return Value

int

at line 98
`__construct(string|null $config = null)`

Constructs the database and initializes the PDO connection

Parameters

string|null

$config

the path to the config file to use, generated by Install()

Exceptions

DatabaseConfigException	if the given path does not exist
InvalidDriverException	if the driver in the config is invalid

at line 155
`static string GetInstallUsage()`

Returns a string with the primary CLI usage for Install()

Return Value

string

at line 161
`static array GetInstallUsages()`

Returns the CLI usages specific to each driver

Return Value

array

at line 177
`static string|null Install(Input $input)`

Creates and tests a new database config from the given user input

Parameters

Input

$input

input parameters

Return Value

string|null

the database config file contents

Exceptions

Throwable

if the database config is not valid and PDO fails

at line 237
`array GetClientObject()`

returns the array of config that was loaded from the config file

Return Value

array

{driver:string, connect:string, ?username:string, ?password:true, ?persistent:bool}

at line 250
`array getInfo()`

returns an array with some PDO attributes for debugging

Return Value

array

{driver:string, cversion:string, sversion:string, info:string}

at line 265
`Database setReadOnly(bool $ro = true)`

Sets the database as writeable or readonly

Parameters

bool

$ro

Return Value

string

at line 321
`string SQLUpsert(string $query)`

Returns the driver-specific SQL UPSERT DO NOTHING query

Parameters

string

$query

the query after INSERT INTO (e.g. table (columns) VALUES (vals)

Return Value

string

compiled query

at line 331
`bool inTransaction()`

Returns true if the DB is currently in a transaction

Return Value

bool

at line 343
`array|int|null query(string $sql, int $type, array|null $data = null)`

Sends an SQL query down to the database, possibly beginning a transaction

Parameters

string	$sql	the SQL query string, with placeholder data values
int	$type	whether the query is a read, a write, or both (bitset)
array\|null	$data	associative array of data replacements for the prepared statement

Return Value

array|int|null

an associative array of the query results for reads, row count for writes

Exceptions

DatabaseReadOnlyException

if the query is a write and the DB is read-only

at line 411
`private string logQuery(string $sql, array|null $data)`

Logs a query to the internal query history, logging the actual data values if debug allows

Parameters

string	$sql
array\|null	$data

at line 514
`array getAllQueries()`

Returns the array of query history

Return Value

array

string array

Database

Constants

Properties

Methods

Details

at line 90 int getDriver()

Return Value

See also

at line 98 __construct(string|null $config = null)

Parameters

Exceptions

at line 155 static string GetInstallUsage()

Return Value

at line 161 static array GetInstallUsages()

Return Value

at line 177 static string|null Install(Input $input)

Parameters

Return Value

Exceptions

See also

at line 237 array GetClientObject()

Return Value

at line 250 array getInfo()

Return Value

at line 265 Database setReadOnly(bool $ro = true)

Parameters

Return Value

at line 268 bool isReadOnly()

Return Value

at line 274 Database importTemplate(string $path)

Parameters

Return Value

at line 280 Database importFile(string $path)

Parameters

Return Value

at line 288 protected bool SupportsRETURNING()

Return Value

at line 295 protected bool RequiresSAVEPOINT()

Return Value

at line 298 protected bool BinaryAsStreams()

Return Value

at line 301 protected bool BinaryEscapeInput()

Return Value

at line 304 protected bool UsePublicSchema()

Return Value

at line 307 string SQLConcat(string ...$args)

Parameters

Return Value

at line 321 string SQLUpsert(string $query)

Parameters

Return Value

at line 331 bool inTransaction()

Return Value

at line 343 array|int|null query(string $sql, int $type, array|null $data = null)

Parameters

Return Value

Exceptions

at line 411 private string logQuery(string $sql, array|null $data)

Parameters

Return Value

at line 433 private void fetchStreams(array $rows)

Parameters

Return Value

at line 446 void beginTransaction()

Return Value

at line 459 rollback()

at line 472 commit()

at line 485 private void startTimingQuery()

Return Value

at line 492 private void stopTimingQuery(string $sql, int $type, bool $count = true)

Parameters

Return Value

at line 499 Database pushStatsContext()

Return Value

at line 505 DBStats|null popStatsContext()

Return Value

at line 514 array getAllQueries()

Return Value

at line 90
`int getDriver()`

at line 98
`__construct(string|null $config = null)`

at line 155
`static string GetInstallUsage()`

at line 161
`static array GetInstallUsages()`

at line 177
`static string|null Install(Input $input)`

at line 237
`array GetClientObject()`

at line 250
`array getInfo()`

at line 265
`Database setReadOnly(bool $ro = true)`

at line 268
`bool isReadOnly()`

at line 274
`Database importTemplate(string $path)`

at line 280
`Database importFile(string $path)`

at line 288
`protected bool SupportsRETURNING()`

at line 295
`protected bool RequiresSAVEPOINT()`

at line 298
`protected bool BinaryAsStreams()`

at line 301
`protected bool BinaryEscapeInput()`

at line 304
`protected bool UsePublicSchema()`

at line 307
`string SQLConcat(string ...$args)`

at line 321
`string SQLUpsert(string $query)`

at line 331
`bool inTransaction()`

at line 343
`array|int|null query(string $sql, int $type, array|null $data = null)`

at line 411
`private string logQuery(string $sql, array|null $data)`

at line 433
`private void fetchStreams(array $rows)`

at line 446
`void beginTransaction()`

at line 459
`rollback()`

at line 472
`commit()`

at line 485
`private void startTimingQuery()`

at line 492
`private void stopTimingQuery(string $sql, int $type, bool $count = true)`

at line 499
`Database pushStatsContext()`

at line 505
`DBStats|null popStatsContext()`

at line 514
`array getAllQueries()`