├── .gitignore ├── Dockerfile ├── DuckDB.php ├── Getting_started_with_phpffi_ipc_2021_ThomasBley.pdf ├── LICENSE ├── create_csv.php ├── duckdb.h ├── libduckdb.so ├── readme.md ├── singlefile.php ├── test.php └── test.sql /.gitignore: -------------------------------------------------------------------------------- 1 | test.csv.gz 2 | test.db 3 | duckdb 4 | .* 5 | 6 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM php:7.4-cli-buster 2 | 3 | RUN apt-get -y update \ 4 | && DEBIAN_FRONTEND=noninteractive apt-get -y --no-install-recommends install libffi-dev \ 5 | && docker-php-ext-configure ffi --with-ffi \ 6 | && docker-php-ext-install ffi \ 7 | && apt-get clean \ 8 | && rm -rf /tmp/* /var/lib/apt/lists/* /var/cache/apt/archives/* 9 | -------------------------------------------------------------------------------- /DuckDB.php: -------------------------------------------------------------------------------- 1 | ffi = FFI::cdef(file_get_contents($headersPath), $libraryPath); 12 | 13 | $this->db = $this->ffi->new('duckdb_database'); 14 | $this->conn = $this->ffi->new('duckdb_connection'); 15 | 16 | $error = $this->ffi->duckdb_open($databasePath, FFI::addr($this->db)); 17 | if ($error) { 18 | throw new Exception('error open: ' . $databasePath); 19 | } 20 | 21 | $error = $this->ffi->duckdb_connect($this->db, FFI::addr($this->conn)); 22 | if ($error) { 23 | throw new Exception('error connect'); 24 | } 25 | } 26 | 27 | public function __destruct() 28 | { 29 | $this->ffi->duckdb_disconnect(FFI::addr($this->conn)); 30 | $this->ffi->duckdb_close(FFI::addr($this->db)); 31 | FFI::free($this->conn); 32 | FFI::free($this->db); 33 | unset($this->ffi); 34 | } 35 | 36 | public function query(string $query): array 37 | { 38 | $result = $this->ffi->new('duckdb_result'); 39 | 40 | $error = $this->ffi->duckdb_query($this->conn, $query, FFI::addr($result)); 41 | if ($error) { 42 | $message = FFI::string($result->error_message); 43 | 44 | $this->ffi->duckdb_destroy_result(FFI::addr($result)); 45 | 46 | throw new Exception($message); 47 | } 48 | 49 | $data = []; 50 | $columns = []; 51 | 52 | for ($col = 0; $col < $result->column_count; $col++) { 53 | $columns[] = FFI::string($result->columns[$col]->name); 54 | 55 | for ($row = 0; $row < $result->row_count; $row++) { 56 | $value = $this->ffi->duckdb_value_varchar(FFI::addr($result), $col, $row); 57 | 58 | $data[$row][$columns[$col]] = FFI::string($value); 59 | 60 | FFI::free($value); 61 | } 62 | } 63 | 64 | $this->ffi->duckdb_destroy_result(FFI::addr($result)); 65 | 66 | return $data; 67 | } 68 | } 69 | -------------------------------------------------------------------------------- /Getting_started_with_phpffi_ipc_2021_ThomasBley.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/thbley/php-duckdb-integration/3f7ddd8b7dedd90acdd588cd19d6f8c4a763ea73/Getting_started_with_phpffi_ipc_2021_ThomasBley.pdf -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Thomas Bley 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /create_csv.php: -------------------------------------------------------------------------------- 1 | 24 | #include 25 | #include 26 | 27 | typedef uint64_t idx_t; 28 | 29 | typedef enum DUCKDB_TYPE { 30 | DUCKDB_TYPE_INVALID = 0, 31 | // bool 32 | DUCKDB_TYPE_BOOLEAN, 33 | // int8_t 34 | DUCKDB_TYPE_TINYINT, 35 | // int16_t 36 | DUCKDB_TYPE_SMALLINT, 37 | // int32_t 38 | DUCKDB_TYPE_INTEGER, 39 | // int64_t 40 | DUCKDB_TYPE_BIGINT, 41 | // float 42 | DUCKDB_TYPE_FLOAT, 43 | // double 44 | DUCKDB_TYPE_DOUBLE, 45 | // duckdb_timestamp (us) 46 | DUCKDB_TYPE_TIMESTAMP, 47 | // duckdb_timestamp (s) 48 | DUCKDB_TYPE_TIMESTAMP_S, 49 | // duckdb_timestamp (ns) 50 | DUCKDB_TYPE_TIMESTAMP_NS, 51 | // duckdb_timestamp (ms) 52 | DUCKDB_TYPE_TIMESTAMP_MS, 53 | // duckdb_date 54 | DUCKDB_TYPE_DATE, 55 | // duckdb_time 56 | DUCKDB_TYPE_TIME, 57 | // duckdb_interval 58 | DUCKDB_TYPE_INTERVAL, 59 | // duckdb_hugeint 60 | DUCKDB_TYPE_HUGEINT, 61 | // const char* 62 | DUCKDB_TYPE_VARCHAR, 63 | // duckdb_blob 64 | DUCKDB_TYPE_BLOB 65 | } duckdb_type; 66 | 67 | typedef struct { 68 | int32_t year; 69 | int8_t month; 70 | int8_t day; 71 | } duckdb_date; 72 | 73 | typedef struct { 74 | int8_t hour; 75 | int8_t min; 76 | int8_t sec; 77 | int16_t micros; 78 | } duckdb_time; 79 | 80 | typedef struct { 81 | duckdb_date date; 82 | duckdb_time time; 83 | } duckdb_timestamp; 84 | 85 | typedef struct { 86 | int32_t months; 87 | int32_t days; 88 | int64_t micros; 89 | } duckdb_interval; 90 | 91 | typedef struct { 92 | uint64_t lower; 93 | int64_t upper; 94 | } duckdb_hugeint; 95 | 96 | typedef struct { 97 | void *data; 98 | idx_t size; 99 | } duckdb_blob; 100 | 101 | typedef struct { 102 | void *data; 103 | bool *nullmask; 104 | duckdb_type type; 105 | char *name; 106 | } duckdb_column; 107 | 108 | typedef struct { 109 | idx_t column_count; 110 | idx_t row_count; 111 | duckdb_column *columns; 112 | char *error_message; 113 | } duckdb_result; 114 | 115 | // typedef struct { 116 | // void *data; 117 | // bool *nullmask; 118 | // } duckdb_column_data; 119 | 120 | // typedef struct { 121 | // int column_count; 122 | // int count; 123 | // duckdb_column_data *columns; 124 | // } duckdb_chunk; 125 | 126 | typedef void *duckdb_database; 127 | typedef void *duckdb_connection; 128 | typedef void *duckdb_prepared_statement; 129 | typedef void *duckdb_appender; 130 | 131 | typedef enum { DuckDBSuccess = 0, DuckDBError = 1 } duckdb_state; 132 | 133 | //! Opens a database file at the given path (nullptr for in-memory). Returns DuckDBSuccess on success, or DuckDBError on 134 | //! failure. [OUT: database] 135 | duckdb_state duckdb_open(const char *path, duckdb_database *out_database); 136 | //! Closes the database. 137 | void duckdb_close(duckdb_database *database); 138 | 139 | //! Creates a connection to the specified database. [OUT: connection] 140 | duckdb_state duckdb_connect(duckdb_database database, duckdb_connection *out_connection); 141 | //! Closes the specified connection handle 142 | void duckdb_disconnect(duckdb_connection *connection); 143 | 144 | //! Executes the specified SQL query in the specified connection handle. [OUT: result descriptor] 145 | duckdb_state duckdb_query(duckdb_connection connection, const char *query, duckdb_result *out_result); 146 | //! Destroys the specified result 147 | void duckdb_destroy_result(duckdb_result *result); 148 | 149 | //! Returns the column name of the specified column. The result does not need to be freed; 150 | //! the column names will automatically be destroyed when the result is destroyed. 151 | const char *duckdb_column_name(duckdb_result *result, idx_t col); 152 | 153 | // SAFE fetch functions 154 | // These functions will perform conversions if necessary. On failure (e.g. if conversion cannot be performed) a special 155 | // value is returned. 156 | 157 | //! Converts the specified value to a bool. Returns false on failure or NULL. 158 | bool duckdb_value_boolean(duckdb_result *result, idx_t col, idx_t row); 159 | //! Converts the specified value to an int8_t. Returns 0 on failure or NULL. 160 | int8_t duckdb_value_int8(duckdb_result *result, idx_t col, idx_t row); 161 | //! Converts the specified value to an int16_t. Returns 0 on failure or NULL. 162 | int16_t duckdb_value_int16(duckdb_result *result, idx_t col, idx_t row); 163 | //! Converts the specified value to an int64_t. Returns 0 on failure or NULL. 164 | int32_t duckdb_value_int32(duckdb_result *result, idx_t col, idx_t row); 165 | //! Converts the specified value to an int64_t. Returns 0 on failure or NULL. 166 | int64_t duckdb_value_int64(duckdb_result *result, idx_t col, idx_t row); 167 | //! Converts the specified value to an uint8_t. Returns 0 on failure or NULL. 168 | uint8_t duckdb_value_uint8(duckdb_result *result, idx_t col, idx_t row); 169 | //! Converts the specified value to an uint16_t. Returns 0 on failure or NULL. 170 | uint16_t duckdb_value_uint16(duckdb_result *result, idx_t col, idx_t row); 171 | //! Converts the specified value to an uint64_t. Returns 0 on failure or NULL. 172 | uint32_t duckdb_value_uint32(duckdb_result *result, idx_t col, idx_t row); 173 | //! Converts the specified value to an uint64_t. Returns 0 on failure or NULL. 174 | uint64_t duckdb_value_uint64(duckdb_result *result, idx_t col, idx_t row); 175 | //! Converts the specified value to a float. Returns 0.0 on failure or NULL. 176 | float duckdb_value_float(duckdb_result *result, idx_t col, idx_t row); 177 | //! Converts the specified value to a double. Returns 0.0 on failure or NULL. 178 | double duckdb_value_double(duckdb_result *result, idx_t col, idx_t row); 179 | //! Converts the specified value to a string. Returns nullptr on failure or NULL. The result must be freed with free. 180 | char *duckdb_value_varchar(duckdb_result *result, idx_t col, idx_t row); 181 | //! Fetches a blob from a result set column. Returns a blob with blob.data set to nullptr on failure or NULL. The 182 | //! resulting "blob.data" must be freed with free. 183 | duckdb_blob duckdb_value_blob(duckdb_result *result, idx_t col, idx_t row); 184 | 185 | // Prepared Statements 186 | 187 | //! prepares the specified SQL query in the specified connection handle. [OUT: prepared statement descriptor] 188 | duckdb_state duckdb_prepare(duckdb_connection connection, const char *query, 189 | duckdb_prepared_statement *out_prepared_statement); 190 | 191 | duckdb_state duckdb_nparams(duckdb_prepared_statement prepared_statement, idx_t *nparams_out); 192 | 193 | //! binds parameters to prepared statement 194 | duckdb_state duckdb_bind_boolean(duckdb_prepared_statement prepared_statement, idx_t param_idx, bool val); 195 | duckdb_state duckdb_bind_int8(duckdb_prepared_statement prepared_statement, idx_t param_idx, int8_t val); 196 | duckdb_state duckdb_bind_int16(duckdb_prepared_statement prepared_statement, idx_t param_idx, int16_t val); 197 | duckdb_state duckdb_bind_int32(duckdb_prepared_statement prepared_statement, idx_t param_idx, int32_t val); 198 | duckdb_state duckdb_bind_int64(duckdb_prepared_statement prepared_statement, idx_t param_idx, int64_t val); 199 | #duckdb_state duckdb_bind_uint8(duckdb_prepared_statement prepared_statement, idx_t param_idx, int8_t val); 200 | #duckdb_state duckdb_bind_uint16(duckdb_prepared_statement prepared_statement, idx_t param_idx, int16_t val); 201 | duckdb_state duckdb_bind_uint32(duckdb_prepared_statement prepared_statement, idx_t param_idx, uint32_t val); 202 | duckdb_state duckdb_bind_uint64(duckdb_prepared_statement prepared_statement, idx_t param_idx, uint64_t val); 203 | duckdb_state duckdb_bind_float(duckdb_prepared_statement prepared_statement, idx_t param_idx, float val); 204 | duckdb_state duckdb_bind_double(duckdb_prepared_statement prepared_statement, idx_t param_idx, double val); 205 | duckdb_state duckdb_bind_varchar(duckdb_prepared_statement prepared_statement, idx_t param_idx, 206 | const char *val); 207 | duckdb_state duckdb_bind_varchar_length(duckdb_prepared_statement prepared_statement, idx_t param_idx, 208 | const char *val, idx_t length); 209 | duckdb_state duckdb_bind_blob(duckdb_prepared_statement prepared_statement, idx_t param_idx, 210 | const void *data, idx_t length); 211 | duckdb_state duckdb_bind_null(duckdb_prepared_statement prepared_statement, idx_t param_idx); 212 | 213 | //! Executes the prepared statements with currently bound parameters 214 | duckdb_state duckdb_execute_prepared(duckdb_prepared_statement prepared_statement, 215 | duckdb_result *out_result); 216 | 217 | //! Destroys the specified prepared statement descriptor 218 | void duckdb_destroy_prepare(duckdb_prepared_statement *prepared_statement); 219 | 220 | duckdb_state duckdb_appender_create(duckdb_connection connection, const char *schema, const char *table, 221 | duckdb_appender *out_appender); 222 | 223 | duckdb_state duckdb_appender_begin_row(duckdb_appender appender); 224 | duckdb_state duckdb_appender_end_row(duckdb_appender appender); 225 | 226 | duckdb_state duckdb_append_bool(duckdb_appender appender, bool value); 227 | 228 | duckdb_state duckdb_append_int8(duckdb_appender appender, int8_t value); 229 | duckdb_state duckdb_append_int16(duckdb_appender appender, int16_t value); 230 | duckdb_state duckdb_append_int32(duckdb_appender appender, int32_t value); 231 | duckdb_state duckdb_append_int64(duckdb_appender appender, int64_t value); 232 | 233 | duckdb_state duckdb_append_uint8(duckdb_appender appender, uint8_t value); 234 | duckdb_state duckdb_append_uint16(duckdb_appender appender, uint16_t value); 235 | duckdb_state duckdb_append_uint32(duckdb_appender appender, uint32_t value); 236 | duckdb_state duckdb_append_uint64(duckdb_appender appender, uint64_t value); 237 | 238 | duckdb_state duckdb_append_float(duckdb_appender appender, float value); 239 | duckdb_state duckdb_append_double(duckdb_appender appender, double value); 240 | 241 | duckdb_state duckdb_append_varchar(duckdb_appender appender, const char *val); 242 | duckdb_state duckdb_append_varchar_length(duckdb_appender appender, const char *val, idx_t length); 243 | duckdb_state duckdb_append_blob(duckdb_appender appender, const void *data, idx_t length); 244 | duckdb_state duckdb_append_null(duckdb_appender appender); 245 | 246 | duckdb_state duckdb_appender_flush(duckdb_appender appender); 247 | duckdb_state duckdb_appender_close(duckdb_appender appender); 248 | 249 | duckdb_state duckdb_appender_destroy(duckdb_appender *appender); 250 | -------------------------------------------------------------------------------- /libduckdb.so: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/thbley/php-duckdb-integration/3f7ddd8b7dedd90acdd588cd19d6f8c4a763ea73/libduckdb.so -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | PHP example to integrate DuckDB using PHP-FFI 2 | ----------------------------------------------- 3 | 4 | Currently there is no PHP extension available for using DuckDB, so I created a small library using PHP-FFI. 5 | 6 | DuckDB is an embeddable SQL OLAP database management system. 7 | It does not require external servers. Databases are stored in single files (similar to SQLite). 8 | Compared to SQLite, DuckDB is much faster. E.g. I imported 16M rows from a CSV file in 5s on my notebook (i5-8250U). 9 | 10 | DuckDB can import CSV files with automatic format detection and automatic table creation using: 11 | 12 | CREATE TABLE test1 AS SELECT * FROM read_csv_auto('test1.csv'); 13 | CREATE TABLE test2 AS SELECT * FROM read_csv_auto('test2.csv.gz'); 14 | 15 | Usage: 16 | 17 | php -dffi.enable=1 test.php 18 | 19 | or: 20 | 21 | docker build -t php-ffi . 22 | docker run -it --rm -v $(pwd):/code php-ffi php /code/test.php 23 | 24 | Requirements: 25 | 26 | PHP 7.4+ with FFI extension enabled 27 | 28 | References: 29 | 30 | - Slides: https://github.com/thbley/php-duckdb-integration/blob/master/Getting_started_with_phpffi_ipc_2021_ThomasBley.pdf 31 | - https://duckdb.org 32 | - https://github.com/cwida/duckdb 33 | - https://github.com/cwida/duckdb/releases/latest/download/libduckdb-linux-amd64.zip 34 | - https://www.php.net/manual/en/book.ffi.php 35 | -------------------------------------------------------------------------------- /singlefile.php: -------------------------------------------------------------------------------- 1 | new('duckdb_database'); 13 | $con = $ffi->new('duckdb_connection'); 14 | $result = $ffi->new('duckdb_result'); 15 | 16 | $ffi->duckdb_open(null, FFI::addr($db)); 17 | $ffi->duckdb_connect($db, FFI::addr($con)); 18 | 19 | $query = 'select current_date;'; 20 | $ffi->duckdb_query($con, $query, FFI::addr($result)); 21 | 22 | $val = $ffi->duckdb_value_varchar(FFI::addr($result), 0, 0); 23 | echo FFI::string($val); 24 | 25 | FFI::free($val); 26 | $ffi->duckdb_destroy_result(FFI::addr($result)); 27 | 28 | $ffi->duckdb_disconnect(FFI::addr($con)); 29 | FFI::free($con); 30 | 31 | $ffi->duckdb_close(FFI::addr($db)); 32 | FFI::free($db); 33 | 34 | unset($ffi); 35 | -------------------------------------------------------------------------------- /test.php: -------------------------------------------------------------------------------- 1 | query('CREATE TABLE IF NOT EXISTS test_table (i INTEGER, j INTEGER, k VARCHAR)'); 12 | 13 | $db->query("INSERT INTO test_table VALUES (3, 4, 'FOO'), (5, 6, 'BAR'), (7, NULL, 'BAZ')"); 14 | 15 | $result = $db->query('SELECT * FROM test_table'); 16 | print_r($result); 17 | -------------------------------------------------------------------------------- /test.sql: -------------------------------------------------------------------------------- 1 | .open test.db 2 | PRAGMA enable_profiling; 3 | CREATE TABLE test1 AS SELECT * FROM read_csv_auto('test.csv.gz'); 4 | DESCRIBE test1; 5 | --------------------------------------------------------------------------------