Quickstart

Get Embucket running and execute your first Snowflake SQL query in under 5 minutes

This quickstart guide will have you running Embucket and executing Snowflake SQL queries in under 5 minutes.

Prerequisites

This quickstart uses Docker for the fastest setup. Make sure you have Docker installed and running on your system.

If you prefer other installation methods, see the Installation guide.

Start Embucket

1. Run the Embucket container

   Start Embucket using Docker:

   docker run --name embucket --rm -p 3000:3000 embucket/embucket
   

   This command:

   • Downloads the Embucket image (if not already cached)
   • Starts the server on port 3000
   • Runs with default configuration suitable for local development

   The server starts immediately with an embedded metastore. You should see log output indicating the server is ready.

2. Install Snowflake CLI

   Install the Snowflake CLI to interact with Embucket:

   pip install snowflake-cli
   

   If you already have the Snowflake CLI installed, you can skip this step.

3. Configure connection to Embucket

   Find your Snowflake CLI config file path:

   snow --info | grep "config_file_path" -A 1
   

   Set the config path:

   CONFIG=<your_config_file_path>
   

   Add the local Embucket connection configuration:

   echo '
   [connections.local]
   host = "localhost"
   region = "us-east-2"
   port = 3000
   protocol = "http"
   database = "embucket"
   schema = "public"
   warehouse = "em.wh"
   password = "embucket"
   account = "acc.local"
   user = "embucket"
   ' >> $CONFIG
   

   These default credentials work out of the box for local development. For production deployments, see the Configuration guide.

4. Test the connection

   Verify the connection to Embucket:

   snow connection test -c local
   

   Expected output:

   +-----------------------------+
   | key             | value     |
   |-----------------+-----------|
   | Connection name | local     |
   | Status          | OK        |
   | Host            | localhost |
   | Account         | acc       |
   | User            | embucket  |
   | Role            | not set   |
   | Database        | embucket  |
   | Warehouse       | em.wh     |
   +-----------------------------+
   

   If you see Status | OK, your connection is configured correctly!

5. Run your first query

   Execute a Snowflake SQL query against Embucket:

   snow sql -c local -q "select dateadd(day, -1, current_timestamp()) as yesterday;"
   

   Expected output:

   +----------------------------------+
   | yesterday                        |
   |----------------------------------|
   | 2025-01-02 03:04:05.040000+00:00 |
   +----------------------------------+
   

   Try more Snowflake SQL functions like DATEDIFF, CONCAT, or complex queries with CTEs!

Verification

You’ve successfully:

• ✅ Started an Embucket instance
• ✅ Configured the Snowflake CLI to connect to Embucket
• ✅ Executed a Snowflake SQL query with date functions

Congratulations! You’re now running Snowflake SQL dialect against a local Embucket instance.

Try More Queries

Now that you have Embucket running, try some more queries:

Basic SELECT

snow sql -c local -q "SELECT 'Hello, Embucket!' as message;"

Date and Time Functions

snow sql -c local -q "
SELECT 
  current_timestamp() as now,
  dateadd(day, 7, current_date()) as next_week,
  datediff(day, '2024-01-01', current_date()) as days_since_new_year;
"

String Functions

snow sql -c local -q "
SELECT 
  concat('Embu', 'cket') as name,
  upper('snowflake sql') as dialect,
  length('Apache Iceberg') as length;
"

Next Steps

Now that you have Embucket running locally, explore more capabilities:

Connect to External Catalogs

Connect to AWS S3 Table Buckets or external Iceberg tables

Create Tables

Create and manage Iceberg tables with Snowflake SQL

Integration with dbt

Run your dbt projects against Embucket

Production Deployment

Deploy Embucket to production environments

Troubleshooting

Connection Refused

If you see connection refused errors:

• Verify the Docker container is running: docker ps
• Check that port 3000 is not in use by another service
• Ensure you’re using protocol = "http" in the connection config (not https)

CLI Not Found

If the snow command is not found:

• Ensure Python pip is installed
• Try reinstalling: pip install --upgrade snowflake-cli
• Verify your PATH includes Python’s bin directory

Configuration Issues

If the connection test fails:

• Double-check the config file path: snow --info
• Verify the configuration was added correctly: cat $CONFIG
• Ensure the [connections.local] section is properly formatted

For production deployments, never use default credentials. See the Security guide for best practices.