docs: add readme, license and examples

.gitignore

@@ -2,3 +2,5 @@
 .DS_Store
 test*.db
 *.o
+local.db
+example

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Turso (libSQL)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,157 @@
+<p align="center">
+  <a href="https://tur.so/turso-c">
+    <picture>
+      <img src="/.github/cover.png" alt="libSQL C" />
+    </picture>
+  </a>
+  <h1 align="center">libSQL C</h1>
+</p>
+
+<p align="center">
+  Databases for C multi-tenant AI Apps.
+</p>
+
+<p align="center">
+  <a href="https://tur.so/turso-c"><strong>Turso</strong></a> ·
+  <a href="https://docs.turso.tech"><strong>Docs</strong></a> ·
+  <a href="https://docs.turso.tech/sdk/c/quickstart"><strong>Quickstart</strong></a> ·
+  <a href="https://docs.turso.tech/sdk/c/reference"><strong>SDK Reference</strong></a> ·
+  <a href="https://turso.tech/blog"><strong>Blog &amp; Tutorials</strong></a>
+</p>
+
+<p align="center">
+  <a href="LICENSE">
+    <picture>
+      <img src="https://img.shields.io/github/license/tursodatabase/libsql-c?color=0F624B" alt="MIT License" />
+    </picture>
+  </a>
+  <a href="https://tur.so/discord-c">
+    <picture>
+      <img src="https://img.shields.io/discord/933071162680958986?color=0F624B" alt="Discord" />
+    </picture>
+  </a>
+  <a href="#contributors">
+    <picture>
+      <img src="https://img.shields.io/github/contributors/tursodatabase/libsql-c?color=0F624B" alt="Contributors" />
+    </picture>
+  </a>
+  <a href="https://packagist.org/packages/turso/libsql">
+    <picture>
+      <img src="https://img.shields.io/packagist/dt/turso/libsql?color=0F624B" alt="Total downloads" />
+    </picture>
+  </a>
+  <a href="/examples">
+    <picture>
+      <img src="https://img.shields.io/badge/browse-examples-0F624B" alt="Examples" />
+    </picture>
+  </a>
+</p>
+
+## Features
+
+- 🔌 Works offline with [Embedded Replicas](https://docs.turso.tech/features/embedded-replicas/introduction)
+- 🌎 Works with remote Turso databases
+- ✨ Works with Turso [AI & Vector Search](https://docs.turso.tech/features/ai-and-embeddings)
+
+> [!WARNING]
+> This SDK is currently in technical preview, and mostly used for internal use when building other libSQL SDKs. <a href="https://tur.so/discord-c">Join us in Discord</a> to report any issues.
+
+## Install
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/your-repo/libsql-c.git
+   cd libsql-c
+   ```
+
+2. Build the library:
+
+   ```bash
+   cargo build --release
+   ```
+
+3. The compiled library will be in `target/release/`:
+
+   - `liblibsql.so` (Linux)
+   - `liblibsql.dylib` (macOS)
+   - `liblibsql.dll` (Windows)
+
+4. Copy `libsql.h` and the compiled library to your project directory or a standard system location.
+
+## Quickstart
+
+The example below uses Embedded Replicas and syncs data every 1000ms from Turso.
+
+1. Write your program:
+
+   ```c
+   #include <stdio.h>
+   #include "libsql.h"
+
+   int main() {
+       libsql_setup((libsql_config_t){0});
+
+       libsql_database_t db = libsql_database_init((libsql_database_desc_t){
+           .path = "test.db"
+       });
+
+       if (db.err) {
+           fprintf(stderr, "Error: %s\n", libsql_error_message(db.err));
+           return 1;
+       }
+
+       libsql_connection_t conn = libsql_database_connect(db);
+       if (conn.err) {
+           fprintf(stderr, "Connection error: %s\n", libsql_error_message(conn.err));
+           return 1;
+       }
+
+       const char* sql = "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT);"
+                         "INSERT INTO users (name) VALUES ('Alice');";
+
+       libsql_batch_t batch = libsql_connection_batch(conn, sql);
+       if (batch.err) {
+           fprintf(stderr, "Batch error: %s\n", libsql_error_message(batch.err));
+           return 1;
+       }
+
+       printf("Database operations completed successfully.\n");
+
+       libsql_connection_deinit(conn);
+       libsql_database_deinit(db);
+
+       return 0;
+   }
+   ```
+
+2. Compile your program, linking against the libsql library:
+
+   ```
+   gcc -o example example.c -L/path/to/libsql -llibsql
+   ```
+
+3. Run your program:
+   ```
+   ./example
+   ```
+
+## Documentation
+
+Visit our [official documentation](https://docs.turso.tech/sdk/c).
+
+## Support
+
+Join us [on Discord](https://tur.so/discord-c) to get help using this SDK. Report security issues [via email](mailto:[email protected]).
+
+## Contributors
+
+See the [contributing guide](CONTRIBUTING.md) to learn how to get involved.
+
+![Contributors](https://contrib.nn.ci/api?repo=tursodatabase/libsql-c)
+
+<a href="https://github.com/tursodatabase/libsql-c/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22">
+  <picture>
+    <img src="https://img.shields.io/github/issues-search/tursodatabase/libsql-c?label=good%20first%20issue&query=label%3A%22good%20first%20issue%22%20&color=0F624B" alt="good first issue" />
+  </picture>
+</a>

examples/local/Makefile

@@ -0,0 +1,15 @@
+CC = gcc
+LDFLAGS = -L../../target/release -Wl,-rpath,../../target/release
+LIBS = -llibsql
+
+TARGET = example
+
+all: $(TARGET)
+
+$(TARGET): example.c
+	$(CC) $(LDFLAGS) -o $@ $< $(LIBS)
+
+clean:
+	rm -f $(TARGET)
+
+.PHONY: all clean

examples/local/example.c

@@ -0,0 +1,134 @@
+#include "../../libsql.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+int main() {
+    libsql_setup((libsql_config_t){0});
+
+    libsql_database_t db =
+        libsql_database_init((libsql_database_desc_t){.path = "local.db"});
+    if (db.err) {
+        fprintf(
+            stderr,
+            "Error initializing database: %s\n",
+            libsql_error_message(db.err)
+        );
+        return 1;
+    }
+
+    libsql_connection_t conn = libsql_database_connect(db);
+    if (conn.err) {
+        fprintf(
+            stderr,
+            "Error connecting to database: %s\n",
+            libsql_error_message(conn.err)
+        );
+        return 1;
+    }
+
+    // Drop and create table, insert initial row
+    const char *setup_sql =
+        "DROP TABLE IF EXISTS users;"
+        "CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT);"
+        "INSERT INTO users (name) VALUES ('Iku Turso');";
+
+    libsql_batch_t batch = libsql_connection_batch(conn, setup_sql);
+    if (batch.err) {
+        fprintf(
+            stderr,
+            "Error executing setup batch: %s\n",
+            libsql_error_message(batch.err)
+        );
+        return 1;
+    }
+
+    // Insert combinations of forenames and surnames
+    const char *forenames[] = {"John", "Mary", "Alice", "Mark"};
+    const char *surnames[] = {"Doe", "Smith", "Jones", "Taylor"};
+    int forename_count = sizeof(forenames) / sizeof(forenames[0]);
+    int surname_count = sizeof(surnames) / sizeof(surnames[0]);
+
+    libsql_statement_t stmt =
+        libsql_connection_prepare(conn, "INSERT INTO users (name) VALUES (?)");
+    if (stmt.err) {
+        fprintf(
+            stderr,
+            "Error preparing statement: %s\n",
+            libsql_error_message(stmt.err)
+        );
+        return 1;
+    }
+
+    for (int i = 0; i < forename_count; i++) {
+        for (int j = 0; j < surname_count; j++) {
+            char full_name[100];
+            snprintf(
+                full_name, sizeof(full_name), "%s %s", forenames[i], surnames[j]
+            );
+
+            libsql_statement_reset(stmt);
+            libsql_statement_bind_value(
+                stmt, libsql_text(full_name, strlen(full_name))
+            );
+
+            libsql_execute_t result = libsql_statement_execute(stmt);
+            if (result.err) {
+                fprintf(
+                    stderr,
+                    "Error inserting %s: %s\n",
+                    full_name,
+                    libsql_error_message(result.err)
+                );
+            }
+        }
+    }
+
+    libsql_statement_deinit(stmt);
+
+    // Query and print all users
+    libsql_statement_t query_stmt =
+        libsql_connection_prepare(conn, "SELECT * FROM users");
+    if (query_stmt.err) {
+        fprintf(
+            stderr,
+            "Error preparing query: %s\n",
+            libsql_error_message(query_stmt.err)
+        );
+        return 1;
+    }
+
+    libsql_rows_t rows = libsql_statement_query(query_stmt);
+    if (rows.err) {
+        fprintf(
+            stderr,
+            "Error executing query: %s\n",
+            libsql_error_message(rows.err)
+        );
+        return 1;
+    }
+
+    libsql_row_t row;
+    while (!(row = libsql_rows_next(rows)).err && !libsql_row_empty(row)) {
+        libsql_result_value_t id = libsql_row_value(row, 0);
+        libsql_result_value_t name = libsql_row_value(row, 1);
+
+        if (id.err || name.err) {
+            fprintf(stderr, "Error retrieving row values\n");
+            continue;
+        }
+
+        printf(
+            "%lld %s\n", id.ok.value.integer, (char *)name.ok.value.text.ptr
+        );
+
+        libsql_row_deinit(row);
+    }
+
+    libsql_rows_deinit(rows);
+    libsql_statement_deinit(query_stmt);
+    libsql_connection_deinit(conn);
+    libsql_database_deinit(db);
+
+    return 0;
+}