Skip to content

Getting started

This page takes you from subscription to your first DuckDB query. It takes about ten minutes, most of it waiting for the instance to boot.

1. Subscribe and launch

  1. Open the listing and subscribe.
  2. Launch the AMI on t3.medium or larger, with a gp3 root volume of at least 16 GiB. Turn on EBS encryption if your policies require it.
  3. Choose how you will connect:
    • Session Manager (recommended): attach an instance profile that allows AWS Systems Manager, such as one with AmazonSSMManagedInstanceCore. No inbound rule is needed.
    • SSH: select your EC2 key pair, and set the TCP 22 rule to your administrator CIDR. The listing's default security group allows 22 only from 127.0.0.1/32, which blocks SSH until you change it.

You do not need to attach any S3 permissions to get started. IAM only matters when you query your own bucket. See Reading from S3.

2. Connect as ubuntu

With Session Manager, start a session from the EC2 console or the AWS CLI, then switch to the ubuntu user:

sudo -iu ubuntu

With SSH:

ssh -i <your-key.pem> ubuntu@<public-ip>

3. Wait for first boot

On first boot, the sushi-duckdb-firstboot service creates the workspace and the default settings. Wait for cloud-init, then check that it finished:

sudo cloud-init status --wait
systemctl is-active sushi-duckdb-firstboot.service

The second command prints active when first boot is complete.

First boot creates:

Path Purpose
/etc/duckdb/duckdb.env Memory and spill limits used by duckdb-sql
/etc/duckdb/customer-s3.sql.example Commented S3 example
/etc/duckdb/secrets/ Protected folder for your S3 SQL file. Owned root:duckdb, mode 0750.
/var/lib/duckdb/ Workspace for the duckdb service user

4. Run the walkthrough

As ubuntu, run the bundled demo:

bash /opt/sushi/docs/demo.sh

It checks first boot, prints the DuckDB version, confirms that ubuntu cannot read the secrets folder, sums a small CSV file, converts it to Parquet, queries the Parquet file and runs the image self-test. It finishes with SUSHI_CUSTOMER_DEMO_PASSED.

5. Run your own query

duckdb-sql runs one SQL file and prints the result as CSV without a header. Create a file that sums the sample orders:

cat > ~/orders-sum.sql <<'SQL'
SELECT sum(cents)::BIGINT
FROM read_csv('/opt/sushi/share/duckdb/examples/orders.csv', header = true,
  columns = {'order_id': 'BIGINT', 'sku': 'VARCHAR', 'cents': 'BIGINT'});
SQL
/opt/sushi/bin/duckdb-sql ~/orders-sum.sql

The result is 3575.

Write the same data to Parquet and read it back:

cat > ~/to-parquet.sql <<'SQL'
COPY (
  SELECT * FROM read_csv('/opt/sushi/share/duckdb/examples/orders.csv', header = true,
    columns = {'order_id': 'BIGINT', 'sku': 'VARCHAR', 'cents': 'BIGINT'})
) TO '/home/ubuntu/orders.parquet' (FORMAT PARQUET);
SELECT sum(cents)::BIGINT FROM read_parquet('/home/ubuntu/orders.parquet');
SQL
/opt/sushi/bin/duckdb-sql ~/to-parquet.sql

The last line of the output is 3575.

You can also start the interactive shell with duckdb for local CSV and Parquet work. Use duckdb-sql when you need the pinned httpfs and aws extensions, or the memory limits in /etc/duckdb/duckdb.env.

Next steps