Running SQL queries over HTTP

The most basic way to run queries on Seafowl is by sending POST requests to its HTTP endpoint.

Read-only SELECT queries

curl -H "Content-Type: application/json" http://localhost:8080/q \
  -d@-<<EOF
{"query": "SELECT 1"}
EOF

Write queries

Seafowl is designed to be queried directly from the user's browser, without intermediate backend applications. By default, it allows anyone to execute SELECT queries and requires authorization to execute writes.

This means that to execute writes and DDL (such as CREATE TABLE), you will need a "bearer token" passed in the Authorization header.

When you start Seafowl for the first time, it will generate a password at random and output it, as well as write its SHA-256 hash to the configuration file.

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer 2Ux0FMpIifxS4EQVxvBhyBQl9EfZ0Cq1"\
  http://localhost:8080/q -d@-<<EOF
{"query": "CREATE TABLE new_table (key INT, value VARCHAR)"}
EOF

This is only for convenience. We recommend you change the password when deploying Seafowl or disable writes altogether if you don't need your instance to be writeable.

Changing the password

Seafowl stores the SHA-256 hash of the password in the config file. This is to prevent your password from being obtained in case someone other than you gains access to the config file.

To generate a new password, you can use this Bash snippet:

pw=$(< /dev/urandom LC_ALL=C tr -dc A-Za-z0-9 | head -c${1:-32};echo -n)
pw_hash=$(echo -n $pw | sha256sum - | head -c 64)
echo -e "Password: $pw\nHash: $pw_hash"

This outputs, for example:

Password: 2Ux0FMpIifxS4EQVxvBhyBQl9EfZ0Cq1
Hash: 512184b955833c7ca620c46d53d250951a113ca4e77845eea0b1eb7e53b0c417

You can then add the SHA hash to your seafowl.toml file.

[frontend.http]
# ...
write = "512184b955833c7ca620c46d53d250951a113ca4e77845eea0b1eb7e53b0c417"

Or, if you're deploying Seafowl to somewhere that lets you pass secrets as environment variables, you can set this environment variable:

SEAFOWL__FRONTEND__HTTP__WRITE_ACCESS=512184b955833c7ca620c46d53d250951a113ca4e77845eea0b1eb7e53b0c417

Making both reads and writes require a password

Besides writes, you can also make read-only queries to your Seafowl instance require a password:

write = "[password hash]"
read = "[password hash]"

These can be different or the same. Note that someone with a write password can still read data, but not vice versa.