tlc-claude-code 0.7.8 → 0.8.1

package/server/node_modules/.package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "tlc-server",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
@@ -10,21 +10,16 @@
       "integrity": "sha512-Cj++n1Mekf9ETfdc16TlDi+cDDQF0W7EcbyRHYOAeZdsAe8M/FJg18itDTSwyHfar2WIezawM9o0EKaRGVKygQ==",
       "license": "Apache-2.0"
     },
-    "node_modules/@embedded-postgres/linux-x64": {
-      "version": "18.1.0-beta.15",
-      "resolved": "https://registry.npmjs.org/@embedded-postgres/linux-x64/-/linux-x64-18.1.0-beta.15.tgz",
-      "integrity": "sha512-AvFLqFLBdaAJIBjgyH7ejVVtgMss/DqAuE05FGyaoxmwuMQtr7c5rIm3kUbM+RzOzDFZZY9EzU67OQt5wlmxCA==",
-      "cpu": [
-        "x64"
-      ],
-      "hasInstallScript": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=16"
+    "node_modules/@electric-sql/pglite-socket": {
+      "version": "0.0.20",
+      "resolved": "https://registry.npmjs.org/@electric-sql/pglite-socket/-/pglite-socket-0.0.20.tgz",
+      "integrity": "sha512-J5nLGsicnD9wJHnno9r+DGxfcZWh+YJMCe0q/aCgtG6XOm9Z7fKeite8IZSNXgZeGltSigM9U/vAWZQWdgcSFg==",
+      "license": "Apache-2.0",
+      "bin": {
+        "pglite-server": "dist/scripts/server.js"
+      },
+      "peerDependencies": {
+        "@electric-sql/pglite": "0.3.15"
       }
     },
     "node_modules/@types/http-proxy": {
@@ -77,15 +72,6 @@
       "integrity": "sha512-PCVAQswWemu6UdxsDFFX/+gVeYqKAod3D3UVm91jHwynguOwAvYPhx8nNlM++NqRcK6CxxpUafjmhIdKiHibqg==",
       "license": "MIT"
     },
-    "node_modules/async-exit-hook": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/async-exit-hook/-/async-exit-hook-2.0.1.tgz",
-      "integrity": "sha512-NW2cX8m1Q7KPA7a5M2ULQeZ2wR5qI5PAbw5L0UOMxdioVk9PMZ0h1TmyZEkPYrCvYjDlFICusOu1dlEKAAeXBw==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=0.12.0"
-      }
-    },
     "node_modules/binary-extensions": {
       "version": "2.3.0",
       "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.3.0.tgz",
@@ -280,29 +266,6 @@
       "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==",
       "license": "MIT"
     },
-    "node_modules/embedded-postgres": {
-      "version": "18.1.0-beta.15",
-      "resolved": "https://registry.npmjs.org/embedded-postgres/-/embedded-postgres-18.1.0-beta.15.tgz",
-      "integrity": "sha512-JZZuPouEAk4vNaYODGGNIPYTMO/Al09Y8L2WvcqGdO3+fPFzJl4lhxJm8EfMOpJpi/x9tH1Ba47ZGE4/TTJjtA==",
-      "license": "MIT",
-      "dependencies": {
-        "async-exit-hook": "^2.0.1",
-        "pg": "^8.7.3"
-      },
-      "engines": {
-        "node": ">=16"
-      },
-      "optionalDependencies": {
-        "@embedded-postgres/darwin-arm64": "^18.1.0-beta.15",
-        "@embedded-postgres/darwin-x64": "^18.1.0-beta.15",
-        "@embedded-postgres/linux-arm": "^18.1.0-beta.15",
-        "@embedded-postgres/linux-arm64": "^18.1.0-beta.15",
-        "@embedded-postgres/linux-ia32": "^18.1.0-beta.15",
-        "@embedded-postgres/linux-ppc64": "^18.1.0-beta.15",
-        "@embedded-postgres/linux-x64": "^18.1.0-beta.15",
-        "@embedded-postgres/windows-x64": "^18.1.0-beta.15"
-      }
-    },
     "node_modules/encodeurl": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-2.0.0.tgz",
