Connection
class Connection implements ConnectionInterface (View source)
Traits
Properties
| static protected array | $macros | The registered string macros. |
from Macroable |
| protected PDO|Closure | $pdo | The active PDO connection. |
|
| protected PDO|Closure | $readPdo | The active PDO connection used for reads. |
|
| protected string | $database | The name of the connected database. |
|
| protected string|null | $readWriteType | The type of the connection. |
|
| protected string | $tablePrefix | The table prefix for the connection. |
|
| protected array | $config | The database connection configuration options. |
|
| protected callable | $reconnector | The reconnector instance for the connection. |
|
| protected Grammar | $queryGrammar | The query grammar implementation. |
|
| protected Grammar | $schemaGrammar | The schema grammar implementation. |
|
| protected Processor | $postProcessor | The query post processor implementation. |
|
| protected Dispatcher | $events | The event dispatcher instance. |
|
| protected int | $fetchMode | The default fetch mode of the connection. |
|
| protected int | $transactions | The number of active transactions. |
|
| protected DatabaseTransactionsManager | $transactionsManager | The transaction manager instance. |
|
| protected bool | $recordsModified | Indicates if changes have been made to the database. |
|
| protected bool | $readOnWriteConnection | Indicates if the connection should use the "write" PDO connection. |
|
| protected array | $queryLog | All of the queries run against the connection. |
|
| protected bool | $loggingQueries | Indicates whether queries are being logged. |
|
| protected float | $totalQueryDuration | The duration of all executed queries in milliseconds. |
|
| protected array | $queryDurationHandlers | All of the registered query duration handlers. |
|
| protected bool | $pretending | Indicates if the connection is in a "dry run". |
|
| protected Closure[] | $beforeExecutingCallbacks | All of the callbacks that should be invoked before a query is executed. |
|
| protected Connection | $doctrineConnection | The instance of Doctrine connection. |
|
| protected array<string,string> | $doctrineTypeMappings | Type mappings that should be registered with new Doctrine connections. |
|
| static protected Closure[] | $resolvers | The connection resolvers. |
Methods
| bool | causedByConcurrencyError(Throwable $e) Determine if the given exception was caused by a concurrency error such as a deadlock or serialization failure. |
from DetectsConcurrencyErrors |
| bool | causedByLostConnection(Throwable $e) Determine if the given exception was caused by a lost connection. |
from DetectsLostConnections |
| mixed | transaction(Closure $callback, int $attempts = 1) Execute a Closure within a transaction. |
from ManagesTransactions |
| void | handleTransactionException(Throwable $e, int $currentAttempt, int $maxAttempts) Handle an exception encountered when running a transacted statement. |
from ManagesTransactions |
| void | beginTransaction() Start a new database transaction. |
from ManagesTransactions |
| void | createTransaction() Create a transaction within the database. |
from ManagesTransactions |
| void | createSavepoint() Create a save point within the database. |
from ManagesTransactions |
| void | handleBeginTransactionException(Throwable $e) Handle an exception from a transaction beginning. |
from ManagesTransactions |
| void | commit() Commit the active database transaction. |
from ManagesTransactions |
| bool | afterCommitCallbacksShouldBeExecuted() Determine if after commit callbacks should be executed. |
from ManagesTransactions |
| void | handleCommitTransactionException(Throwable $e, int $currentAttempt, int $maxAttempts) Handle an exception encountered when committing a transaction. |
from ManagesTransactions |
| void | rollBack(int|null $toLevel = null) Rollback the active database transaction. |
from ManagesTransactions |
| void | performRollBack(int $toLevel) Perform a rollback within the database. |
from ManagesTransactions |
| void | handleRollBackException(Throwable $e) Handle an exception from a rollback. |
from ManagesTransactions |
| int | transactionLevel() Get the number of active transactions. |
from ManagesTransactions |
| void | afterCommit(callable $callback) Execute the callback after a transaction commits. |
from ManagesTransactions |
| int | secondsUntil(DateTimeInterface|DateInterval|int $delay) Get the number of seconds until the given DateTime. |
from InteractsWithTime |
| int | availableAt(DateTimeInterface|DateInterval|int $delay = 0) Get the "available at" UNIX timestamp. |
from InteractsWithTime |
| DateTimeInterface|int | parseDateInterval(DateTimeInterface|DateInterval|int $delay) If the given value is an interval, convert it to a DateTime instance. |
from InteractsWithTime |
| int | currentTime() Get the current system time as a UNIX timestamp. |
from InteractsWithTime |
| static void | macro(string $name, object|callable $macro) Register a custom macro. |
from Macroable |
| static void | mixin(object $mixin, bool $replace = true) Mix another object into the class. |
from Macroable |
| static bool | hasMacro(string $name) Checks if macro is registered. |
from Macroable |
| static void | flushMacros() Flush the existing macros. |
from Macroable |
| static mixed | __callStatic(string $method, array $parameters) Dynamically handle calls to the class. |
from Macroable |
| mixed | __call(string $method, array $parameters) Dynamically handle calls to the class. |
from Macroable |
| void | __construct(PDO|Closure $pdo, string $database = '', string $tablePrefix = '', array $config = []) Create a new database connection instance. |
|
| void | useDefaultQueryGrammar() Set the query grammar to the default implementation. |
|
| Grammar | getDefaultQueryGrammar() Get the default query grammar instance. |
|
| void | useDefaultSchemaGrammar() Set the schema grammar to the default implementation. |
|
| Grammar|null | getDefaultSchemaGrammar() Get the default schema grammar instance. |
|
| void | useDefaultPostProcessor() Set the query post processor to the default implementation. |
|
| Processor | getDefaultPostProcessor() Get the default post processor instance. |
|
| Builder | getSchemaBuilder() Get a schema builder instance for the connection. |
|
| Builder | table(Closure|Builder|string $table, string|null $as = null) Begin a fluent query against a database table. |
|
| Builder | query() Get a new query builder instance. |
|
| mixed | selectOne(string $query, array $bindings = [], bool $useReadPdo = true) Run a select statement and return a single result. |
|
| mixed | scalar(string $query, array $bindings = [], bool $useReadPdo = true) Run a select statement and return the first column of the first row. |
|
| array | selectFromWriteConnection(string $query, array $bindings = []) Run a select statement against the database. |
|
| array | select(string $query, array $bindings = [], bool $useReadPdo = true) Run a select statement against the database. |
|
| array | selectResultSets(string $query, array $bindings = [], bool $useReadPdo = true) Run a select statement against the database and returns all of the result sets. |
|
| Generator | cursor(string $query, array $bindings = [], bool $useReadPdo = true) Run a select statement against the database and returns a generator. |
|
| PDOStatement | prepared(PDOStatement $statement) Configure the PDO prepared statement. |
|
| PDO | getPdoForSelect(bool $useReadPdo = true) Get the PDO connection to use for a select query. |
|
| bool | insert(string $query, array $bindings = []) Run an insert statement against the database. |
|
| int | update(string $query, array $bindings = []) Run an update statement against the database. |
|
| int | delete(string $query, array $bindings = []) Run a delete statement against the database. |
|
| bool | statement(string $query, array $bindings = []) Execute an SQL statement and return the boolean result. |
|
| int | affectingStatement(string $query, array $bindings = []) Run an SQL statement and get the number of rows affected. |
|
| bool | unprepared(string $query) Run a raw, unprepared query against the PDO connection. |
|
| array | pretend(Closure $callback) Execute the given callback in "dry run" mode. |
|
| array | withFreshQueryLog(Closure $callback) Execute the given callback in "dry run" mode. |
|
| void | bindValues(PDOStatement $statement, array $bindings) Bind values to their parameters in the given statement. |
|
| array | prepareBindings(array $bindings) Prepare the query bindings for execution. |
|
| mixed | run(string $query, array $bindings, Closure $callback) Run a SQL statement and log its execution context. |
|
| mixed | runQueryCallback(string $query, array $bindings, Closure $callback) Run a SQL statement. |
|
| void | logQuery(string $query, array $bindings, float|null $time = null) Log a query in the connection's query log. |
|
| float | getElapsedTime(int $start) Get the elapsed time since a given starting point. |
|
| void | whenQueryingForLongerThan(DateTimeInterface|CarbonInterval|float|int $threshold, callable $handler) Register a callback to be invoked when the connection queries for longer than a given amount of time. |
|
| void | allowQueryDurationHandlersToRunAgain() Allow all the query duration handlers to run again, even if they have already run. |
|
| float | totalQueryDuration() Get the duration of all run queries in milliseconds. |
|
| void | resetTotalQueryDuration() Reset the duration of all run queries. |
|
| mixed | handleQueryException(QueryException $e, string $query, array $bindings, Closure $callback) Handle a query exception. |
|
| mixed | tryAgainIfCausedByLostConnection(QueryException $e, string $query, array $bindings, Closure $callback) Handle a query exception that occurred during query execution. |
|
| mixed|false | reconnect() Reconnect to the database. |
|
| void | reconnectIfMissingConnection() Reconnect to the database if a PDO connection is missing. |
|
| void | disconnect() Disconnect from the underlying PDO connection. |
|
| $this | beforeExecuting(Closure $callback) Register a hook to be run just before a database query is executed. |
|
| void | listen(Closure $callback) Register a database query listener with the connection. |
|
| array|null | fireConnectionEvent(string $event) Fire an event for this connection. |
|
| void | event(mixed $event) Fire the given event if possible. |
|
| Expression | raw(mixed $value) Get a new raw query expression. |
|
| string | escape(string|float|int|bool|null $value, bool $binary = false) Escape a value for safe SQL embedding. |
|
| string | escapeString(string $value) Escape a string value for safe SQL embedding. |
|
| string | escapeBool(bool $value) Escape a boolean value for safe SQL embedding. |
|
| string | escapeBinary(string $value) Escape a binary value for safe SQL embedding. |
|
| bool | hasModifiedRecords() Determine if the database connection has modified any database records. |
|
| void | recordsHaveBeenModified(bool $value = true) Indicate if any records have been modified. |
|
| $this | setRecordModificationState(bool $value) Set the record modification state. |
|
| void | forgetRecordModificationState() Reset the record modification state. |
|
| $this | useWriteConnectionWhenReading(bool $value = true) Indicate that the connection should use the write PDO connection for reads. |
|
| bool | isDoctrineAvailable() Is Doctrine available? |
|
| bool | usingNativeSchemaOperations() Indicates whether native alter operations will be used when dropping, renaming, or modifying columns, even if Doctrine DBAL is installed. |
|
| Column | getDoctrineColumn(string $table, string $column) Get a Doctrine Schema Column instance. |
|
| AbstractSchemaManager | getDoctrineSchemaManager() Get the Doctrine DBAL schema manager for the connection. |
|
| Connection | getDoctrineConnection() Get the Doctrine DBAL database connection instance. |
|
| void | registerDoctrineType(Type|string $class, string $name, string $type) Register a custom Doctrine mapping type. |
|
| PDO | getPdo() Get the current PDO connection. |
|
| PDO|Closure|null | getRawPdo() Get the current PDO connection parameter without executing any reconnect logic. |
|
| PDO | getReadPdo() Get the current PDO connection used for reading. |
|
| PDO|Closure|null | getRawReadPdo() Get the current read PDO connection parameter without executing any reconnect logic. |
|
| $this | setPdo(PDO|Closure|null $pdo) Set the PDO connection. |
|
| $this | setReadPdo(PDO|Closure|null $pdo) Set the PDO connection used for reading. |
|
| $this | setReconnector(callable $reconnector) Set the reconnect instance on the connection. |
|
| string|null | getName() Get the database connection name. |
|
| string|null | getNameWithReadWriteType() Get the database connection full name. |
|
| mixed | getConfig(string|null $option = null) Get an option from the configuration options. |
|
| string | getDriverName() Get the PDO driver name. |
|
| Grammar | getQueryGrammar() Get the query grammar used by the connection. |
|
| $this | setQueryGrammar(Grammar $grammar) Set the query grammar used by the connection. |
|
| Grammar | getSchemaGrammar() Get the schema grammar used by the connection. |
|
| $this | setSchemaGrammar(Grammar $grammar) Set the schema grammar used by the connection. |
|
| Processor | getPostProcessor() Get the query post processor used by the connection. |
|
| $this | setPostProcessor(Processor $processor) Set the query post processor used by the connection. |
|
| Dispatcher | getEventDispatcher() Get the event dispatcher used by the connection. |
|
| $this | setEventDispatcher(Dispatcher $events) Set the event dispatcher instance on the connection. |
|
| void | unsetEventDispatcher() Unset the event dispatcher for this connection. |
|
| $this | setTransactionManager(DatabaseTransactionsManager $manager) Set the transaction manager instance on the connection. |
|
| void | unsetTransactionManager() Unset the transaction manager for this connection. |
|
| bool | pretending() Determine if the connection is in a "dry run". |
|
| array | getQueryLog() Get the connection query log. |
|
| void | flushQueryLog() Clear the query log. |
|
| void | enableQueryLog() Enable the query log on the connection. |
|
| void | disableQueryLog() Disable the query log on the connection. |
|
| bool | logging() Determine whether we're logging queries. |
|
| string | getDatabaseName() Get the name of the connected database. |
|
| $this | setDatabaseName(string $database) Set the name of the connected database. |
|
| $this | setReadWriteType(string|null $readWriteType) Set the read / write type of the connection. |
|
| string | getTablePrefix() Get the table prefix for the connection. |
|
| $this | setTablePrefix(string $prefix) Set the table prefix in use by the connection. |
|
| Grammar | withTablePrefix(Grammar $grammar) Set the table prefix and return the grammar. |
|
| static void | resolverFor(string $driver, Closure $callback) Register a connection resolver. |
|
| static mixed | getResolver(string $driver) Get the connection resolver for the given driver. |
Details
protected bool causedByConcurrencyError(Throwable $e)
Determine if the given exception was caused by a concurrency error such as a deadlock or serialization failure.
protected bool causedByLostConnection(Throwable $e)
Determine if the given exception was caused by a lost connection.
mixed transaction(Closure $callback, int $attempts = 1)
Execute a Closure within a transaction.
protected void handleTransactionException(Throwable $e, int $currentAttempt, int $maxAttempts)
Handle an exception encountered when running a transacted statement.
void beginTransaction()
Start a new database transaction.
protected void createTransaction()
Create a transaction within the database.
protected void createSavepoint()
Create a save point within the database.
protected void handleBeginTransactionException(Throwable $e)
Handle an exception from a transaction beginning.
void commit()
Commit the active database transaction.
protected bool afterCommitCallbacksShouldBeExecuted()
Determine if after commit callbacks should be executed.
protected void handleCommitTransactionException(Throwable $e, int $currentAttempt, int $maxAttempts)
Handle an exception encountered when committing a transaction.
void rollBack(int|null $toLevel = null)
Rollback the active database transaction.
protected void performRollBack(int $toLevel)
Perform a rollback within the database.
protected void handleRollBackException(Throwable $e)
Handle an exception from a rollback.
int transactionLevel()
Get the number of active transactions.
void afterCommit(callable $callback)
Execute the callback after a transaction commits.
protected int secondsUntil(DateTimeInterface|DateInterval|int $delay)
Get the number of seconds until the given DateTime.
protected int availableAt(DateTimeInterface|DateInterval|int $delay = 0)
Get the "available at" UNIX timestamp.
protected DateTimeInterface|int parseDateInterval(DateTimeInterface|DateInterval|int $delay)
If the given value is an interval, convert it to a DateTime instance.
protected int currentTime()
Get the current system time as a UNIX timestamp.
static void macro(string $name, object|callable $macro)
Register a custom macro.
static void mixin(object $mixin, bool $replace = true)
Mix another object into the class.
static bool hasMacro(string $name)
Checks if macro is registered.
static void flushMacros()
Flush the existing macros.
static mixed __callStatic(string $method, array $parameters)
Dynamically handle calls to the class.
mixed __call(string $method, array $parameters)
Dynamically handle calls to the class.
void __construct(PDO|Closure $pdo, string $database = '', string $tablePrefix = '', array $config = [])
Create a new database connection instance.
void useDefaultQueryGrammar()
Set the query grammar to the default implementation.
protected Grammar getDefaultQueryGrammar()
Get the default query grammar instance.
void useDefaultSchemaGrammar()
Set the schema grammar to the default implementation.
protected Grammar|null getDefaultSchemaGrammar()
Get the default schema grammar instance.
void useDefaultPostProcessor()
Set the query post processor to the default implementation.
protected Processor getDefaultPostProcessor()
Get the default post processor instance.
Builder getSchemaBuilder()
Get a schema builder instance for the connection.
Builder table(Closure|Builder|string $table, string|null $as = null)
Begin a fluent query against a database table.
Builder query()
Get a new query builder instance.
mixed selectOne(string $query, array $bindings = [], bool $useReadPdo = true)
Run a select statement and return a single result.
mixed scalar(string $query, array $bindings = [], bool $useReadPdo = true)
Run a select statement and return the first column of the first row.
array selectFromWriteConnection(string $query, array $bindings = [])
Run a select statement against the database.
array select(string $query, array $bindings = [], bool $useReadPdo = true)
Run a select statement against the database.
array selectResultSets(string $query, array $bindings = [], bool $useReadPdo = true)
Run a select statement against the database and returns all of the result sets.
Generator cursor(string $query, array $bindings = [], bool $useReadPdo = true)
Run a select statement against the database and returns a generator.
protected PDOStatement prepared(PDOStatement $statement)
Configure the PDO prepared statement.
protected PDO getPdoForSelect(bool $useReadPdo = true)
Get the PDO connection to use for a select query.
bool insert(string $query, array $bindings = [])
Run an insert statement against the database.
int update(string $query, array $bindings = [])
Run an update statement against the database.
int delete(string $query, array $bindings = [])
Run a delete statement against the database.
bool statement(string $query, array $bindings = [])
Execute an SQL statement and return the boolean result.
int affectingStatement(string $query, array $bindings = [])
Run an SQL statement and get the number of rows affected.
bool unprepared(string $query)
Run a raw, unprepared query against the PDO connection.
array pretend(Closure $callback)
Execute the given callback in "dry run" mode.
protected array withFreshQueryLog(Closure $callback)
Execute the given callback in "dry run" mode.
void bindValues(PDOStatement $statement, array $bindings)
Bind values to their parameters in the given statement.
array prepareBindings(array $bindings)
Prepare the query bindings for execution.
protected mixed run(string $query, array $bindings, Closure $callback)
Run a SQL statement and log its execution context.
protected mixed runQueryCallback(string $query, array $bindings, Closure $callback)
Run a SQL statement.
void logQuery(string $query, array $bindings, float|null $time = null)
Log a query in the connection's query log.
protected float getElapsedTime(int $start)
Get the elapsed time since a given starting point.
void whenQueryingForLongerThan(DateTimeInterface|CarbonInterval|float|int $threshold, callable $handler)
Register a callback to be invoked when the connection queries for longer than a given amount of time.
void allowQueryDurationHandlersToRunAgain()
Allow all the query duration handlers to run again, even if they have already run.
float totalQueryDuration()
Get the duration of all run queries in milliseconds.
void resetTotalQueryDuration()
Reset the duration of all run queries.
protected mixed handleQueryException(QueryException $e, string $query, array $bindings, Closure $callback)
Handle a query exception.
protected mixed tryAgainIfCausedByLostConnection(QueryException $e, string $query, array $bindings, Closure $callback)
Handle a query exception that occurred during query execution.
mixed|false reconnect()
Reconnect to the database.
void reconnectIfMissingConnection()
Reconnect to the database if a PDO connection is missing.
void disconnect()
Disconnect from the underlying PDO connection.
$this beforeExecuting(Closure $callback)
Register a hook to be run just before a database query is executed.
void listen(Closure $callback)
Register a database query listener with the connection.
protected array|null fireConnectionEvent(string $event)
Fire an event for this connection.
protected void event(mixed $event)
Fire the given event if possible.
Expression raw(mixed $value)
Get a new raw query expression.
string escape(string|float|int|bool|null $value, bool $binary = false)
Escape a value for safe SQL embedding.
protected string escapeString(string $value)
Escape a string value for safe SQL embedding.
protected string escapeBool(bool $value)
Escape a boolean value for safe SQL embedding.
protected string escapeBinary(string $value)
Escape a binary value for safe SQL embedding.
bool hasModifiedRecords()
Determine if the database connection has modified any database records.
void recordsHaveBeenModified(bool $value = true)
Indicate if any records have been modified.
$this setRecordModificationState(bool $value)
Set the record modification state.
void forgetRecordModificationState()
Reset the record modification state.
$this useWriteConnectionWhenReading(bool $value = true)
Indicate that the connection should use the write PDO connection for reads.
bool isDoctrineAvailable()
Is Doctrine available?
bool usingNativeSchemaOperations()
Indicates whether native alter operations will be used when dropping, renaming, or modifying columns, even if Doctrine DBAL is installed.
Column getDoctrineColumn(string $table, string $column)
Get a Doctrine Schema Column instance.
AbstractSchemaManager getDoctrineSchemaManager()
Get the Doctrine DBAL schema manager for the connection.
Connection getDoctrineConnection()
Get the Doctrine DBAL database connection instance.
void registerDoctrineType(Type|string $class, string $name, string $type)
Register a custom Doctrine mapping type.
PDO getPdo()
Get the current PDO connection.
PDO|Closure|null getRawPdo()
Get the current PDO connection parameter without executing any reconnect logic.
PDO getReadPdo()
Get the current PDO connection used for reading.
PDO|Closure|null getRawReadPdo()
Get the current read PDO connection parameter without executing any reconnect logic.
$this setReconnector(callable $reconnector)
Set the reconnect instance on the connection.
string|null getName()
Get the database connection name.
string|null getNameWithReadWriteType()
Get the database connection full name.
mixed getConfig(string|null $option = null)
Get an option from the configuration options.
string getDriverName()
Get the PDO driver name.
Grammar getQueryGrammar()
Get the query grammar used by the connection.
$this setQueryGrammar(Grammar $grammar)
Set the query grammar used by the connection.
Grammar getSchemaGrammar()
Get the schema grammar used by the connection.
$this setSchemaGrammar(Grammar $grammar)
Set the schema grammar used by the connection.
Processor getPostProcessor()
Get the query post processor used by the connection.
$this setPostProcessor(Processor $processor)
Set the query post processor used by the connection.
Dispatcher getEventDispatcher()
Get the event dispatcher used by the connection.
$this setEventDispatcher(Dispatcher $events)
Set the event dispatcher instance on the connection.
void unsetEventDispatcher()
Unset the event dispatcher for this connection.
$this setTransactionManager(DatabaseTransactionsManager $manager)
Set the transaction manager instance on the connection.
void unsetTransactionManager()
Unset the transaction manager for this connection.
bool pretending()
Determine if the connection is in a "dry run".
array getQueryLog()
Get the connection query log.
void flushQueryLog()
Clear the query log.
void enableQueryLog()
Enable the query log on the connection.
void disableQueryLog()
Disable the query log on the connection.
bool logging()
Determine whether we're logging queries.
string getDatabaseName()
Get the name of the connected database.
$this setDatabaseName(string $database)
Set the name of the connected database.
$this setReadWriteType(string|null $readWriteType)
Set the read / write type of the connection.
string getTablePrefix()
Get the table prefix for the connection.
$this setTablePrefix(string $prefix)
Set the table prefix in use by the connection.
static void resolverFor(string $driver, Closure $callback)
Register a connection resolver.
static mixed getResolver(string $driver)
Get the connection resolver for the given driver.
© Taylor Otwell
Licensed under the MIT License.
Laravel is a trademark of Taylor Otwell.
https://laravel.com/api/10.x/Illuminate/Database/Connection.html