You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 809b73b
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/1-essentials/03-database.md
+34Lines changed: 34 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -36,6 +36,40 @@ return new PostgresConfig(
36
36
);
37
37
```
38
38
39
+
### Connecting with a connection string
40
+
41
+
Some hosting providers, such as Laravel Cloud, inject the connection details as a single `DATABASE_URL` environment variable. Each configuration class provides a `fromConnectionString()` method that builds the configuration from such a connection string:
Components missing from the connection string fall back to their defaults. Any other constructor argument may be passed by name, and takes precedence over the values parsed from the connection string:
To connect through a Unix socket, pass its path as a percent-encoded host, or as the `host` query parameter for PostgreSQL and the `unix_socket` query parameter for MySQL:
{b`Tempest\Database\Config\MysqlConfig`} accepts the `mysql` and `mariadb` schemes, {b`Tempest\Database\Config\PostgresConfig`} accepts `postgres`, `postgresql` and `pgsql`, and {b`Tempest\Database\Config\SQLiteConfig`} accepts connection strings such as `sqlite:///path/to/database.sqlite` and `sqlite::memory:`. Credentials containing special characters must be percent-encoded.
70
+
71
+
The parsed components are also available through the {b`Tempest\Database\Config\DatabaseConnectionString`} value object, using `DatabaseConnectionString::from()`.
72
+
39
73
## Querying the database
40
74
41
75
Multiple approaches exist for querying the database, all of which execute a {b`Tempest\Database\Query`} on the {b`Tempest\Database\Database`} class. The most straightforward approach is to inject {b`Tempest\Database\Database`}:
* @param string $scheme The scheme, such as `mysql` or `postgres`.
22
+
* @param null|string $host The host, or the path to a Unix socket.
23
+
* @param null|int $port The port.
24
+
* @param null|string $username The username.
25
+
* @param null|string $password The password.
26
+
* @param null|string $path The path following the authority, such as `/database` or `/path/to/database.sqlite`.
27
+
* @param array<string,string> $parameters The query parameters, such as `sslmode` or `connect_timeout`.
28
+
*/
29
+
publicfunction__construct(
30
+
publicreadonlystring$scheme,
31
+
publicreadonly ?string$host = null,
32
+
publicreadonly ?int$port = null,
33
+
publicreadonly ?string$username = null,
34
+
#[SensitiveParameter]
35
+
publicreadonly ?string$password = null,
36
+
publicreadonly ?string$path = null,
37
+
publicreadonlyarray$parameters = [],
38
+
) {}
39
+
40
+
/**
41
+
* Creates a DatabaseConnectionString instance from a connection string, such as `postgres://user:password@host:5432/database?sslmode=require`. Components are percent-decoded, so a Unix socket may be given as a percent-encoded host.
* Creates a MySQL configuration from a connection string, such as `mysql://user:password@host:3306/database?charset=utf8mb4`. Components missing from the connection string fall back to their defaults, and query parameters are appended to the DSN. A Unix socket may be given as a percent-encoded host or as the `unix_socket` query parameter.
113
+
*
114
+
* @param string $connectionString The connection string. Supported schemes are `mysql` and `mariadb`.
115
+
* @param mixed ...$options Named constructor arguments, which take precedence over the values parsed from the connection string.
* Creates a PostgreSQL configuration from a connection string, such as `postgres://user:password@host:5432/database?sslmode=require`. Components missing from the connection string fall back to their defaults, and query parameters are appended to the DSN. As with libpq, the `host`, `port`, `user`, `password` and `dbname` query parameters take precedence over the other components, so a Unix socket may be given as `postgres:///database?host=/var/run/postgresql` or as a percent-encoded host.
90
+
*
91
+
* @param string $connectionString The connection string. Supported schemes are `postgres`, `postgresql` and `pgsql`.
92
+
* @param mixed ...$options Named constructor arguments, which take precedence over the values parsed from the connection string.
returnnewself('The database connection string could not be parsed. Make sure it is a valid URI with a scheme, e.g. `mysql://user:password@host:3306/database`.');
14
+
}
15
+
16
+
publicstaticfunctionhostWasMissing(): self
17
+
{
18
+
returnnewself('The database connection string must contain a host, or a Unix socket in its query parameters.');
0 commit comments