README

Apache Iceberg for PHP, powered by libduckdb

Installation

Run:

composer require ankane/seaduck

Add scripts to composer.json to download the shared library:

    "scripts": {
        "post-install-cmd": "SeaDuck\\Library::check",
        "post-update-cmd": "SeaDuck\\Library::check"
    }

And run:

composer install

Getting Started

Create a client for an Iceberg catalog

use SeaDuck\S3TablesCatalog;

$catalog = new S3TablesCatalog(arn: 'arn:aws:s3tables:...');

Note: SeaDuck requires a default namespace, which is main by default. This namespace is created if it does not exist. Pass defaultNamespace to use a different one.

Create a table

$catalog->sql('CREATE TABLE events (id bigint, name text)');

Load data from a file

$catalog->sql("COPY events FROM 'data.csv'");

You can also load data directly from other data sources

$catalog->attach('blog', 'postgres://localhost:5432/blog');
$catalog->sql('INSERT INTO events SELECT * FROM blog.events');

Query the data

$catalog->sql('SELECT COUNT(*) FROM events')->toArray();

Namespaces

List namespaces

$catalog->listNamespaces();

Create a namespace

$catalog->createNamespace('main');

Check if a namespace exists

$catalog->namespaceExists('main');

Drop a namespace

$catalog->dropNamespace('main');

Tables

List tables

$catalog->listTables();

Check if a table exists

$catalog->tableExists('events');

Drop a table

$catalog->dropTable('events');

Snapshots

Get snapshots for a table

$catalog->snapshots('events');

Query the data at a specific snapshot version or time

$catalog->sql('SELECT * FROM events AT (VERSION => ?)', [3]);
// or
$catalog->sql('SELECT * FROM events AT (TIMESTAMP => ?)', [new DateTime()]);

SQL Safety

Use parameterized queries when possible

$catalog->sql('SELECT * FROM events WHERE id = ?', [1]);

For places that do not support parameters, use quote or quoteIdentifier

$quotedTable = $catalog->quoteIdentifier('events');
$quotedFile = $catalog->quote('path/to/data.csv');
$catalog->sql("COPY $quotedTable FROM $quotedFile");

History

View the changelog

Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help:

• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features

To get started with development:

git clone https://github.com/ankane/seaduck-php.git
cd seaduck
composer install

# REST catalog
docker compose up
CATALOG=rest composer test

# S3 Tables catalog
CATALOG=s3tables composer test

# Glue catalog
CATALOG=glue composer test