OpenSwoole Coroutine Postgres Client

The Coroutine Postgres Client is included in the main extension since version v4.8.0.

Coroutine PHP PostgreSQL Client, support for using Postgres with OpenSwoole and coroutines.

You can use the provided Postgres client within a coroutine context without blocking the process.

You can enable Coroutine PHP PostgreSQL Client with option: --with-postgres[=DIR].

If you are using Open Swoole < v4.8.0, you can install ext-postgresql.

Prerequisites

• libpq is required.
• ext-postgresql is requried.

Ubuntu

You may use sudo apt-get install libpq-dev.

CentOS

You may use yum install postgresql10-devel.

Other

You may specify a custom location for libpq with ./configure --with-postgres[=DIR].

Installing ext-postgresql

Once you have OpenSwoole installed, you can compile and install the ext-postgresql client:

git clone [email protected]:openswoole/ext-postgresql.git
phpize
./configure
make && make install

You must choose a version from the release page which is compatible with OpenSwoole's version

How to use OpenSwoole Postgres Client

The methods available are same as the original PHP PostgreSQL client.

General Example

<?php

co::run(function()
{
    $pg = new use OpenSwoole\Coroutine\PostgreSQL();

    $conn = $pg->connect("host=127.0.0.1;port=5432;dbname=test;user=postgres;password=***");

    if(!$conn)
    {
        var_dump($pg->error);
        return;
    }

    $result = $pg->query('SELECT * FROM test;');

    $arr = $pg->fetchAll($result);
    var_dump($arr);
});

Transaction Processing

<?php

co::run(function()
{
    $pg = new OpenSwoole\Coroutine\PostgreSQL();

    $conn = $pg->connect("host=127.0.0.1;port=5432;dbname=test;user=postgres;password=***");

    $pg->query('BEGIN');
    $result = $pg->query('SELECT * FROM test');
    $arr = $pg->fetchAll($result);
    $pg->query('COMMIT');

    var_dump($arr);
});

Methods

• OpenSwoole\Coroutine\PostgreSQL->connect(...)
• OpenSwoole\Coroutine\PostgreSQL->query(...)
• OpenSwoole\Coroutine\PostgreSQL->fetchAll(...)
• OpenSwoole\Coroutine\PostgreSQL->affectedRows(...)
• OpenSwoole\Coroutine\PostgreSQL->numRows(...)
• OpenSwoole\Coroutine\PostgreSQL->fetchObject(...)
• OpenSwoole\Coroutine\PostgreSQL->fetchAssoc(...)
• OpenSwoole\Coroutine\PostgreSQL->fetchArray(...)
• OpenSwoole\Coroutine\PostgreSQL->fetchRow(...)
• OpenSwoole\Coroutine\PostgreSQL->metaData(...)
• OpenSwoole\Coroutine\PostgreSQL->prepare(...)
• OpenSwoole\Coroutine\PostgreSQL->reset()
• OpenSwoole\Coroutine\PostgreSQL->status()

Check query result status

The following query result status are available:

• \OpenSwoole\Constant::PGRES_EMPTY_QUERY
• \OpenSwoole\Constant::PGRES_COMMAND_OK
• \OpenSwoole\Constant::PGRES_TUPLES_OK
• \OpenSwoole\Constant::PGRES_BAD_RESPONSE
• \OpenSwoole\Constant::PGRES_NONFATAL_ERROR
• \OpenSwoole\Constant::PGRES_FATAL_ERROR

You can check the result status with value $conn->resultStatus.

<?php
co::run(function()
{
    $pg = new OpenSwoole\Coroutine\PostgreSQL();
    $conn = $pg->connect("host=127.0.0.1;port=5432;dbname=test;user=postgres;password=***");
    $pg->query('SELECT 1');
    var_dump($conn->resultStatus);
    if (!(in_array($conn->resultStatus, [\OpenSwoole\Constant::PGRES_EMPTY_QUERY, \OpenSwoole\Constant::PGRES_COMMAND_OK, \OpenSwoole\Constant::PGRES_TUPLES_OK]))) {
        throw new Exception("PG client error", $conn->errCode);
    }
});

Dealing with Errors

<?php

use OpenSwoole\Coroutine\PostgreSQL;

co::run(function()
{
    $pg = new OpenSwoole\Coroutine\PostgreSQL();

    $conn = $pg->connect("host=127.0.0.1;port=5432;dbname=test;user=postgres;password=***");

    if(!$conn)
    {
        var_dump($pg->error);
        return;
    }

    $result = $pg->query('SELECT * FROM weather;');
    if(!$result)
    {
        var_dump($pg->error);
        return;
    }

    $arr = $pg->fetchAll($result);
    var_dump($arr);

    $result = $pg->query('SELECT * FROM weather;');
    if(!$result)
    {
        var_dump($pg->error);
        return;
    }

    $arr = $pg->fetchAll($result);
    var_dump($arr);
});

From the example we can use $pg->error to output any problems we have and check what went wrong.

Client Timeouts

All network requests (establish a connection, send data and receive data) may time out.

As each OpenSwoole client is written using coroutines, their timeouts are set the same way, refer to the timeout guide to understand how to setup timeouts.