{"_id":"@anglinb/pulumi-clickhouse","name":"@anglinb/pulumi-clickhouse","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@anglinb/pulumi-clickhouse","version":"0.0.1","type":"module","main":"./dist-lib/index.js","module":"./dist-lib/index.js","types":"./dist-lib/index.d.ts","exports":{".":{"import":"./dist-lib/index.js","types":"./dist-lib/index.d.ts"}},"scripts":{"test":"bun run build:effect &&  vitest run","test:watch":"bun run build:effect && vitest","test:ui":"bun run build:effect && vitest --ui","build":"bun run build:lib && bun run build:effect","build:watch":"bun run build:lib:watch && bun run build:effect:watch","build:lib":"tsc --project tsconfig.build.json","build:lib:watch":"tsc --project tsconfig.build.json --watch","prepublishOnly":"bun run build","build:effect":"esbuild ./lib/effect/get-client.ts --platform=node --bundle --format=cjs --outfile=dist/get-client.cjs","build:effect:watch":"esbuild ./lib/effect/get-client.ts --platform=node --bundle --format=cjs --outfile=dist/get-client.cjs --watch","docker:up":"docker-compose up -d","docker:down":"docker-compose down -v","typecheck":"bun tsc --noEmit"},"devDependencies":{"@effect/vitest":"^0.23.12","@types/bun":"latest","vitest":"^3.2.4"},"peerDependencies":{"typescript":"^5.8.3"},"dependencies":{"@effect/experimental":"^0.51.12","@effect/sql":"^0.40.12","@effect/sql-clickhouse":"^0.31.3","@pulumi/pulumi":"^3.181.0","effect":"^3.16.12","esbuild":"^0.25.6"},"packageManager":"yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e","publishConfig":{"access":"public"},"_id":"@anglinb/pulumi-clickhouse@0.0.1","gitHead":"da9027cebda0e1f965a76db7403caae2f5e3b3fc","description":"A Pulumi dynamic provider for managing ClickHouse databases and tables with TypeScript support.","_nodeVersion":"24.3.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-NtkOAceKBZfkNfg0ez0AlEdlaG49zecu9GuR/ccqh/GVkE2OxB90WB/u+voqXK75dR/vr4sBXpGJPVQdOICuyQ==","shasum":"357142058aacc566d806a51bfa98ae4c7537c05a","tarball":"https://registry.npmjs.org/@anglinb/pulumi-clickhouse/-/pulumi-clickhouse-0.0.1.tgz","fileCount":39,"unpackedSize":1352611,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAZ+EpWq3SeY4ux9TghjOmz/vWy7UT4DKwzLF5/ILHcwAiBQdYL+5k+lilQj7DTzi/e5R8p8KvbBhlAdmyyezPpAPg=="}]},"_npmUser":{"name":"anglinb","email":"brianranglin@gmail.com","actor":{"name":"anglinb","email":"brianranglin@gmail.com","type":"user"}},"directories":{},"maintainers":[{"name":"anglinb","email":"brianranglin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pulumi-clickhouse_0.0.1_1752118100992_0.9155815784124597"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-10T03:28:20.873Z","0.0.1":"2025-07-10T03:28:21.172Z","modified":"2025-07-10T03:28:21.458Z"},"maintainers":[{"name":"anglinb","email":"brianranglin@gmail.com"}],"description":"A Pulumi dynamic provider for managing ClickHouse databases and tables with TypeScript support.","readme":"# Pulumi ClickHouse Provider\n\nA Pulumi dynamic provider for managing ClickHouse databases and tables with TypeScript support.\n\n## Features\n\n- **Database Management**: Create, update, and delete ClickHouse databases\n- **Table Management**: Full CRUD operations for ClickHouse tables\n- **Advanced Table Features**: \n  - Materialized columns\n  - Custom engines (MergeTree, etc.)\n  - Partitioning and ordering\n  - Primary keys and sampling\n  - TTL configuration\n  - Custom settings\n- **Safety Features**: \n  - `allowDrop` flags to prevent accidental deletions\n  - Column protection (prevents removal without explicit permission)\n- **Effect.ts Integration**: Built with Effect for robust error handling and functional programming\n- **TypeScript Support**: Full type safety and IntelliSense\n\n## Installation\n\n```bash\nnpm install @anglinb/pulumi-clickhouse\n# or\nyarn add @anglinb/pulumi-clickhouse\n# or\nbun add @anglinb/pulumi-clickhouse\n```\n\n## Quick Start\n\n```typescript\nimport { ClickhouseDatabase, ClickhouseTable } from \"@anglinb/pulumi-clickhouse\";\n\n// ClickHouse connection configuration\nconst clickhouseConfig = {\n  url: \"http://localhost:8123\",\n  username: \"default\", \n  password: \"your-password\",\n  database: \"system\"\n};\n\n// Create a database\nconst myDatabase = new ClickhouseDatabase(\"my-database\", {\n  name: \"analytics_db\",\n  engine: \"Atomic\",\n  comment: \"Analytics database for user events\",\n  settings: {\n    default_table_engine: \"MergeTree\"\n  },\n  allowDrop: true\n}, clickhouseConfig);\n\n// Create a table\nconst eventsTable = new ClickhouseTable(\"events-table\", {\n  name: \"user_events\", \n  databaseName: myDatabase.name,\n  engine: \"MergeTree()\",\n  columns: [\n    {\n      name: \"event_id\",\n      type: \"UInt64\",\n      comment: \"Unique event identifier\"\n    },\n    {\n      name: \"user_id\", \n      type: \"UInt64\",\n      comment: \"User identifier\"\n    },\n    {\n      name: \"event_name\",\n      type: \"String\",\n      comment: \"Name of the event\"\n    },\n    {\n      name: \"timestamp\",\n      type: \"DateTime\",\n      default: \"now()\",\n      comment: \"Event timestamp\"\n    },\n    {\n      name: \"event_date\",\n      type: \"Date\", \n      materialized: \"toDate(timestamp)\",\n      comment: \"Materialized date column for partitioning\"\n    }\n  ],\n  orderBies: [\"timestamp\", \"user_id\"],\n  partitionBy: \"toYYYYMM(event_date)\",\n  primaryKeys: [\"event_id\"],\n  allowDrops: true\n}, clickhouseConfig);\n```\n\n## Configuration\n\n### ClickHouse Connection Config\n\n```typescript\ninterface ClickhouseProviderConfig {\n  url: string;        // ClickHouse HTTP interface URL\n  username: string;   // Database username\n  password: string;   // Database password  \n  database: string;   // Default database (usually \"system\")\n}\n```\n\n## Database Management\n\n### Creating a Database\n\n```typescript\nconst database = new ClickhouseDatabase(\"resource-name\", {\n  name: \"my_database\",\n  engine: \"Atomic\",                    // Database engine\n  comment: \"Description of database\",  // Optional\n  settings: {                          // Optional settings\n    default_table_engine: \"MergeTree\"\n  },\n  allowDrop: true                      // Required for deletion\n}, clickhouseConfig);\n```\n\n### Database Properties\n\n```typescript\n// Access database properties\nconst dbName = database.name;        // Output<string>\nconst dbEngine = database.engine;    // Output<string>\nconst dbUuid = database.uuid;        // Output<string>\nconst dbComment = database.comment;  // Output<string>\n```\n\n## Table Management\n\n### Basic Table Creation\n\n```typescript\nconst table = new ClickhouseTable(\"table-resource\", {\n  name: \"user_data\",\n  databaseName: \"my_database\", \n  engine: \"MergeTree()\",\n  columns: [\n    { name: \"id\", type: \"UInt64\" },\n    { name: \"name\", type: \"String\" },\n    { name: \"email\", type: \"String\" }\n  ],\n  orderBies: [\"id\"],\n  allowDrops: true\n}, clickhouseConfig);\n```\n\n### Advanced Table Features\n\n```typescript\nconst advancedTable = new ClickhouseTable(\"advanced-table\", {\n  name: \"analytics_events\",\n  databaseName: \"analytics\", \n  engine: \"MergeTree()\",\n  columns: [\n    {\n      name: \"event_id\",\n      type: \"UInt64\", \n      comment: \"Primary identifier\"\n    },\n    {\n      name: \"user_id\",\n      type: \"UInt64\"\n    },\n    {\n      name: \"event_time\", \n      type: \"DateTime\",\n      default: \"now()\"\n    },\n    {\n      name: \"event_date\",\n      type: \"Date\",\n      materialized: \"toDate(event_time)\", // Materialized column\n      comment: \"Auto-generated date for partitioning\"\n    },\n    {\n      name: \"properties\",\n      type: \"String\"\n    }\n  ],\n  // Table structure\n  orderBies: [\"event_time\", \"user_id\"],     // ORDER BY clause\n  partitionBy: \"toYYYYMM(event_date)\",      // PARTITION BY\n  primaryKeys: [\"event_id\"],                // PRIMARY KEY\n  sampleBy: \"event_id\",                     // SAMPLE BY\n  \n  // Performance and storage\n  ttl: \"event_time + INTERVAL 90 DAY\",     // TTL policy\n  settings: {                               // Table settings\n    \"index_granularity\": \"8192\",\n    \"merge_max_block_size\": \"8192\"\n  },\n  \n  // Metadata and safety\n  comment: \"User analytics events table\",\n  allowDrops: true,                         // Allow destructive operations\n  \n  // Optional cluster support\n  clusterName: \"my_cluster\"                 // For distributed setups\n}, clickhouseConfig);\n```\n\n### Table Properties\n\n```typescript\n// Access table properties\nconst tableName = table.name;           // Output<string>\nconst tableDatabase = table.databaseName; // Output<string>\nconst tableEngine = table.engine;       // Output<string>\nconst tableColumns = table.columns;     // Output<TableColumn[]>\nconst tableUuid = table.uuid;          // Output<string>\n```\n\n## Column Types and Features\n\n### Basic Columns\n\n```typescript\n{\n  name: \"user_id\",\n  type: \"UInt64\",\n  comment: \"User identifier\"\n}\n```\n\n### Default Values\n\n```typescript\n{\n  name: \"created_at\", \n  type: \"DateTime\",\n  default: \"now()\",\n  comment: \"Creation timestamp\"\n}\n```\n\n### Materialized Columns\n\n```typescript\n{\n  name: \"user_name_upper\",\n  type: \"String\", \n  materialized: \"upper(user_name)\",\n  comment: \"Uppercase version of user name\"\n}\n```\n\n## Safety Features\n\n### Database Protection\n\n```typescript\nconst protectedDb = new ClickhouseDatabase(\"protected-db\", {\n  name: \"important_data\",\n  engine: \"Atomic\",\n  allowDrop: false  // Prevents accidental deletion\n}, config);\n\n// This will fail:\n// protectedDb.delete() -> Error: allowDrop must be set to true\n```\n\n### Column Protection\n\n```typescript\nconst protectedTable = new ClickhouseTable(\"protected-table\", {\n  name: \"critical_data\",\n  databaseName: \"production\",\n  engine: \"MergeTree()\",\n  columns: [\n    { name: \"id\", type: \"UInt64\" },\n    { name: \"data\", type: \"String\" }\n  ],\n  allowDrops: false  // Prevents column removal/modification\n}, config);\n\n// Removing columns will require allowDrops: true\n```\n\n## Error Handling\n\nThe provider includes comprehensive error logging with SQL context:\n\n```typescript\n// Errors include the full SQL query and ClickHouse error details\ntry {\n  const table = new ClickhouseTable(\"bad-table\", {\n    name: \"invalid-name!\",  // Invalid character\n    databaseName: \"nonexistent\",\n    engine: \"InvalidEngine\",\n    columns: []\n  }, config);\n} catch (error) {\n  console.log(error.message);\n  // Output:\n  // ClickHouse query failed\n  // Query: CREATE TABLE `nonexistent`.`invalid-name!` ...\n  // Cause: DB::Exception: Invalid table name...\n}\n```\n\n## Development\n\n### Building\n\n```bash\n# Build the library\nbun run build\n\n# Build just TypeScript \nbun run build:lib\n\n# Build just Effect client\nbun run build:effect\n\n# Watch mode\nbun run build:watch\n```\n\n### Testing\n\n```bash\n# Run tests (requires ClickHouse running)\nbun run test\n\n# Run specific test file\nbun vitest run ./test/clickhouse-table.test.ts\n\n# Watch mode\nbun run test:watch\n```\n\n### ClickHouse Setup\n\nFor development, start ClickHouse with Docker:\n\n```bash\n# Start ClickHouse\nbun run docker:up\n\n# Stop ClickHouse  \nbun run docker:down\n```\n\nOr use the provided `docker-compose.yml`:\n\n```yaml\nversion: '3.8'\nservices:\n  clickhouse:\n    image: clickhouse/clickhouse-server:latest\n    ports:\n      - \"8123:8123\"  # HTTP interface\n      - \"9000:9000\"  # Native interface\n    environment:\n      CLICKHOUSE_PASSWORD: clickhouse\n    volumes:\n      - clickhouse_data:/var/lib/clickhouse\n\nvolumes:\n  clickhouse_data:\n```\n\n## Examples\n\nSee the `/examples` directory for complete working examples:\n\n- Basic database and table creation\n- Advanced table features\n- Production configurations\n- Error handling patterns\n\n## Requirements\n\n- Node.js 18+\n- ClickHouse 21.3+\n- Pulumi 3.0+\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass: `bun run test`\n6. Submit a pull request\n\n## License\n\nMIT\n\n## Support\n\nFor issues and questions:\n- Open an issue on GitHub\n- Check the examples directory\n- Review the test files for usage patterns","readmeFilename":"README.md","_rev":"1-309df405f3e716cf1b98fd6a39c85caa"}