hostdb 0.29.0 → 0.31.0

package/README.md

@@ -1,8 +1,8 @@
 # hostdb
 
-Pre-built database binaries for all major platforms, distributed via GitHub Releases.
+Pre-built database binaries for all major platforms, distributed via Cloudflare R2 (mirrored from GitHub Releases). Also a **typed npm package** (`hostdb`) that bundles the registry offline so consumers can resolve versions and download URLs without a network round-trip to `registry.layerbase.host`.
 
-**Primary consumer:** [SpinDB](https://github.com/robertjbass/spindb) - a CLI tool for spinning up local database instances
+**Primary consumer:** [SpinDB](https://github.com/robertjbass/spindb) — a CLI tool for spinning up local database instances. SpinDB depends on `hostdb` as a pinned npm dependency; bumping `hostdb` is how SpinDB picks up new database versions.
 
 ## Philosophy
 
@@ -51,20 +51,52 @@ pnpm dbs
 
 ## Querying Available Binaries
 
-SpinDB (or any consumer) can fetch `releases.json` for available binaries:
+### As an npm package (recommended)
 
 ```bash
-curl https://raw.githubusercontent.com/robertjbass/hostdb/main/releases.json
+pnpm add hostdb         # or: npm install hostdb / yarn add hostdb
+```
+
+```ts
+import {
+  resolveVersion,
+  getReleaseInfo,
+  listEngines,
+} from 'hostdb'
+
+// Short-form version → full pinned version (LTS-aware via the defaults block)
+resolveVersion('postgresql', '17')       // '17.10.0'
+resolveVersion('mongodb', '8')           // '8.0.23'   (LTS pick, not the highest 8.x)
+resolveVersion('mysql', '8')             // '8.4.9'    (LTS, not the 9.x latest)
+
+// Find the R2 download URL + sha256 for a specific platform
+getReleaseInfo('postgresql', '17.10.0', 'linux-x64')
+// → { url: 'https://registry.layerbase.host/...', sha256: '...', size: 165123456 }
+
+// All bundled engines
+listEngines()  // ['clickhouse', 'cockroachdb', ..., 'weaviate']
+```
+
+The published tarball ships `databases.json`, `releases.json`, and `downloads.json` baked in. No runtime network calls. Pin to an exact version (e.g., `"hostdb": "0.31.0"` — no caret, no tilde) so the snapshot is deterministic for any given consumer release.
+
+Full API surface is locked in `tests/api-shape.test.ts` (currently 19 exported names).
+
+### As raw JSON
+
+```bash
+curl https://registry.layerbase.host/releases.json
 ```
 
 **Download URL pattern:**
 ```
-https://github.com/robertjbass/hostdb/releases/download/{tag}/{filename}
+https://registry.layerbase.host/{tag}/{filename}
 
 # Example:
-https://github.com/robertjbass/hostdb/releases/download/mysql-8.4.3/mysql-8.4.3-darwin-arm64.tar.gz
+https://registry.layerbase.host/mysql-8.4.3/mysql-8.4.3-darwin-arm64.tar.gz
 ```
 
+GitHub Releases (`https://github.com/robertjbass/hostdb/releases/download/...`) are the upstream source; R2 is the canonical mirror.
+
 ## Configuration Files
 
 | File | Purpose |

package/databases.json

@@ -12,14 +12,25 @@
       "hostedServiceAllowed": true,
       "protocol": null,
       "note": "Windows binaries unavailable. Require WSL.",
+      "defaults": {
+        "25": "25.12.3.21"
+      },
       "versions": {
         "25.12.3.21": true
       },
-      "platforms": ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64"],
+      "platforms": [
+        "linux-x64",
+        "linux-arm64",
+        "darwin-x64",
+        "darwin-arm64"
+      ],
       "cliTools": {
         "server": "clickhouse-server",
         "client": "clickhouse-client",
-        "utilities": ["clickhouse-local", "clickhouse-benchmark"],
+        "utilities": [
+          "clickhouse-local",
+          "clickhouse-benchmark"
+        ],
         "enhanced": []
       },
       "connection": {
@@ -42,6 +53,9 @@
       "hostedServiceAllowed": false,
       "protocol": "postgresql",
       "note": "CockroachDB Software License restricts competing cloud services; fine for local dev",
+      "defaults": {
+        "25": "25.4.2"
+      },
       "versions": {
         "25.4.2": true
       },
@@ -56,7 +70,10 @@
         "server": "cockroach",
         "client": "cockroach",
         "utilities": [],
-        "enhanced": ["pgcli", "usql"],
+        "enhanced": [
+          "pgcli",
+          "usql"
+        ],
         "note": "Single binary; use 'cockroach start-single-node' for server, 'cockroach sql' for client"
       },
       "connection": {
@@ -79,6 +96,9 @@
       "hostedServiceAllowed": true,
       "protocol": null,
       "note": "",
+      "defaults": {
+        "3": "3.5.1"
+      },
       "versions": {
         "3.5.1": true
       },
@@ -116,7 +136,11 @@
       "hostedServiceAllowed": true,
       "protocol": null,
       "note": "",
+      "defaults": {
+        "1": "1.4.4"
+      },
       "versions": {
+        "1.4.4": true,
         "1.4.3": true
       },
       "platforms": [
@@ -130,7 +154,9 @@
         "server": null,
         "client": "duckdb",
         "utilities": [],
-        "enhanced": ["usql"]
+        "enhanced": [
+          "usql"
+        ]
       },
       "connection": {
         "runtime": "embedded",
@@ -152,6 +178,10 @@
       "hostedServiceAllowed": true,
       "protocol": "mongodb",
       "note": "FerretDB v2 requires PostgreSQL-DocumentDB; v1 uses plain PostgreSQL",
+      "defaults": {
+        "1": "1.24.2",
+        "2": "2.7.0"
+      },
       "versions": {
         "2.7.0": {
           "platforms": [
@@ -188,7 +218,10 @@
       "cliTools": {
         "server": "ferretdb",
         "client": "mongosh",
-        "utilities": ["mongodump", "mongorestore"],
+        "utilities": [
+          "mongodump",
+          "mongorestore"
+        ],
         "enhanced": []
       },
       "connection": {
@@ -211,6 +244,9 @@
       "hostedServiceAllowed": true,
       "protocol": null,
       "note": "v3.0 is a Rust rewrite using Apache Arrow/DataFusion. Single binary with bundled Python runtime for plugin system. Most popular time-series database by adoption.",
+      "defaults": {
+        "3": "3.8.0"
+      },
       "versions": {
         "3.8.0": true
       },
@@ -238,6 +274,48 @@
       },
       "spindbStatus": "completed"
     },
+    "libsql": {
+      "displayName": "libSQL",
+      "description": "SQLite fork by Turso with server mode (sqld), HTTP API, replication, and embedded replica support",
+      "type": "Embedded SQL",
+      "sourceRepo": "https://github.com/tursodatabase/libsql",
+      "license": "MIT",
+      "commercialUse": true,
+      "hostedServiceAllowed": true,
+      "protocol": "sqlite",
+      "note": "Windows binaries unavailable. Require WSL.",
+      "defaults": {
+        "0": "0.24.32"
+      },
+      "versions": {
+        "0.24.32": true
+      },
+      "platforms": [
+        "linux-x64",
+        "linux-arm64",
+        "darwin-x64",
+        "darwin-arm64"
+      ],
+      "cliTools": {
+        "server": "sqld",
+        "client": null,
+        "utilities": [],
+        "enhanced": [
+          "litecli",
+          "usql"
+        ],
+        "note": "HTTP API; use Turso client SDKs or any libSQL/SQLite client"
+      },
+      "connection": {
+        "runtime": "server",
+        "defaultPort": 8080,
+        "scheme": "http",
+        "defaultDatabase": null,
+        "defaultUser": null,
+        "queryLanguage": "SQL"
+      },
+      "spindbStatus": "in-progress"
+    },
     "mariadb": {
       "displayName": "MariaDB",
       "description": "Community-developed fork of MySQL with enhanced performance, storage engines, and features",
@@ -248,9 +326,16 @@
       "hostedServiceAllowed": true,
       "protocol": null,
       "note": "",
+      "defaults": {
+        "10": "10.11.16",
+        "11": "11.8.6"
+      },
       "versions": {
+        "11.8.6": true,
         "11.8.5": true,
+        "11.4.10": true,
         "11.4.5": true,
+        "10.11.16": true,
         "10.11.15": true
       },
       "platforms": [
@@ -263,8 +348,15 @@
       "cliTools": {
         "server": "mariadbd",
         "client": "mariadb",
-        "utilities": ["mariadb-dump", "mariadb-import", "mariadb-admin"],
-        "enhanced": ["mycli", "usql"]
+        "utilities": [
+          "mariadb-dump",
+          "mariadb-import",
+          "mariadb-admin"
+        ],
+        "enhanced": [
+          "mycli",
+          "usql"
+        ]
       },
       "connection": {
         "runtime": "server",
@@ -286,7 +378,11 @@
       "hostedServiceAllowed": true,
       "protocol": null,
       "note": "",
+      "defaults": {
+        "1": "1.43.1"
+      },
       "versions": {
+        "1.43.1": true,
         "1.33.1": true
       },
       "platforms": [
@@ -323,9 +419,16 @@
       "hostedServiceAllowed": false,
       "protocol": null,
       "note": "SSPL restricts offering MongoDB as a competing managed database service (i.e., MongoDB Atlas competitors). Commercial use in applications, local dev, and internal use is fine. FerretDB available as fully open-source alternative.",
+      "defaults": {
+        "7": "7.0.34",
+        "8": "8.0.23"
+      },
       "versions": {
+        "8.2.9": true,
         "8.2.3": true,
+        "8.0.23": true,
         "8.0.17": true,
+        "7.0.34": true,
         "7.0.28": true
       },
       "platforms": [
@@ -366,15 +469,72 @@
       "hostedServiceAllowed": true,
       "protocol": null,
       "note": "",
+      "defaults": {
+        "8": "8.4.9",
+        "9": "9.6.0"
+      },
       "versions": {
-        "9.6.0": true,
+        "9.6.0": {
+          "note": "mysqlpump removed in MySQL 9.0; 9.x uses mysqldump only",
+          "cliTools": {
+            "server": "mysqld",
+            "client": "mysql",
+            "utilities": [
+              "mysqldump",
+              "mysqladmin"
+            ],
+            "enhanced": [
+              "mycli",
+              "usql"
+            ]
+          }
+        },
         "9.5.0": {
           "deprecated": true,
-          "note": "Deprecated; superseded by 9.6.0"
+          "note": "Deprecated; superseded by 9.6.0. mysqlpump removed in MySQL 9.0.",
+          "cliTools": {
+            "server": "mysqld",
+            "client": "mysql",
+            "utilities": [
+              "mysqldump",
+              "mysqladmin"
+            ],
+            "enhanced": [
+              "mycli",
+              "usql"
+            ]
+          }
         },
         "9.1.0": {
           "deprecated": true,
-          "note": "Deprecated; superseded by 9.6.0"
+          "note": "Deprecated; superseded by 9.6.0. mysqlpump removed in MySQL 9.0.",
+          "cliTools": {
+            "server": "mysqld",
+            "client": "mysql",
+            "utilities": [
+              "mysqldump",
+              "mysqladmin"
+            ],
+            "enhanced": [
+              "mycli",
+              "usql"
+            ]
+          }
+        },
+        "8.4.9": {
+          "note": "mysqlpump removed in 8.4.9",
+          "cliTools": {
+            "server": "mysqld",
+            "client": "mysql",
+            "utilities": [
+              "mysqldump",
+              "mysqladmin"
+            ],
+            "enhanced": [
+              "mycli",
+              "usql"
+            ]
+          }
         },
         "8.4.3": true,
         "8.0.40": {
@@ -392,8 +552,15 @@
       "cliTools": {
         "server": "mysqld",
         "client": "mysql",
-        "utilities": ["mysqldump", "mysqlpump", "mysqladmin"],
-        "enhanced": ["mycli", "usql"]
+        "utilities": [
+          "mysqldump",
+          "mysqlpump",
+          "mysqladmin"
+        ],
+        "enhanced": [
+          "mycli",
+          "usql"
+        ]
       },
       "connection": {
         "runtime": "server",
@@ -415,10 +582,20 @@
       "hostedServiceAllowed": true,
       "protocol": null,
       "note": "",
+      "defaults": {
+        "15": "15.18.0",
+        "16": "16.14.0",
+        "17": "17.10.0",
+        "18": "18.4.0"
+      },
       "versions": {
+        "18.4.0": true,
         "18.1.0": true,
+        "17.10.0": true,
         "17.7.0": true,
+        "16.14.0": true,
         "16.11.0": true,
+        "15.18.0": true,
         "15.15.0": true
       },
       "platforms": [
@@ -438,7 +615,10 @@
           "createdb",
           "dropdb"
         ],
-        "enhanced": ["pgcli", "usql"]
+        "enhanced": [
+          "pgcli",
+          "usql"
+        ]
       },
       "connection": {
         "runtime": "server",
@@ -460,15 +640,30 @@
       "hostedServiceAllowed": true,
       "protocol": "postgresql",
       "note": "Backend for FerretDB v2 only; includes pg_cron, pgvector, PostGIS, rum extensions. Not available on Windows.",
+      "defaults": {
+        "17": "17-0.107.0"
+      },
       "versions": {
         "17-0.107.0": true
       },
-      "platforms": ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64"],
+      "platforms": [
+        "linux-x64",
+        "linux-arm64",
+        "darwin-x64",
+        "darwin-arm64"
+      ],
       "cliTools": {
         "server": "postgres",
         "client": "psql",
-        "utilities": ["pg_dump", "pg_restore", "initdb", "pg_ctl"],
-        "enhanced": ["pgcli"]
+        "utilities": [
+          "pg_dump",
+          "pg_restore",
+          "initdb",
+          "pg_ctl"
+        ],
+        "enhanced": [
+          "pgcli"
+        ]
       },
       "connection": {
         "runtime": "server",
@@ -490,6 +685,9 @@
       "hostedServiceAllowed": true,
       "protocol": null,
       "note": "",
+      "defaults": {
+        "1": "1.16.3"
+      },
       "versions": {
         "1.16.3": true
       },
@@ -534,6 +732,9 @@
           "note": "QuestDB uses PostgreSQL client tools (psql, pgcli) for its wire protocol; PostgreSQL remains installed as a standalone database when QuestDB is removed"
         }
       ],
+      "defaults": {
+        "9": "9.2.3"
+      },
       "versions": {
         "9.2.3": true
       },
@@ -548,7 +749,10 @@
         "server": "questdb",
         "client": "psql",
         "utilities": [],
-        "enhanced": ["pgcli", "usql"],
+        "enhanced": [
+          "pgcli",
+          "usql"
+        ],
         "note": "PostgreSQL wire protocol; use psql or pgcli"
       },
       "connection": {
@@ -571,8 +775,13 @@
       "hostedServiceAllowed": false,
       "protocol": null,
       "note": "RSALv2 restricts building competing products to Redis itself. AGPL-3.0 (8.0+) requires source disclosure if you modify Redis and offer it as a network service. Commercial use in applications, local dev, and internal use is fine. Valkey available as BSD-licensed drop-in alternative.",
+      "defaults": {
+        "7": "7.4.9",
+        "8": "8.4.0"
+      },
       "versions": {
         "8.4.0": true,
+        "7.4.9": true,
         "7.4.7": true
       },
       "platforms": [
@@ -585,8 +794,14 @@
       "cliTools": {
         "server": "redis-server",
         "client": "redis-cli",
-        "utilities": ["redis-benchmark", "redis-check-aof", "redis-check-rdb"],
-        "enhanced": ["iredis"]
+        "utilities": [
+          "redis-benchmark",
+          "redis-check-aof",
+          "redis-check-rdb"
+        ],
+        "enhanced": [
+          "iredis"
+        ]
       },
       "connection": {
         "runtime": "server",
@@ -608,7 +823,11 @@
       "hostedServiceAllowed": true,
       "protocol": null,
       "note": "",
+      "defaults": {
+        "3": "3.53.1"
+      },
       "versions": {
+        "3.53.1": true,
         "3.51.2": true
       },
       "platforms": [
@@ -622,7 +841,10 @@
         "server": null,
         "client": "sqlite3",
         "utilities": [],
-        "enhanced": ["litecli", "usql"]
+        "enhanced": [
+          "litecli",
+          "usql"
+        ]
       },
       "connection": {
         "runtime": "embedded",
@@ -644,6 +866,9 @@
       "hostedServiceAllowed": false,
       "protocol": null,
       "note": "Rust-based; single binary. License is BSL-1.1 (not Apache-2.0); prohibits competing DBaaS offerings. Converts to Apache-2.0 after 4 years per release. Fine for local dev and internal use.",
+      "defaults": {
+        "2": "2.3.2"
+      },
       "versions": {
         "2.3.2": true
       },
@@ -681,6 +906,9 @@
       "hostedServiceAllowed": true,
       "protocol": null,
       "note": "Written in Zig; single binary with built-in REPL client. Uses a custom binary protocol (not HTTP/SQL). macOS uses a universal (fat) binary for both x64 and arm64.",
+      "defaults": {
+        "0": "0.16.70"
+      },
       "versions": {
         "0.16.70": true
       },
@@ -718,6 +946,9 @@
       "hostedServiceAllowed": true,
       "protocol": null,
       "note": "Rewritten from Java to Rust in v3.0 (Dec 2024). Binaries distributed via Cloudsmith and GitHub Releases.",
+      "defaults": {
+        "3": "3.8.0"
+      },
       "versions": {
         "3.8.0": true
       },
@@ -755,8 +986,14 @@
       "hostedServiceAllowed": true,
       "protocol": "redis",
       "note": "",
+      "defaults": {
+        "8": "8.0.9",
+        "9": "9.0.4"
+      },
       "versions": {
+        "9.0.4": true,
         "9.0.1": true,
+        "8.0.9": true,
         "8.0.6": true
       },
       "platforms": [
@@ -769,8 +1006,12 @@
       "cliTools": {
         "server": "valkey-server",
         "client": "valkey-cli",
-        "utilities": ["valkey-benchmark"],
-        "enhanced": ["iredis"]
+        "utilities": [
+          "valkey-benchmark"
+        ],
+        "enhanced": [
+          "iredis"
+        ]
       },
       "connection": {
         "runtime": "server",
@@ -792,6 +1033,9 @@
       "hostedServiceAllowed": true,
       "protocol": null,
       "note": "Go-based single binary (CGO_ENABLED=0). Linux from official releases; macOS/Windows cross-compiled from source.",
+      "defaults": {
+        "1": "1.35.7"
+      },
       "versions": {
         "1.35.7": true
       },

package/dist/checksums.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared checksum utilities for fetching and parsing checksums.txt files
+ */
+/**
+ * Parse checksums.txt content into a record of filename -> hash
+ */
+export declare function parseChecksums(content: string): Record<string, string>;
+/**
+ * Fetch checksums.txt from a GitHub release using the API (avoids CDN caching issues)
+ *
+ * @param repo - Repository in "owner/repo" format
+ * @param tag - Release tag name
+ * @returns Record of filename -> SHA256 hash, or empty object if not found
+ */
+export declare function fetchChecksums(repo: string, tag: string): Promise<Record<string, string>>;
+//# sourceMappingURL=checksums.d.ts.map

package/dist/checksums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checksums.d.ts","sourceRoot":"","sources":["../lib/checksums.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAYtE;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAwDjC"}

package/dist/checksums.js

@@ -0,0 +1,74 @@
+/**
+ * Shared checksum utilities for fetching and parsing checksums.txt files
+ */
+/**
+ * Parse checksums.txt content into a record of filename -> hash
+ */
+export function parseChecksums(content) {
+    const checksums = {};
+    for (const line of content.split('\n')) {
+        // Format: "hash  filename" or "hash *filename" (binary mode)
+        const match = line.match(/^([a-f0-9]{64})\s+\*?(.+)$/);
+        if (match) {
+            checksums[match[2]] = match[1];
+        }
+    }
+    return checksums;
+}
+/**
+ * Fetch checksums.txt from a GitHub release using the API (avoids CDN caching issues)
+ *
+ * @param repo - Repository in "owner/repo" format
+ * @param tag - Release tag name
+ * @returns Record of filename -> SHA256 hash, or empty object if not found
+ */
+export async function fetchChecksums(repo, tag) {
+    // First try to get the asset URL from the API
+    const apiUrl = `https://api.github.com/repos/${repo}/releases/tags/${tag}`;
+    const apiResponse = await fetch(apiUrl, {
+        headers: {
+            Accept: 'application/vnd.github.v3+json',
+            'User-Agent': 'hostdb-checksums',
+            ...(process.env.GITHUB_TOKEN
+                ? { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` }
+                : {}),
+        },
+    });
+    if (!apiResponse.ok) {
+        return {};
+    }
+    const release = (await apiResponse.json());
+    const checksumAsset = release.assets.find((a) => a.name === 'checksums.txt');
+    if (!checksumAsset) {
+        return {};
+    }
+    // Use API asset download (works for both private and public repos)
+    const assetApiUrl = `https://api.github.com/repos/${repo}/releases/assets/${checksumAsset.id}`;
+    const assetApiResponse = await fetch(assetApiUrl, {
+        headers: {
+            Accept: 'application/octet-stream',
+            'User-Agent': 'hostdb-checksums',
+            ...(process.env.GITHUB_TOKEN
+                ? { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` }
+                : {}),
+        },
+        redirect: 'follow',
+    });
+    if (assetApiResponse.ok) {
+        const content = await assetApiResponse.text();
+        return parseChecksums(content);
+    }
+    // Fallback: try browser_download_url (only works for public repos)
+    if (!process.env.GITHUB_TOKEN) {
+        const browserResponse = await fetch(checksumAsset.browser_download_url, {
+            headers: { 'User-Agent': 'hostdb-checksums' },
+            redirect: 'follow',
+        });
+        if (browserResponse.ok) {
+            const content = await browserResponse.text();
+            return parseChecksums(content);
+        }
+    }
+    return {};
+}
+//# sourceMappingURL=checksums.js.map