{"id":27373505,"url":"https://github.com/satur-io/duckdb-php","last_synced_at":"2025-04-13T11:15:12.719Z","repository":{"id":287655666,"uuid":"940054796","full_name":"satur-io/duckdb-php","owner":"satur-io","description":"DuckDB API for PHP 🐘 🦆","archived":false,"fork":false,"pushed_at":"2025-04-13T05:47:35.000Z","size":212471,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-04-13T11:14:53.760Z","etag":null,"topics":["database","duckdb","ffi","ffi-bindings","ffi-wrapper","performance","php","php-library","php8"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/satur-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-27T14:42:16.000Z","updated_at":"2025-04-13T05:47:39.000Z","dependencies_parsed_at":"2025-04-13T06:12:32.902Z","dependency_job_id":null,"html_url":"https://github.com/satur-io/duckdb-php","commit_stats":null,"previous_names":["satur-io/duckdb-php"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satur-io%2Fduckdb-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satur-io%2Fduckdb-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satur-io%2Fduckdb-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satur-io%2Fduckdb-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/satur-io","download_url":"https://codeload.github.com/satur-io/duckdb-php/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248703198,"owners_count":21148118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","duckdb","ffi","ffi-bindings","ffi-wrapper","performance","php","php-library","php8"],"created_at":"2025-04-13T11:15:12.253Z","updated_at":"2025-04-13T11:15:12.700Z","avatar_url":"https://github.com/satur-io.png","language":"C","funding_links":[],"categories":["Client APIs"],"sub_categories":[],"readme":"\u003cimg alt=\"DuckDB logo\" src=\"docs/DuckDB-PHP-logo-noborders.svg\" height=\"150\"\u003e\n\n## DuckDB API for PHP\n\n[![Github Actions Badge](https://github.com/satur-io/duckdb-php/actions/workflows/php_test_main.yml/badge.svg?branch=main)](https://github.com/satur-io/duckdb-php/actions)\n[![Github Actions Badge](https://github.com/satur-io/duckdb-php/actions/workflows/php_test_nightly.yml/badge.svg?branch=main)](https://github.com/satur-io/duckdb-php/actions)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=satur-io_duckdb-php\u0026metric=alert_status\u0026token=4a4bd82eff843d2b4a93bf4552b6db78e598ecfa)](https://sonarcloud.io/summary/new_code?id=satur-io_duckdb-php)\n\nThis package provides a [DuckDB](https://github.com/duckdb/duckdb) Client API for PHP.\n\nFocused on performance, it uses the official [C API](https://duckdb.org/docs/api/c/overview.html) internally through [FFI](https://www.php.net/manual/en/book.ffi.php), achieving good benchmarks.\nThis library is more than just a wrapper for the C API; it introduces custom, PHP-friendly methods to simplify working with DuckDB. It is compatible with Linux, Windows, and macOS, requiring PHP version 8.3 or higher.\n\n### Install\n\n```shell\ncomposer require satur.io/duckdb\n```\n\n### Quick Start\n\n```php\nDuckDB::sql(\"SELECT 'quack' as my_column\")-\u003eprint();\n```\n\n```\n-------------------\n| my_column       |\n-------------------\n| quack           |\n-------------------\n```\n\n\u003e It's that simple! :duck:\n\nLet's see how prepared statements work.\n\n#### Prepared Statements\n```php\n$duckDB = DuckDB::create();\n\n$duckDB-\u003equery(\"CREATE TABLE test (i INTEGER, b BOOL, f FLOAT);\");\n$duckDB-\u003equery('INSERT INTO test VALUES (3, true, 1.1), (5, true, 1.2), (3, false, 1.1), (3, null, 1.2);');\n\n$boolPreparedStatement = $duckDB-\u003epreparedStatement('SELECT * FROM test WHERE b = $1');\n$boolPreparedStatement-\u003ebindParam(1, true);\n$result = $boolPreparedStatement-\u003eexecute();\n$result-\u003eprint();\n\n$intPreparedStatement = $duckDB-\u003epreparedStatement('SELECT * FROM test WHERE i = ?');\n$intPreparedStatement-\u003ebindParam(1, 3);\n$result = $intPreparedStatement-\u003eexecute();\n$result-\u003eprint();\n```\n#### DuckDB powerful\n\nDuckDB provides some amazing features. For example, \nyou can query remote files directly.\n\nLet's use an aggregate function to calculate the average of a column\nfor a parquet remote file:\n\n```php\nDuckDB::sql(\n    'SELECT \"Reporting Year\", avg(\"Gas Produced, MCF\") as \"AVG Gas Produced\" \n                FROM \"https://github.com/plotly/datasets/raw/refs/heads/master/oil-and-gas.parquet\" \n                WHERE \"Reporting Year\" BETWEEN 1985 AND 1990\n                GROUP BY \"Reporting Year\";'\n)-\u003eprint();\n```\n\n```\n--------------------------------------\n| Reporting Year   | AVG Gas Produce |\n--------------------------------------\n| 1985             | 2461.4047344111 |\n| 1986             | 6060.8575605681 |\n| 1987             | 5047.5813074014 |\n| 1988             | 4763.4090541633 |\n| 1989             | 4175.2989758837 |\n| 1990             | 3706.9404742437 |\n--------------------------------------\n```\n\nOr summarize a remote csv:\n\n```php\nDuckDB::sql('SUMMARIZE TABLE \"https://blobs.duckdb.org/data/Star_Trek-Season_1.csv\";')-\u003eprint();\n```\n\n```\n------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\n| column_name      | column_type      | min              | max              | approx_unique    | avg              | std              | q25              | q50              | q75              | count            | null_percentage |\n------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\n| season_num       | BIGINT           | 1                | 1                | 1                | 1.0              | 0.0              | 1                | 1                | 1                | 30               | 0               |\n| episode_num      | BIGINT           | 0                | 29               | 29               | 14.5             | 8.8034084308295  | 7                | 14               | 22               | 30               | 0               |\n| aired_date       | DATE             | 1965-02-28       | 1967-04-13       | 35               |                  |                  | 1966-10-20       | 1966-12-22       | 1967-02-16       | 30               | 0               |\n| cnt_kirk_hookup  | BIGINT           | 0                | 2                | 3                | 0.3333333333333  | 0.6064784348631  | 0                | 0                | 1                | 30               | 0               |\n\n...\n\n```\n\nI would recommend taking a look at the [DuckDB documentation](https://duckdb.org/docs/stable/sql/introduction) to figure out\nall possibilities.\n\n\u003e [!TIP]\n\u003e Do you want more use cases? Check the [examples folder](examples).\n\n### Requirements\n- Linux, macOS, or Windows\n- x64 platform\n- PHP \u003e= 8.3\n- ext-ffi\n\n#### Recommended\n- ext-bcmath - Needed for big integers (\u003e PHP_INT_MAX)\n- ext-zend-opcache - For better performance\n\n### Type Support\n| DuckDB Type              | SQL Type     | PHP Type                      |                                    Read                                    |                                    Bind                                    |\n|--------------------------|--------------|-------------------------------|:--------------------------------------------------------------------------:|:--------------------------------------------------------------------------:|\n| DUCKDB_TYPE_BOOLEAN      | BOOLEAN      | bool                          |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_TINYINT      | TINYINT      | int                           |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_SMALLINT     | SMALLINT     | int                           |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_INTEGER      | INTEGER      | int                           |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_BIGINT       | BIGINT       | int                           |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_UTINYINT     | UTINYINT     | int                           |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_USMALLINT    | USMALLINT    | int                           |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_UINTEGER     | UINTEGER     | int                           |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_UBIGINT      | UBIGINT      | string                        | [:ballot_box_with_check:](https://github.com/satur-io/duckdb-php/issues/1) | [:ballot_box_with_check:](https://github.com/satur-io/duckdb-php/issues/1) |\n| DUCKDB_TYPE_FLOAT        | FLOAT        | float                         |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_DOUBLE       | DOUBLE       | float                         |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_TIMESTAMP    | TIMESTAMP    | Saturio\\DuckDB\\Type\\Timestamp |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_DATE         | DATE         | Saturio\\DuckDB\\Type\\Date      |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_TIME         | TIME         | Saturio\\DuckDB\\Type\\Time      |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_INTERVAL     | INTERVAL     | Saturio\\DuckDB\\Type\\Interval  |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_HUGEINT      | HUGEINT      | string                        | [:ballot_box_with_check:](https://github.com/satur-io/duckdb-php/issues/1) |                             :white_check_mark:                             |\n| DUCKDB_TYPE_UHUGEINT     | UHUGEINT     | string                        | [:ballot_box_with_check:](https://github.com/satur-io/duckdb-php/issues/1) |                             :white_check_mark:                             |\n| DUCKDB_TYPE_VARCHAR      | VARCHAR      | string                        |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_BLOB         | BLOB         | string                        | [:ballot_box_with_check:](https://github.com/satur-io/duckdb-php/issues/2) |                                    :x:                                     |\n| DUCKDB_TYPE_TIMESTAMP_S  | TIMESTAMP_S  | Saturio\\DuckDB\\Type\\Timestamp |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_TIMESTAMP_MS | TIMESTAMP_MS | Saturio\\DuckDB\\Type\\Timestamp |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_TIMESTAMP_NS | TIMESTAMP_NS | Saturio\\DuckDB\\Type\\Timestamp |                             :white_check_mark:                             |                                    :x:                                     |\n| DUCKDB_TYPE_UUID         | UUID         | Saturio\\DuckDB\\Type\\UUID      |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_TIME_TZ      | TIMETZ       | Saturio\\DuckDB\\Type\\Time      |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_TIMESTAMP_TZ | TIMESTAMPTZ  | Saturio\\DuckDB\\Type\\Timestamp |                             :white_check_mark:                             |                             :white_check_mark:                             |\n| DUCKDB_TYPE_DECIMAL      | DECIMAL      | float                         |                             :white_check_mark:                             |                                    :x:                                     |\n| DUCKDB_TYPE_ENUM         | ENUM         | string                        |                             :white_check_mark:                             |                            :small_blue_diamond:                            |\n| DUCKDB_TYPE_LIST         | LIST         | array                         |                             :white_check_mark:                             |                            :small_blue_diamond:                            |\n| DUCKDB_TYPE_STRUCT       | STRUCT       | array                         |                             :white_check_mark:                             |                            :small_blue_diamond:                            |\n| DUCKDB_TYPE_ARRAY        | ARRAY        | array                         |                             :white_check_mark:                             |                            :small_blue_diamond:                            |\n| DUCKDB_TYPE_MAP          | MAP          | array                         |                             :white_check_mark:                             |                            :small_blue_diamond:                            |\n| DUCKDB_TYPE_UNION        | UNION        | mixed                         |                             :white_check_mark:                             |                            :small_blue_diamond:                            |\n| DUCKDB_TYPE_BIT          | BIT          | string                        |                                    :x:                                     |                            :small_blue_diamond:                            |\n| DUCKDB_TYPE_VARINT       | VARINT       | string                        |                                    :x:                                     |                                    :x:                                     |\n\n:white_check_mark: Fully supported\n\n:ballot_box_with_check: Partially supported / Needs improvements\n\n:x: Not supported\n\n:small_blue_diamond: Not applicable\n\n### Other PHP DuckDB Integrations\n\nThis project takes inspiration from [thbley/php-duckdb-integration](https://github.com/thbley/php-duckdb-integration) and [kambo-1st/duckdb-php](https://github.com/kambo-1st/duckdb-php). Without these prior works, **satur-io/duckdb-php** might not exist.\n\nHowever, there are some key differences:\n- **satur-io/duckdb-php** leverages all modern C API methods, avoiding deprecated ones.\n- It supports all major platforms (Linux, macOS, and Windows) and automatically selects the appropriate C library.\n- Prioritizes performance.\n- Simple to install and use.\n- Bundles all necessary resources into a single Composer package.\n\n\n### Contributions Are Welcome\n\nThere are several open issues you can contribute to. Feel free to create new issues for feature requests or bug reports. Contributions of any kind are highly appreciated!\n\nIf you'd like to contribute, please follow these steps:\n1. Fork the repository.\n2. Create a new branch for your feature or bug fix.\n3. Commit your changes with clear and concise messages.\n4. Submit a pull request with a detailed description of your changes.\n\n\u003e [!NOTE]\n\u003e Please include tests for any new functionality or bug fixing.\n\nThank you for helping improve this project!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsatur-io%2Fduckdb-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsatur-io%2Fduckdb-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsatur-io%2Fduckdb-php/lists"}