Add initial version of ParadeDB extension (#122)

* add initial version of ParadeDB extension

LocalStack extension for ParadeDB (PostgreSQL-based search and analytics).
Features:
- Runs paradedb/paradedb Docker container
- Exposes PostgreSQL port 5432 for direct connections
- Configurable via PARADEDB_POSTGRES_USER/PASSWORD/DB env vars
- Integration tests for basic SQL and pg_search BM25 functionality
- CI workflow for automated testing

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix ParadeDB tests to use v2 API syntax

Update tests to use the new ParadeDB v2 API:
- Use CREATE INDEX ... USING bm25 instead of CALL paradedb.create_bm25()
- Use ||| operator for disjunction (OR) search
- Use &&& operator for conjunction (AND) search
- Use pdb.score() for relevance scoring
- Use DROP INDEX instead of paradedb.drop_bm25()

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* [paradedb] Prefer more distinct connection credentials

* [paradedb] Also allow port to be overridden

This can be helpful to avoid clashing with another locally-running
postgres, for example.

* [paradedb] Additional project keywords

* [paradedb] Remove hallucinated project description

* [paradedb] Fix hallucinated example

* [paradedb] Just use the quickstart example as a test

No need to exhaustively verify or showcase different aspects of paradedb here.

* [paradedb] Apply formatter

* [paradedb] Add to main list of available extensions

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Steve Purcell <steve@sanityinc.com>

Author: 3 people

.github/workflows/paradedb.yml

@@ -0,0 +1,53 @@
+name: LocalStack ParadeDB Extension Tests
+
+on:
+  push:
+    paths:
+      - paradedb/**
+    branches:
+      - main
+  pull_request:
+    paths:
+      - .github/workflows/paradedb.yml
+      - paradedb/**
+  workflow_dispatch:
+
+env:
+  LOCALSTACK_DISABLE_EVENTS: "1"
+  LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
+
+jobs:
+  integration-tests:
+    name: Run Integration Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup LocalStack and extension
+        run: |
+          cd paradedb
+
+          docker pull localstack/localstack-pro &
+          docker pull paradedb/paradedb &
+          pip install localstack
+
+          make install
+          make lint
+          make dist
+          localstack extensions -v install file://$(ls ./dist/localstack_extension_paradedb-*.tar.gz)
+
+          DEBUG=1 localstack start -d
+          localstack wait
+
+      - name: Run integration tests
+        run: |
+          cd paradedb
+          make test
+
+      - name: Print logs
+        if: always()
+        run: |
+          localstack logs
+          localstack stop

README.md

@@ -76,6 +76,7 @@ You can install the respective extension by calling `localstack extensions insta
 | [Stripe](https://github.com/localstack/localstack-extensions/tree/main/stripe)                     | localstack-extension-stripe | 0.2.0   | Stable |
 | [Terraform Init](https://github.com/localstack/localstack-extensions/tree/main/terraform-init)     | localstack-extension-terraform-init | 0.2.0   | Experimental |
 | [TypeDB](https://github.com/localstack/localstack-extensions/tree/main/typedb)                     | localstack-extension-typedb | 0.1.3   | Experimental |
+| [ParadeDB](https://github.com/localstack/localstack-extensions/tree/main/paradedb)                     | localstack-extension-paradedb | 0.1.0   | Experimental |
 
 
 ## Developing Extensions

flake.nix

@@ -0,0 +1,22 @@
+{
+  description = "localstack-extensions";
+
+  inputs = {
+    nixpkgs.url = "nixpkgs/nixpkgs-unstable";
+  };
+
+  outputs = { self, nixpkgs }@inputs:
+    (
+      let
+        forAllSystems = nixpkgs.lib.genAttrs nixpkgs.lib.platforms.all;
+      in
+      {
+        devShell = forAllSystems (system:
+          let pkgs = import nixpkgs { inherit system; }; in
+            pkgs.mkShell {
+              buildInputs = with pkgs; [ uv python311 python311Packages.pip ty ];
+            }
+        );
+      }
+    );
+}

paradedb/.gitignore

@@ -0,0 +1,5 @@
+.venv
+dist
+build
+**/*.egg-info
+.eggs

paradedb/Makefile

@@ -0,0 +1,48 @@
+VENV_BIN = python3 -m venv
+VENV_DIR ?= .venv
+VENV_ACTIVATE = $(VENV_DIR)/bin/activate
+VENV_RUN = . $(VENV_ACTIVATE)
+TEST_PATH ?= tests
+
+usage:          ## Shows usage for this Makefile
+	@cat Makefile | grep -E '^[a-zA-Z_-]+:.*?## .*$$' | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+venv: $(VENV_ACTIVATE)
+
+$(VENV_ACTIVATE): pyproject.toml
+	test -d .venv || $(VENV_BIN) .venv
+	$(VENV_RUN); pip install --upgrade pip setuptools plux
+	$(VENV_RUN); pip install -e .[dev]
+	touch $(VENV_DIR)/bin/activate
+
+clean:
+	rm -rf .venv/
+	rm -rf build/
+	rm -rf .eggs/
+	rm -rf *.egg-info/
+
+install: venv   ## Install dependencies
+	$(VENV_RUN); python -m plux entrypoints
+
+dist: venv      ## Create distribution
+	$(VENV_RUN); python -m build
+
+publish: clean-dist venv dist   ## Publish extension to pypi
+	$(VENV_RUN); pip install --upgrade twine; twine upload dist/*
+
+entrypoints: venv   ## Generate plugin entrypoints for Python package
+	$(VENV_RUN); python -m plux entrypoints
+
+format:		    ## Run ruff to format the codebase
+	$(VENV_RUN); python -m ruff format .; make lint
+
+lint:		    ## Run ruff to lint the codebase
+	$(VENV_RUN); python -m ruff check --output-format=full .
+
+test:		    ## Run integration tests (requires LocalStack running with the Extension installed)
+	$(VENV_RUN); pytest $(PYTEST_ARGS) $(TEST_PATH)
+
+clean-dist: clean
+	rm -rf dist/
+
+.PHONY: clean clean-dist dist install publish usage venv format test

paradedb/README.md

@@ -0,0 +1,95 @@
+ParadeDB on LocalStack
+======================
+
+This repo contains a [LocalStack Extension](https://github.com/localstack/localstack-extensions) that facilitates developing [ParadeDB](https://www.paradedb.com)-based applications locally.
+
+ParadeDB is an Elasticsearch alternative built on Postgres. It provides full-text search with BM25 scoring, hybrid search combining semantic and keyword search, and real-time analytics capabilities.
+
+After installing the extension, a ParadeDB server instance will become available and can be accessed using standard PostgreSQL clients.
+
+## Connection Details
+
+Once the extension is running, you can connect to ParadeDB using any PostgreSQL client with the following default credentials:
+
+- **Host**: `localhost` (or the Docker host if running in a container)
+- **Port**: `5432` (mapped from the container)
+- **Database**: `mydatabase`
+- **Username**: `myuser`
+- **Password**: `mypassword`
+
+Example connection using `psql`:
+```bash
+psql -h localhost -p 5432 -U myuser -d mydatabase
+```
+
+Example connection using Python:
+```python
+import psycopg2
+
+conn = psycopg2.connect(
+    host="localhost",
+    port=5432,
+    database="mydatabase",
+    user="myuser",
+    password="mypassword"
+)
+```
+
+## ParadeDB Features
+
+ParadeDB includes the **pg_search** extension, for both search and
+analytics workloads.
+
+Example of BM25 scoring, from the excellent [quickstart guide](https://docs.paradedb.com/documentation/getting-started/quickstart):
+
+```sql
+CALL paradedb.create_bm25_test_table(
+  schema_name => 'public',
+  table_name => 'mock_items'
+);
+
+CREATE INDEX search_idx ON mock_items
+USING bm25 (id, description, category, rating, in_stock, created_at, metadata, weight_range)
+WITH (key_field='id');
+
+SELECT description, pdb.score(id)
+FROM mock_items
+WHERE description ||| 'running shoes' AND rating > 2
+ORDER BY score DESC
+LIMIT 5;
+```
+
+## Configuration
+
+The following environment variables can be passed to the LocalStack container to configure the extension:
+
+* `PARADEDB_POSTGRES_USER`: PostgreSQL username (default: `myuser`)
+* `PARADEDB_POSTGRES_PASSWORD`: PostgreSQL password (default: `mypassword`)
+* `PARADEDB_POSTGRES_DB`: Default database name (default: `mydatabase`)
+
+## Prerequisites
+
+* Docker
+* LocalStack Pro (free trial available)
+* `localstack` CLI
+* `make`
+
+## Install from GitHub repository
+
+This extension can be installed directly from this Github repo via:
+
+```bash
+localstack extensions install "git+https://github.com/localstack/localstack-extensions.git#egg=localstack-extension-paradedb&subdirectory=paradedb"
+```
+
+## Install local development version
+
+Please refer to the docs [here](https://github.com/localstack/localstack-extensions?tab=readme-ov-file#start-localstack-with-the-extension) for instructions on how to start the extension in developer mode.
+
+## Change Log
+
+* `0.1.0`: Initial version of the extension
+
+## License
+
+The code in this repo is available under the Apache 2.0 license.

paradedb/localstack_paradedb/__init__.py

@@ -0,0 +1 @@
+name = "localstack_paradedb"

paradedb/localstack_paradedb/extension.py

@@ -0,0 +1,70 @@
+import os
+import logging
+
+from localstack_paradedb.utils.docker import DatabaseDockerContainerExtension
+
+LOG = logging.getLogger(__name__)
+
+# Environment variables for configuration
+ENV_POSTGRES_USER = "PARADEDB_POSTGRES_USER"
+ENV_POSTGRES_PASSWORD = "PARADEDB_POSTGRES_PASSWORD"
+ENV_POSTGRES_DB = "PARADEDB_POSTGRES_DB"
+ENV_POSTGRES_PORT = "PARADEDB_POSTGRES_PORT"
+
+# Default values
+DEFAULT_POSTGRES_USER = "myuser"
+DEFAULT_POSTGRES_PASSWORD = "mypassword"
+DEFAULT_POSTGRES_DB = "mydatabase"
+DEFAULT_POSTGRES_PORT = 5432
+
+
+class ParadeDbExtension(DatabaseDockerContainerExtension):
+    name = "paradedb"
+
+    # Name of the Docker image to spin up
+    DOCKER_IMAGE = "paradedb/paradedb"
+
+    def __init__(self):
+        # Get configuration from environment variables
+        postgres_user = os.environ.get(ENV_POSTGRES_USER, DEFAULT_POSTGRES_USER)
+        postgres_password = os.environ.get(
+            ENV_POSTGRES_PASSWORD, DEFAULT_POSTGRES_PASSWORD
+        )
+        postgres_db = os.environ.get(ENV_POSTGRES_DB, DEFAULT_POSTGRES_DB)
+        postgres_port = int(os.environ.get(ENV_POSTGRES_PORT, DEFAULT_POSTGRES_PORT))
+
+        # Environment variables to pass to the container
+        env_vars = {
+            "POSTGRES_USER": postgres_user,
+            "POSTGRES_PASSWORD": postgres_password,
+            "POSTGRES_DB": postgres_db,
+        }
+
+        super().__init__(
+            image_name=self.DOCKER_IMAGE,
+            container_ports=[postgres_port],
+            env_vars=env_vars,
+        )
+
+        # Store configuration for connection info
+        self.postgres_user = postgres_user
+        self.postgres_password = postgres_password
+        self.postgres_db = postgres_db
+        self.postgres_port = postgres_port
+
+    def get_connection_info(self) -> dict:
+        """Return connection information for ParadeDB."""
+        info = super().get_connection_info()
+        info.update(
+            {
+                "database": self.postgres_db,
+                "user": self.postgres_user,
+                "password": self.postgres_password,
+                "port": self.postgres_port,
+                "connection_string": (
+                    f"postgresql://{self.postgres_user}:{self.postgres_password}"
+                    f"@{self.container_host}:{self.postgres_port}/{self.postgres_db}"
+                ),
+            }
+        )
+        return info