Swoole Coroutine Postgres Client

Notice: the documentation is suitable for PHP extension swoole until v4.7.1, we only support PHP extension openswoole from v4.7.1


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.

This client is maintained as a extension to Swoole, you can find it at: https://github.com/swoole/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-libpq-dir=/etc/postgresql.


Installing ext-postgresql

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

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

Then add extension=swoole_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

use Swoole\Coroutine\PostgreSQL;

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

use Swoole\Coroutine\PostgreSQL;

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


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.