@@ -1232,6 +1195,13 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/sudo-prompt": {
+      "version": "9.2.1",
+      "resolved": "https://registry.npmjs.org/sudo-prompt/-/sudo-prompt-9.2.1.tgz",
+      "integrity": "sha512-Mu7R0g4ig9TUuGSxJavny5Rv0egCEtpZRNMrZaYS1vxkiIxGiGUwoezU3LazIQ+KE04hTrTfNPgxU5gzi7F5Pw==",
+      "deprecated": "Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.",
+      "license": "MIT"
+    },
     "node_modules/to-regex-range": {
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",

package/server/node_modules/@electric-sql/pglite-socket/CHANGELOG.md

@@ -0,0 +1,146 @@
+# @electric-sql/pglite-socket
+
+## 0.0.20
+
+### Patch Changes
+
+- 54a4873: allow extensions to be loaded via '-e/--extensions <list>' cmd line parameter'
+- 45bff97: added pgcrypto extension
+- Updated dependencies [45bff97]
+- Updated dependencies [5ec474f]
+  - @electric-sql/pglite@0.3.15
+
+## 0.0.19
+
+### Patch Changes
+
+- Updated dependencies [8785034]
+- Updated dependencies [90cfee8]
+  - @electric-sql/pglite@0.3.14
+
+## 0.0.18
+
+### Patch Changes
+
+- Updated dependencies [ad3d0d8]
+  - @electric-sql/pglite@0.3.13
+
+## 0.0.17
+
+### Patch Changes
+
+- Updated dependencies [ce0e74e]
+  - @electric-sql/pglite@0.3.12
+
+## 0.0.16
+
+### Patch Changes
+
+- Updated dependencies [9a104b9]
+  - @electric-sql/pglite@0.3.11
+
+## 0.0.15
+
+### Patch Changes
+
+- Updated dependencies [ad765ed]
+  - @electric-sql/pglite@0.3.10
+
+## 0.0.14
+
+### Patch Changes
+
+- e40ccad: Upgrade emsdk
+- Updated dependencies [e40ccad]
+  - @electric-sql/pglite@0.3.9
+
+## 0.0.13
+
+### Patch Changes
+
+- bd263aa: fix oom; other fixes
+- Updated dependencies [f12a582]
+- Updated dependencies [bd263aa]
+  - @electric-sql/pglite@0.3.8
+
+## 0.0.12
+
+### Patch Changes
+
+- Updated dependencies [0936962]
+  - @electric-sql/pglite@0.3.7
+
+## 0.0.11
+
+### Patch Changes
+
+- Updated dependencies [6898469]
+- Updated dependencies [469be18]
+- Updated dependencies [64e33c7]
+  - @electric-sql/pglite@0.3.6
+
+## 0.0.10
+
+### Patch Changes
+
+- Updated dependencies [6653899]
+- Updated dependencies [5f007fc]
+  - @electric-sql/pglite@0.3.5
+
+## 0.0.9
+
+### Patch Changes
+
+- 38a55d0: fix cjs/esm misconfigurations
+- Updated dependencies [1fcaa3e]
+- Updated dependencies [38a55d0]
+- Updated dependencies [aac7003]
+- Updated dependencies [8ca254d]
+  - @electric-sql/pglite@0.3.4
+
+## 0.0.8
+
+### Patch Changes
+
+- Updated dependencies [ea2c7c7]
+  - @electric-sql/pglite@0.3.3
+
+## 0.0.7
+
+### Patch Changes
+
+- 5a47f4d: better handling of closing the socket
+- 6f8dd08: with the `npx pglite-server` command, add the ability to pass a command to run after the server is ready, along with passing a new DATABASE_URL environment variable to the command. This allows for a command like `npx pglite-server -r "npm run dev:inner" --include-database-url` to run a dev server that uses the pglite server as the database.
+
+## 0.0.6
+
+### Patch Changes
+
+- Updated dependencies [e2c654b]
+  - @electric-sql/pglite@0.3.2
+
+## 0.0.5
+
+### Patch Changes
+
+- f975f77: Updated README
+- d9b52d5: allows unix socket connections
+
+## 0.0.4
+
+### Patch Changes
+
+- 027baed: missing shebang
+
+## 0.0.3
+
+### Patch Changes
+
+- 1c2dc84: fix pglite-socket exports
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies [713364e]
+  - @electric-sql/pglite@0.3.1

package/server/node_modules/@electric-sql/pglite-socket/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/server/node_modules/@electric-sql/pglite-socket/README.md

@@ -0,0 +1,265 @@
+# pglite-socket
+
+A socket implementation for PGlite enabling remote connections. This package is a simple wrapper around the `net` module to allow PGlite to be used as a PostgreSQL server.
+
+There are two main components to this package:
+
+- [`PGLiteSocketServer`](#pglitesocketserver) - A TCP server that allows PostgreSQL clients to connect to a PGlite database instance.
+- [`PGLiteSocketHandler`](#pglitesockethandler) - A low-level handler for a single socket connection to PGlite. This class handles the raw protocol communication between a socket and PGlite, and can be used to create a custom server.
+
+The package also includes a [CLI](#cli-usage) for quickly starting a PGlite socket server.
+
+Note: As PGlite is a single-connection database, it is not possible to have multiple simultaneous connections open. This means that the socket server will only support a single client connection at a time. While a `PGLiteSocketServer` or `PGLiteSocketHandler` are attached to a PGlite instance they hold an exclusive lock preventing any other connections, or queries on the PGlite instance.
+
+## Installation
+
+```bash
+npm install @electric-sql/pglite-socket
+# or
+yarn add @electric-sql/pglite-socket
+# or
+pnpm add @electric-sql/pglite-socket
+```
+
+## Usage
+
+```typescript
+import { PGlite } from '@electric-sql/pglite'
+import { PGLiteSocketServer } from '@electric-sql/pglite-socket'
+
+// Create a PGlite instance
+const db = await PGlite.create()
+
+// Create and start a socket server
+const server = new PGLiteSocketServer({
+  db,
+  port: 5432,
+  host: '127.0.0.1',
+})
+
+await server.start()
+console.log('Server started on 127.0.0.1:5432')
+
+// Handle graceful shutdown
+process.on('SIGINT', async () => {
+  await server.stop()
+  await db.close()
+  console.log('Server stopped and database closed')
+  process.exit(0)
+})
+```
+
+## API
+
+### PGLiteSocketServer
+
+Creates a TCP server that allows PostgreSQL clients to connect to a PGlite database instance.
+
+#### Options
+
+- `db: PGlite` - The PGlite database instance
+- `port?: number` - The port to listen on (default: 5432). Use port 0 to let the OS assign an available port
+- `host?: string` - The host to bind to (default: 127.0.0.1)
+- `path?: string` - Unix socket path to bind to (takes precedence over host:port)
+- `inspect?: boolean` - Print the incoming and outgoing data to the console (default: false)
+
+#### Methods
+
+- `start(): Promise<void>` - Start the socket server
+- `stop(): Promise<void>` - Stop the socket server
+
+#### Events
+
+- `listening` - Emitted when the server starts listening
+- `connection` - Emitted when a client connects
+- `error` - Emitted when an error occurs
+- `close` - Emitted when the server is closed
+
+### PGLiteSocketHandler
+
+Low-level handler for a single socket connection to PGlite. This class handles the raw protocol communication between a socket and PGlite.
+
+#### Options
+
+- `db: PGlite` - The PGlite database instance
+- `closeOnDetach?: boolean` - Whether to close the socket when detached (default: false)
+- `inspect?: boolean` - Print the incoming and outgoing data to the console in hex and ascii (default: false)
+
+#### Methods
+
+- `attach(socket: Socket): Promise<PGLiteSocketHandler>` - Attach a socket to this handler
+- `detach(close?: boolean): PGLiteSocketHandler` - Detach the current socket from this handler
+- `isAttached: boolean` - Check if a socket is currently attached
+
+#### Events
+
+- `data` - Emitted when data is processed through the handler
+- `error` - Emitted when an error occurs
+- `close` - Emitted when the socket is closed
+
+#### Example
+
+```typescript
+import { PGlite } from '@electric-sql/pglite'
+import { PGLiteSocketHandler } from '@electric-sql/pglite-socket'
+import { createServer, Socket } from 'net'
+
+// Create a PGlite instance
+const db = await PGlite.create()
+
+// Create a handler
+const handler = new PGLiteSocketHandler({
+  db,
+  closeOnDetach: true,
+  inspect: false,
+})
+
+// Create a server that uses the handler
+const server = createServer(async (socket: Socket) => {
+  try {
+    await handler.attach(socket)
+    console.log('Client connected')
+  } catch (err) {
+    console.error('Error attaching socket', err)
+    socket.end()
+  }
+})
+
+server.listen(5432, '127.0.0.1')
+```
+
+## Examples
+
+See the [examples directory](./examples) for more usage examples.
+
+## CLI Usage
+
+This package provides a command-line interface for quickly starting a PGlite socket server.
+
+```bash
+# Install globally
+npm install -g @electric-sql/pglite-socket
+
+# Start a server with default settings (in-memory database, port 5432)
+pglite-server
+
+# Start a server with custom options
+pglite-server --db=/path/to/database --port=5433 --host=0.0.0.0 --debug=1
+
+# Using short options
+pglite-server -d /path/to/database -p 5433 -h 0.0.0.0 -v 1
+
+# Show help
+pglite-server --help
+```
+
+### CLI Options
+
+- `-d, --db=PATH` - Database path (default: memory://)
+- `-p, --port=PORT` - Port to listen on (default: 5432). Use 0 to let the OS assign an available port
+- `-h, --host=HOST` - Host to bind to (default: 127.0.0.1)
+- `-u, --path=UNIX` - Unix socket to bind to (takes precedence over host:port)
+- `-v, --debug=LEVEL` - Debug level 0-5 (default: 0)
+- `-e, --extensions=LIST` - Comma-separated list of extensions to load (e.g., vector,pgcrypto)
+- `-r, --run=COMMAND` - Command to run after server starts
+- `--include-database-url` - Include DATABASE_URL in subprocess environment
+- `--shutdown-timeout=MS` - Timeout for graceful subprocess shutdown in ms (default: 5000)
+
+### Development Server Integration
+
+The `--run` option is particularly useful for development workflows where you want to use PGlite as a drop-in replacement for PostgreSQL. This allows you to wrap your development server and automatically provide it with a DATABASE_URL pointing to your PGlite instance.
+
+```bash
+# Start your Next.js dev server with PGlite
+pglite-server --run "npm run dev" --include-database-url
+
+# Start a Node.js app with PGlite
+pglite-server --db=./dev-db --run "node server.js" --include-database-url
+
+# Start multiple services (using a process manager like concurrently)
+pglite-server --run "npx concurrently 'npm run dev' 'npm run worker'" --include-database-url
+```
+
+When using `--run` with `--include-database-url`, the subprocess will receive a `DATABASE_URL` environment variable with the correct connection string for your PGlite server. This enables seamless integration with applications that expect a PostgreSQL connection string.
+
+### Using in npm scripts
+
+You can add the CLI to your package.json scripts for convenient execution:
+
+```json
+{
+  "scripts": {
+    "db:start": "pglite-server --db=./data/mydb --port=5433",
+    "db:dev": "pglite-server --db=memory:// --debug=1",
+    "dev": "pglite-server --db=./dev-db --run 'npm run start:dev' --include-database-url",
+    "dev:clean": "pglite-server --run 'npm run start:dev' --include-database-url"
+  }
+}
+```
+
+Then run with:
+
+```bash
+npm run dev          # Start with persistent database
+npm run dev:clean    # Start with in-memory database
+```
+
+### Unix Socket Support
+
+For better performance in local development, you can use Unix sockets instead of TCP:
+
+```bash
+# Start server on a Unix socket
+pglite-server --path=/tmp/pglite.sock --run "npm run dev" --include-database-url
+
+# The DATABASE_URL will be: postgresql://postgres:postgres@/postgres?host=/tmp
+```
+
+### Connecting to the server
+
+Once the server is running, you can connect to it using any PostgreSQL client:
+
+#### Using psql
+
+```bash
+PGSSLMODE=disable psql -h localhost -p 5432 -d template1
+```
+
+#### Using Node.js clients
+
+```javascript
+// Using node-postgres
+import pg from 'pg'
+const client = new pg.Client({
+  host: 'localhost',
+  port: 5432,
+  database: 'template1'
+})
+await client.connect()
+
+// Using postgres.js
+import postgres from 'postgres'
+const sql = postgres({
+  host: 'localhost',
+  port: 5432,
+  database: 'template1'
+})
+
+// Using environment variable (when using --include-database-url)
+const sql = postgres(process.env.DATABASE_URL)
+```
+
+### Limitations and Tips
+
+- Remember that PGlite only supports one connection at a time. If you're unable to connect, make sure no other client is currently connected.
+- For development purposes, using an in-memory database (`--db=memory://`) is fastest but data won't persist after the server is stopped.
+- For persistent storage, specify a file path for the database (e.g., `--db=./data/mydb`).
+- When using debug mode (`--debug=1` or higher), additional protocol information will be displayed in the console.
+- To allow connections from other machines, set the host to `0.0.0.0` with `--host=0.0.0.0`.
+- SSL connections are **NOT** supported. For `psql`, set env var `PGSSLMODE=disable`.
+- When using `--run`, the server will automatically shut down if the subprocess exits with a non-zero code.
+- Use `--shutdown-timeout` to adjust how long to wait for graceful subprocess termination (default: 5 seconds).
+
+## License
+
+Apache 2.0