Swoole 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 Swoole 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 Swoole installed, you can compile and install the ext-postgresql client:

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

Then add extension=openswoole_postgresql.so to your php.ini file to enable the Swoole Postgres extension.

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

How to use Swoole Postgres Client

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

General Example

<?php

Co\run(function()
{
    $pg = new use Swoole\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 Swoole\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

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

Check query result status

The following query result status are available:

• \OPENSWOOLE_PGRES_EMPTY_QUERY
• \OPENSWOOLE_PGRES_COMMAND_OK
• \OPENSWOOLE_PGRES_TUPLES_OK
• \OPENSWOOLE_PGRES_BAD_RESPONSE
• \OPENSWOOLE_PGRES_NONFATAL_ERROR
• \OPENSWOOLE_PGRES_FATAL_ERROR

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

<?php
Co\run(function()
{
    $pg = new Swoole\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_PGRES_EMPTY_QUERY, \OPENSWOOLE_PGRES_COMMAND_OK, \OPENSWOOLE_PGRES_TUPLES_OK]))) {
        throw new Exception("PG client error", $conn->errCode);
    }
});

Dealing with Errors

<?php

use Swoole\Coroutine\PostgreSQL;

Co\run(function()
{
    $pg = new Swoole\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 Swoole client is written using coroutines, their timeouts are set the same way, refer to the timeout guide to understand how to setup timeouts.