Connecting to Managed Services

Once your managed service is deployed, you can connect to it from your Codesphere workspaces. Each service lists non-sensitive connection details in their respective settings page, in the overview tab (or in the details property in the public API payload). This guide provides examples for connecting to common services.

Prerequisites

Ensure your workspace and the managed service are in the same team to allow for network access.

PostgreSQL

Codesphere provides a standard PostgreSQL service. You can connect to it using any PostgreSQL compatible client, such as psql or Node.js libraries like pg.

Connection Details

You can find these in the service details page:

• Host/DSN: The internal hostname or full connection string with redacted password.
• Port: 5432 (Standard PostgreSQL port).
• Username: Defined during setup (for root user postgres or your custom username that you provided).
• Password: The secret you provided during setup for the specified username.

Terminal (psql)

You can use the psql command-line tool directly from your workspace terminal.

# Install psql
nix-env -iA nixpkgs.postgresql

# General syntax
psql "postgres://<username>@<hostname>:5432/<database>" -W

# Example
psql "postgres://[email protected]:5432/mydb" -W

Node.js

Using the pg library:

const { Client } = require('pg');

const client = new Client({
    connectionString: 'postgres://admin:[email protected]:5432/mydb'
});

await client.connect();
const res = await client.query('SELECT $1::text as message', ['Hello Codesphere!']);
console.log(res.rows[0].message); // Hello Codesphere!
await client.end();

Babelfish (SQL Server Compatible)

Babelfish for PostgreSQL allows it to understand the T-SQL protocol, making it compatible with SQL Server clients.

Unlike with standard PostgreSQL, Babelfish does support specifying a name for the initial database. The initial database is always named master. You can create additional databases after provisioning.

Connection Details

• Host/DSN: The internal hostname or full connection string with redacted password.
• Port: 1433 (Standard SQL Server port).
• Username: postgres (you can create additional users after provisioning).
• Password: As configured.
• Database: Initially master.

Terminal (tsql)

You can use tsql (part of the FreeTDS package) to connect. Note that tsql might need to be installed in your workspace.

# Install FreeTDS
nix-env -iA nixpkgs.freetds

# Syntax
# TDSENCRYPTION=required tsql -H <hostname> -p 1433 -U <username> -D <database>

# Example:
TDSENCRYPTION=required tsql -H ms-babelfish-v1-123-my-server.ms-postgres -p 1433 -U postgres -D master

Node.js

Using the mssql library:

const sql = require('mssql');

(async () => {
    const config = {
        user: 'postgres',
        password: 'superSecret',
        server: 'ms-babelfish-v1-123-my-server.ms-postgres',
        port: 1433,
        database: 'master',
        options: {
            encrypt: true,
            // Codesphere uses a self-signed certificate
            trustServerCertificate: false
        }
    };

    await sql.connect(config);
    const result = await sql.query`SELECT 1 as val`;
    console.log(result.recordset[0].val);
})();

S3 (Object Storage)

The S3 Managed Service provides an S3-compatible object storage API.

Connection Details

• Endpoint: The URL of the service (e.g., http://10.0.0.20:9000).
• Access Key: Generated during setup.
• Secret Key: Generated during setup.

Terminal (mc)

The MinIO Client (mc) is a robust tool for interacting with S3-compatible APIs.

# 1. install
nix-env -iA nixpkgs.minio-client

# 2. Configure alias
mc alias set my-storage http://10.0.0.20:9000 "$ACCESS_KEY" "$SECRET_KEY"

# 3. List buckets
mc ls my-storage

# 4. Copy file
mc cp myfile.txt my-storage/my-bucket/

Node.js

Using the AWS SDK for JavaScript v3 (@aws-sdk/client-s3):

const { S3 } = require("@aws-sdk/client-s3");

const s3 = new S3({
    endpoint: "http://10.0.0.20:9000",
    region: "us-east-1", // Dummy region, required by SDK
    credentials: {
        accessKeyId: "YOUR_ACCESS_KEY",
        secretAccessKey: "YOUR_SECRET_KEY"
    },
    forcePathStyle: true, // Crucial for custom S3 providers
    tls: false, // initial connection is often HTTP internally
});

// List buckets
const { Buckets } = await s3.listBuckets({});
console.log(Buckets);

Codesphere Document DB (MongoDB compatible)

Codesphere Document DB is a document database with MongoDB compatibility. It leverages a FerretDB proxy which implements the MongoDB wire protocol as a translation layer and routes queries to a PostgreSQL database leveraging the DocumentDB extension.

Connection Details

• Host: The internal hostname.
• DSN: The full connection string with redacted password
• Port: 27017 (Standard MongoDB port).
• Username: postgres (you can create additional users after provisioning).
• Password: As configured.
• Auth Source: postgres

Terminal (mongosh)

You can use mongosh to connect from your workspace terminal.

No TLS Encryption between the client and the FerretDB Proxy

# Install mongosh
nix-env -iA nixpkgs.mongosh
source ~/.nix-profile/etc/profile.d/nix.sh

# Syntax
mongosh "mongodb://<username>:<password>@<hostname>:27017/ferretdb?authSource=postgres"

# Example
db.myCollection.insertOne({ message: "Hello Codesphere!" })

Node.js

Using the mongodb driver:

const { MongoClient } = require('mongodb');

const client = new MongoClient(
    'mongodb://postgres:[email protected]:27017/ferretdb'
);

await client.connect();
const db = client.db('ferretdb');
const collection = db.collection('myCollection');

const result = await collection.insertOne({ message: 'Hello Codesphere!' });
console.log(result.insertedId);

await client.close();