{"id":17870,"library":"pg-micro","title":"pg-micro: PostgreSQL-compatible Embeddable Database","description":"pg-micro is an experimental, in-process reimplementation of PostgreSQL, currently at version 0.0.5. It is built as an experimental fork of Turso, which is a full, from-scratch rewrite of SQLite in Rust. Unlike other approaches that try to compile PostgreSQL to WebAssembly or translate PostgreSQL syntax to SQLite, pg-micro directly parses the PostgreSQL language using `libpg_query` (the same parser PostgreSQL itself uses) and compiles it to SQLite bytecode for execution on Turso's engine. This approach aims to provide a fast, embeddable, single-file database that natively understands PostgreSQL syntax, targeting ephemeral, low-touch, short-lived, and small database use cases. Its key differentiators include 100% PostgreSQL syntax fidelity, direct compilation to SQLite bytecode, and a standard SQLite-compatible storage format, allowing for dual access via PostgreSQL and SQLite syntax. Release cadence is currently irregular due to its experimental nature and close ties to Turso's development cycle.","status":"active","version":"0.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/glommer/pgmicro","tags":["javascript","typescript"],"install":[{"cmd":"npm install pg-micro","lang":"bash","label":"npm"},{"cmd":"yarn add pg-micro","lang":"bash","label":"yarn"},{"cmd":"pnpm add pg-micro","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary entry point for establishing a database connection is `connect`.","wrong":"const { connect } = require('pg-micro');","symbol":"connect","correct":"import { connect } from 'pg-micro';"},{"note":"The `Database` class is a named export, not a default export.","wrong":"import Database from 'pg-micro';","symbol":"Database","correct":"import { Database } from 'pg-micro';"},{"note":"Import types using `import type` for clarity and to ensure they are stripped from compiled JavaScript.","symbol":"Row","correct":"import { type Row } from 'pg-micro';"}],"quickstart":{"code":"import { connect } from 'pg-micro';\n\nasync function runExample() {\n  // Connect to an in-memory database for a quick test\n  // For a file-backed database, pass a path like 'myapp.db'\n  const db = await connect(':memory:');\n\n  try {\n    // Execute DDL statement to create a table\n    await db.exec(\n      \"CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT, email TEXT)\"\n    );\n    console.log('Table \"users\" created.');\n\n    // Insert data into the table using prepared statements\n    const insertStmt = db.prepare(\n      \"INSERT INTO users (name, email) VALUES ($1, $2)\"\n    );\n    await insertStmt.run('Alice', 'alice@example.com');\n    await insertStmt.run('Bob', 'bob@example.com');\n    console.log('Data inserted into \"users\" table.');\n\n    // Query data using a prepared statement and fetch all rows\n    const rows = await db.prepare(\"SELECT * FROM users\").all();\n    console.log('Fetched rows:', rows);\n    // Expected output: \n    // [\n    //   { id: 1, name: 'Alice', email: 'alice@example.com' },\n    //   { id: 2, name: 'Bob', email: 'bob@example.com' }\n    // ]\n\n  } catch (error) {\n    console.error('Database operation failed:', error);\n  } finally {\n    // Always close the database connection when done\n    await db.close();\n    console.log('Database connection closed.');\n  }\n}\n\nrunExample();","lang":"typescript","description":"Demonstrates connecting to an in-memory pg-micro database, creating a table, inserting data with prepared statements, and querying results."},"warnings":[{"fix":"Refer to the latest GitHub repository and any available changelogs for the most up-to-date API and usage patterns before upgrading. Pin exact versions in production.","message":"As `pg-micro` is an experimental project (version 0.0.5), its API is subject to frequent and significant breaking changes. Relying on specific internal behaviors or undocumented features is highly discouraged as they may change without major version bumps.","severity":"breaking","affected_versions":">=0.0.1"},{"fix":"Thoroughly test complex PostgreSQL queries and features in `pg-micro` to confirm compatibility and expected behavior. Check the project's documentation or issue tracker for known limitations.","message":"`pg-micro` is built on a Rust-based SQLite-compatible storage engine (Turso). While it parses 100% PostgreSQL syntax, some advanced or niche PostgreSQL features (e.g., specific extensions, complex stored procedures, certain non-standard functions) might not yet be fully supported or have different performance characteristics compared to a native PostgreSQL server.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Monitor both `pg-micro` and `Turso` repositories for significant updates, architectural changes, or potential shifts in project direction. Consider the long-term viability in relation to Turso's status.","message":"The project is explicitly an \"experimental fork of Turso\" with a stated guideline to \"Minimize changes to the Turso core.\" This means its development path is heavily influenced by Turso's evolution, which is also under active development. Stability and long-term maintenance are tied to Turso's ecosystem.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure all database operations complete before calling `db.close()`. Use `await` for asynchronous operations. Re-establish a new connection if further operations are needed after closing.","cause":"Attempting to perform operations on a `pg-micro` Database instance after it has been explicitly closed with `db.close()`, or if the connection failed to establish initially.","error":"Error: Database is closed"},{"fix":"Simplify the SQL query, or consult the `pg-micro` GitHub repository and issues for known limitations regarding specific PostgreSQL features or syntax. Test queries incrementally to identify the problematic part.","cause":"Executing PostgreSQL SQL that contains syntax not yet fully supported by `pg-micro`'s translation layer or is incompatible with the underlying SQLite bytecode compilation. While it parses 100% PostgreSQL, some constructs might not translate directly.","error":"Syntax error near '...' / Unexpected token"},{"fix":"Ensure `await connect(...)` completes successfully and that the returned `Database` instance is valid before attempting to call its methods. Add error handling around the `connect` call.","cause":"This typically occurs if the `db` object (the `Database` instance) was not successfully initialized or is `null`/`undefined` when `db.prepare()` or `db.exec()` is called. This might happen if `connect()` failed or was not awaited.","error":"TypeError: Cannot read properties of undefined (reading 'prepare')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}