Skip to content

Commit a5f4ac0

Browse files
dhernandezdhernandez
committed
core: new installation methods
1 parent ddab2e7 commit a5f4ac0

12 files changed

Lines changed: 239 additions & 18 deletions

File tree

‎.gitattributes‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,4 @@ preload.php export-ignore
2121
README.md export-ignore
2222
ROADMAP.md export-ignore
2323
sonar-project.properties export-ignore
24+
lib export-ignore

‎.github/workflows/php_test.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ jobs:
9494
merge-multiple: true
9595

9696
- name: SonarQube Scan
97-
uses: SonarSource/sonarqube-scan-action@v5.3.1
97+
uses: SonarSource/sonarqube-scan-action@v6.0.0
9898
env:
9999
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
100100

‎.github/workflows/release-libs.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Generate Release Assets (DuckDB C libs)
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
jobs:
8+
build-and-upload:
9+
runs-on: ubuntu-latest
10+
11+
steps:
12+
- name: Checkout code
13+
uses: actions/checkout@v4
14+
15+
- name: Define target folders 📁
16+
id: folders
17+
run: |
18+
echo "folders=linux-amd64 linux-arm64 osx-universal windows-amd64 windows-arm64" >> $GITHUB_OUTPUT
19+
20+
- name: Compress and Upload Assets 🚀
21+
run: |
22+
RELEASE_ID=${{ github.event.release.id }}
23+
24+
for FOLDER in ${{ steps.folders.outputs.folders }}; do
25+
ASSET_NAME="${FOLDER}.zip"
26+
FILE_PATH="./lib/${FOLDER}"
27+
ZIP_PATH="./${ASSET_NAME}"
28+
29+
echo "Processing folder: ${FOLDER}"
30+
31+
zip -r -j -9 "${ZIP_PATH}" "${FILE_PATH}"
32+
33+
if [ -f "${ZIP_PATH}" ]; then
34+
echo "Successfully created ${ASSET_NAME}"
35+
echo "Uploading ${ASSET_NAME}..."
36+
gh asset upload "${ZIP_PATH}" --repo "${{ github.repository }}" --release-id "${RELEASE_ID}" --clobber
37+
38+
echo "Upload of ${ASSET_NAME} complete."
39+
else
40+
echo "Error: Failed to create ${ASSET_NAME}"
41+
exit 1
42+
fi
43+
done
44+
env:
45+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎README.md‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=satur-io_duckdb-php&metric=alert_status&token=4a4bd82eff843d2b4a93bf4552b6db78e598ecfa)](https://sonarcloud.io/summary/new_code?id=satur-io_duckdb-php)
88
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=satur-io_duckdb-php&metric=coverage)](https://sonarcloud.io/summary/new_code?id=satur-io_duckdb-php)
99
[![Packagist Version](https://img.shields.io/packagist/v/satur.io/duckdb?style=flat&logo=packagist&logoColor=white)](https://packagist.org/packages/satur.io/duckdb)
10-
![DuckDB C API Version](https://img.shields.io/badge/DuckDB_C_API-v1.3.2-%23FFF100?logo=duckdb)
10+
![DuckDB C API Version](https://img.shields.io/badge/DuckDB_C_API-v1.4.1-%23FFF100?logo=duckdb)
1111

1212

1313
This package provides a [DuckDB](https://github.com/duckdb/duckdb) Client API for PHP.
@@ -17,9 +17,23 @@ This library is more than just a wrapper for the C API; it introduces custom, PH
1717

1818
### Install
1919

20+
#### Plugin (recommended for newcomers)
2021
```shell
21-
composer require satur.io/duckdb
22+
composer require satur.io/duckdb-plugin
2223
```
24+
> [!INFO]
25+
> You will need to trust `satur.io/duckdb-plugin` to execute code to use this installation method,
26+
> check [installation](https://duckdb-php.readthedocs.io/en/latest/installation) for more details.
27+
28+
This is the simplest way to have all the required resources at once. After running this command,
29+
that`s all! You can go to [Quick start](#quick-start).
30+
31+
If for any reason you don't want to use the plugin, or you prefer a customizable installation,
32+
please use any of the advanced installation options.
33+
34+
#### Advanced installation
35+
36+
Check [Advanced installation section](https://duckdb-php.readthedocs.io/en/latest/installation/#advanced-installation) in the docs.
2337

2438
### Documentation
2539

‎composer.json‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,13 @@
2727
}
2828
],
2929
"require": {
30-
"ext-ffi": "*",
31-
"php": ">=8.3"
30+
"ext-ffi": "*",
31+
"php": ">=8.3"
3232
},
3333
"suggest": {
3434
"ext-zend-opcache": "For a better perfomance using a preload function",
35-
"ext-bcmath": "Required for numbers > PHP_INT_MAX"
35+
"ext-bcmath": "Required for numbers > PHP_INT_MAX",
36+
"ext-zip": "Required for C library downloader"
3637
},
3738
"require-dev": {
3839
"phpunit/phpunit": "^11.5",
@@ -48,7 +49,7 @@
4849
"benchmark": "vendor/bin/phpbench run --config=phpbench-local.json --report=duckdb_benchmark_report",
4950
"benchmark-regression": "./scripts/run_local_benchmark_regression.sh"
5051
},
51-
"bin": ["test/Performance/duckdb_api"],
52+
"bin": ["install-c-lib", "test/Performance/duckdb_api"],
5253
"config": {
5354
"process-timeout": 0
5455
}

‎docs/md/getting-started.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,17 @@
22

33
## Install
44

5-
You can install the DuckDB PHP package using Composer by running the following command:
5+
You can install the DuckDB PHP package and all the required resources
6+
using Composer by requiring the plugin installer:
67

78
```bash
8-
$ composer require satur.io/duckdb
9+
$ composer require satur.io/duckdb-plugin
910
```
1011

12+
This is the recommended option for newcomers and should be enough to
13+
start using DuckDB from PHP. For more advanced options,
14+
check other [installation](installation.md) methods.
15+
1116
## Query
1217

1318
`Saturio\DuckDB\DuckDB` is the main entrypoint to start using the library.

‎docs/md/installation.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Installation
2+
3+
## Plugin (recommended for newcomers)
4+
```shell
5+
composer require satur.io/duckdb-plugin
6+
```
7+
8+
This will install the `satur.io/duckdb-plugin` package,
9+
and it's the simplest way to have all the required resources at once.
10+
11+
The plugin installs `satur.io/duckdb` and download the necessary DuckDB C library for your OS.
12+
13+
You will need to trust `satur.io/duckdb-plugin` to execute code for this installation method.
14+
15+
You can check the plugin source code [in its repo](https://github.com/satur-io/duckdb-plugin).
16+
17+
If for any reason you don't want to use the plugin, or you prefer a customizable installation,
18+
please use any of the advanced installation options.
19+
20+
## Advanced installation options
21+
22+
Basically, to use this library you need the `satur.io/duckdb` package
23+
and the official C library files provided by DuckDB (both the header file and the binary).
24+
25+
Unfortunately, C libraries are OS and platform dependant. Also, the header file needs some changes
26+
to be used in PHP via FFI.
27+
28+
For each `satur.io/duckdb` release (from v2.0 on), we include the
29+
fixed headers and the binaries for all supported platforms as assets.
30+
31+
!!! quote
32+
You can take a look at `scripts/get_libraries.sh`, the script used to get the libraries
33+
and adapt the headers files, and `.github/workflows/release-libs.yml` the action to publish
34+
the assets.
35+
36+
### Using the downloader script
37+
38+
Install `satur.io/duckdb`
39+
```shell
40+
composer require satur.io/duckdb
41+
```
42+
43+
To download the C libraries for your OS-platform, we provide a simple script.
44+
The script downloads the required files for the current package version in the
45+
desired path:
46+
47+
```shell
48+
./vendor/bin/install-c-lib
49+
```
50+
51+
After running the command, you should see a requirement for setting the `DUCKDB_PHP_PATH`
52+
environment variable to the path where you downloaded the library.
53+
54+
### Downloading the library by yourself
55+
56+
Install `satur.io/duckdb`
57+
```shell
58+
composer require satur.io/duckdb
59+
```
60+
61+
Download C library, for example:
62+
```shell
63+
mkdir -p ~/duckdb-macos-lib && curl -s -L https://github.com/satur-io/duckdb-php/releases/download/1.2.0-beta.1/osx-universal.zip -o /tmp/duckdb.zip && unzip /tmp/duckdb.zip -d ~/duckdb-macos-lib && rm /tmp/duckdb.zip
64+
```
65+
66+
As in the previous case, you need to set the `DUCKDB_PHP_PATH`
67+
environment variable to the path.
68+
```shell
69+
export DUCKDB_PHP_PATH=~/duckdb-macos-lib
70+
```

‎install-c-lib‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
install-c-lib.php

‎install-c-lib.php‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
#!/usr/bin/env php
2+
<?php
3+
require_once __DIR__ . '/vendor/autoload.php';
4+
5+
use Composer\InstalledVersions;
6+
use Saturio\DuckDB\CLib\Downloader;
7+
8+
$version = InstalledVersions::getPrettyVersion('satur.io/duckdb');
9+
$path = 'lib';
10+
11+
echo "\033[32mInstallation path\033[0m (\033[36m" . $path . "\033[0m): ";
12+
13+
$user_input = trim(fgets(STDIN));
14+
15+
if (!empty($user_input)) {
16+
$path = $user_input;
17+
}
18+
19+
echo "\n\033[36mDownloading DuckDB C library in {$path}\033[0m\n";
20+
Downloader::download($path, $version);
21+
$fullPath = realpath($path);
22+
echo "\033[32mC library downloaded\033[0m\n";
23+
echo "\n\033[31mNow please set the environment variable DUCKDB_PHP_PATH={$fullPath}\033[0m\n\n";

‎mkdocs.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ nav:
99
- Intro:
1010
- 'index.md'
1111
- 'getting-started.md'
12+
- 'installation.md'
1213
- Usage:
1314
- 'running-queries.md'
1415
- 'read-resultset-content.md'

0 commit comments

Comments
 (0)