# Getting Started

Source: https://wiki.faucetdb.ai/getting-started

Faucet turns a PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, SQLite or Snowflake database into a secure REST API and an MCP server for AI agents. It is a single open-source (MIT) binary with a built-in admin UI, role-based access control and an OpenAPI 3.1 spec. This page takes you from install to your first API call in a few minutes.

## Installation

### npm (Node.js 18+)

The fastest way to try Faucet — just run one command:

```bash
npx @faucetdb/faucet serve
```

Or install globally:

```bash
npm install -g @faucetdb/faucet
faucet serve
```

### Homebrew (macOS / Linux)

```bash
brew install faucetdb/tap/faucet
```

### Go Install

Requires Go 1.25+:

```bash
go install github.com/faucetdb/faucet/cmd/faucet@latest
```

### Docker

```bash
docker pull faucetdb/faucet:latest
docker run -p 8080:8080 -v faucet-data:/data faucetdb/faucet:latest
```

### Binary Download

Download pre-built binaries from the [GitHub Releases](https://github.com/faucetdb/faucet/releases) page. Available for:

| OS      | Architecture |
|---------|-------------|
| Linux   | amd64, arm64 |
| macOS   | amd64, arm64 |
| Windows | amd64, arm64 |

Extract and place the `faucet` binary in your `PATH`.

### Build from Source

```bash
git clone https://github.com/faucetdb/faucet.git
cd faucet
make build
# Binary is at ./bin/faucet
```

To build with the embedded admin UI:

```bash
cd ui && npm install && npm run build && cd ..
make build
```

## 60-Second Quickstart

### 1. Start Faucet

```bash
faucet serve
```

The server starts in the background and returns control to your terminal:

```
 _____ _   _   _  ___ ___ _____
|  ___/ \ | | | |/ __| __|_   _|
| |_ / _ \| |_| | (__|  _| | |
|_| /_/ \_\___,_|\___|___| |_|

  Faucet v0.1.14 | Database → API in seconds
  Listening on http://0.0.0.0:8080
  Admin UI:   http://localhost:8080/
  OpenAPI:    http://localhost:8080/openapi.json
  MCP:        http://localhost:8080/mcp

  First run detected! Set up your admin account:
    Web UI:  http://localhost:8080/setup
    CLI:     faucet admin create --email admin@example.com --password changeme123

  Server running in background (PID 12345)
  Logs: ~/.faucet/faucet.log
```

### 2. Create your admin account

Open `http://localhost:8080` in your browser. On first run, Faucet opens the setup wizard. Enter an email and a password of at least 8 characters.

![The first step of the setup wizard: create your admin account](https://wiki.faucetdb.ai/screenshots/setup-admin.webp)

### 3. Connect a database

Pick your database, then enter the same details you'd give any database client: host, port, database, username and password. You don't need to write a connection string or escape special characters in your password. Click **Test connection**. Faucet connects, counts your tables, and the line from your database to `/api/v1/<name>` lights up. Then click **Add database**.

![Connecting a PostgreSQL database in the setup wizard; the connection test found 4 tables](https://wiki.faucetdb.ai/screenshots/setup-connect.webp)

The **API name** (filled in from your database name) becomes part of every URL, so `shop` gives you `/api/v1/shop/_table/orders`. If the test fails, Faucet tells you what to check: a refused connection, an unknown host, a wrong password, or TLS settings. See [Admin UI → Connect a database](https://wiki.faucetdb.ai/admin-ui#connect-a-database) for every option, including connection strings and the per-database fields.

### 4. Create a key and make your first request

Faucet's REST API and MCP server authenticate with API keys, and every key carries a **role** that says what it may do.

1. Open **Roles** and create a role. For a first test, **Read only** on **All databases** is a good choice.
2. Open **API keys**, click **Create key**, and pick that role. Faucet shows the key once, along with a `curl` command and an MCP config that already contain it.

```bash
# List the tables in the "shop" database
curl http://localhost:8080/api/v1/shop/_table \
  -H "X-API-Key: faucet_YOUR_KEY"

# Query records with a filter, newest first
curl "http://localhost:8080/api/v1/shop/_table/orders?filter=status%3D'shipped'&order=placed_at%20DESC&limit=10" \
  -H "X-API-Key: faucet_YOUR_KEY"
```

The **Overview** page tracks these steps for you, and the **API explorer** sends requests from the browser without any key setup.

### 5. Connect an AI agent (optional)

Open **AI agents (MCP)** in the admin UI, paste your key, and copy the ready-made config for Claude Code, Claude Desktop, Cursor, VS Code, Windsurf or ChatGPT. See the [MCP Server guide](https://wiki.faucetdb.ai/mcp-server) for details.

::: details Prefer the command line?
Every step above also works from the CLI. Add databases **before** starting the server, because a running server only loads CLI-added databases on its next start (databases added in the admin UI are live immediately).

```bash
faucet admin create --email admin@example.com --password changeme123

faucet db add --name shop --driver postgres \
  --host localhost --user faucet_api --password 's3cret@!' --database shop

faucet role create --name reader --verbs GET
faucet key create --role reader    # prints the key once

faucet serve
curl http://localhost:8080/api/v1/shop/_table -H "X-API-Key: faucet_YOUR_KEY"
```

You can also connect a database through the API with `POST /api/v1/system/service`. See the [API Reference](https://wiki.faucetdb.ai/api-reference#post-api-v1-system-service).
:::

## Configuration

Faucet looks for configuration in this order:

1. Command-line flags (highest priority)
2. Environment variables with `FAUCET_` prefix
3. `faucet.yaml` in the current directory
4. `~/.faucet/faucet.yaml`

### Configuration File Example

```yaml
server:
  host: 0.0.0.0
  port: 8080

auth:
  jwt_secret: "your-secret-key-change-in-production"
```

### Environment Variables

All configuration options can be set via environment variables with the `FAUCET_` prefix:

```bash
export FAUCET_SERVER_PORT=9090
export FAUCET_AUTH_JWT_SECRET="my-production-secret"
```

### Data Directory

Faucet stores its configuration (services, roles, API keys, admin accounts) in a SQLite database. By default this lives at `~/.faucet/`. Override with:

```bash
faucet serve --data-dir /var/lib/faucet
```

## Supported Databases

| Database | Versions | Hosted options | Driver | Tutorial |
|----------|----------|----------------|--------|----------|
| PostgreSQL | 9.6 – 17 | Amazon RDS, Aurora, Supabase, Neon, Azure Database | `postgres` | [PostgreSQL](https://wiki.faucetdb.ai/tutorial-postgres) |
| MySQL | 5.7 – 9.x | Amazon RDS, Aurora MySQL, PlanetScale, Azure MySQL | `mysql` | [MySQL and MariaDB](https://wiki.faucetdb.ai/tutorial-mysql) |
| MariaDB | 10.2 – 11.x | SkySQL, Amazon RDS for MariaDB | `mysql` (MySQL driver) | [MySQL and MariaDB](https://wiki.faucetdb.ai/tutorial-mysql#mariadb-notes) |
| SQL Server | 2012 – 2022 | Azure SQL Database, Amazon RDS | `mssql` | [SQL Server](https://wiki.faucetdb.ai/tutorial-sqlserver) |
| Oracle | 12c – 26ai | Oracle Cloud (OCI), Amazon RDS, Azure | `oracle` | [Oracle](https://wiki.faucetdb.ai/tutorial-oracle) |
| Snowflake | Current | AWS, Azure, GCP | `snowflake` | [Snowflake](https://wiki.faucetdb.ai/tutorial-snowflake) |
| SQLite | 3.35+ | Local file, in-memory | `sqlite` | [SQLite](https://wiki.faucetdb.ai/tutorial-sqlite) |

Connection fields, DSN formats and TLS options for each one are in [Database Connectors](https://wiki.faucetdb.ai/database-connectors).

## What's Next

- [Admin UI](https://wiki.faucetdb.ai/admin-ui) -- a tour of every page in the built-in dashboard
- [API Reference](https://wiki.faucetdb.ai/api-reference) -- full REST API documentation
- [CLI Reference](https://wiki.faucetdb.ai/cli-reference) -- all CLI commands and flags
- [Filter Syntax](https://wiki.faucetdb.ai/filter-syntax) -- query filtering language
- [Database Connectors](https://wiki.faucetdb.ai/database-connectors) -- DSN formats and driver details
- [RBAC](https://wiki.faucetdb.ai/rbac) -- roles, API keys, and access control
- [MCP Server](https://wiki.faucetdb.ai/mcp-server) -- AI agent integration
- [Connect Base44, Replit and ChatGPT](https://wiki.faucetdb.ai/ai-app-builders) -- reach a private database from cloud AI tools
- [LLM Integration Guide](https://wiki.faucetdb.ai/llm-guide) -- how agents should discover and query data
- [FAQ](https://wiki.faucetdb.ai/faq) and [Troubleshooting](https://wiki.faucetdb.ai/troubleshooting) -- quick answers and error fixes
- [Deployment](https://wiki.faucetdb.ai/deployment) -- production deployment guide
- [PostgreSQL Tutorial](https://wiki.faucetdb.ai/tutorial-postgres) -- connect and query PostgreSQL databases
- [MySQL and MariaDB Tutorial](https://wiki.faucetdb.ai/tutorial-mysql) -- connect and query MySQL and MariaDB databases
- [SQL Server Tutorial](https://wiki.faucetdb.ai/tutorial-sqlserver) -- connect and query SQL Server databases
- [Oracle Tutorial](https://wiki.faucetdb.ai/tutorial-oracle) -- connect and query Oracle databases
- [Snowflake Tutorial](https://wiki.faucetdb.ai/tutorial-snowflake) -- connect and query Snowflake
- [SQLite Tutorial](https://wiki.faucetdb.ai/tutorial-sqlite) -- connect and query SQLite databases