--- title: "HeliosDB Nano Protocol Server - Quick Start Guide" --- # HeliosDB Nano Protocol Server - Quick Start Guide ## Overview HeliosDB Nano server mode exposes the PostgreSQL wire protocol by default, with optional MySQL protocol support when enabled. ## Installation Build from source: ```bash cd HeliosDB-Nano cargo build --release ``` The binary will be at `target/release/heliosdb-nano`. ## Starting the Server ### Basic Start ```bash heliosdb-nano start ``` This will: - Create data directory at `./heliosdb-data` - Start a PostgreSQL-compatible server on `127.0.0.1:5432` - Start the HTTP health endpoint unless disabled with `--http-port 0` ### Custom Data Directory ```bash heliosdb-nano start --data-dir /var/lib/heliosdb ``` ### Listen on All Interfaces ```bash heliosdb-nano start --listen 0.0.0.0 ``` ### Full Example ```bash # Start server with custom settings heliosdb-nano start \ --data-dir /var/lib/heliosdb \ --listen 0.0.0.0 \ --port 5432 # The startup banner prints PostgreSQL connection strings for psql, # Python, Node.js, and JDBC clients. ``` ## Connecting to the Server ### Using psql ```bash psql -h localhost -p 5432 -d heliosdb ``` Example session: ```sql heliosdb=> CREATE TABLE users (id INT, name TEXT); CREATE TABLE heliosdb=> INSERT INTO users VALUES (1, 'Alice'); INSERT 0 1 heliosdb=> SELECT * FROM users; id | name ----+------- 1 | Alice ``` ### Using Python ```python import psycopg with psycopg.connect("host=localhost port=5432 dbname=heliosdb") as conn: with conn.cursor() as cur: cur.execute("CREATE TABLE users (id INT, name TEXT)") cur.execute("INSERT INTO users VALUES (1, 'Alice')") cur.execute("SELECT * FROM users") print(cur.fetchall()) ``` ### Using Java (JDBC) ```java import java.sql.*; public class HeliosDBExample { public static void main(String[] args) throws SQLException { // Connect to HeliosDB Nano String url = "jdbc:postgresql://localhost:5432/heliosdb"; Connection conn = DriverManager.getConnection(url, "postgres", ""); // Execute SQL Statement stmt = conn.createStatement(); stmt.execute("CREATE TABLE users (id INT, name TEXT)"); stmt.execute("INSERT INTO users VALUES (1, 'Alice')"); // Query data ResultSet rs = stmt.executeQuery("SELECT * FROM users"); while (rs.next()) { System.out.println( "ID: " + rs.getInt("id") + ", Name: " + rs.getString("name") ); } // Close rs.close(); stmt.close(); conn.close(); } } ``` ## Supported SQL Use PostgreSQL-style SQL from clients: ### Tables ```sql -- Create table CREATE TABLE users ( id INT PRIMARY KEY, name VARCHAR(100), email VARCHAR(255), created_at TIMESTAMP ); -- Insert data INSERT INTO users VALUES (1, 'Alice', 'alice@example.com', CURRENT_TIMESTAMP); -- Query data SELECT * FROM users; SELECT * FROM users WHERE id = 1; -- Update data UPDATE users SET email = 'newemail@example.com' WHERE id = 1; -- Delete data DELETE FROM users WHERE id = 1; -- Drop table DROP TABLE users; ``` ### Vector Search (HeliosDB Extension) ```sql -- Create table with vector column CREATE TABLE embeddings ( id INT, content TEXT, embedding VECTOR(768) ); -- Insert vector data INSERT INTO embeddings VALUES ( 1, 'Hello world', '[0.1, 0.2, 0.3, ...]'::VECTOR ); -- Vector similarity search SELECT * FROM embeddings ORDER BY embedding <-> '[0.1, 0.2, 0.3, ...]'::VECTOR LIMIT 10; ``` ## Stopping the Server Press `Ctrl+C` to gracefully shut down: ``` ^C Received shutdown signal (Ctrl+C) Server shutting down Protocol listeners stopped Server shutdown complete ``` ## Other Modes ### REPL Mode (Interactive) ```bash heliosdb-nano repl ``` Interactive SQL shell: ``` HeliosDB Nano - Interactive Shell Type 'help' for help, 'exit' to quit helios> CREATE TABLE users (id INT, name TEXT); OK (1 row affected) helios> INSERT INTO users VALUES (1, 'Alice'); OK (1 row inserted) helios> SELECT * FROM users; +----+-------+ | id | name | +----+-------+ | 1 | Alice | +----+-------+ 1 row helios> exit Goodbye! ``` ### Initialize New Database ```bash heliosdb-nano init /path/to/database ``` ## Troubleshooting ### Port Already in Use **Error**: "Failed to bind to 127.0.0.1:5432" **Solution**: Another process is using port 5432. Either stop that process or use a different port: ```bash # Find what's using the port lsof -i :5432 # Use a different port heliosdb-nano start --port 15432 ``` ### Connection Refused **Error**: Client cannot connect **Solution**: 1. Verify server is running: `ps aux | grep heliosdb-nano` 2. Check if firewall is blocking the configured server port 3. Try connecting from localhost first 4. Check server logs for errors ### PostgreSQL Client Won't Connect **Error**: psql or other PostgreSQL clients fail to connect **Reason**: The server may not be running, may be bound to a different address, or may require authentication options that the client did not provide. **Solution**: Check the startup banner for the exact host and port, then retry with the matching `psql -h -p ` settings. ## File Locations After starting the server, you'll find: ``` ./heliosdb-data/ # Data directory ├── CURRENT # RocksDB current version ├── IDENTITY # Database identity ├── LOCK # Lock file ├── LOG # RocksDB log ├── MANIFEST-* # RocksDB manifest ├── OPTIONS-* # RocksDB options └── *.sst # Data files (SST tables) ``` ## Environment Variables ```bash # Set log level export RUST_LOG=info export RUST_LOG=debug # More verbose export RUST_LOG=trace # Most verbose # Start server with logging RUST_LOG=debug heliosdb-nano start ``` ## Next Steps 1. Review PostgreSQL protocol tests in `tests/protocol_tests.rs` 2. Check adapter layer source in `src/protocols/adapters/` 3. Run protocol checks with `cargo test protocol` ## Support For issues or questions: - Check documentation in `docs/` - Review test files for usage examples - Examine source code in `src/` ## Operating Notes 1. Configure authentication with `--auth` and `--password` when exposing the server outside local development. 2. Use `--tls-cert` and `--tls-key` when clients require TLS. 3. Use `--mysql` only when the MySQL compatibility listener is needed. 4. Use `--http-port 0` to disable the HTTP health endpoint.