# Run your first query

Install ParticleDB, start a local server, create a table, and read your first record.

Source: https://particledb.ai/getting-started/quickstart/

## 1. Install

```bash
curl -fsSL https://get.particledb.ai | bash
```

Check the installation:

```bash
particledb --version
particledb start --help
```

See [installation](/installation/binary/) for supported platforms and manual installation.

## 2. Start locally

```bash
particledb start \
  --data-dir ./pdb-dev \
  --http-addr 127.0.0.1:7173 \
  --pg-addr 127.0.0.1:5432 \
  --redis-addr 127.0.0.1:6379 \
  --mysql-addr 127.0.0.1:3307 \
  --metrics-addr 127.0.0.1:7175 \
  --no-unix-sockets \
  --no-auth
```

Keep this process running. `--no-auth` disables authentication, so use this setup only for development on a trusted local machine. See [local development](/guides/local-development/) for listener settings and [security](/guides/security/) before exposing a server.

## 3. Connect from your language

In another terminal, install a client and run the example. The clients connect to `localhost:7173`, the ParticleDB port, by default. The example creates a table, writes a row, reads it back and uses a key on the same connection.

#### Python

Install: `pip install particledb`

```python
import particledb

db = particledb.connect()  # localhost:7173
db.execute("CREATE TABLE agents (id BIGINT PRIMARY KEY, name TEXT)")
db.execute("INSERT INTO agents VALUES ($1, $2)", [1, "planner"])
print(db.query("SELECT id, name FROM agents WHERE id = $1", [1]))
db.kv_set("agent:1:status", "ready")
print(db.kv_get("agent:1:status").decode())
```

Output:

```
[{'id': 1, 'name': 'planner'}]
ready
```

#### TypeScript

Install: `npm install @particledb/sdk`

```typescript
import { ParticleDB } from '@particledb/sdk';

const db = await ParticleDB.connect();  // localhost:7173
await db.execute('CREATE TABLE agents (id BIGINT PRIMARY KEY, name TEXT)');
await db.execute('INSERT INTO agents VALUES ($1, $2)', [1, 'planner']);
console.log(await db.queryOne('SELECT id, name FROM agents WHERE id = $1', [1]));
await db.kv.set('agent:1:status', 'ready');
console.log(await db.kv.get('agent:1:status'));
await db.close();
```

Output:

```
{ id: 1, name: 'planner' }
ready
```

#### Java

Dependency: `implementation("ai.particledb:particledb-java-sdk:1.1.3")`

Inside main, with import com.particledb.ParticleDB.

```java
var db = ParticleDB.connect(); // localhost:7173
db.execute("CREATE TABLE agents (id BIGINT PRIMARY KEY, name TEXT)");
db.execute("INSERT INTO agents VALUES (?, ?)", 1L, "planner");
System.out.println(db.queryOne("SELECT id, name FROM agents WHERE id = ?", 1L));
db.kv().set("agent:1:status", "ready");
System.out.println(db.kv().get("agent:1:status"));
```

Output:

```
Row{id=1, name=planner}
ready
```

#### Go

Install: `go get github.com/particledb-ai/particledb-go@v0.2.2`

Inside func main. Errors are ignored here for brevity; check them in real code.

```go
ctx := context.Background()
db, _ := particledb.NewPool(ctx, "") // localhost:7173
db.Exec(ctx, "CREATE TABLE agents (id BIGINT PRIMARY KEY, name TEXT)")
db.Exec(ctx, "INSERT INTO agents VALUES ($1, $2)", 1, "planner")
var name string
db.QueryRow(ctx, "SELECT name FROM agents WHERE id = $1", 1).Scan(&name)
db.KVSet(ctx, []byte("agent:1:status"), []byte("ready"))
status, _ := db.KVGet(ctx, []byte("agent:1:status"))
fmt.Println(name, string(status))
```

Output:

```
planner ready
```

#### Rust

Install: `cargo add particledb-sdk`

Inside fn main() -> particledb_sdk::Result, with use particledb_sdk::{Config, ParticleDB, Value}.

```rust
let db = ParticleDB::connect(Config::default())?; // localhost:7173
db.execute("CREATE TABLE agents (id BIGINT PRIMARY KEY, name TEXT)", &[])?;
db.execute("INSERT INTO agents VALUES ($1, $2)", &[Value::Int64(1), Value::String("planner".into())])?;
let row = db.query_one("SELECT name FROM agents WHERE id = $1", &[Value::Int64(1)])?.unwrap();
println!("{}", row.get_by_name::<String>("name")?);
db.kv().set("agent:1:status", "ready")?;
println!("{:?}", db.kv().get("agent:1:status")?);
```

Output:

```
planner
Some("ready")
```

#### SQL

Install: `particledb cli`

```sql
CREATE TABLE agents (id BIGINT PRIMARY KEY, name TEXT);
INSERT INTO agents VALUES (1, 'planner');
SELECT id, name FROM agents WHERE id = 1;
SELECT KV_SET('agent:1:status', 'ready');
SELECT KV_GET('agent:1:status');
```

Output:

```
1|planner
OK
ready
```

The other pages show each task in the language you pick here. See your [language guide](/sdks/overview/) for authentication, pooling and error handling.

## PostgreSQL-compatible clients

Tools that speak the PostgreSQL protocol, such as psql and existing drivers, connect to the SQL client address instead, port 5432 in the start command above. This reads the row the example wrote:

```bash
psql -h 127.0.0.1 -p 5432 -U postgres -d particledb -c "SELECT id, name FROM agents"
```

See [PostgreSQL compatibility](/connectivity/pg-wire/) for supported drivers and differences.

## HTTP API

The HTTP API on the same port takes SQL as JSON. This sequence uses its own table:
### Create a table

Send a SQL statement to the database from another terminal:

```bash
curl --fail-with-body http://localhost:7173/v1/sql \
  -H 'Content-Type: application/json' \
  -d '{"sql":"CREATE TABLE tasks (id BIGINT PRIMARY KEY, title TEXT, status TEXT)"}'
```

### Write a record

```bash
curl --fail-with-body http://localhost:7173/v1/sql \
  -H 'Content-Type: application/json' \
  -d "{\"sql\":\"INSERT INTO tasks VALUES (1, 'First task', 'pending')\"}"
```

### Read it back

```bash
curl --fail-with-body http://localhost:7173/v1/sql \
  -H 'Content-Type: application/json' \
  -d '{"sql":"SELECT id, title, status FROM tasks ORDER BY id"}'
```

The response's `rows` array contains:

```json
[{"id":1,"title":"First task","status":"pending"}]
```

This guide creates the table once. For a fresh rerun, use a new development data directory or remove the sample table from your development database.

## Next steps

1. Choose a [language client](/sdks/overview/).
2. Learn [parameters and transactions](/guides/relational-data/).
3. Add [search and memory](/guides/search-and-memory/) or [key-value](/guides/key-value/) where your application needs them.
4. Move reusable logic into [Particles](/particles/overview/).
5. Review [security](/guides/security/) and [deployment](/guides/deployment/).

For a disposable test setup, follow [local development](/guides/local-development/). For an existing database, start with [migration](/operations/migration/).
